Initial commit of Descrybe v2 without local scratch artifacts.

Drop one-shot tmp/axe scripts and agent i18n scratch so the Gitea tree is deployable.
2026-08-09 22:47:43 +02:00
commit 8580c996c3
1285 changed files with 325780 additions and 0 deletions
@@ -0,0 +1,70 @@
+# 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.