Vision and requirements
Product: Scriptorium
Last updated: 2026-10-15
Vision
Scriptorium is a public learning room for SQL. A visitor moves from a single-column SELECT to joins, grouping, windows, and a recursive walk of who cited whom, then tries their own statements against a library that is already filled in.
The room is free to open. The records live in the browser. Nothing the visitor types is sent to a server, and nothing is kept after a refresh.
The curriculum speaks SQL, and it names the MySQL form wherever this engine differs. Stored procedures and user variables are on the page to be read. They do not run here, because the engine in the page is SQLite compiled to WebAssembly. A shared MySQL server cannot stay at zero cost once anyone can type arbitrary SQL.
Users
- Visitor — reads a lesson, runs it, then changes the SQL and runs it again.
- Builder — ships the static site and keeps the lessons, the seed, and these documents together.
Principles
- Zero cost — static export, no account, no paid API, no database host. sql.js is MIT.
- A real result — runnable lessons execute against the seed. A reading lesson says so before the visitor hits Run.
- The same records — refresh and Reset restore the seed, so a lesson always starts from the manuscripts on the table.
- One visual system — AetherForge chrome: paper
#F6EAD8, ink#152028, petrol#0F4C5C, Source Serif 4, Source Sans 3, IBM Plex Mono for SQL, frosted panels. The mark is an open folio. The backdrop is scholars at a table of manuscripts and papers. - Living documents — the vision page and the architecture page render these files. A change to the app updates the files in the same work.
In scope
- Lessons grouped from reading a table through recursive common table expressions, including moving frames, EXCLUDE, and pivot and unpivot, plus a plan, the two MySQL-only forms, and Oracle illustrations of MATCH_RECOGNIZE, PIVOT, and UNPIVOT.
- A playground with the table list, an editor, Run, Reset, and a result grid. The table list scrolls inside its panel. NULL is shown as NULL. MATCH_RECOGNIZE, PIVOT, and UNPIVOT stay locked, because MySQL does not support them, and a walkthrough explains the Oracle rows.
- Try it opens
/playwith that lesson's SQL. Read it does the same for a lesson that cannot run. /visionrenders this document./architecturedraws the conceptual, logical, and physical views, then renders the architecture document./releasesrendersCHANGELOG.md. The header version chip links there.- Sample tables:
scholars,works,libraries,holdings,readings,annotations, andcitations. - Source repository: https://github.com/jmaret/scriptorium.
Out of scope
- A MySQL server, accounts, saved queries, or a shared database.
- An AetherForge catalog entry, until that is asked for.
- Stored procedures and session user variables. They are shown, and they are not executed. MATCH_RECOGNIZE, PIVOT, and UNPIVOT are not executed either: the statement cannot be edited, and Run shows an Oracle illustration with a walkthrough. MySQL does not implement those operators.
Requirements
| ID | Requirement | Status |
|---|---|---|
| V-1 | Lessons run from choosing columns through a recursive citation walk, with moving frames, EXCLUDE, pivot, and unpivot | Met |
| V-2 | The playground runs visitor SQL on the seeded tables and shows a grid or an error | Met |
| V-3 | Refresh and Reset restore the seed. Writes last only in that tab | Met |
| V-4 | MySQL notes name dialect differences. Procedures and user variables are reading lessons. MATCH_RECOGNIZE, PIVOT, and UNPIVOT stay locked and show an Oracle illustration with a walkthrough | Met |
| V-5 | /vision renders this document | Met |
| V-6 | /architecture shows conceptual, logical, and physical diagrams, then the architecture document | Met |
| V-7 | /releases renders the changelog. The header chip links to it and shows the package version | Met |
| V-8 | The chrome matches AetherForge, with the folio mark and the scholar-and-manuscript backdrop | Met |
| V-9 | The site is a static export with no auth and no paid dependency | Met |
| V-10 | A code change updates this document, the architecture document, and CHANGELOG.md together | Met |
Acceptance
A visitor can open a lesson, run it, change the SQL, reset the records, read the vision and the three architecture drawings, and open the release notes from the version chip. The page does not ask for a sign-in, and a query does not leave the browser.
Changelog
- 2026-10-15 — The typefaces ship with the site, so a production build does not download them.
- 2026-10-15 — A failed open can be retried. Operator names inside a comment or a quote run as ordinary SQL.
- 2026-10-15 — The source repository is https://github.com/jmaret/scriptorium.
- 2026-10-15 — MATCH_RECOGNIZE, PIVOT, and UNPIVOT cannot be edited. A walkthrough explains the Oracle rows.
- 2026-10-15 — MATCH_RECOGNIZE, PIVOT, and UNPIVOT show an Oracle illustration when Run is pressed.
- 2026-10-15 — Pivot and unpivot run with CASE and UNION ALL. The PIVOT and UNPIVOT operators are shown and not executed.
- 2026-10-15 — Moving totals and averages, EXCLUDE frames, and a reading lesson for MATCH_RECOGNIZE.
- 2026-10-15 — First room: lessons, playground, vision, architecture drawings, and release notes.