feat(website): asciinema cast pipeline + landing quickstart demo

Settle the cast toolchain (STYLE.md #9) and build the demo pipeline end to
end. Driver: autocast, chosen by spike — its !Interactive feeds keys to the
running TUI and captures the redraw, the right model for a full-screen
crossterm app. asciinema-automation was rejected (assumes shell echo/\n Enter;
produced a garbled cast against the TUI).

- add asciinema-player; Cast.astro (player island) + Demo.astro (the WASM-swap
  seam, ADR-website-001 §3)
- casts-src/: human-readable command-lists (casts.mjs) + generate.mjs, exposed
  as `pnpm casts`; expands steps to autocast YAML and records to public/casts/.
  Command-lists are the durable source; .cast files are regenerable (final
  re-record sweep due once the app is locked).
- quickstart.cast (create -> add columns -> insert -> show data) embedded on
  the landing page above the feature cards.

Verified: pnpm build clean (25 pages); player + cast bundled and served;
landing HTML references the cast. Visual playback check pending (no headless
browser here — verify via dev server over the tunnel).
This commit is contained in:
claude@clouddev1
2026-06-10 12:59:50 +00:00
parent c0cc92a741
commit fbf449f9e0
9 changed files with 658 additions and 8 deletions
+29 -8
View File
@@ -131,15 +131,31 @@ Relationships: `books.author_id → authors.author_id` (1:n); `loans` joins
`books` and `members` (the m:n bridge). Show `shortid` on the Types page via
a small standalone example, not by complicating this schema.
## asciinema casts [DECIDED, details OPEN]
## asciinema casts [DECIDED]
- Casts show *flow/motion*; static code blocks show *exact input/output*.
Prefer a code block when a still example suffices.
- Pair a hero/landing cast with a text transcript or the equivalent docs
snippet (accessibility + SEO).
- Recorded via a scripted-input driver for paced, re-recordable sessions
(ADR-website-001 §2; recipe in `README.md`). **[OPEN]**: cast file naming,
fixed terminal size, light/dark theme handling.
- **Driver: `autocast`** (ADR-website-001 §2; chosen by the 2026-06-10
spike). `autocast`'s `!Interactive` feeds keys to the running TUI and
captures the redraw — the correct model for a full-screen crossterm app.
`asciinema-automation` was rejected: it assumes *shell* semantics (Enter as
`\n`, and an `expect()` echo-check per keystroke), which a redrawing TUI
breaks — it produced a garbled cast.
- **Authoring workflow.** Source command-lists live in `casts-src/casts.mjs`
(human-readable steps: `type` / `wait` / `key`). `pnpm casts` runs
`casts-src/generate.mjs`, which expands them to autocast YAML (one key per
character; Enter = `^M`) and records to `public/casts/<name>.cast`. The
command-lists are the durable source; **`.cast` files are regenerable** —
re-run `pnpm casts` to re-record as the app evolves (a final sweep is due
once the app is locked). Needs a `cargo build` binary at `../target/debug`.
- **Embedding.** `Demo.astro` (the WASM-swap seam, ADR-website-001 §3) wraps
`Cast.astro` (asciinema-player island). Call sites use `Demo`.
- **Conventions.** Terminal geometry per cast (default 90×26); file name =
cast `name`; player theme `asciinema` for now. **[OPEN]**: light/dark player
theme sync with the Starlight theme toggle (player theme is currently fixed;
refine in Phase B).
## Formatting [DECIDED, refine]
@@ -156,6 +172,13 @@ a small standalone example, not by complicating this schema.
Decide these as we write; record the outcome (and escalate to an ADR if
significant).
**Resolved (2026-06-10):**
9. ~~Cast scripting toolchain~~**`autocast`**, proven by spike over
`asciinema-automation` (which can't drive a full-screen TUI). Source
command-lists in `casts-src/`, `pnpm casts` to record. See the *asciinema
casts* section above. (Remaining sub-item: light/dark player theme sync —
folded into #8 / Phase B.)
**Resolved (2026-06-05):**
1. ~~Depth / organising spine~~**Pragmatic** four-section split (see
Structure above).
@@ -172,7 +195,5 @@ significant).
7. **Versioning.** Version selectors at/after v1, or single-version for
launch? (Leaning single-version for launch.)
8. **SEO/meta conventions.** Title/description patterns, Open Graph — settle
with Phase B (landing) and the `site` URL.
9. **Cast scripting toolchain.** Confirm the scripted-input driver
(`asciinema-automation`/autocast vs alternative) via a test run; define
the `.cast` script format + storage location. (Execution task, in flight.)
with Phase B (landing) and the `site` URL. Also: light/dark player-theme
sync for embedded casts.