@cs4alhaider/screenbook 0.1.0

package/skill/references/app-mode.md

@@ -0,0 +1,77 @@
+# App mode — embedding whole single-page apps
+
+An app-type feature puts an ENTIRE existing SPA inside the ScreenBook shell: its views appear
+in the sidebar as screens, deep links work, dark/RTL/scenario toggles drive it — without
+rewriting the app as file-per-screen.
+
+## Registering
+
+CLI (preferred): `screenbook app add <src> [--id x --title "X" --icon 🧩 --device ios --chrome self|engine --cooperative]`
+or during scaffold: `screenbook init . --app path/to/index.html`. MCP: `add_app {src, …}`.
+
+This writes an app-type feature:
+
+```json
+{ "id": "legacy-ios", "title": "Legacy app", "icon": "🧩", "order": 9,
+  "type": "app",
+  "src": "apps/legacy/index.html",
+  "device": "ios",
+  "chrome": "self",
+  "driver": "driver.js" }
+```
+
+- `src` — project-root-relative path to the app's entry HTML (served same-origin).
+- `device` — which bezel frames it (`ios`/`android`/`web`/`none`).
+- `chrome` — `"self"` when the app draws its own status/home bars (engine shows bezel only);
+  `"engine"` for full engine chrome.
+- `driver` — present for **driven** (sealed) apps; absent for **cooperative** apps.
+
+## Two integration modes, one protocol
+
+**Cooperative** — the app includes the runtime itself and registers:
+
+```html
+<script src="../engine/app-bridge.js"></script>
+<script>
+  AppBridge.register({
+    title: 'Notes',
+    screens: () => [{ id: 'inbox', title: 'Inbox', description: '…', group: '…' }],
+    go: (id) => router.show(id),
+    current: () => router.current,
+    set: (env) => {           /* { mode, dir, lang, scenario, theme, vars } */
+      document.body.classList.toggle('dark', env.mode === 'dark');
+    },
+    scenarios: () => [{ id: 'empty', title: 'Empty state' }]   // optional: maps the app's own 🎭
+  });
+</script>
+```
+
+Call `AppBridge.navigated(id)` whenever the app navigates on its own (the shell follows).
+An adapter may also declare `ignoreErrors: [/pattern/]` — known-benign console noise from a
+sealed app's own libraries (e.g. a CDN map library's teardown race). Use narrowly and comment
+why; everything else still fails validation.
+
+**Driven** — the app's files stay byte-untouched. A `driver.js` in the FEATURE folder (not the
+app!) is injected by the shell after the app loads, and makes the same `AppBridge.register`
+call by reaching into the app's own globals (registries, router, toggles). `app add` scaffolds
+a commented template. Drivers may poll briefly if the app boots async.
+
+## Behavior in the shell
+
+- Sidebar lists the app-reported screens (title/description/group; no status pills or dates).
+- Screen click / deep link `#feature/screen` → `sba:go` into the app; in-app navigation
+  reflects back into the URL.
+- Mode/dir/lang/theme/scenario changes arrive live via `set(env)` — `env.vars` carries the
+  flattened theme tokens if the app wants to adopt them. No reloads.
+- If the driver reports `scenarios()`, they populate the 🎭 dropdown for this feature.
+- flows.json works over app screen ids too (steps play through the app).
+
+## Validation gate (what `validate` requires)
+
+Static: `src` exists · declared driver file exists. Browser: the app must **register within
+20s, report ≥1 screen, and every reported screen is visited once — zero console errors
+anywhere** (the runtime forwards the app's console.error/uncaught errors). A broken driver
+fails loudly with `driver <fn>: <message>` rows.
+
+Debug tips: veil says "App hasn't registered" → driver didn't run or threw before register
+(check the browser console via `serve`); zero screens → `screens()` returned `[]`.

package/skill/references/bridge-api.md

@@ -0,0 +1,55 @@
+# Bridge API (`window.Engine`)
+
+The bridge is the single include every screen carries. It is dual-mode: driven by the shell
+over postMessage when embedded, self-booting when the screen is opened directly.
+
+## Lifecycle
+
+```js
+Engine.ready(function (data) {
+  // called once theme vars + data are applied; `data` === Engine.data
+});
+```
+
+- Register any time — late callbacks fire immediately (async microtask).
+- On scenario/data changes the shell reloads the iframe, so `ready` re-runs cleanly.
+- Mode / direction / language / theme changes apply LIVE (no reload): CSS vars and the
+  `<html>` attributes just change. React to them with CSS, not JS, whenever possible.
+
+## Surface
+
+| API | Detail |
+|-----|--------|
+| `Engine.data` | Frozen object: seed ⊕ scenario (`patch`/`remove`), `{{today±N}}` already resolved. Never mutate; copy what you need. |
+| `Engine.state` | Cross-screen KV on localStorage: `get(key, fallback)` · `set(key, value)` (JSON-serializable) · `subscribe(key, cb) → unsubscribe` · `keys()`. Fires across iframes via storage events. Namespaced `sb:state:*`; the shell's ↺ button clears it. |
+| `Engine.go(id)` | Same as clicking `data-go="id"`. Same-feature navigation only. |
+| `Engine.toast(msg)` | Token-styled toast at the safe-area bottom, auto-dismisses. |
+| `Engine.t(key, vars?)` | Strings from the feature's `i18n.json` (key-first): active language → `defaultLanguage` → the key itself; `{name}` placeholders interpolate from `vars`. Language switches reload the screen, so binding at ready-time is always correct. See `i18n.md`. |
+| `Engine.env` | `{ mode: 'light'\|'dark', dir: 'ltr'\|'rtl', lang, device, scenario, theme, embedded }`. Read-only snapshot; attributes on `<html>` mirror it live. |
+| `Engine.meta` | This screen's parsed meta block. |
+| `Engine.kit` | The pure helpers (deepMerge, applyScenario, resolveDateTokens, themeVars) if you ever need them. |
+
+## Environment on `<html>`
+
+The bridge sets: `data-mode="light|dark"` · `data-device` · `dir` · `lang` · all theme CSS
+vars · `--safe-top` / `--safe-bottom`.
+
+Idioms:
+
+```css
+/* dark-specific rule when tokens aren't enough */
+html[data-mode="dark"] .hero { filter: brightness(.9); }
+
+/* RTL-safe spacing — prefer logical properties over left/right */
+.row { padding-inline-start: 16px; margin-inline-end: 8px; }
+```
+
+```js
+/* language-aware copy — screens own their strings (no engine i18n in v1) */
+var copy = Engine.env.lang === 'ar' ? AR : EN;
+```
+
+## Errors
+
+Uncaught errors, failed resource loads, unhandled rejections and `console.error` calls are
+forwarded to the shell and FAIL the self-test. Keep the console clean — that's the contract.

package/skill/references/cli-mcp.md

@@ -0,0 +1,53 @@
+# CLI + MCP
+
+Both are thin faces over the same core (scan, parse meta, regenerate manifests, atomic
+writes, stamp `updated`, validate). Prefer MCP tools when available — they validate the
+contract and keep manifests fresh automatically.
+
+## CLI (`node engine/cli/screenbook.js …` or the `screenbook` bin)
+
+| Command | Does |
+|---------|------|
+| `init [dir] [--name X] [--force] [--app <src>]` | Scaffold a project: app.config.json, starter theme + welcome feature, review/, CLAUDE.md, `.claude/skills/screenbook/`. `--app` also registers an existing SPA in that folder as an embedded app. |
+| `app add <src> [dir] [--id --title --icon --device --chrome self\|engine --cooperative]` | Embed an existing single-page app as an app-type feature; scaffolds an injectable driver template unless `--cooperative`. |
+| `serve [dir] [--port 4600]` | Static server with: `/engine/*` mounted from the package (projects don't need a local engine copy), live reload over SSE, automatic manifest regen on screen saves, `review/comments.json` disk sync, no-cache headers always. `/` redirects to the studio. |
+| `manifest [dir]` | Rescan `features/*/screens/*.html` → regenerate each `manifest.json` (only writes on change). |
+| `validate [dir] [--static] [--json]` | Static contract checks; then (unless `--static`) headless Chrome renders **every screen × theme × light/dark × ltr/rtl**, asserting Engine.ready fires, meta is present, zero console errors. Exit code 0 = green. |
+| `screenshot [dir] --screen f/s [--mode light,dark] [--dir ltr,rtl] [--scenario id] [--theme id] [--lang xx] [--out dir]` | PNG(s) of the screen inside its real device frame (comma lists make a matrix). Default out: `review/screenshots/`. |
+
+Browser commands need `playwright-core` (uses installed Chrome) or `playwright` installed
+in `engine/`.
+
+## MCP server (`node engine/mcp/server.js --root <project>`, stdio)
+
+Read: `list_features` · `list_screens {feature}` · `get_screen {feature, screen}` ·
+`get_data {feature}` · `get_theme {id?}` · `get_flows {feature}` ·
+`get_review_comments {feature?, unresolvedOnly?}`
+
+Write: `add_screen {feature, screen, html}` · `update_screen {feature, screen, html}`
+(both validate the contract, stamp `updated`, regen manifest; add fails on existing,
+update fails on missing) · `remove_screen` · `add_feature {id, title, icon, description}` ·
+`add_app {src, id?, device?, chrome?, driver?}` (embed an existing SPA — see app-mode.md) ·
+`set_data {feature, seed?, scenarios?}` · `set_theme {id, theme}` · `set_flows {feature, flows}` ·
+`resolve_comment {id, resolved?}`
+
+Verify: `validate {mode: "static"|"full"}` · `screenshot {feature, screen, mode?, dir?,
+scenario?, theme?, lang?, return_image?}`
+
+Register with Claude Code:
+```
+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 .
+```
+
+## Serve endpoints (for tooling)
+
+`GET /__sb/health` → `{screenbook: true}` · `GET /__sb/events` → SSE change stream ·
+`GET|POST /__sb/review/comments` → review pins. The shell auto-detects these — under any
+other static server it falls back to localStorage for review comments.
+
+## Gates
+
+1. `validate` static errors → fix before anything else (broken meta, missing bridge, bad refs).
+2. `validate` full → the machine-verified fixed point. Screens with console errors are bugs.
+3. Unresolved review comments → the humans' queue for you; resolve them explicitly.

package/skill/references/flows.md

@@ -0,0 +1,44 @@
+# Flows (`features/<f>/flows.json`)
+
+Flows are named walkthrough sequences the shell plays for stakeholders — a guided story
+with captions, not a test script.
+
+## Schema
+
+```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 — the empty state invites planning.",
+        "scenario": "new-user" },
+      { "screen": "020-wizard",
+        "note": "Seven questions shape the trip DNA." },
+      { "screen": "030-overview" } ] } ] }
+```
+
+Step fields:
+- `screen` (required) — a screen id in the same feature. Validation fails on dangling refs.
+- `note` (optional) — caption shown in the player bar; write it as presenter narration.
+- `scenario` (optional) — pins the 🎭 scenario from this step onward; the previous scenario
+  is restored when the flow exits.
+- `mode` (optional) — pin `light`/`dark` for a step the same way.
+
+## Player behavior
+
+- The ▶ dropdown in the shell lists flows of the current feature; picking one starts at
+  step 1 and shows a floating bar: ← / → , "2 / 5", the note, and ✕ to exit.
+- Arrow keys step while a flow is active (direction-aware in RTL).
+- Deep links carry the flow: `#feature/screen?flow=create-trip&step=1` — share a URL that
+  drops a stakeholder into the middle of the story.
+- Manually clicking another screen in the sidebar exits the flow.
+
+## Writing good flows
+
+- 3–7 steps; one idea per step; notes in the product's voice ("Votes decide, not WhatsApp").
+- Lead with the scenario that makes the step's point (empty state → first slide, busy state
+  → dashboard step).
+- End on the money shot (publish, confirmation, the AI acting).

package/skill/references/i18n.md

@@ -0,0 +1,52 @@
+# i18n strings (`features/<f>/i18n.json` + `Engine.t`)
+
+Opt-in per feature. Without an i18n.json, screens simply own their text (the v1 way —
+still perfectly legal for single-language features).
+
+## The strings file — key-first
+
+```json
+{
+  "slide1.title": { "en": "One home for the whole trip", "ar": "بيت واحد للرحلة كلها" },
+  "slide1.next":  { "en": "Continue", "ar": "متابعة" },
+  "greet":        { "en": "{name}, your next story is waiting", "ar": "يا {name}، حكايتك القادمة بانتظارك" }
+}
+```
+
+Every key holds all its translations side by side — reviewers see the Arabic next to the
+English, and gaps are visually obvious. Dot-namespace keys by screen or concern
+(`slide1.*`, `common.*`).
+
+## Using it in screens
+
+```js
+Engine.t('slide1.title')                 // active language, resolved at ready-time
+Engine.t('greet', { name: 'Lina' })      // {var} placeholders interpolate
+```
+
+A tidy pattern (see the Rahhal onboarding feature): put the FULL key in markup and fill in
+one pass —
+
+```html
+<h1 data-copy="slide1.title"></h1>
+<script>
+  Engine.ready(function () {
+    document.querySelectorAll('[data-copy]').forEach(function (el) {
+      el.textContent = Engine.t(el.getAttribute('data-copy'));
+    });
+  });
+</script>
+```
+
+## Semantics
+
+- **Fallback chain**: requested language → project `defaultLanguage` → the key string itself.
+  Screens never crash on missing copy.
+- **Language switches reload the screen** (same as scenario changes) — `Engine.t` binds at
+  ready-time; no re-render API needed. `dir` flips automatically for RTL languages.
+- **Validation warns, never blocks**: `validate` reports keys missing a configured language,
+  languages not in `app.config.json`, and `Engine.t("key")` calls with no entry — as
+  warnings. Authoring stays unblocked; gaps stay visible.
+- Standalone screens fetch `../i18n.json` themselves and honor `?lang=ar`.
+- Read/write via MCP: `get_data` / `set_data {feature, i18n}` (full replacement, shape-checked).
+- Embedded apps (app mode) own their i18n — the shell just forwards `env.lang` to the driver.

package/skill/references/scenarios.md

@@ -0,0 +1,45 @@
+# Mock data + scenarios
+
+Every feature owns its data: `data/seed.json` (the baseline) and `data/scenarios.json`
+(named lifecycle states layered over it). The shell's 🎭 dropdown switches scenarios;
+screens receive the merged result in `Engine.ready(data)`.
+
+## seed.json
+
+Plain JSON, shaped however the feature needs. Model the *demo-complete* state — the one
+that makes screens look alive.
+
+## scenarios.json
+
+```json
+{ "list": [
+  { "id": "default",  "icon": "🧪", "title": "Full demo",
+    "description": "Baseline seed, untouched." },
+
+  { "id": "new-user", "icon": "🆕", "title": "Brand-new user",
+    "description": "Empty everything.",
+    "remove": ["trips", "user.firstName"],
+    "patch": { "user": { "isNew": true } } },
+
+  { "id": "mid-trip", "icon": "🟢", "title": "Mid-trip — Day 3",
+    "patch": { "trips": { "italy": {
+      "phase": "Traveling",
+      "startDate": "{{today-2}}", "endDate": "{{today+7}}" } } } } ] }
+```
+
+Semantics, in order:
+1. `remove`: array of dot-paths deleted from a copy of the seed (`"trips.italy.hotel"`).
+2. `patch`: deep-merged over the result — objects merge recursively, **arrays and scalars
+   replace wholesale** (to change one array item, patch the whole array).
+3. Date tokens: any string may contain `{{today}}`, `{{today+3}}`, `{{today-2}}` —
+   resolved to real ISO `YYYY-MM-DD` dates at injection, so time-relative states are
+   always literally true when demoed.
+
+## Designing good scenarios
+
+- Always keep `id: "default"` (no patch/remove) — the baseline the self-test uses.
+- Model *lifecycle*, not variants: brand-new / mid-journey / done / edge (expired, offline,
+  over-budget). Each should visibly change at least one screen.
+- Screens must survive every scenario: guard bindings (`d.user && d.user.firstName`) —
+  the empty-state scenario is where prototypes usually break.
+- Flows can pin a scenario per step, so build scenarios with the demo story in mind.

package/skill/references/screen-contract.md

@@ -0,0 +1,83 @@
+# Screen contract
+
+One screen = one standalone HTML file at `features/<feature>/screens/<id>.html`.
+The id is the filename without `.html`; a numeric prefix (`010-home`) is the sidebar-order
+fallback and keeps directory listings readable. Prefer ids like `010-home`, `020-wizard`.
+
+## Anatomy
+
+```html
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>Cart</title>
+
+  <!-- 1. REQUIRED meta block — the file is the source of truth (manifest is derived) -->
+  <script type="application/json" id="screen-meta">
+  {
+    "title": "Cart",
+    "description": "Line items, totals, checkout entry.",
+    "order": 30,
+    "device": "ios",
+    "status": "wip",
+    "tags": ["commerce"],
+    "group": "Purchase",
+    "statusBar": "dark"
+  }
+  </script>
+
+  <!-- 2. REQUIRED bridge — the ONLY engine include, exact relative path -->
+  <script src="../../../engine/bridge.js"></script>
+
+  <!-- 3. Optional shared feature look/helpers (explicit opt-in per screen) -->
+  <link rel="stylesheet" href="shared.css">
+  <script src="shared.js" defer></script>
+
+  <style>/* screen-local styles, tokens only: var(--color-bg) etc. */</style>
+</head>
+<body>
+  <main>…plain HTML…</main>
+  <button data-go="040-checkout">Checkout</button>
+  <script>
+    Engine.ready(function (data) { /* bind data */ });
+  </script>
+</body>
+</html>
+```
+
+## Meta fields
+
+| Field | Required | Notes |
+|-------|----------|-------|
+| `title` | ✅ | Sidebar row title. |
+| `description` | recommended | One sentence; shows under the title. |
+| `order` | recommended | Number; ties broken by filename. Missing → numeric filename prefix. |
+| `device` | recommended | `ios` 393×852 · `android` 412×915 · `web` 1280×760 · `none` bare. Default `none`. |
+| `devices` | optional | Variant array (e.g. `["ios","android"]`) — ONE file rendered in several frames; the stage shows switcher chips, the self-test renders every listed device, the Device filter matches any of them. `device` stays the primary/default. |
+| `status` | optional | Free string; `draft` / `wip` / `ready` / `review` get colored pills. |
+| `tags` | optional | Array of short strings, searchable. |
+| `group` | optional | Sidebar section header (screens with the same group cluster). |
+| `statusBar` | optional | `light` or `dark` — forces status-bar/home-bar ink over full-bleed art. |
+| `updated` | auto | Stamped on every CLI/MCP save. Set manually only to override the stamp. |
+
+## Layout rules
+
+- The device frame draws all hardware (status bar, island/punch-hole, home/gesture bar,
+  browser chrome). Screens NEVER draw hardware — instead pad:
+  `padding-top: calc(var(--safe-top) + …)` and `padding-bottom: calc(var(--safe-bottom) + …)`.
+  (`--safe-top`/`--safe-bottom` are `59px/34px` on ios, `42px/24px` on android, `0/0` elsewhere.)
+- Sheets, modals, popovers live INSIDE the screen file as hidden markup; toggle them with
+  screen-local JS. They are not separate sidebar entries.
+- Screens must render sensibly with empty `Engine.data` / `Engine.state` (guard your bindings).
+- Zero-JS static screens are legal. CDN libraries are fine (iframe isolation).
+- Duplicating markup between screens is expected and accepted — no partials/templating.
+  Shared look belongs in `shared.css` / `shared.js`, included explicitly.
+
+## Standalone mode
+
+Every screen opens directly (no shell): the bridge self-loads `app.config.json`, the default
+theme and `data/seed.json`, then honors query params `?scenario=…&mode=dark&dir=rtl&lang=ar&theme=…`.
+`data-go` falls back to plain `<id>.html` links (query string preserved). If nothing is
+fetchable, fallback tokens keep the screen legible — it should never look broken alone.

package/skill/references/tokens.md

@@ -0,0 +1,56 @@
+# Design tokens (`themes/<id>.json`)
+
+Themes are JSON, flattened by the engine to CSS custom properties. Users restyle the whole
+project without touching CSS files.
+
+## Schema
+
+```json
+{
+  "id": "default",
+  "title": "Rahhal Warm",
+  "modes": {
+    "light": {
+      "color":  { "accent": "#BF5B24", "bg": "#F7F2EA", "card": "#FFFFFF",
+                  "ink": "#241C13", "ink-2": "#6E6152", "line": "#EAE1D2" },
+      "font":   { "sans": "-apple-system, 'SF Pro Text', sans-serif",
+                  "serif": "ui-serif, 'New York', Georgia, serif" },
+      "radius": { "card": "20px", "chip": "999px" },
+      "space":  { "page": "16px" }
+    },
+    "dark": {
+      "color": { "accent": "#E1793B", "bg": "#171108", "card": "#231A10",
+                 "ink": "#F4EBDD", "ink-2": "#BCAC96", "line": "#37291A" }
+    }
+  }
+}
+```
+
+## Rules
+
+- **Flattening**: nested paths join with `-` and get a `--` prefix:
+  `color.ink-2` → `--color-ink-2`, `radius.card` → `--radius-card`. Any group name works
+  (`elevation`, `duration`, …) — the four above are the convention screens rely on.
+- **Dark = delta**: `modes.dark` deep-merges over `modes.light`; list only what changes.
+- Values are raw CSS strings — keep units inside the value (`"20px"`, not `20`).
+- Naming is DTCG-compatible (group/key), so tokens can later import/export to design tools.
+
+## Discipline for screens
+
+- Color/typography/radius/spacing come from `var(--…)`. Hard-coded values are reserved for
+  one-off art (e.g. full-bleed brand gradients on onboarding slides).
+- Always provide both modes for colors you add; test with the shell's dark toggle.
+- The conventional core set every theme should define:
+  `color.accent/bg/card/ink/ink-2/line`, `font.sans` (+ `serif` if used),
+  `radius.card/chip`, `space.page`.
+- Register new themes in `app.config.json` `themes` array (`set_theme` does this for you);
+  the first entry is the default.
+
+## Theme Lab (in the shell)
+
+The 🎨 chip in the studio topbar opens the **Theme Lab**: every token of the active theme as
+editable rows (color pickers for hex values), applied to the hosted screens **live**. Humans
+use it to explore palettes; **Save** writes `themes/<id>.json` back to disk when `engine serve`
+is running (Export downloads the JSON otherwise). If a reviewer hands you an exported theme
+JSON or a saved change, treat the file on disk as the source of truth — read it with
+`get_theme` before further edits.