feat(web): opt-in page tutorials — Supa Choi Sensei docks beside the live UI #84

Merged
yuuhikaze merged 3 commits from web/tutorials into master 2026-10-25 04:50:12 -05:00
Owner

Closes #81.

What

A 💡︎ bulb in the top bar (amber, the one warm accent in the phosphor palette) appears on editor, ops, regex, grammar and machines. Pressing it docks Supa Choi Sensei (the dojo's Scene.svelte, reused) beside the live UI and walks the section: theory first, UI second, worked examples, ending every walk with a your turn exercise.

Pieces

  • Content (web/src/lib/tutorial/content/): 5 sections × 8–12 steps, en + es inline, in the sensei's voice. Regex: Kleene 1956 → reading (a|b)*abb inside-out → [SHOW ME] Thompson conversion → NFA semantics → ε as glue → why NFAs exist → equivalence-checking homework → state elimination. Editor: canvas/handles, Σ, run with trace, ε-closure in the trace, ACCEPT vs REJECT. Ops: subset construction (Rabin–Scott), 2ⁿ warning, Hopcroft/Moore, table-filling/Myhill–Nerode, complement-honesty-on-DFAs, product construction. Grammar: derivations/trees, ambiguity, CNF why+what, CYK chart reading, membership. Machines: the stack as ledger, TM tape/head, multi-tape/nondeterminism buy comfort not power, halting, and aⁿbⁿcⁿ as the final exercise.
  • Demo runner: sequential fill/click/navigate/wait; fill dispatches input so Svelte binds update; bounded polling for late-mounting targets; failure is non-fatal — sensei turns stern, explains, tutorial continues. Success → happy + "now you try it".
  • Spotlight: non-blocking clip-path hole + hairline ring around the step's target; re-measures on scroll/resize; nothing dims when a step has no highlight.
  • Dock: step dots, [ < ] [ > ], [ X ] CLOSE, [ SHOW ME ] when a demo exists; ArrowLeft/Right + Escape; snappy typewriter that respects prefers-reduced-motion.
  • Top bar: minimal edit — bulb button only, 2 new i18n keys (common.tutorial, common.tutorialOpen, en+es parity). All step copy and dock labels are inline in the tutorial module to keep merge surface with parallel i18n work near zero.

Rot guard

bun test asserts every demo/highlight selector is a well-formed data-tut hook and greps the actual .svelte sources for it — UI renames now fail tests instead of demos. Plus registry-shape validation (ids unique, en/es present, actions well-typed, sections end with the exercise) and mocked-DOM runner tests.

Verify

  • bun run check 0 errors · bun test 63 pass · bun run build ✓
  • Live walk (vite :5174 → API :8080, playwright): bulb opens dock on /regex, [SHOW ME] fills (a|b)*abb → TO NFA → result panel spotlighted, sensei happy; machines TM demo runs 0011 and spotlights the tape; Escape closes; Arrow keys navigate.

🤖 Generated with Claude Code

Closes #81. ## What A `💡︎` bulb in the top bar (amber, the one warm accent in the phosphor palette) appears on **editor, ops, regex, grammar and machines**. Pressing it docks Supa Choi Sensei (the dojo's `Scene.svelte`, reused) beside the live UI and walks the section: **theory first, UI second, worked examples**, ending every walk with a *your turn* exercise. ## Pieces - **Content** (`web/src/lib/tutorial/content/`): 5 sections × 8–12 steps, en + es inline, in the sensei's voice. Regex: Kleene 1956 → reading `(a|b)*abb` inside-out → [SHOW ME] Thompson conversion → NFA semantics → ε as glue → why NFAs exist → equivalence-checking homework → state elimination. Editor: canvas/handles, Σ, run with trace, ε-closure in the trace, ACCEPT vs REJECT. Ops: subset construction (Rabin–Scott), 2ⁿ warning, Hopcroft/Moore, table-filling/Myhill–Nerode, complement-honesty-on-DFAs, product construction. Grammar: derivations/trees, ambiguity, CNF why+what, CYK chart reading, membership. Machines: the stack as ledger, TM tape/head, multi-tape/nondeterminism buy comfort not power, halting, and aⁿbⁿcⁿ as the final exercise. - **Demo runner**: sequential `fill/click/navigate/wait`; `fill` dispatches `input` so Svelte binds update; bounded polling for late-mounting targets; failure is non-fatal — sensei turns `stern`, explains, tutorial continues. Success → `happy` + "now you try it". - **Spotlight**: non-blocking clip-path hole + hairline ring around the step's target; re-measures on scroll/resize; nothing dims when a step has no `highlight`. - **Dock**: step dots, `[ < ] [ > ]`, `[ X ] CLOSE`, `[ SHOW ME ]` when a demo exists; ArrowLeft/Right + Escape; snappy typewriter that respects `prefers-reduced-motion`. - **Top bar**: minimal edit — bulb button only, 2 new i18n keys (`common.tutorial`, `common.tutorialOpen`, en+es parity). All step copy and dock labels are inline in the tutorial module to keep merge surface with parallel i18n work near zero. ## Rot guard `bun test` asserts every demo/highlight selector is a well-formed `data-tut` hook **and** greps the actual `.svelte` sources for it — UI renames now fail tests instead of demos. Plus registry-shape validation (ids unique, en/es present, actions well-typed, sections end with the exercise) and mocked-DOM runner tests. ## Verify - `bun run check` 0 errors · `bun test` 63 pass · `bun run build` ✓ - Live walk (vite :5174 → API :8080, playwright): bulb opens dock on /regex, `[SHOW ME]` fills `(a|b)*abb` → TO NFA → result panel spotlighted, sensei happy; machines TM demo runs 0011 and spotlights the tape; Escape closes; Arrow keys navigate. 🤖 Generated with [Claude Code](https://claude.com/claude-code)
Forgejo #81. A bulb in reach of every section docks Supa Choi Sensei
beside the live UI: theory first, UI second, worked examples, and a
"your turn" exercise at the end of each walk.

- lib/tutorial: types (Step, DemoAction), registry (5 sections, 8-12
  steps each), demo runner over a mockable host, browser host (fill
  dispatches input events so Svelte binds update; fill/click poll so
  late-mounting targets are found), reactive state
- Dock.svelte reuses the dojo's Scene.svelte: typewriter bubble
  (reduced-motion aware), step dots, [<] [>], [ X ] CLOSE, [ SHOW ME ]
  when the step carries a demo; ArrowLeft/Right and Escape keys
- Spotlight.svelte dims everything but the step's target (non-blocking
  clip-path hole + hairline ring; re-measures on scroll/resize/pulse)
- inline en/es content for editor, ops, regex, grammar, machines;
  all step copy lives here, not in the i18n dictionaries
- data-tut hooks on the pages/panels the demos and spotlights target

Co-Authored-By: GLM (OpenCode) <dev@yhkze.net>
[ 💡︎ ] (text-presentation glyph) beside the language/music controls,
amber (--bulb #fbbf24) — the single warm accent in the phosphor
palette. Visible only on pages with a tutorial entry; title and
aria-label come from two new i18n keys (en+es parity).

Co-Authored-By: GLM (OpenCode) <dev@yhkze.net>
test(web): tutorial rot-guard and demo-runner tests
All checks were successful
ci / web (pull_request) Successful in 4m20s
ci / rust (pull_request) Successful in 11m43s
ci / image (oven/bun:1.4.2-debian=docker-image://git.yhkze.net/actions/bun:1.4.2-debian node:22-bookworm-slim=docker-image://git.yhkze.net/actions/node:22-bookworm-slim , web, web.Dockerfile, rgxr-web) (pull_request) Has been skipped
ci / image (rust:1-slim-bookworm=docker-image://git.yhkze.net/actions/rust:1-slim-bookworm debian:bookworm-slim=docker-image://git.yhkze.net/actions/debian:bookworm-slim , ., api.Dockerfile, rgxr-api) (pull_request) Has been skipped
97bc85414f
- every highlight/fill/click selector must be a well-formed data-tut
  hook AND appear in some .svelte source file, so future UI renames
  fail CI instead of a silent broken demo
- registry shape: 8-12 steps per section, ids unique, en/es present,
  demo actions well-typed (absolute paths, bounded waits), demos
  always carry a highlight, sections end with the "your turn" step
- demo runner: sequential order, non-fatal failure reporting
  (action index + error), empty demo

Co-Authored-By: GLM (OpenCode) <dev@yhkze.net>
yuuhikaze merged commit 23547d9e98 into master 2026-10-25 04:50:12 -05:00
Sign in to join this conversation.
No reviewers
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!84
No description provided.