web: per-section tutorials — the sensei walks you through (v1: deterministic) #81

Closed
opened 2026-10-25 04:26:17 -05:00 by yuuhikaze · 0 comments
Owner

Per-page opt-in tutorials so people who never took theory of computation can learn the material and the tool. A unicode lightbulb in the top bar (accent color, e.g. amber token, standing off the green phosphor) opens a docked Supa Choi sensei who walks through that section: theory first, UI second, worked examples throughout.

UX decisions (owner-confirmed)

  • Opt-in per click — no first-run tour, no seen/resume flags, zero persistence
  • Sensei docked bottom-right, reusing Scene.svelte (moods, talking animation, speech bubble) — real UI stays live underneath
  • Spotlight steps: each step may target a selector; the rest dims (non-blocking), the target glows
  • [ SHOW ME ] in v1: steps may carry demo actions (fill inputs, press buttons, navigate) the app performs in front of the user, then invites them to try
  • Keyboard: ←/→ steps, ESC closes; step dots + prev/next in the bubble
  • Bulb hidden on pages without a tutorial; dojo skips it (the sensei already lives there)

Scope v1

Sections: regex, editor, ops, grammar, machines. ~8–12 curated steps each, {en, es} content inline (follow the dojo lines.ts precedent, not the global i18n dict).

Implementation sketch

  • web/src/lib/tutorial/: types.ts (Step { id, title, body, highlight?, demo? }, DemoAction = fill | click | navigate | wait), registry.ts, one file per section
  • Tutorial dock component (sensei via Scene.svelte + bubble + controls), spotlight overlay via getBoundingClientRect + box-shadow, recomputed on resize
  • Demo runner executes a step's actions sequentially with sane waits; failures are non-fatal (bubble says so, sensei goes stern)
  • Top bar: 💡 (U+1F4A1 + VS15 text presentation) styled with a new amber accent token; per-page mapping in the registry
  • bun test + svelte-check green; unit tests for the demo runner and step shape validation (every highlight selector must exist on its page — guard against rot)

v2 (separate issue later)

Final step per tutorial: "ask me anything" wired to the dojo brain endpoint (LLM, optional, needs API key). Land deterministic v1 first.

Per-page opt-in tutorials so people who never took theory of computation can learn the material *and* the tool. A unicode lightbulb in the top bar (accent color, e.g. amber token, standing off the green phosphor) opens a docked Supa Choi sensei who walks through that section: theory first, UI second, worked examples throughout. ## UX decisions (owner-confirmed) - Opt-in per click — no first-run tour, no seen/resume flags, zero persistence - Sensei docked bottom-right, reusing Scene.svelte (moods, talking animation, speech bubble) — real UI stays live underneath - Spotlight steps: each step may target a selector; the rest dims (non-blocking), the target glows - [ SHOW ME ] in v1: steps may carry demo actions (fill inputs, press buttons, navigate) the app performs in front of the user, then invites them to try - Keyboard: ←/→ steps, ESC closes; step dots + prev/next in the bubble - Bulb hidden on pages without a tutorial; dojo skips it (the sensei already lives there) ## Scope v1 Sections: regex, editor, ops, grammar, machines. ~8–12 curated steps each, {en, es} content inline (follow the dojo lines.ts precedent, not the global i18n dict). ## Implementation sketch - web/src/lib/tutorial/: types.ts (Step { id, title, body, highlight?, demo? }, DemoAction = fill | click | navigate | wait), registry.ts, one file per section - Tutorial dock component (sensei via Scene.svelte + bubble + controls), spotlight overlay via getBoundingClientRect + box-shadow, recomputed on resize - Demo runner executes a step's actions sequentially with sane waits; failures are non-fatal (bubble says so, sensei goes stern) - Top bar: 💡 (U+1F4A1 + VS15 text presentation) styled with a new amber accent token; per-page mapping in the registry - bun test + svelte-check green; unit tests for the demo runner and step shape validation (every highlight selector must exist on its page — guard against rot) ## v2 (separate issue later) Final step per tutorial: "ask me anything" wired to the dojo brain endpoint (LLM, optional, needs API key). Land deterministic v1 first.
Sign in to join this conversation.
No labels
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
k8s-services/rgxr#81
No description provided.