descrybe/docs/tutorial.md

In-app tutorial (Descrybe v2)

Hands-on product tour in apps/web. Progress is stored in localStorage under descrybe.tutorial.v2.

Behavior

• Skip tour — ends the tour entirely (status: skipped). Restart from the header or dashboard.
• Pause / Escape — dismisses the overlay but keeps in_progress so Resume tutorial works.
• Action steps — no free Continue. The user must click the highlighted control (advanceOn: "click") or complete a real success path (advanceOn: "action" via tutorial.reportAction(stepId)).
• Informational steps — only welcome and done use Continue / Done.
• Restart tutorial — shown after completed or skipped; starts from step 1.

Step list

#	id	Route / UI	Advance when
1	welcome	/dashboard welcome header	Continue
2	standard-fields-nav	Nav → Standard Fields	Click data-tour="nav-standard-fields"
3	enable-recommended	/standard-fields	Enable recommended API succeeds
4	feeds-nav	Nav → Feeds	Click data-tour="nav-feeds"
5	open-feed	/feeds	Click Map (data-tour="feed-open-mapping")
6	auto-map	/feeds/{id}/mapping	Auto-map applies suggestions
7	save-mappings	mapping footer	Save Mappings succeeds
8	sync-process-sample	mapping footer	Sync + Process sample succeeds
9	products-nav	Nav → Products	Click data-tour="nav-products"
10	products-result	/products table	Click data-tour="products-table"
11	export-feeds-nav	Nav → Export Feeds	Click data-tour="nav-export-feeds"
12	export-create	/export-feeds	Click Create Export Feed
13	campaigns-nav	Nav → Campaigns	Click data-tour="nav-campaigns"
14	campaigns-create	/campaigns	Click New campaign
15	done	/dashboard	Done

There is no Uploads step — uploads were removed from the main nav; feeds cover catalog ingest.

Key files

Path	Role
apps/web/src/lib/tutorial/steps.ts	Step definitions
apps/web/src/lib/tutorial/state.svelte.ts	Controller (start / resume / restart / skip / reportAction)
apps/web/src/lib/tutorial/storage.ts	localStorage read/write
apps/web/src/lib/tutorial/dom.ts	Preferential selector matching
apps/web/src/lib/components/tutorial/TutorialOverlay.svelte	Spotlight overlay + progress
apps/web/src/lib/components/Nav.svelte	data-tour="nav-*" attrs
apps/web/src/routes/+layout.svelte	Header Start / Resume / Restart
apps/web/src/routes/dashboard/+page.svelte	Dashboard Start / Resume / Restart

Wiring success (advanceOn: "action")

Pages call tutorial.reportAction("<step-id>") only after a successful operation:

• standard-fields/+page.svelte → enable-recommended
• feeds/[feedId]/mapping/+page.svelte → auto-map, save-mappings, sync-process-sample

Manual test checklist

1. Clear localStorage key descrybe.tutorial.v2 (or use Restart).
2. Dashboard → Start tutorial → Continue on welcome.
3. Confirm action steps show no Continue button; only Skip tour / Pause / Back.
4. Click each highlighted nav item / control; confirm progress bar advances.
5. On mapping: Auto-map → Save → Sync sample must succeed before advance.
6. Pause, reload, Resume tutorial restores the same step.
7. Skip tour, then Restart tutorial from header.
8. Complete through Done; Restart tutorial appears.

Notes

• Soft-route steps (auto-map, save-mappings, sync-process-sample) do not auto-navigate; they wait until you open a feed mapping URL.
• If Map is missing, add a feed first — the tour does not skip ahead.
• Selector lists (comma-separated) are resolved in listed order, not document order.