@cs4alhaider/screenbook 0.2.0 → 0.2.1

package/README.md

@@ -1,15 +1,19 @@
-# ⧉ ScreenBook
+<p align="center">
+  <a href="https://cs4alhaider.github.io/screenbook/">
+    <img src="docs/brand/readme-header.png" alt="ScreenBook — plain-file screens built by AI agents, reviewed by humans. Offline. Versioned. Owned by you." width="100%">
+  </a>
+</p>
 
-**Your local design studio for prototyping real products with AI agents — offline, versioned, and owned by you.**
+**A design workspace for AI agents to present to humans — fully offline, agent-agnostic, and owned by you.**
 
-ScreenBook turns a folder on your machine into a professional prototyping studio: every screen
+ScreenBook turns a folder on your machine into the design workspace your AI agents work in: every screen
 of your product rendered inside real device frames — iPhone, Android, browser — with live mock
 data, dark mode, right-to-left languages, guided demo walkthroughs, and a built-in design-review
 workflow. AI agents build and revise the screens through a standard interface; you and your
 stakeholders review, comment, and approve. When a screen is final, you hand that same file to
 your agent and say: *now build the native version.*
 
-![The ScreenBook studio](docs/shots/hero-studio.png)
+![The ScreenBook studio](docs/shots/hero-studio-light.png)
 
 ```bash
 npm install -g @cs4alhaider/screenbook
@@ -68,7 +72,7 @@ from *Regular morning* to *First visit* — the same screens now show the empty
 Toggle dark mode. Switch to Arabic and watch the layout mirror right-to-left. Nothing is
 staged; the "order ready by 08:44" timestamp is computed from *today* every time you demo.
 
-![Scenario-driven data on a real dashboard frame](docs/shots/web-dashboard.png)
+![Scenario-driven data on a real dashboard frame](docs/shots/web-dashboard-light.png)
 
 **3. Your team comments on the pixels, not around them.** Turn on 📌 Review Mode and click
 anywhere: each pin captures the screen, the data state, the theme, the mode, the direction,
@@ -91,7 +95,7 @@ The prototype you approved *is* the design document — no Figma-to-code guesswo
 different in the mockup." The same works for Jetpack Compose, React Native, Flutter, or web
 components.
 
-![One click from English light to Arabic dark](docs/shots/rtl-arabic.png)
+![One toggle from LTR light to RTL dark](docs/shots/rtl-arabic-dark.png)
 
 ## Two commands to your own studio
 
@@ -134,7 +138,7 @@ screenbook serve "$(npm root -g)/@cs4alhaider/screenbook/examples/tokens-lab"  #
 - **Theme Lab** — every design token visible and editable live against your screens; save
   writes the JSON back to disk. Dark mode is a delta, not a fork.
 
-  ![Theme Lab](docs/shots/theme-lab.png)
+  ![Theme Lab](docs/shots/theme-lab-light.png)
 - **Flows** — guided, captioned walkthroughs for stakeholder demos; every step is a shareable
   URL that opens in the exact state (screen, data, theme, direction).
 - **Review Mode** — pinned comments with full context, synced to a JSON file your agent reads
@@ -143,7 +147,7 @@ screenbook serve "$(npm root -g)/@cs4alhaider/screenbook/examples/tokens-lab"  #
   right-to-left is a first-class toggle, not an afterthought.
 - **Embed existing prototypes** — already have a working single-page prototype? One command
   mounts the *whole app* inside the studio without touching its files
-  (`screenbook app add legacy/index.html`) — see [App mode](docs/app-mode-guide.md).
+  (`screenbook app add legacy/index.html`) — see [App mode](docs/guides/app-mode.md).
 - **A machine-verified quality gate** — `screenbook validate` renders every screen in every
   theme × light/dark × LTR/RTL and fails on any console error. Green means done — for humans
   and agents alike.
@@ -151,7 +155,8 @@ screenbook serve "$(npm root -g)/@cs4alhaider/screenbook/examples/tokens-lab"  #
   create screens, update data, restyle themes, take device-framed screenshots, run the gate.
 
 Full guides: **[docs/](docs/README.md)** — getting started, the studio tour, the authoring
-contract, CLI and agent references, troubleshooting.
+contract, CLI and agent references, troubleshooting — or browse them on the website:
+**[cs4alhaider.github.io/screenbook](https://cs4alhaider.github.io/screenbook/)**.
 
 ## The shape of a project
 

package/bridge.js

@@ -12,7 +12,7 @@
 (function () {
   'use strict';
 
-  var VERSION = '0.2.0';
+  var VERSION = '0.2.1';
 
   /* ------------------------------------------------------------------ *
    *  EngineKit — pure helpers shared by bridge (screens) and shell
@@ -139,7 +139,16 @@
     none:    { top: '0px',  bottom: '0px' }
   };
 
-  /* Compact, stable-ish CSS path for review pins ("#cart > button.buy:nth-of-type(2)"). */
+  /*
+   * Compact, stable-ish CSS path for review pins ("#cart > button.buy:nth-of-type(2)").
+   * Walks from the clicked element up towards <html>, one selector segment per hop:
+   *   1. An id ends the walk immediately — "#cart" is unique enough on its own.
+   *   2. Otherwise use the tag name plus at most two classes ("button.buy") so the
+   *      segment stays readable even on utility-class-heavy markup.
+   *   3. If siblings share the tag, disambiguate with :nth-of-type(n).
+   *   4. Stop after 6 segments — deeper paths add noise, not identity; the pin also
+   *      stores x/y percentages, so the path is a hint for humans/agents, not an address.
+   */
   function cssPath(el) {
     var parts = [];
     while (el && el.nodeType === 1 && el !== document.documentElement && parts.length < 6) {
@@ -317,6 +326,9 @@
       });
     }
 
+    /* Cross-screen sync: `storage` fires in every OTHER document on the origin
+       when one screen writes. e.key === null means localStorage.clear() — the
+       shell's ↺ reset — so every subscriber gets told its key is gone. */
     window.addEventListener('storage', function (e) {
       if (!e.key || e.key.indexOf(PREFIX) !== 0) {
         if (e.key === null) Object.keys(stateEmitter).forEach(function (k) { emit(k, undefined); });
@@ -543,6 +555,8 @@
 
   function standaloneInit() {
     if (initDone) return;
+    /* Screens live at features/<feature>/screens/<id>.html — three levels below
+       the project root, so app.config.json and themes/ resolve from ../../.. */
     var root = '../../..';
     var config = null;
 

package/cli/postinstall.js

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+/* Printed by npm right after `npm install -g` — the one moment a new user is
+   guaranteed to be looking at the terminal and ready for instructions.
+   Must NEVER fail an install: everything is wrapped, exit code is always 0.
+   Skipped in CI (and via SCREENBOOK_SKIP_BANNER=1). */
+
+try {
+  if (!process.env.CI && !process.env.SCREENBOOK_SKIP_BANNER) {
+    const tty = !!process.stdout.isTTY;
+    const paint = (code) => (s) => (tty ? `\x1b[${code}m${s}\x1b[0m` : s);
+    const bold = paint('1');
+    const dim = paint('2');
+    const green = paint('32');
+    const accent = paint('36');
+
+    console.log(`
+  ${bold('⧉ ScreenBook')} ${green('installed')} — a design workspace for AI agents, to present to humans.
+
+  ${bold('Start in any project:')}
+    ${accent('screenbook init')}     ${dim('scaffolds .screenbook/ — brief.md, theme, starter screen, agent skill')}
+    ${accent('screenbook serve')}    ${dim('opens your studio at')} http://127.0.0.1:4600
+
+  ${bold('Connect your AI agent')} ${dim('(Claude Code shown — any MCP client works):')}
+    claude mcp add screenbook -- npx -y @cs4alhaider/screenbook mcp --root .
+
+  ${bold('Or explore a finished demo first:')}
+    screenbook serve "$(npm root -g)/@cs4alhaider/screenbook/examples/qahwa"
+
+  ${dim('Docs & guides')}   https://cs4alhaider.github.io/screenbook/
+  ${dim('Bugs & ideas')}    https://github.com/cs4alhaider/screenbook/issues
+`);
+  }
+} catch { /* a banner must never break an install */ }
+process.exit(0);

package/cli/screenbook.js

@@ -10,7 +10,7 @@ import { startServer } from '../core/serve.js';
 import * as T from './templates.js';
 
 const ENGINE_DIR = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
-const VERSION = '0.2.0';
+const VERSION = '0.2.1';
 
 /* ---------------- arg parsing ---------------- */
 
@@ -236,9 +236,13 @@ async function cmdApp() {
   positional.splice(0, 2, positional[2]);   // remaining positional = project dir
   const root = await requireRoot();
 
-  /* Normalize src: apps usually live in the USER'S project. With a .screenbook
-     root, record them as project/<path> (served via the /project mount).
-     Relative paths are taken relative to the project directory. */
+  /* Normalize src to something the server can actually mount. Relative paths
+     are taken relative to the project directory. Three cases:
+       1. inside the ScreenBook root itself       → keep it root-relative
+       2. inside the user's project (.screenbook) → "project/<path>" — served
+          by the /project mount that maps one level above the root
+       3. anywhere else → keep the raw argument and let addApp's existence
+          check produce the error message */
   const isDotRoot = path.basename(root) === '.screenbook';
   const projectDir = isDotRoot ? path.dirname(root) : root;
   const absSrc = path.isAbsolute(srcArg) ? srcArg : path.resolve(projectDir, srcArg);
@@ -292,21 +296,28 @@ async function cmdScreenshot() {
 }
 
 function help() {
-  console.log(`${bold('screenbook')} ${VERSION} — static prototype studio
+  console.log(`${bold('⧉ screenbook')} ${VERSION} — a design workspace for AI agents, to present to humans
 
-  ${bold('init')} [dir] [--name X] [--force]     scaffold a consumer project (+ CLAUDE.md + skill)
+  ${bold('Start here')}
+    ${ok('screenbook init')}                   scaffold .screenbook/ in your project — write brief.md first
+    ${ok('screenbook serve')}                  your studio → http://127.0.0.1:4600
+    claude mcp add screenbook -- npx -y @cs4alhaider/screenbook mcp --root .
+                                      ${dim('connect your AI agent (any MCP client works)')}
+
+  ${bold('Commands')}
+  ${bold('init')} [dir] [--name X] [--force]     scaffold a consumer project (+ agent contract + skill)
              [--app <src>] also register an existing SPA in that folder as an embedded app
   ${bold('app add')} <src> [dir] [--id --title --icon --device --chrome self|engine --cooperative]
                                         embed an existing single-page app (driver scaffolded unless --cooperative)
   ${bold('serve')} [dir] [--port 4600]           static server · live reload · manifest refresh · review sync
   ${bold('manifest')} [dir]                      rescan screens → regenerate features/*/manifest.json
-  ${bold('validate')} [dir] [--static] [--json]  static checks + headless browser self-test
-  ${bold('mcp')} [--root dir]                    start the stdio MCP server (for agents):
-                                        claude mcp add screenbook -- npx -y @cs4alhaider/screenbook mcp --root .
+  ${bold('validate')} [dir] [--static] [--json]  static checks + headless browser self-test — the done gate
   ${bold('screenshot')} [dir] --screen f/s       PNG of a screen in its device frame
              [--mode light,dark] [--dir ltr,rtl] [--scenario id] [--theme id] [--lang xx] [--out dir]
+  ${bold('mcp')} [--root dir]                    stdio MCP server — 18 authoring tools for agents
 
-  Projects are folders with app.config.json + features/ + themes/ (see engine/CLAUDE.md).`);
+  ${dim('Docs & guides')}   https://cs4alhaider.github.io/screenbook/
+  ${dim('Bugs & ideas')}    https://github.com/cs4alhaider/screenbook/issues`);
 }
 
 const commands = {

package/core/serve.js

@@ -102,7 +102,7 @@ export function startServer({ root, engineDir, port = 4600, quiet = false }) {
       }
 
       if (p === '/__sb/health') {
-        send(res, 200, JSON.stringify({ screenbook: true, version: '0.2.0', root: path.basename(root) }),
+        send(res, 200, JSON.stringify({ screenbook: true, version: '0.2.1', root: path.basename(root) }),
           { 'Content-Type': 'application/json' });
         return;
       }

package/docs/README.md

@@ -3,19 +3,30 @@
 Start here. Each guide is short, self-contained, and ordered by how you'll actually meet
 the tool.
 
+## Guides — using ScreenBook
+
 | Guide | Read it when |
 |-------|--------------|
-| [Getting started](getting-started.md) | First contact — prerequisites, install, your first project in five minutes |
-| [The studio](studio-guide.md) | A tour of every control in the shell: sidebar, dropdowns, flows, review, Theme Lab, self-test |
-| [Authoring](authoring-guide.md) | You're building screens by hand — the full contract for screens, data, scenarios, themes, flows, strings |
-| [CLI reference](cli.md) | Every command and flag |
-| [AI agents & MCP](mcp-agents.md) | Hooking ScreenBook to Claude Code (or any MCP client) so agents author screens for you |
-| [App mode](app-mode-guide.md) | Embedding an EXISTING single-page app instead of (or alongside) file-per-screen features |
-| [Troubleshooting](troubleshooting.md) | Something's red, blank, or missing |
-
-Two more references live at the repo root:
-
-- **[CLAUDE.md](../CLAUDE.md)** — the authoring contract written for AI agents (scaffolded
-  into every project by `init`; humans are welcome to read it too).
-- **[TESTING.md](../TESTING.md)** — the engine's own test map, if you're contributing to
-  ScreenBook itself.
+| [Getting started](guides/getting-started.md) | First contact — prerequisites, install, your first project in five minutes |
+| [The studio](guides/studio.md) | A tour of every control in the shell: sidebar, dropdowns, flows, review, Theme Lab, self-test |
+| [Authoring](guides/authoring.md) | You're building screens by hand — the full contract for screens, data, scenarios, themes, flows, strings |
+| [App mode](guides/app-mode.md) | Embedding an EXISTING single-page app instead of (or alongside) file-per-screen features |
+| [Troubleshooting](guides/troubleshooting.md) | Something's red, blank, or missing |
+
+## Reference — looking things up
+
+| Reference | Covers |
+|-----------|--------|
+| [CLI](reference/cli.md) | Every command and flag: `init` · `serve` · `manifest` · `validate` · `screenshot` · `app add` · `mcp` |
+| [AI agents & MCP](reference/mcp-agents.md) | Hooking ScreenBook to Claude Code (or any MCP client) so agents author screens for you |
+
+## Contributing — hacking on ScreenBook itself
+
+| Document | Covers |
+|----------|--------|
+| [Architecture](contributing/architecture.md) | How the engine works: the shell, the bridge protocol, the core, CLI, MCP server, and the self-test |
+| [Testing map](contributing/testing.md) | Every test layer, what it covers, how to run it, and where the gaps are |
+
+One more reference lives at the repo root: **[AGENTS.md](../AGENTS.md)** — the authoring
+contract written for AI agents (scaffolded into every project by `init`; humans are welcome
+to read it too).

package/docs/contributing/architecture.md

@@ -0,0 +1,153 @@
+# Architecture — how the engine works
+
+One mental model: **two worlds meeting at plain files.**
+
+- **The studio** runs in the browser — plain ES modules, zero dependencies, no build step.
+  It reads the project's JSON + HTML over HTTP and renders screens in iframes.
+- **The tooling** runs in Node — the CLI and the MCP server, sharing one core. Exactly one
+  dependency (`playwright-core`), used only for headless validation and screenshots.
+
+Nothing is generated, bundled, or transpiled. What's in the repo is what executes.
+
+## Repo map
+
+```
+bridge.js          the ONLY file a screen includes — Engine API + sb:* protocol + EngineKit
+app-bridge.js      runs inside an embedded SPA — AppBridge API + sba:* protocol
+index.html         the studio page (loads shell/main.js)
+shell/             the studio, one module per concern (see below)
+core/              Node core shared by CLI + MCP: fs, meta, project API, server, browser
+cli/screenbook.js  command dispatcher: init · serve · manifest · validate · screenshot · app · mcp
+cli/templates.js   everything `init` scaffolds into a fresh project
+mcp/server.js      stdio JSON-RPC MCP server — 18 tools over the same core
+skill/             the agent skill `init` copies into consumer projects
+examples/          runnable demo projects that double as test fixtures
+test/              the engine's own suite (node:test) — see the testing map
+```
+
+## The bridge (`bridge.js`)
+
+A screen is a standalone HTML document whose only obligation is a meta block and one
+script include: the bridge. It boots in one of two modes:
+
+- **Embedded** — the screen is inside the studio's iframe. The bridge sends `sb:hello`,
+  the shell answers `sb:init` with everything the screen needs (theme, mode, dir, lang,
+  merged data, i18n, review pins). Live changes arrive as `sb:update` / `sb:review`.
+- **Standalone** — the screen was opened directly. The bridge self-loads
+  `app.config.json`, the theme, seed + scenarios, and i18n from their conventional
+  relative paths, honoring `?scenario=…&mode=dark&dir=rtl&lang=…` — so a screen file is
+  demoable with zero infrastructure. If an `sb:hello` goes unanswered for 600ms (iframed
+  by something that isn't the shell), it falls back to standalone.
+
+The top half of the file is **EngineKit** — the pure logic both worlds must agree on:
+deep merge, scenario overlay (`remove` dot-paths, then `patch`), `{{today±N}}` date
+tokens, token flattening (`color.ink-2` → `--color-ink-2`), dark-over-light theme
+resolution, i18n lookup, and the CSS-path builder for review pins. The shell loads
+`bridge.js` too (with `window.__SCREENBOOK_SHELL__` set) purely to reuse this kit — the
+merge/flatten/date logic exists exactly once. The Node unit tests load the same file in a
+VM, so the browser and the tests exercise identical code.
+
+What screens see: `Engine.ready(cb)` · `Engine.data` (frozen) · `Engine.env` ·
+`Engine.state` (localStorage-backed KV that syncs across screens via `storage` events) ·
+`Engine.go` / `data-go` · `Engine.t` · `Engine.toast`.
+
+## The shell (`shell/`)
+
+A tiny unidirectional loop, no framework:
+
+```
+store.js  →  set(patch)  →  subscribers get the set of changed keys  →  each module
+             re-renders only what its keys touch  →  syncHash() mirrors state to the URL
+```
+
+| Module | Owns |
+|--------|------|
+| `store.js` | UI state, selectors, hash deep links (`#feature/screen?scenario=…&mode=…`) |
+| `net.js` | project loading (config, features, themes), serve detection, SSE, review persistence |
+| `main.js` | boot, toolbar wiring, keyboard, live reload, the change→render map |
+| `screenhost.js` | the mounted iframe: builds frames, speaks sb:*/sba:*, pushes env updates |
+| `frames.js` | device chrome (iPhone island/status bar, Android punch-hole, browser bar) + scale-to-fit |
+| `sidebar.js` | searchable, grouped screen list |
+| `toolbar.js` | dropdown/toggle/action chip widgets |
+| `flowplayer.js` | walkthrough playback; steps can pin scenarios; restores state on exit |
+| `review.js` | pins, the comments panel, disk/localStorage persistence |
+| `themelab.js` | live token editing; dark stays a delta; save writes `themes/<id>.json` |
+| `selftest.js` | the in-browser render matrix (below) |
+
+Two decisions carry most of the weight here. **Screens live in iframes** — full style and
+error isolation, which is what lets the gate say "zero console errors" and mean it. And
+**state changes are described, not performed** — `set({mode:'dark'})` doesn't touch the
+DOM; every interested module reacts, which is why deep links, flows, and the self-test can
+drive the studio through the same door the toolbar uses.
+
+## App mode (`app-bridge.js`)
+
+An embedded SPA mounts once and is *driven* over `sba:*` instead of being remounted per
+screen. The adapter (`screens()`, `go()`, optional `current()`/`set()`/`scenarios()`)
+gets registered in one of two ways: **cooperative** — the app includes `app-bridge.js`
+itself; **driven** — the shell injects the runtime plus a project-owned `driver.js` into
+the (same-origin) iframe after load, so the app's own files stay byte-untouched.
+
+## The Node core (`core/`)
+
+| Module | Owns |
+|--------|------|
+| `fsx.js` | atomic writes (temp + rename), change-detecting JSON writes — every CLI/MCP write goes through here |
+| `meta.js` | the screen-meta block: parse, rewrite, `updated` stamping, the screen lint, `data-go` extraction |
+| `project.js` | **the one Project API** both CLI and MCP import: root resolution, feature scan, derived manifests, screen CRUD with lint-on-write, data/theme/flow/comment accessors, static validation |
+| `serve.js` | the dev server: project root + `/screenbook/*` package mount + `/project/*` parent mount, no-cache everywhere, SSE live reload, watch → debounced manifest regen, review/theme write-back APIs |
+| `browser.js` | headless side: playwright→system-Chrome resolution ladder (auto-download as last resort), the headless self-test wrapper, framed screenshots via the shell's `?solo=1` |
+
+The CLI and the MCP server are both **thin faces over `project.js`** — same validation,
+same atomic writes, same manifest regeneration, whether a human or an agent is typing.
+`manifest.json` is always derived from the screens' meta blocks; it exists so the studio
+can boot on any dumb static server, but the CLI/MCP/serve regenerate it — never edit it.
+
+## The gate (`selftest.js` + `validate`)
+
+`?selftest=1` renders **every screen × device variant × theme × light/dark × LTR/RTL** in
+hidden iframes (a small worker pool), replaying the exact shell handshake per combo, and
+requires `Engine.ready` + a meta title + zero console errors. Embedded apps must register
+within 20s, report ≥1 screen, and survive a visit to every screen they report.
+`screenbook validate` = static checks from `project.js` first, then this same matrix run
+headlessly, with results read off `window.__selftestResult`. Green is the definition of
+done — for humans and agents alike.
+
+## The protocols
+
+| Message | Direction | Meaning |
+|---------|-----------|---------|
+| `sb:hello` | screen → shell | bridge booted; carries the parsed meta |
+| `sb:init` | shell → screen | full environment: theme, mode, dir, lang, device, scenario, data, i18n, review |
+| `sb:update` | shell → screen | live env change (theme/mode/dir/lang) — no reload |
+| `sb:review` | shell → screen | review state + pins to render |
+| `sb:ready` | screen → shell | `Engine.ready` callbacks ran; hide the veil |
+| `sb:go` | screen → shell | `data-go`/`Engine.go` navigation request |
+| `sb:console-error` | screen → shell | forwarded error (also feeds the self-test) |
+| `sb:pin-request` / `sb:pin-open` | screen → shell | review-mode clicks |
+| `sba:hello` / `sba:screens` / `sba:current` | app → shell | registration, screen list, navigation echo |
+| `sba:go` / `sba:env` | shell → app | drive navigation / apply environment live |
+
+## Rules that keep it simple
+
+1. **No build, ever.** The studio must run from a folder on disk. Adding a bundler is a
+   rejected feature, not a missing one.
+2. **The viewer has zero dependencies; the tooling has one.** Anything heavier belongs in
+   a consumer project, not here.
+3. **Screens are standalone documents.** Every screen must work opened directly — the
+   bridge's standalone mode is a contract, not a fallback.
+4. **Derived files are never hand-edited** (`manifest.json`), and **every write is
+   atomic** (`fsx.js`) — agents and humans share the same safety rails.
+5. **One core, two faces.** New authoring capability goes into `core/project.js` first;
+   the CLI command and the MCP tool are wrappers.
+
+## Adding things
+
+- **A CLI command** → implement against `core/project.js`, register it in the `commands`
+  map in `cli/screenbook.js`, document it in [the CLI reference](../reference/cli.md).
+- **An MCP tool** → same core call, plus an entry in `TOOLS` in `mcp/server.js` (schema +
+  description are the agent's documentation — write them like you'd brief a new hire).
+- **A studio control** → a widget in `main.js#buildControls()`, state in `store.js`, and a
+  reaction in `onChange`; if it must survive reload, add its key to the hash sync.
+- **Anything** → update [the testing map](testing.md) and keep `npm test` +
+  `validate` green on the examples.

package/{TESTING.md → docs/contributing/testing.md}

@@ -2,21 +2,26 @@
 
 > The "don't forget" file: every test layer, what it covers, how to run it, and where the
 > gaps are. Update this whenever a layer is added or a gap closes. Definition of done for
-> any engine change: **`npm test` green AND `validate` green on all four projects below.**
+> any engine change: **`npm test` green AND `validate` green on the bundled examples.**
 
 ## How to run everything
 
+From a checkout of this repo:
+
 ```bash
-cd engine
 npm i                # once — playwright-core (drives your installed Chrome)
-npm test             # unit + E2E suites (node:test, ~58 tests, ~60s incl. browser)
+npm test             # unit + E2E suites (node:test, 64 tests, ~60s incl. browser)
 
-# full browser matrix on every project that ships in this repo:
-node cli/screenbook.js validate ..                        # Rahhal (repo root)
+# full browser matrix on the projects that ship in this repo:
 node cli/screenbook.js validate examples/qahwa
 node cli/screenbook.js validate examples/tokens-lab
+node cli/screenbook.js validate examples/spa-demo
 ```
 
+Docs screenshots (`docs/shots/`, light + dark variants of every subject) are regenerated in
+one shot with `node tools/capture-shots.mjs` — it serves scratch copies of the examples, so
+nothing in the repo is mutated by the capture run.
+
 ## Layers
 
 | Layer | File(s) | Covers |
@@ -36,7 +41,7 @@ node cli/screenbook.js validate examples/tokens-lab
 
 | Project | Exercises |
 |---------|-----------|
-| repo root (Rahhal) | iOS frame, AR/RTL/i18n screens, scenarios with `remove`, flows, `statusBar` override, shared.css/js — **plus both certified prototypes embedded as driven apps** (`features/rahhal-ios` 31 screens · `features/rahhal-web` 11 screens, drivers injected, `docs/mockups/` byte-untouched) |
+| the maintainer's host project (not shipped) | iOS frame, AR/RTL/i18n screens, scenarios with `remove`, flows, `statusBar` override, shared.css/js — plus two certified, sealed prototypes embedded as **driven** apps (31 + 11 screens, drivers injected, app files byte-untouched) |
 | `examples/qahwa` | iOS + **Android** + **web** frames in one project, in-screen sheet (EN-24), `Engine.state` cart, feature groups, device filter |
 | `examples/tokens-lab` | **Multi-theme** (Theme ▾ + theme axis in the matrix), **bare `none` frame**, live token re-skin, MutationObserver pattern |
 | `examples/spa-demo` | **Cooperative app mode** — a one-page notes app including `app-bridge.js` itself; engine chrome on an app |
@@ -50,5 +55,5 @@ node cli/screenbook.js validate examples/tokens-lab
 - RTL screenshot diffing / visual regression (screenshots exist; no baseline comparison).
 - Windows: paths are POSIX-tested only; `fs.watch` recursive + rename semantics unverified.
 - `file://` standalone mode has no automated check (manual only; fallback tokens by design).
-- Driven-app injection path in the shell suite uses the cooperative mini-app only; the two
-  Rahhal drivers are covered by root `validate` (64/64), not by `npm test`.
+- Driven-app injection path in the shell suite uses the cooperative mini-app only; real
+  driven-app drivers are exercised in the maintainer's host project, not by `npm test`.

package/docs/{app-mode-guide.md → guides/app-mode.md}

@@ -5,20 +5,26 @@ App mode puts the WHOLE app inside the studio: its views appear in the sidebar,
 work, dark/RTL/scenario controls drive it — and for sealed apps, **not one byte of the
 app's files changes**.
 
-![A sealed app running inside the studio](shots/app-mode.png)
+![A sealed app running inside the studio](../shots/app-mode-light.png)
 
 ## Register it
 
 ```bash
-node engine/cli/screenbook.js app add legacy/index.html --device ios --chrome self
+screenbook app add legacy/index.html --device ios --chrome self
 ```
 
 That writes an app-type feature:
 
-```json
-{ "id": "legacy", "title": "Legacy app", "type": "app",
-  "src": "legacy/index.html", "device": "ios", "chrome": "self",
-  "driver": "driver.js" }
+```jsonc
+{
+  "id": "legacy",              // feature id — the folder name under features/
+  "title": "Legacy app",       // shown in the Feature ▾ dropdown
+  "type": "app",               // app-type feature: one embedded SPA instead of file screens
+  "src": "legacy/index.html",  // project-relative entry point the studio mounts
+  "device": "ios",             // bezel: ios · android · web · none
+  "chrome": "self",            // the app draws its own status/home bars — bezel only
+  "driver": "driver.js"        // injected adapter (omitted for --cooperative apps)
+}
 ```
 
 - `device` picks the bezel; `chrome: "self"` means the app draws its own status/home bars
@@ -72,8 +78,9 @@ reported screen, and **a clean visit to every reported screen — zero console e
 Driver bugs surface as `driver <fn>: <message>` rows. `ignoreErrors` patterns are for
 narrow, documented third-party noise only — everything else still fails.
 
-## Reference drivers
+## Reference material
 
-This repo's root project embeds two real, sealed prototypes — `features/rahhal-ios/driver.js`
-(screen registry, dark/RTL state, scenario player, router wrap) and
-`features/rahhal-web/driver.js` (view/tab model) — read them when writing yours.
+For the **driven** path, `app add` scaffolds a fully commented `driver.js` template — its
+TODOs walk you through `screens()`, `go()` and `set()` against your app's real globals.
+For the **cooperative** path, `examples/spa-demo` inside the package is a complete working
+app to copy from.

package/docs/{authoring-guide.md → guides/authoring.md}

@@ -30,8 +30,14 @@ features/trip-planning/
   <meta name="viewport" content="width=device-width, initial-scale=1">
   <title>Home</title>
   <script type="application/json" id="screen-meta">
-  { "title": "Home", "description": "Entry point.", "order": 10,
-    "device": "ios", "status": "wip", "tags": ["core"] }
+  {
+    "title": "Home",
+    "description": "Entry point.",
+    "order": 10,
+    "device": "ios",
+    "status": "wip",
+    "tags": ["core"]
+  }
   </script>
   <script src="../../../screenbook/bridge.js"></script>
   <link rel="stylesheet" href="shared.css">
@@ -80,11 +86,19 @@ Rules that keep everything sane:
 
 `seed.json` is the demo-complete state. `scenarios.json` layers named states over it:
 
-```json
-{ "list": [
-  { "id": "default",  "icon": "🧪", "title": "Full demo" },
-  { "id": "new-user", "icon": "🆕", "title": "Brand-new user",
-    "remove": ["trips", "user.points"], "patch": { "user": { "isNew": true } } } ] }
+```jsonc
+{
+  "list": [
+    { "id": "default", "icon": "🧪", "title": "Full demo" },  // baseline — the seed, untouched
+    {
+      "id": "new-user",
+      "icon": "🆕",
+      "title": "Brand-new user",
+      "remove": ["trips", "user.points"],       // 1. delete these dot-paths from the seed…
+      "patch": { "user": { "isNew": true } }    // 2. …then deep-merge this over what's left
+    }
+  ]
+}
 ```
 
 `remove` deletes dot-paths, then `patch` deep-merges (arrays replace whole). Date tokens —
@@ -101,9 +115,11 @@ delta over light. Edit visually in the 🎨 Theme Lab and Save. Register extra t
 
 `i18n.json`, key-first — every key shows all its languages side by side:
 
-```json
-{ "home.title": { "en": "Trips", "ar": "الرحلات" },
-  "home.greet": { "en": "{name}, welcome back", "ar": "يا {name}، أهلاً بعودتك" } }
+```jsonc
+{
+  "home.title": { "en": "Trips", "ar": "الرحلات" },
+  "home.greet": { "en": "{name}, welcome back", "ar": "يا {name}، أهلاً بعودتك" }  // {name} fills from Engine.t vars
+}
 ```
 
 `Engine.t('home.greet', {name})` — fallback: active language → `defaultLanguage` → the key.
@@ -111,10 +127,20 @@ Language switches reload the screen. Gaps show up as `validate` warnings, never
 
 ## Flows
 
-```json
-{ "list": [ { "id": "pitch", "title": "The pitch", "icon": "✨",
-  "steps": [ { "screen": "010-home", "note": "Start empty.", "scenario": "new-user" },
-             { "screen": "020-detail", "note": "One tap deeper." } ] } ] }
+```jsonc
+{
+  "list": [
+    {
+      "id": "pitch",
+      "title": "The pitch",
+      "icon": "✨",
+      "steps": [
+        { "screen": "010-home", "note": "Start empty.", "scenario": "new-user" },  // a step may pin a scenario
+        { "screen": "020-detail", "note": "One tap deeper." }                      // …the note is presenter narration
+      ]
+    }
+  ]
+}
 ```
 
 Write notes as presenter narration; 3–7 steps; end on the money shot.
@@ -122,8 +148,8 @@ Write notes as presenter narration; 3–7 steps; end on the money shot.
 ## After editing by hand
 
 ```bash
-node engine/cli/screenbook.js manifest .    # if you added/renamed screens
-node engine/cli/screenbook.js validate .    # the done gate
+screenbook manifest    # if you added/renamed screens
+screenbook validate    # the done gate
 ```
 
 (Under `serve`, manifests regenerate automatically on save. MCP writes do both for you.)

package/docs/{getting-started.md → guides/getting-started.md}

@@ -9,18 +9,10 @@
 | **Google Chrome installed** | `validate` and `screenshot` (headless checks) | used through `playwright-core`; see below if you don't have Chrome |
 | **Git** | recommended | ScreenBook writes plain files — git is your undo and your review tool |
 
-Nothing else. No bundler, no framework, no global installs. The viewer has **zero**
-dependencies; the CLI has exactly one *dev* dependency (`playwright-core`) used only for
-headless validation and screenshots.
-
-One-time setup for the headless checks:
-
-```bash
-cd engine
-npm i                       # installs playwright-core (~3s, no browser download)
-# no Chrome on this machine? use a bundled browser instead:
-npm i -D playwright && npx playwright install chromium
-```
+Nothing else. No bundler, no framework, no build step. The studio itself has **zero**
+dependencies; the CLI carries exactly one (`playwright-core`), used only for headless
+validation and screenshots — it comes along automatically with the install below. On a
+machine without Chrome, the first `validate` downloads a headless browser once, by itself.
 
 ## Install
 
@@ -69,15 +61,15 @@ the sidebar. That's the whole loop.
 Already have a single-page prototype? Embed it whole instead of rewriting:
 
 ```bash
-node engine/cli/screenbook.js init . --app path/to/index.html
+screenbook init . --app path/to/index.html
 ```
 
-(see [App mode](app-mode-guide.md)).
+(see [App mode](app-mode.md)).
 
 ## The definition of done
 
 ```bash
-node engine/cli/screenbook.js validate .
+screenbook validate
 ```
 
 Green means: every screen renders in every theme × light/dark × LTR/RTL with **zero console

package/docs/{studio-guide.md → guides/studio.md}

@@ -1,8 +1,9 @@
 # The studio, control by control
 
-Open `http://127.0.0.1:4600` (or `/engine/index.html` under any server).
+Open `http://127.0.0.1:4600` — `screenbook serve` redirects straight to the studio at
+`/screenbook/`.
 
-![The studio](shots/hero-studio.png)
+![The studio](../shots/hero-studio-light.png)
 
 ## Top bar
 

package/docs/{troubleshooting.md → guides/troubleshooting.md}

@@ -1,13 +1,13 @@
 # Troubleshooting
 
 **The studio is blank / "could not load this project".**
-The shell expects to live at `<project>/engine/` with `app.config.json` one level up.
-Serve the PROJECT root (not `engine/`), then open `/engine/index.html`. Under
-`screenbook serve` the `/engine/*` mount handles this automatically.
+The studio expects `app.config.json` one level above where it's mounted. `screenbook serve`
+wires this automatically (the studio lives at `/screenbook/`, your project at `/`). Under a
+plain static server, serve the PROJECT root — never the studio folder itself.
 
 **My new screen isn't in the sidebar.**
 The sidebar reads the derived `features/<f>/manifest.json`. Under `serve` it regenerates on
-save; under any other server run `node engine/cli/screenbook.js manifest .`. Also check the
+save; under any other server run `screenbook manifest`. Also check the
 meta block parses (validate says exactly what's wrong).
 
 **The screen shows "Loading…" forever.**
@@ -23,8 +23,10 @@ the console). Cooperative app: the include path to `engine/app-bridge.js` is wro
 them cooperative.
 
 **`validate` fails with "No headless browser available".**
-`cd engine && npm i` (uses your installed Chrome via playwright-core). No Chrome:
-`npm i -D playwright && npx playwright install chromium`.
+The checks drive your installed Google Chrome via `playwright-core` (bundled with the
+package), and on a Chrome-less machine they download a headless browser once, automatically.
+If both routes failed (offline machine, blocked download), run
+`npx playwright-core install chromium` when you're back online.
 
 **`validate` is red on a screen that looks fine.**
 The gate is zero console errors across every theme × mode × direction. The failure row
@@ -51,5 +53,6 @@ Python's server sends cache headers; hard-reload, or use `screenbook serve`
 (no-store on everything — this problem is why).
 
 **Something engine-side looks wrong.**
-`?selftest=1` in the browser for the live matrix; `TESTING.md` maps every layer
-(`npm test` inside `engine/` runs the engine's own 61-test suite).
+`?selftest=1` in the browser for the live matrix; the [testing map](../contributing/testing.md)
+covers every layer (`npm test` in a checkout of the ScreenBook repo runs the engine's own
+64-test suite).

package/docs/{cli.md → reference/cli.md}

@@ -7,8 +7,9 @@ npm install -g @cs4alhaider/screenbook
 ```
 
 Alternatives that need no install: `npx -y @cs4alhaider/screenbook <command>`, or from a
-checkout `node engine/cli/screenbook.js <command>`. Every command takes an optional project
-directory (default: the current one; running from inside `engine/` resolves to its parent).
+checkout `node cli/screenbook.js <command>`. Every command takes an optional project
+directory (default: the current one; running from inside `.screenbook/` resolves to its
+parent project automatically).
 
 ## `init [dir] [--name X] [--force] [--app <src>] [--cooperative]`
 
@@ -20,8 +21,8 @@ embedded app (driver scaffolded unless `--cooperative`).
 
 The dev server. Static hosting with:
 
-- `/engine/*` mounted from the package folder — projects and the bundled examples work even
-  without a local `engine/` copy
+- the studio runtime mounted at `/screenbook/*` straight from the installed package
+  (`/engine/*` kept as a compatibility alias) — your project never carries runtime code
 - live reload over SSE — saving any project file refreshes the studio; screen edits reload
   the current frame
 - automatic `manifest.json` regeneration when screens change
@@ -57,8 +58,8 @@ Device-framed PNGs via headless Chrome. Options: `--mode light,dark` · `--dir l
 
 Embed an existing single-page app as an app-type feature. Scaffolds an injectable
 `driver.js` template (fill in `screens()` / `go()` / `set()`) unless `--cooperative`, in
-which case the app is expected to include `engine/app-bridge.js` itself. See
-[App mode](app-mode-guide.md).
+which case the app is expected to include the packaged `app-bridge.js` itself. See
+[App mode](../guides/app-mode.md).
 
 ## `mcp [--root dir]`
 

package/mcp/server.js

@@ -16,7 +16,7 @@ import {
 } from '../core/project.js';
 
 const ENGINE_DIR = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
-const VERSION = '0.2.0';
+const VERSION = '0.2.1';
 
 const rootFlagIx = process.argv.indexOf('--root');
 const rootArg = rootFlagIx > -1 ? process.argv[rootFlagIx + 1] : undefined;
@@ -332,6 +332,8 @@ async function handle(msg) {
       const tool = TOOLS.find((t) => t.name === params?.name);
       if (!tool) return replyError(id, -32602, `unknown tool: ${params?.name}`);
       try {
+        /* `extra` is a side channel: a tool can set extra.imagePath and the
+           file is attached to the reply as inline MCP image content. */
         const extra = {};
         const result = await tool.run(params.arguments || {}, extra);
         const content = [{ type: 'text', text: JSON.stringify(result, null, 2) }];

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@cs4alhaider/screenbook",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "publishConfig": {
     "access": "public"
   },
-  "description": "ScreenBook — a static, no-build prototype studio. Drop folders of HTML screens + JSON (data, scenarios, tokens) and get a device-framed gallery with review mode, flows, self-tests, a CLI and an MCP server for AI agents.",
+  "description": "ScreenBook — a design workspace for AI agents to present to humans. HTML screens + JSON data in real device frames, with review mode, flows, themes, self-tests, a CLI and an MCP server. Fully offline, no build step, and any MCP agent can drive it.",
   "type": "module",
   "bin": {
     "screenbook": "cli/screenbook.js"
@@ -36,13 +36,13 @@
     "examples/",
     "docs/",
     "AGENTS.md",
-    "CLAUDE.md",
-    "TESTING.md"
+    "CLAUDE.md"
   ],
   "dependencies": {
     "playwright-core": "^1.45.0"
   },
   "scripts": {
+    "postinstall": "node cli/postinstall.js",
     "test": "node --test",
     "serve": "node cli/screenbook.js serve ..",
     "validate": "node cli/screenbook.js validate .."
@@ -51,7 +51,7 @@
     "type": "git",
     "url": "git+https://github.com/cs4alhaider/screenbook.git"
   },
-  "homepage": "https://github.com/cs4alhaider/screenbook#readme",
+  "homepage": "https://cs4alhaider.github.io/screenbook/",
   "bugs": {
     "url": "https://github.com/cs4alhaider/screenbook/issues"
   }

package/shell/screenhost.js

@@ -218,6 +218,9 @@ export function showScreen({ bust = false } = {}) {
     return;
   }
 
+  /* Same feature + same device chrome → keep the mounted frame and only swap
+     the iframe's document below; rebuilding the hardware around the screen on
+     every navigation would flash and drop the fit scale. */
   const device = effectiveDevice(entry);
   const sameFrame = current &&
     current.featureId === store.ui.feature &&

package/shell/selftest.js

@@ -36,6 +36,17 @@ function combos(project) {
   return list;
 }
 
+/*
+ * Render ONE (screen × device × theme × mode × dir) combination in a hidden
+ * iframe and judge it. The choreography mirrors what the real shell does:
+ *   1. Mount the screen at true device dimensions, parked far off-screen.
+ *   2. The bridge inside sends sb:hello → answer with a full sb:init payload
+ *      (theme, mode, dir, default-scenario data) exactly like screenhost would.
+ *   3. Collect every sb:console-error the screen reports along the way.
+ *   4. On sb:ready, wait SETTLE_MS for late errors, then judge: a meta block
+ *      with a title + zero console errors = green.
+ *   5. A screen that never reaches ready fails via READY_TIMEOUT.
+ */
 function runCombo(project, combo) {
   return new Promise((resolve) => {
     const started = performance.now();
@@ -236,6 +247,7 @@ export async function runSelftest() {
     }
   }
 
+  /* N workers drain one shared queue — at most CONCURRENCY iframes live at once. */
   const queue = all.slice();
   await Promise.all(Array.from({ length: CONCURRENCY }, async () => {
     while (queue.length) {

package/shell/store.js

@@ -68,6 +68,8 @@ export function activeScenario(featureId = store.ui.feature) {
 /* ---------------- hash routing ---------------- */
 
 const HASH_KEYS = ['scenario', 'mode', 'theme', 'dir', 'lang', 'flow'];
+/* Re-entrancy guard: applyHash() → set() → syncHash() must not rewrite the
+   URL with half-applied state while we're still parsing it. */
 let applyingHash = false;
 
 export function parseHash() {