npm - @cs4alhaider/screenbook - Versions diffs - 0.1.0 - Mend

@cs4alhaider/screenbook 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (91) hide show

package/CLAUDE.md +185 -0
package/LICENSE +21 -0
package/README.md +208 -0
package/TESTING.md +54 -0
package/app-bridge.js +131 -0
package/bridge.js +598 -0
package/cli/screenbook.js +290 -0
package/cli/templates.js +139 -0
package/core/browser.js +108 -0
package/core/fsx.js +71 -0
package/core/meta.js +94 -0
package/core/project.js +482 -0
package/core/serve.js +224 -0
package/docs/README.md +21 -0
package/docs/app-mode-guide.md +79 -0
package/docs/authoring-guide.md +129 -0
package/docs/cli.md +78 -0
package/docs/getting-started.md +88 -0
package/docs/mcp-agents.md +60 -0
package/docs/shots/android-dark.png +0 -0
package/docs/shots/app-mode.png +0 -0
package/docs/shots/hero-studio.png +0 -0
package/docs/shots/rtl-arabic.png +0 -0
package/docs/shots/theme-lab.png +0 -0
package/docs/shots/theming-noir.png +0 -0
package/docs/shots/web-dashboard.png +0 -0
package/docs/studio-guide.md +64 -0
package/docs/troubleshooting.md +55 -0
package/examples/qahwa/app.config.json +9 -0
package/examples/qahwa/features/order/data/scenarios.json +25 -0
package/examples/qahwa/features/order/data/seed.json +21 -0
package/examples/qahwa/features/order/feature.json +7 -0
package/examples/qahwa/features/order/flows.json +16 -0
package/examples/qahwa/features/order/manifest.json +78 -0
package/examples/qahwa/features/order/screens/010-menu.html +121 -0
package/examples/qahwa/features/order/screens/020-drink.html +120 -0
package/examples/qahwa/features/order/screens/030-cart.html +99 -0
package/examples/qahwa/features/order/screens/040-status.html +125 -0
package/examples/qahwa/features/order/screens/050-status-android.html +95 -0
package/examples/qahwa/features/order/screens/shared.css +146 -0
package/examples/qahwa/features/roastery/data/scenarios.json +35 -0
package/examples/qahwa/features/roastery/data/seed.json +17 -0
package/examples/qahwa/features/roastery/feature.json +7 -0
package/examples/qahwa/features/roastery/flows.json +14 -0
package/examples/qahwa/features/roastery/manifest.json +32 -0
package/examples/qahwa/features/roastery/screens/010-orders.html +103 -0
package/examples/qahwa/features/roastery/screens/020-menu-editor.html +88 -0
package/examples/qahwa/features/roastery/screens/shared.css +115 -0
package/examples/qahwa/review/comments.json +3 -0
package/examples/qahwa/themes/qahwa.json +43 -0
package/examples/spa-demo/app/index.html +100 -0
package/examples/spa-demo/app.config.json +9 -0
package/examples/spa-demo/features/notes-app/feature.json +11 -0
package/examples/spa-demo/review/comments.json +3 -0
package/examples/spa-demo/themes/default.json +15 -0
package/examples/tokens-lab/app.config.json +9 -0
package/examples/tokens-lab/features/lab/data/scenarios.json +5 -0
package/examples/tokens-lab/features/lab/data/seed.json +3 -0
package/examples/tokens-lab/features/lab/feature.json +7 -0
package/examples/tokens-lab/features/lab/flows.json +14 -0
package/examples/tokens-lab/features/lab/manifest.json +33 -0
package/examples/tokens-lab/features/lab/screens/010-swatches.html +112 -0
package/examples/tokens-lab/features/lab/screens/020-typography.html +115 -0
package/examples/tokens-lab/review/comments.json +3 -0
package/examples/tokens-lab/themes/noir.json +32 -0
package/examples/tokens-lab/themes/paper.json +32 -0
package/index.html +50 -0
package/mcp/server.js +366 -0
package/package.json +57 -0
package/shell/flowplayer.js +85 -0
package/shell/frames.js +108 -0
package/shell/main.js +397 -0
package/shell/net.js +126 -0
package/shell/review.js +213 -0
package/shell/screenhost.js +380 -0
package/shell/selftest.js +275 -0
package/shell/shell.css +952 -0
package/shell/sidebar.js +112 -0
package/shell/store.js +119 -0
package/shell/themelab.js +186 -0
package/shell/toast.js +15 -0
package/shell/toolbar.js +128 -0
package/skill/SKILL.md +52 -0
package/skill/references/app-mode.md +77 -0
package/skill/references/bridge-api.md +55 -0
package/skill/references/cli-mcp.md +53 -0
package/skill/references/flows.md +44 -0
package/skill/references/i18n.md +52 -0
package/skill/references/scenarios.md +45 -0
package/skill/references/screen-contract.md +83 -0
package/skill/references/tokens.md +56 -0

package/CLAUDE.md ADDED Viewed

@@ -0,0 +1,185 @@
+# ScreenBook — authoring contract
+> This file ships with ScreenBook and is scaffolded into consumer projects by `init` (it is the
+> contract from EN-22/EN-32). You are authoring **screens, data, themes and flows** for a
+> ScreenBook prototype project. You never need to read or edit anything under `engine/` —
+> everything you can do is defined here. Engine developers: see `engine/ENGINE-BRIEF.md` instead.
+## What this is
+ScreenBook is a static, no-build prototype studio. A project is just folders of standalone HTML
+screens plus JSON files. The shell (`engine/index.html`) turns them into a navigable,
+device-framed gallery with data scenarios, themes, dark/RTL toggles, guided flows, review
+comments and a self-test.
+## Project layout (convention over configuration)
+```
+app.config.json              ← name, features order, devices, themes, languages
+themes/default.json          ← design tokens (light + dark), flattened to CSS vars
+features/<feature-id>/
+  feature.json               ← { id, title, icon, description, order }
+  manifest.json              ← DERIVED index — never edit; CLI/MCP regenerates it
+  flows.json                 ← named walkthroughs: { list: [{id, title, icon, steps: […]}] }
+  data/seed.json             ← mock data for the feature
+  data/scenarios.json        ← named overlays over the seed (empty states, mid-trip, …)
+  screens/
+    shared.css / shared.js   ← optional feature-wide look/helpers (screens opt in per file)
+    010-home.html            ← one file = one screen; numeric prefix = sidebar order fallback
+review/comments.json         ← Review-Mode pins from humans (read them, fix, resolve)
+engine/                      ← the studio itself — NEVER edit
+```
+## The screen contract (the whole truth in one file)
+```html
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>Home</title>
+  <script type="application/json" id="screen-meta">
+  {
+    "title": "Trips home",
+    "description": "Entry point — active trip hero, drafts, memories.",
+    "order": 10,
+    "device": "ios",
+    "status": "draft",
+    "tags": ["core"]
+  }
+  </script>
+  <script src="../../../engine/bridge.js"></script>
+</head>
+<body>
+  <button data-go="020-wizard">Plan a trip</button>
+  <script>
+    Engine.ready(function (data) { /* seed ⊕ active scenario, dates resolved */ });
+  </script>
+</body>
+</html>
+```
+Rules:
+- The meta block is **required** (`title` at minimum) — the self-test fails without it.
+  `device`: `ios` (393×852) · `android` (412×915) · `web` (1280×760) · `none` (bare).
+  Optional: `devices` (variant array, e.g. `["ios","android"]` — one file rendered in each
+  listed frame; self-test covers all of them), `status` (draft/wip/ready/review), `tags`,
+  `group` (sidebar section), `statusBar` (`light`|`dark` — overrides status-bar/home-bar
+  ink on full-bleed art), `updated` (stamped automatically on save; manual override kept).
+- Exactly one bridge include: `<script src="../../../engine/bridge.js"></script>`.
+- Screens must render sensibly with **empty** `Engine.data` and `Engine.state`.
+- Static screens with zero JS are perfectly legal.
+- Sheets/modals live **inside** the screen that opens them (hidden markup until triggered).
+- Markup duplication across screens is normal — there is no templating system. Shared look
+  goes in `screens/shared.css` + `shared.js`, included explicitly per screen.
+- Screens may pull any library via CDN (`<script src="https://…">`) — iframe isolation makes
+  that safe. Keep it inside the screen.
+- Never draw device hardware (status bar, notch, home bar) — the shell's frame owns it.
+  Pad with `var(--safe-top)` / `var(--safe-bottom)` instead.
+## Bridge API (everything a screen can use)
+| API | Behavior |
+|-----|----------|
+| `Engine.ready(cb)` | `cb(data)` after theme + data are injected. Late registration still fires. |
+| `Engine.data` | Frozen merged mock data: seed ⊕ active scenario, `{{today±N}}` resolved. |
+| `Engine.state` | Shared KV across screens: `get(k, fallback)` / `set(k, v)` / `subscribe(k, cb)` / `keys()`. Survives screen switches; shell has a reset button. |
+| `Engine.go(id)` / `data-go="id"` | Navigate to a sibling screen. Standalone fallback: plain `<id>.html` link. |
+| `Engine.toast(msg)` | Transient toast inside the frame. |
+| `Engine.env` | `{ mode, dir, lang, device, scenario, theme, embedded }`. |
+| `Engine.meta` | This screen's parsed meta block. |
+| CSS vars | Active theme flattened to `--color-*`, `--font-*`, `--radius-*`, `--space-*` on `:root`, plus `--safe-top` / `--safe-bottom`. The bridge also sets `data-mode="light|dark"`, `data-device`, `dir`, `lang` on `<html>`. |
+Dark mode: style with tokens and they flip automatically; for bespoke dark rules use
+`html[data-mode="dark"] .thing { … }`. RTL: layout flips via `dir` — use logical CSS
+(`margin-inline-start`, `inset-inline-end`) instead of left/right when possible.
+Opened standalone (no shell), a screen self-loads the default theme + seed and accepts
+`?scenario=…&mode=dark&dir=rtl&lang=ar&theme=…` query params.
+## Data scenarios (`data/scenarios.json`)
+```json
+{ "list": [
+  { "id": "default",  "icon": "🧪", "title": "Full demo", "description": "Baseline seed." },
+  { "id": "new-user", "icon": "🆕", "title": "Brand-new user",
+    "remove": ["trips"], "patch": { "user": { "isNew": true } } } ] }
+```
+`patch` deep-merges over the seed (arrays replace), `remove` deletes dot-paths first.
+Date tokens `{{today}}`, `{{today+3}}`, `{{today-2}}` resolve to real ISO dates at injection —
+"mid-trip today" is literally today. Always keep a `default` entry.
+## Themes (`themes/<id>.json`)
+```json
+{ "id": "default", "title": "Warm",
+  "modes": {
+    "light": { "color": { "accent": "#BF5B24", "bg": "#F7F2EA", "ink": "#241C13", "ink-2": "#6E6152" },
+               "font": { "sans": "-apple-system, sans-serif" }, "radius": { "card": "20px" } },
+    "dark":  { "color": { "accent": "#E1793B", "bg": "#171108", "ink": "#F4EBDD" } } } }
+```
+Flattening: `color.ink-2` → `--color-ink-2` (nested paths join with `-`). `dark` deep-merges
+over `light`, so only list what changes. Style screens **with tokens**, not hard-coded colors,
+and the whole project can be re-themed from JSON — humans do exactly that in the shell's
+🎨 **Theme Lab** (live token editing; Save writes `themes/<id>.json` under `engine serve`),
+so a theme file may change without an agent touching it. Re-read before editing.
+## Strings (`i18n.json` + `Engine.t`) — optional per feature
+Key-first: `{ "slide1.title": { "en": "…", "ar": "…" } }`. Screens call
+`Engine.t('slide1.title')` (placeholders: `Engine.t('greet', {name})`). Fallback: active
+language → `defaultLanguage` → the key. Language switches reload the screen, so ready-time
+binding is always right. Missing translations are validate WARNINGS, never blockers.
+Features without i18n.json simply own their text inline — also fine.
+## Flows (`flows.json`)
+```json
+{ "list": [ { "id": "create-trip", "title": "Create a trip", "icon": "✨",
+  "description": "From empty home to a planned trip.",
+  "steps": [
+    { "screen": "010-home", "note": "Start here — empty state invites planning." },
+    { "screen": "020-wizard", "note": "Seven questions.", "scenario": "new-user" } ] } ] }
+```
+The shell plays these as guided stakeholder walkthroughs (prev/next + note captions).
+A step may pin a `scenario` (and `mode`). Steps must reference existing screens.
+## Embedded apps (app mode)
+A feature with `"type": "app"` embeds a WHOLE single-page app: `src` (project-relative entry
+HTML), `device`, `chrome: "self"|"engine"` (self = the app draws its own status bars), and
+optionally `driver: "driver.js"` — a project-owned script injected into the app that calls
+`AppBridge.register({screens, go, current?, set?, scenarios?})` so sealed apps stay untouched.
+Cooperative apps include `engine/app-bridge.js` themselves. Register via CLI
+(`screenbook app add <src>`) or MCP (`add_app`). Full contract: the skill's
+`references/app-mode.md`. Validation boots the app and visits every reported screen.
+## Review comments
+Humans pin comments on screens in Review Mode; they land in `review/comments.json` with full
+context (screen, scenario, theme, mode, dir, CSS path of the clicked element). Workflow:
+read them (`get_review_comments`), fix the screens, then `resolve_comment` — don't delete.
+## Doing the work
+Prefer the MCP tools (`add_screen`, `update_screen`, `set_data`, `validate`, `screenshot`, …) —
+they validate the contract, stamp `updated`, regenerate manifests and write atomically.
+Editing screen files directly is fine too; afterwards run:
+```
+node engine/cli/screenbook.js manifest    # rescan → manifest.json
+node engine/cli/screenbook.js validate    # static checks + headless render of every screen
+```
+While `node engine/cli/screenbook.js serve` runs (http://127.0.0.1:4600), every save
+live-reloads the browser and manifests regenerate automatically — no cache-busting, ever.
+**Definition of done: `validate` is green** — zero static errors, every screen renders in
+every theme × light/dark × ltr/rtl with zero console errors. Check review comments too.
+Hard rules: never edit `manifest.json` (derived) · never edit `engine/` · never rename a
+screen that other screens `data-go` to (or fix the references + flows in the same change).

package/LICENSE ADDED Viewed

@@ -0,0 +1,21 @@
+MIT License
+Copyright (c) 2026 Abdullah Alhaider
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md ADDED Viewed

@@ -0,0 +1,208 @@
+# ⧉ ScreenBook
+**A static, no-build prototype studio — built for AI agents to author, humans to review.**
+Drop folders of plain HTML screens plus small JSON files into a project and get a navigable,
+device-framed design gallery: iPhone / Android / browser frames, mock-data scenarios, design-token
+themes, dark/light and LTR/RTL toggles, guided demo flows, pinned review comments, and a
+machine-verified self-test — plus a CLI and an MCP server so agents can build screens
+**without ever holding the engine's implementation in context**.
+![The ScreenBook studio — Qahwa demo project](docs/shots/hero-studio.png)
+## Why this exists
+Prototyping with AI agents has a failure mode: the prototype starts as "just an HTML file,"
+grows into a hand-rolled single-page app, and after a month you have a 20k-line runtime where
+**an agent can't touch one screen without reading the whole world** — and neither can you.
+ScreenBook inverts every cause of that rot:
+| Instead of… | ScreenBook does… |
+|---|---|
+| One growing SPA runtime | **One file = one screen.** Full standalone HTML documents; each opens alone in a browser. |
+| Metadata trapped in code | **Metadata as data.** A JSON block inside each screen; indexes are derived, never hand-kept. |
+| App code and viewer code tangled | **A hard engine/app boundary.** Screens know one include (`bridge.js`) and a tiny API. |
+| Hard-coded demo data | **Seed + scenario overlays** with `{{today±N}}` date tokens — "mid-trip today" is literally today. |
+| CSS forks per restyle | **Design tokens as JSON themes**, flattened to CSS variables, dark mode as a delta. |
+| "Trust me, it works" | **A self-test gate**: every screen × theme × light/dark × LTR/RTL must render with zero console errors. |
+| | | |
+|---|---|---|
+| ![Web dashboard frame](docs/shots/web-dashboard.png) | ![Android frame, dark](docs/shots/android-dark.png) | ![Two-theme re-skin](docs/shots/theming-noir.png) |
+| Browser-chrome frame, scenario-driven data | Android frame, dark mode | Same screens, different theme JSON |
+## Setup
+Requirements: **Node ≥ 18**. For headless validation/screenshots: Google Chrome (or see below).
+Full guides live in **[docs/](docs/README.md)** — getting started & prerequisites, the
+studio tour, the authoring guide, CLI/MCP references, app mode, troubleshooting.
+```bash
+# 1. Put the engine into your project (this repo IS the engine — folder name matters):
+git clone https://github.com/cs4alhaider/screenbook my-prototypes/engine
+#    (npm: @cs4alhaider/screenbook — after first publish)
+# 2. Scaffold the project around it:
+cd my-prototypes
+node engine/cli/screenbook.js init .
+# 3. Run the studio:
+node engine/cli/screenbook.js serve .
+# → http://127.0.0.1:4600  · live reload · manifests auto-regenerate · no cache, ever
+```
+`init` creates `app.config.json`, a starter theme, a `welcome` feature with one screen — and
+drops **`CLAUDE.md`** (the authoring contract) plus a **packaged agent skill** into the project,
+so any AI agent that opens it immediately knows the rules.
+For headless `validate` / `screenshot`, install the one dev dependency once:
+```bash
+cd engine && npm i        # playwright-core — drives your installed Chrome
+# no Chrome? use:  npm i -D playwright && npx playwright install chromium
+```
+Try the shipped examples first:
+```bash
+node engine/cli/screenbook.js serve engine/examples/qahwa       # ☕ coffee app: iOS + Android + web
+node engine/cli/screenbook.js serve engine/examples/tokens-lab  # 🎨 two themes, live token lab
+```
+## How it helps — a five-minute story
+**1. A screen is one honest file.** No framework, no build, one conventional include:
+```html
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <script type="application/json" id="screen-meta">
+  { "title": "Cart", "description": "Lines, totals, checkout.",
+    "order": 30, "device": "ios", "status": "wip" }
+  </script>
+  <script src="../../../engine/bridge.js"></script>
+</head>
+<body>
+  <button data-go="040-checkout">Checkout</button>
+  <script>
+    Engine.ready(function (data) { /* seed ⊕ active scenario, dates resolved */ });
+  </script>
+</body>
+</html>
+```
+Save it under `features/shop/screens/030-cart.html` — it's already in the sidebar, framed as an
+iPhone, styled by your tokens (`var(--color-accent)`), live-reloading on every save.
+**2. Colors are a panel, not a hunt.** The 🎨 **Theme Lab** shows every token the active theme
+defines and edits them **live against the hosted screens** — color pickers for hex values,
+plain fields for fonts/radii/spacing, a theme switcher, Export, and one-click **Save** straight
+back to `themes/<id>.json` while `serve` runs:
+![Theme Lab — live token editing](docs/shots/theme-lab.png)
+**3. States are data, not branches.** Add a scenario and the 🎭 dropdown demos your empty state:
+```json
+{ "id": "first-visit", "icon": "🆕", "title": "First visit",
+  "remove": ["order"], "patch": { "user": { "isNew": true } } }
+```
+**4. Demos tell themselves.** A `flows.json` walkthrough gives stakeholders a guided,
+captioned story — each step can pin its own scenario, and every state is a shareable URL:
+`…#shop/030-cart?scenario=first-visit&mode=dark&dir=rtl`.
+**5. Review closes the loop.** Reviewers pin comments directly on screens; each pin captures
+screen, scenario, theme, mode, direction and the exact element clicked, and syncs to
+`review/comments.json` — where agents read and resolve them.
+**6. The machine decides "done".**
+```bash
+node engine/cli/screenbook.js validate .
+# ✓ static contract checks
+# ✓ 28/28 render checks green across 7 screens   (× themes × dark/light × ltr/rtl, zero console errors)
+```
+## The agent workflow (the actual point)
+Register the MCP server with your agent — for Claude Code:
+```bash
+claude mcp add screenbook -- npx -y @cs4alhaider/screenbook mcp --root .
+# or from a checkout:  claude mcp add screenbook -- node engine/cli/screenbook.js mcp --root .
+```
+Then ask for work in plain language:
+> *"Add a checkout screen to the shop feature: summary card, payment method list from the seed,
+> a pay button that toasts. Match the existing screens. Validate and show me a screenshot."*
+The agent never opens `engine/` — it calls `list_screens` → `get_screen` (steals an existing
+screen's idioms) → `add_screen` (which **lints the contract, stamps the date, regenerates the
+manifest, writes atomically**) → `validate` (full headless render matrix) → `screenshot`
+(a PNG inside the real device frame). Human taste, machine discipline.
+18 tools: `list_features · list_screens · get_screen · add_screen · update_screen ·
+remove_screen · add_feature · get_data · set_data · get_theme · set_theme · get_flows ·
+set_flows · get_review_comments · resolve_comment · validate · screenshot · add_app`.
+## CLI
+| Command | Does |
+|---|---|
+| `init [dir] [--name X]` | Scaffold a project + authoring contract + agent skill |
+| `serve [dir] [--port]` | Studio server: live reload, auto-manifests, review sync, `/engine/*` mounted from this package, no-cache always |
+| `manifest [dir]` | Rescan screens → regenerate derived `manifest.json` per feature |
+| `validate [dir] [--static] [--json]` | Contract checks + headless render of every screen × theme × mode × direction |
+| `screenshot [dir] --screen f/s [--mode light,dark] [--dir ltr,rtl] [--scenario id] [--theme id]` | Device-framed PNGs (comma lists = matrix) |
+## What's in this repo
+```
+bridge.js        the ONLY file screens include (dual-mode: shell-driven / standalone)
+index.html + shell/   the studio: frames, dropdowns, flows, review mode, selftest
+core/            shared project API (scan, manifests, atomic writes, validate, serve, browser)
+cli/ · mcp/      two thin faces over the same core
+CLAUDE.md        the authoring contract agents follow (scaffolded into projects)
+skill/           packaged agent skill + reference docs (scaffolded into projects)
+examples/        qahwa (☕ 3-device demo app) · tokens-lab (🎨 multi-theme lab)
+test/            42-test suite: unit + serve E2E + CLI E2E   →  npm test
+TESTING.md       the full test map and gaps
+```
+RTL and Arabic are first-class (`dir` flipping, per-screen language dictionaries):
+<img src="docs/shots/rtl-arabic.png" width="320" alt="RTL Arabic screen in dark mode">
+## App mode — embed entire existing apps
+Already have a single-page prototype? Don't rewrite it — **embed it**:
+```bash
+node engine/cli/screenbook.js app add legacy/index.html --device ios --chrome self
+```
+The app's views appear in the sidebar as screens, deep links work, dark/RTL/scenario toggles
+drive it live. Cooperative apps include `engine/app-bridge.js` and register themselves
+(`examples/spa-demo`); sealed apps get a small project-owned **driver** injected at runtime —
+**zero changes to the app's own files**. `validate` boots each app and visits every screen it
+reports, still demanding zero console errors.
+![A sealed legacy app running inside the studio](docs/shots/app-mode.png)
+## Status
+**v1 — complete and machine-verified** (studio, 4 frames, scenarios, flows, Theme Lab,
+review mode, selftest, CLI, MCP, agent onboarding, example projects, 44-test suite).
+**v2 — in progress**: app mode ✓ shipped (above) · theme write-back ✓ (Theme Lab Save) ·
+i18n strings ✓ (`Engine.t` + key-first per-feature `i18n.json`, fallback chain, validate
+warnings on gaps) · npm packaging next.
+Born inside [Rahhal](https://github.com/cs4alhaider)'s product lab, where the predecessor
+prototypes grew to ~22k lines and taught every lesson this engine inverts.
+License: MIT.

package/TESTING.md ADDED Viewed

@@ -0,0 +1,54 @@
+# ScreenBook — testing map
+> 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.**
+## How to run everything
+```bash
+cd engine
+npm i                # once — playwright-core (drives your installed Chrome)
+npm test             # unit + E2E suites (node:test, ~58 tests, ~60s incl. browser)
+# full browser matrix on every project that ships in this repo:
+node cli/screenbook.js validate ..                        # Rahhal (repo root)
+node cli/screenbook.js validate examples/qahwa
+node cli/screenbook.js validate examples/tokens-lab
+```
+## Layers
+| Layer | File(s) | Covers |
+|-------|---------|--------|
+| **EngineKit unit** | `test/kit.test.js` | The REAL `bridge.js` loaded in a Node VM exactly as the shell loads it: deepMerge (arrays replace), scenario overlay (remove→patch order, seed immutability), `{{today±N}}` resolution incl. embedded strings, token flattening, dark-over-light theme merge, fallback safety. |
+| **Meta contract unit** | `test/meta.test.js` | Meta block parse errors, `withMeta` round-trip, `updated` stamping incl. the manual-override rule, every `lintScreen` violation, `data-go` extraction, filename-prefix order fallback. |
+| **Atomic fs unit** | `test/fsx.test.js` | Atomic write (no temp leftovers, parent dirs), change-detection writes, JSON fallback/error paths. |
+| **Project API unit** | `test/project.test.js` | Scan/sort, manifest regen stability (no churn), screen CRUD guards (lint reject, dup, missing feature), data/theme/flows shape validation + config registration, review comment filters/resolve, `staticValidate` catching dangling `data-go`, missing/stale manifests, broken flow refs. |
+| **Serve E2E** | `test/serve.test.js` | Real HTTP on an ephemeral port: health, `/` redirect, `/engine/*` package mount, path-traversal refusal, no-cache headers, review GET/POST → disk, **Theme-Lab write-back** (`POST /__sb/theme/:id` → file, bad-shape/bad-id 400s), and the **live-reload pipeline**: raw file write → SSE event → debounced manifest auto-regen. |
+| **CLI E2E** | `test/cli.test.js` | Spawns the real binary per command: `init` (full scaffold incl. CLAUDE.md + skill, `--force` guard), `manifest` (regenerated → unchanged), `validate --static --json` (green → red on a broken screen, exit codes), `serve` (parses printed URL, fetches studio/health/screen), `validate` **full browser** on the init-scaffolded project, `screenshot` (PNG on disk), error paths (no project → exit 2, bad `--screen` spec → exit 2). |
+| **Browser matrix** | shell `?selftest=1` via `validate` | Every screen × theme × light/dark × ltr/rtl: bridge handshake, `Engine.ready` fires, meta present, **zero console errors** (screen AND shell). This is the machine-verified fixed point gate. |
+| **App-mode gate** | same `?selftest=1` pass | Every `type:"app"` feature: app must register (hello) within 20s, report ≥1 screen, and **every reported screen is visited once** — zero console errors (driver failures surface as `driver <fn>:` rows; adapters may declare narrow `ignoreErrors` for third-party noise, e.g. MapLibre teardown). |
+| **Shell interaction E2E** | `test/shell.test.js` | Real Chrome driving the studio against a purpose-built fixture: boot + data binding, live dark/RTL env, `data-go` → deep link, scenario overlay (`remove`) on reload, flow deep links + stepping with pinned scenarios, `Engine.state` across screens + reset chip, **review pinning → disk → resolve**, Theme-Lab live edit reaching the screen, **app mode** (embedded cooperative app: screen list, navigation, env follow). |
+| **MCP session E2E** | `test/mcp.test.js` | Spawns the real stdio server against an init-scaffolded project: initialize (protocol echo + instructions), 18-tool surface, contract enforcement (lint reject, dup reject), full CRUD incl. `add_app`, static validate through the tool, JSON-RPC error shapes (-32601/-32602). |
+## Projects that double as fixtures
+| 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) |
+| `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 |
+| `screenbook init` output | The scaffold itself (validated headlessly inside `test/cli.test.js` on every run); `app add` covered too |
+## Known gaps (candidates for the next hardening pass)
+- ~~Shell interaction suite~~ → **promoted to `test/shell.test.js`** (2026-07-18).
+- ~~MCP server E2E~~ → **promoted to `test/mcp.test.js`** (2026-07-18).
+- Keyboard navigation (↑↓/jk, `/`, flow arrows) not yet asserted in the shell suite.
+- 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`.

package/app-bridge.js ADDED Viewed

@@ -0,0 +1,131 @@
+/*
+ * ScreenBook app-bridge — app mode (EN-20). Runs INSIDE an embedded
+ * single-page app and speaks the sba:* postMessage protocol with the shell.
+ *
+ * Two ways it gets into the app page:
+ *   cooperative — the SPA includes this file itself and calls
+ *                 AppBridge.register(adapter) from its own code
+ *   driven      — the shell injects this file, then injects a project-owned
+ *                 driver script that calls register(); the app's own files
+ *                 stay byte-untouched (how the certified prototypes plug in)
+ *
+ * adapter = {
+ *   title?:       string
+ *   screens():    [{ id, title, description?, group? }]   (required)
+ *   go(id):       navigate the app to a screen             (required)
+ *   current?():   current screen id
+ *   set?(env):    { mode?, dir?, lang?, scenario?, theme?, vars? } applied live
+ *   scenarios?(): [{ id, icon?, title, description? }]     (maps the app's own 🎭)
+ * }
+ * Call AppBridge.navigated(id) whenever the app navigates on its own.
+ */
+(function () {
+  'use strict';
+  var shell = window.parent !== window ? window.parent : null;
+  var adapter = null;
+  var ignoreErrors = [];
+  function send(type, payload) {
+    if (!shell) return;
+    var msg = { type: type };
+    if (payload) Object.keys(payload).forEach(function (k) { msg[k] = payload[k]; });
+    try { shell.postMessage(msg, '*'); } catch (e) { /* shell gone */ }
+  }
+  function reportError(message) {
+    var text = String(message);
+    /* adapters may declare known-benign noise from a sealed app's own libraries
+       (adapter.ignoreErrors: [RegExp|string]) — declared, visible, reviewable */
+    for (var i = 0; i < ignoreErrors.length; i++) {
+      if (ignoreErrors[i].test(text)) return;
+    }
+    send('sba:console-error', { message: text });
+  }
+  function guarded(fn, label) {
+    try { return fn(); }
+    catch (err) {
+      reportError('driver ' + label + ': ' + (err && err.message ? err.message : err));
+      return undefined;
+    }
+  }
+  function normalizeScreens(list) {
+    return (list || []).map(function (s) {
+      if (typeof s === 'string') return { id: s, title: s };
+      return { id: s.id, title: s.title || s.id, description: s.description, group: s.group };
+    }).filter(function (s) { return s.id; });
+  }
+  function pushScreens() {
+    if (!adapter) return;
+    send('sba:screens', { screens: normalizeScreens(guarded(function () { return adapter.screens(); }, 'screens()')) });
+  }
+  window.AppBridge = {
+    register: function (a) {
+      adapter = a || {};
+      ignoreErrors = (adapter.ignoreErrors || []).map(function (p) {
+        return p instanceof RegExp ? p : new RegExp(String(p));
+      });
+      var capabilities = ['go'];
+      if (adapter.set) capabilities.push('env');
+      if (adapter.scenarios) capabilities.push('scenarios');
+      var hello = { title: adapter.title || document.title || 'App', capabilities: capabilities };
+      if (adapter.scenarios) {
+        hello.scenarios = guarded(function () { return adapter.scenarios(); }, 'scenarios()') || [];
+      }
+      send('sba:hello', hello);
+      pushScreens();
+      var cur = adapter.current && guarded(function () { return adapter.current(); }, 'current()');
+      if (cur) send('sba:current', { id: cur });
+    },
+    navigated: function (id) { send('sba:current', { id: id }); },
+    refreshScreens: pushScreens
+  };
+  window.addEventListener('message', function (e) {
+    var msg = e.data;
+    if (!msg || typeof msg.type !== 'string' || !adapter) return;
+    switch (msg.type) {
+      case 'sba:go':
+        guarded(function () { adapter.go(msg.id); }, 'go(' + msg.id + ')');
+        send('sba:current', { id: msg.id });
+        break;
+      case 'sba:env':
+        if (adapter.set) {
+          guarded(function () {
+            adapter.set({ mode: msg.mode, dir: msg.dir, lang: msg.lang, scenario: msg.scenario, theme: msg.theme, vars: msg.vars });
+          }, 'set(env)');
+        }
+        break;
+      case 'sba:ping':
+        send('sba:pong', {});
+        break;
+    }
+  });
+  /* console/error forwarding so `validate` can hold apps to zero errors */
+  if (shell) {
+    window.addEventListener('error', function (e) {
+      if (e.target && e.target !== window && e.target.tagName) {
+        reportError('Resource failed: <' + e.target.tagName.toLowerCase() + '> ' + (e.target.src || e.target.href || ''));
+      } else {
+        reportError((e.message || 'Script error') + (e.filename ? ' (' + e.filename.split('/').pop() + ':' + e.lineno + ')' : ''));
+      }
+    }, true);
+    window.addEventListener('unhandledrejection', function (e) {
+      reportError('Unhandled rejection: ' + (e.reason && e.reason.message ? e.reason.message : e.reason));
+    });
+    var origConsoleError = console.error;
+    console.error = function () {
+      reportError(Array.prototype.map.call(arguments, function (a) {
+        if (typeof a === 'string') return a;
+        if (a && a.stack) return String(a.stack);
+        try { return JSON.stringify(a); } catch (e) { return String(a); }
+      }).join(' '));
+      return origConsoleError.apply(console, arguments);
+    };
+  }
+})();