diff --git a/docs/handoff/20260611-website-handoff-2.md b/docs/handoff/20260611-website-handoff-2.md new file mode 100644 index 0000000..31554b7 --- /dev/null +++ b/docs/handoff/20260611-website-handoff-2.md @@ -0,0 +1,189 @@ +# Website-branch handoff — 2026-06-11 (website-2) + +Second handoff for the **website** work (separate sequence from `main`'s +`YYYYMMDD-handoff-NN.md`). Read `website-1` (2026-06-10) first for the +original scaffolding context; this note covers everything since. + +## State + +- **Branch:** `website`. **HEAD `e782a28`.** Working tree clean. Pushed + through an earlier point; currently **ahead of `origin/website`** (push is + the user's step — never push). +- The website lives in **`website/`** (monorepo; the playground crate is at + the repo root). Living style guide + binding conventions: + **`website/STYLE.md`** (read first). Website decisions: + **`docs/website/adr/20260604-adr-website-001.md`** (the website ADR namespace + — see below). Plan: `docs/website/plans/20260604-website-implementation-plan.md`. + +## What changed since website-1 (commit highlights, newest first) + +``` +e782a28 feat(website): projects cast (vi-nav load picker) + --demo on all casts +927e6b2 Merge branch 'main' (m:n, logging, UI nav, demo overlays, vi-nav) +52860c3 feat(website): casts for first-project/modes/undo-redo; quit via Ctrl-C +ce153bd docs(website): add SQL queries reference page (advanced query surface) +302329d docs(website): record the cast-placement policy in STYLE.md +bb7887e feat(website): relationship-diagram cast on the relationships page +65a48fa feat(website): joins cast on the querying-with-joins guide +c0cc92a docs(website): rewrite Build the library + add Querying with joins guide +10655e4 docs(website): fill the six Reference stubs with worked examples + output +a8f84c9 feat(website): refine casts — trim shell, autoplay+loop landing, cap size +… (cast pipeline, the astro/starlight upgrade, the ADR-namespace move) +``` + +## ADR namespace (important — avoids the recurring collision) + +Website decision records live in their **own namespace**: +`docs/website/adr/` (`-adr-website-.md`, id `ADR-website-NNN`), +indexed by `docs/website/adr/README.md`. They do **not** draw from `main`'s +global ADR integer pool, so a `main` ADR and a website ADR can never collide +again (this is why the latest merge of `main`'s ADR-0045/0046/0047 was +conflict-free). Recorded in ADR-0000 "Numbering discipline". The main +`docs/adr/README.md` intro carries a pointer to the website namespace. + +## Content status + +**Done & verified (build clean, grounded in source, forbidden-terms clean):** +- **Getting started** — installation, first-project, modes, example-library. +- **Using the playground** — command-line-options, the-assistive-editor, + the-output-pane, projects, undo-and-history, export-and-import, + copy-to-clipboard, getting-help. +- **Guides** — build-the-library (full 4-table build, 1:n + m:n bridge), + querying-with-joins. +- **Reference** — types, tables, columns, relationships, indexes, constraints, + inserting-and-editing-data, querying-and-inspecting, **sql-queries** (the + advanced SELECT surface: DISTINCT, GROUP BY/HAVING, set ops, subqueries, + CTEs, CASE/CAST/functions, with a "supported subset" boundary note). +- **Concepts** — projects-and-storage. +- Landing `index.mdx` splash with the quickstart cast. + +**26 pages build clean.** Only expected warning: sitemap needs `site` (Phase B). + +## asciinema casts — the pipeline + the 7 casts + +Pipeline (STYLE.md "asciinema casts", ADR-website-001 §2): +- **Driver: `autocast`** (chosen by spike; `asciinema-automation` can't drive a + full-screen TUI). Sources in `website/casts-src/casts.mjs`; `pnpm casts` + runs `casts-src/generate.mjs` → autocast YAML → `public/casts/.cast`. + Command-lists are the durable source; **`.cast` files are regenerable** — + re-run `pnpm casts` (needs a `cargo build` binary at `../target/debug`). +- **Components:** `Cast.astro` (asciinema-player island) wrapped by + `Demo.astro` (the WASM-swap seam, ADR-website-001 §3). Embed via `` in an **.mdx** page (md can't import). +- **Generator features:** trims each cast to the in-app region (drops shell + launch + the return-to-shell); ends casts with **Ctrl-C** (`{ key: 'CtrlC' }`) + not a typed `quit` (invisible, so the cast ends on the last content frame); + per-cast `holdEnd`, `dataDir` (isolated data root, wiped per run), and + **`--demo` is default-on** (opt out with `demo:false`). +- **The 7 casts:** quickstart (landing, autoplay+loop), assistive-editor, + relationship-diagram, joins, modes, undo-redo, **projects** (the new one: + save as → new → load via the picker, navigated with `j`). + +### `--demo` (#22 / ADR-0047) is on for ALL casts +The demonstration overlay shows a **badge** for special keystrokes +(`[ENTER]`, `[TAB]`, arrows, etc.) — plain characters are NOT badged. This +makes e.g. the assistive-editor's Tab completion visible (`[TAB]`), and the +projects cast's `j`/`k` picker navigation stays *un*surfaced (plain chars) by +design. Captions exist too (a stealth `Ctrl+]`-delimited banner) — usable in +casts for neutral "point something out" labels, not yet used. + +### ⚠️ Cast tooling limits (don't rediscover these) +- autocast can only send **single characters, ASCII control codes (`^X`), and + waits** — **NO arrows / PageUp/PageDown / Home/End / function keys** (those + are escape sequences; the per-key delay makes the terminal read a lone Esc — + verified). So any interaction we want to demo must be reachable via typeable + keys. This is why #24 (vi `j/k` in the picker) was needed for the projects + cast, and why **output-pane scrolling has no cast** (needs PgUp/PgDn). +- `Ctrl+]` (caption toggle) and `Ctrl-C` (quit) ARE sendable (`^]`, `^C`). + +### ⚠️ No-advertising constraint (user, 2026-06-11) +The docs must **NOT** advertise that the load picker supports **vi keys**, nor +that **`Ctrl+]`** is the caption/banner trigger. The `--demo` flag itself MAY +be documented lightly as "a teaching helper that shows special keystrokes" — +and nothing more. Casts may *use* vi-nav and captions (the viewer sees only the +result/banner, not the keystroke), but cast captions must not name `j/k` or +`Ctrl+]`. + +## NEXT WORK — priority order + +### 1. Document the features the `main` merge brought (the biggest gap) +The merge (`927e6b2`) added app features that are **not yet documented**: + +- **m:n convenience command** — `create m:n relationship …` (C4, **ADR-0045**). + The relationships page currently models m:n only via the manual loans-bridge. + Document the convenience command (it auto-generates the junction table). + Ground in ADR-0045 + `tests/it/m2n.rs` + `tests/typing_surface/create_m2n.rs` + for exact syntax. Likely a new section on the **relationships** reference + page and/or a mention in the build-the-library guide. +- **`--demo` flag** — document on **command-line-options** as a teaching helper + that "shows special keystrokes" (per the no-advertising constraint above — + do NOT mention badges-for-vi or captions/`Ctrl+]`). +- **ADR-0046 UI** — the **schema sidebar** (auto-shows on wide terminals, + `Ctrl-O` navigation mode to peek/expand), **responsive two-row input** + + horizontal scroll, and the geometry-fixed hint panel. Decide where in *Using + the playground* (a new "the schema sidebar" page, or fold into the-output-pane + / the-assistive-editor). Ground in ADR-0046. +- FK-message fixes + the X1 logging sweep: **no user-doc impact** (note only). + +Whenever output changed because of the merge, **re-verify any affected static +output blocks** (capture-harness recipe below). + +### 2. Consider a final cast re-record sweep + optional captions +- All casts re-record with `pnpm casts` once the app is "final". +- Optional: add neutral step **captions** (via the demo overlay) to specific + casts to label moments — text must not name keys (constraint above). +- Output-pane scrolling cast remains blocked (PgUp/PgDn unsendable). If desired + later, it needs an app-side typeable scroll key (file an enhancement like #24) + — otherwise leave it to static docs. + +### 3. Phase B — landing/site polish +- Set Starlight **`site`** (production URL) → clears the sitemap warning, + enables sitemap + canonical/OG. Then SEO/meta conventions (STYLE #8). +- Logo + favicon; branding palette (staying on Starlight). +- **Light/dark player theme**: the asciinema player theme is currently fixed + (`asciinema`); sync it to the Starlight theme toggle (folded into STYLE #8). +- Use the `frontend-design` skill. + +### 4. Open STYLE.md decisions +- **#7 Versioning** (leaning single-version for launch). +- **#8 SEO/meta** + the player light/dark theme. + +## Capture-harness recipe (how to get accurate static output for new pages) + +Output blocks must be **captured from the real app, never hand-drawn** +(STYLE.md). Pattern used throughout: +- For `pub` render fns (`render_data_table`, `render_explain_plan`) + the DB + worker API: a throwaway **external** test `tests/doc_capture.rs` that builds + the library schema via `Database` and prints rendered output; run + `cargo test --test doc_capture -- --nocapture --ignored`; paste verbatim + (trim trailing spaces); delete the file. +- For `pub(crate)` fns (`render_structure_with_diagrams`, + `render_relationship_diagram`): an in-crate `#[ignore]` test in + `src/output_render.rs`'s test module instead. +- **Verify box-drawing integrity** after pasting (top `┬` count == bottom `┴`, + equal line lengths) — a mis-paste truncated a CTE border once and the check + caught it. + +## Verify-after-changes checklist +```sh +cd website && pnpm build # clean; 26 pages; only the `site` warning +# from repo root — forbidden terms must be empty: +grep -rniE '\b(DSL|SQLite|STRICT|rusqlite|PRAGMA)\b' website/src/content/ +# internal links + heading anchors: spot-check in dist/ (no link validator installed) +cd website && pnpm casts # regenerate all casts (needs target/debug binary) +``` +Dev server + tunnel for visual checks (player playback, sizing, badges): +`cd website && pnpm dev` (binds 127.0.0.1:4321) then `ssh -L 4321:127.0.0.1:4321 `. +**Visual playback of all 7 casts (now with `--demo` badges) is still pending a +tunnel check by the user.** + +## Process pins +- **Commits:** user-confirmed (show the message first), **no AI attribution**, + **append-only** (no amend/rebase/force-push). Push is the user's step. +- **Ground every page in source** (`src/dsl/*`, `en-US.yaml`, the ADRs) — not + `requirements.md` markers. No engine name, no "DSL" in user-facing copy. +- **Issues** via `tea` (repo `oli/rdbms-playground` on `git.lazyeval.net`; + append `< /dev/null` + `timeout 30`). Open/related: **#22** (demo overlay, + implemented), **#24** (vi picker nav, implemented). Both merged via `927e6b2`. +- Escalate genuine forks; declare epistemic status; write down the `/runda` DA + pass on non-trivial plans.