rdbms-playground/docs/plans/20260604-adr-0042-website.md

Plan: public website and documentation site

Date: 2026-06-04 · Status: ready to build

Decisions for this work are recorded in ADR-0042: Astro 5 + Starlight + Tailwind v4; asciinema demos reusable in docs; the in-page WASM playground deferred behind a stable demo seam; portable static hosting (Vercel target); monorepo (website/); website is the canonical docs home; full-feature-set docs with "planned" callouts; install docs cover prebuilt binaries + package managers. This plan is the how.

Repository layout

The site lives under website/ in this repo; the crate stays at the root.

website/
├── package.json              # pnpm; astro, @astrojs/starlight, tailwind v4
├── astro.config.mjs          # Starlight integration + sidebar nav
├── src/
│   ├── pages/index.astro     # marketing landing (custom, not Starlight)
│   ├── components/
│   │   ├── Demo.astro        # demo SLOT — the WASM-playground seam
│   │   └── Cast.astro        # asciinema-player island wrapper
│   ├── content/docs/         # Starlight MDX docs (the bulk of the work)
│   └── styles/               # shared Tailwind + Starlight theme tokens
├── public/casts/             # recorded *.cast asciinema files
├── README.md                 # local dev + recording recipe
└── STYLE.md                   # living documentation style guide

Root .gitignore gains website/node_modules, website/dist, website/.astro.

Documentation inventory (grounded — drives Phase D scope)

Built from docs/handoff/55–57, docs/adr/*, the command REGISTRY (src/dsl/grammar/mod.rs:603, which also auto-assembles in-app help), the Command enum (src/dsl/command.rs:149), and src/friendly/strings/en-US.yaml — not the coarse requirements.md checkboxes. Test state at survey time: 2151 passing, 0 failing, 1 ignored.

SHIPPED — document as-is (the doc core):

• Input modes: simple, advanced (SQL), : one-shot escape, mode command, per-project mode restore (ADR-0003/0015/0037).
• Full simple-mode command surface: create/drop table; add/drop/rename/ change column; add/drop 1:n relationship (named, ON DELETE/UPDATE CASCADE/SET NULL/RESTRICT, --create-fk); add/drop index; insert/update/ delete (required WHERE + --all-rows; complex WHERE: AND/OR/NOT, LIKE, IS NULL, IN, BETWEEN); show table/data (where/limit); add/drop constraint; explain (ADR-0009/0013/0014/0025/0026/0028/0029).
• Full advanced-mode SQL: CREATE/DROP/ALTER TABLE (cols, constraints, inline
  • table FKs, rename, alter-column-type), CREATE [UNIQUE]/DROP INDEX; SELECT (joins, GROUP BY/HAVING, ORDER BY, LIMIT/OFFSET, UNION/INTERSECT/EXCEPT, WITH [RECURSIVE] CTEs); INSERT (multi-row, ON CONFLICT, RETURNING)/UPDATE/ DELETE; full expression grammar incl. CASE, CAST, curated functions; EXPLAIN over SQL (ADR-0030–0039).
• Types: all ten, advanced-mode SQL aliases, serial/shortid auto-fill (ADR-0005/0011/0017/0018). Constraints: PK incl. compound, NOT NULL, UNIQUE, CHECK, DEFAULT, FK (ADR-0029/0013/0035).
• Undo/redo, history.log journal, replay, --resume, --no-undo (ADR-0006/0034). Projects & storage: project.yaml + CSV + history.log, save/save as/load/new/rebuild, temp projects, --data-dir (ADR-0004/0015). Export/import (zip), clipboard copy/copy all/copy last (ADR-0007/0041).
• Friendly errors (all five categories) + validity indicator (ADR-0019/0027), DSL→SQL teaching echo (ADR-0038), EXPLAIN plan tree (ADR-0028), box-drawing tables (ADR-0016), tab completion + syntax highlighting + in-line editing (ADR-0022).

DOCUMENT WITH CAVEAT: add unique index is advanced-only; simple-mode table rename is intentionally absent (rename is ALTER TABLE … RENAME TO); FK references target single-column PKs only (compound-PK FK refs pending); help <command> detail and richer hint (H2/H3) still partial.

OMIT or MARK "planned": multi-line input (I1), readline shortcuts (I1b), in-flight cancellation / query timeout (I5/B3), seed (SD1), m:n (C4), one-step modify relationship (C3a), show tables/relationships/indexes (V5), ER-diagram view/export (V1/V3), session-log + Markdown export (V4).

Mine verbatim for docs: en-US.yaml help.app.*, help.ddl.*, help.data.*, help.types_reference, parse.usage.* (one-line syntax templates), hint.* — keeps docs and in-app help consistent.

Phases

A — Scaffold

pnpm create astro@latest (Starlight template) in website/; astro add tailwind (Tailwind v4 via @tailwindcss/vite); add @astrojs/starlight-tailwind. Confirm pnpm dev serves and pnpm build emits a static dist/. Echo build steps for traceability.

B — Landing page

Custom src/pages/index.astro (Starlight owns /docs/*). Hero + value prop ("learn relational databases by doing"), feature highlights from the inventory, an embedded demo cast above the fold. Use the frontend-design skill to avoid generic AI aesthetics; honour NFR-4/5/7 (distinctive design, meaningful colour, light/dark).

C — asciinema recording workflow

Record real rdbms-playground sessions to public/casts/*.cast using a scripted-input driver (e.g. asciinema-automation/autocast, or an expect/doitlive script) for paced, re-recordable demos. Record at a fixed sensible cols×rows; provide light + dark player themes. Cast.astro wraps asciinema-player as a client:visible island; the same component embeds casts inline in docs. Document the recipe in website/README.md. (asciinema 2.4.0 is installed.)

D — Documentation (the bulk)

Starlight sidebar, scoped from the inventory; built in priority order:

• Getting started — install (prebuilt binaries + package managers), first project, simple vs. advanced mode.
• Concepts — projects & storage; undo, history & replay.
• Simple-mode command reference — full surface; syntax conventions; simple-command → SQL teaching echo.
• Advanced (SQL) mode — full SQL DDL/DML/SELECT surface.
• Types, Relationships, Constraints, Indexes, Query plans / EXPLAIN.
• Working with the editor — completion, highlighting, validity indicator, in-line editing.
• Errors explained — the friendly error layer.
• Export / import & sharing (E2 recipes), clipboard.

Build order: Tier 1 simple-mode reference + types + constraints + input modes + mined help/usage strings → Tier 2 advanced SQL + relationships + project lifecycle + undo/history → Tier 3 teaching echo + EXPLAIN + errors + completion/highlighting → Tier 4 clipboard + hints + editing.

Conventions live in the living style guide website/STYLE.md (binding rules from ADR-0042 §7 — no engine name, no "DSL", "planned" callouts — plus finer conventions and an open-decisions log for depth/splitting/example dataset/etc. as they settle). Sources to mine: src/dsl/command.rs, src/dsl/grammar/*, the REGISTRY, en-US.yaml, docs/adr/*, docs/simple-mode-limitations.md.

E — Hosting & portability

Keep the default static build (no adapter); dist/ deploys to Vercel or any static host. website/README.md notes the Vercel preset (root dir website/) and the one-line @astrojs/vercel switch if SSR is ever needed.

Demo seam (WASM hook)

Demo.astro exposes a stable contract ({ src, title, height, autoplay }). At launch it renders Cast.astro; later a Playground.astro WASM island swaps in behind the same props on the landing page and in docs, with zero call-site changes. Boundary details are in ADR-0042 §3.

Verification

• pnpm dev renders landing + docs; pnpm build emits a clean static dist/ with no errors/warnings.
• Landing shows at least one playing .cast; the same component renders a cast inline in a docs page (proves reuse).
• Starlight link-check passes (broken internal links fail the build).
• Docs grep clean of forbidden terms: no "DSL", no engine name.
• A dist/ static deploy works on Vercel (manual import) — confirms portability. (No CI gate yet, per ADR-0042 §4.)

Notes / recommendations (non-blocking)

• Doc drift: consider generating the command reference from source (the help REGISTRY / en-US.yaml) rather than hand-writing all of it.
• Accessibility/SEO: pair each hero .cast with a text transcript or the equivalent docs snippet.
• Branding/domain & analytics unspecified — assume none until decided; no third-party trackers without consent.
• Tailwind v4 + Starlight have occasional theme-token friction; the @astrojs/starlight-tailwind plugin is the supported bridge.
• Starlight ships local search (Pagefind) by default.
• No README.md exists at the repo root yet — wanted for the destination repo; out of this plan's core scope but flagged.