claude@clouddev1
a0dd202f67
Projects cast review fixes: - Pace the confirms: `save as` name and `new` now type, pause, then Enter as separate steps, so the viewer can read them before they execute. - Insert `show tables` at each phase (before save / after `new` / after load), since the schema sidebar is hidden at 90 cols (ADR-0046) — the sequence now reads "books -> no tables -> books" so the round-trip is followable. STYLE.md: new "Cast pacing & clarity" guidelines (beat-before-submit; surface state where the sidebar would). Handoff item 2: chase these up across the existing casts.
206 lines
12 KiB
Markdown
206 lines
12 KiB
Markdown
# 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/` (`<date>-adr-website-<NNN>.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/<name>.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 `<Demo
|
|
src="/casts/NAME.cast" … />` 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".
|
|
- **Chase up two pacing/clarity guidelines across the existing casts** (added
|
|
to STYLE.md "Cast pacing & clarity" 2026-06-11; the projects cast already
|
|
follows them):
|
|
1. **Don't submit a command too fast** — a typed-and-`Enter`ed-in-one-instant
|
|
command vanishes before the viewer reads it. Re-review each cast for
|
|
type-then-instant-Enter (especially modal confirms / short commands) and
|
|
add a pause before `Enter` (split `type` and `key:'Enter'` steps).
|
|
2. **Show state where the sidebar would** — at 90 cols the schema sidebar is
|
|
hidden (ADR-0046), so insert `show tables` / `show table` / `show data`
|
|
where state changes, so the viewer can follow what happened.
|
|
- **Review whether caption banners would improve the existing casts.** The
|
|
demo overlay can show a neutral step **caption** (the stealth `Ctrl+]`
|
|
banner) to label or narrate a moment — e.g. marking the phases of the
|
|
build-the-library/projects casts, or calling out the relationship diagram /
|
|
the teaching echo in the modes cast. Go cast-by-cast and decide where a
|
|
caption adds clarity vs. adds noise. Constraint: caption **text must not name
|
|
keys** (no `j/k`, no `Ctrl+]`); it narrates *what* is happening, not *how* it
|
|
was typed. (Captions are wired but not yet used in any cast.)
|
|
- 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 <host>`.
|
|
**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.
|