@cs4alhaider/screenbook 0.1.0 → 0.2.1

package/README.md

@@ -1,208 +1,191 @@
-# ⧉ 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>
 
-**A static, no-build prototype studio — built for AI agents to author, humans to review.**
+**A design workspace for AI agents to present to humans — fully offline, agent-agnostic, and owned by you.**
 
-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**.
+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 — Qahwa demo project](docs/shots/hero-studio.png)
+![The ScreenBook studio](docs/shots/hero-studio-light.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.
+```bash
+npm install -g @cs4alhaider/screenbook
+```
 
-ScreenBook inverts every cause of that rot:
+## Why I built this
 
-| 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. |
+I design and ship products with AI agents every day. The prototyping phase kept failing me in
+the same way: designs lived inside chat windows. A concept would look great in a conversation,
+and then reality arrived — I needed *forty* screens, not one. I needed to see the empty state
+and the busy state. I needed Arabic right-to-left and dark mode. I needed my co-founder to
+point at a button and say "this one, move it." I needed all of it next week, again, revised.
 
-| | | |
-|---|---|---|
-| ![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 |
+Chat canvases aren't built for that. Every iteration re-generates a wall of code inside a
+conversation that will eventually scroll away. Nothing is versioned. Nothing runs offline.
+Reviews happen in screenshots over WhatsApp. And when the design is finally "done," it's
+trapped — there's no clean way to hand it to the next stage of work.
 
-## Setup
+So I built the thing I needed: a studio where **screens are plain files on my disk**, agents
+do the labor, humans do the taste, and the finished prototype becomes the specification for
+the real app.
 
-Requirements: **Node ≥ 18**. For headless validation/screenshots: Google Chrome (or see below).
+## Why not just design in Claude?
 
-Full guides live in **[docs/](docs/README.md)** — getting started & prerequisites, the
-studio tour, the authoring guide, CLI/MCP references, app mode, troubleshooting.
+Keep using Claude — that's the point. ScreenBook isn't a competitor to your AI; it's the
+**workspace your AI works in**. The difference is where the output lives and what you can do
+with it:
 
-```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)
+| Designing in a chat window | Designing in ScreenBook |
+|---|---|
+| One artifact per conversation; multi-screen products fall apart | A whole product: features → screens, organized like your app actually is |
+| Output trapped in the thread; gone when context resets | Plain HTML + JSON files in **your git repo** — diff, branch, revert, forever |
+| Needs the vendor's website, account, and connection | Runs from a folder on your machine — **works fully offline** |
+| Tied to one AI vendor's canvas | **Any agent** that speaks MCP (Claude Code today; the protocol is open) — or no agent at all, it's just files |
+| One rendering, usually desktop-ish | Real device frames: iPhone, Android, browser — plus dark/light, LTR/RTL, and named data states you switch live |
+| "Looks right" is the only test | A machine gate: every screen must render in every theme × mode × direction with **zero console errors** |
+| Feedback = screenshots and paragraphs | **Pin comments on the screen itself**; your agent reads them, fixes, and marks them resolved |
+| Regenerates everything each round | Agent edits one small file per screen — faster, cheaper, and nothing else breaks |
 
-# 2. Scaffold the project around it:
-cd my-prototypes
-node engine/cli/screenbook.js init .
+## What working in it feels like
 
-# 3. Run the studio:
-node engine/cli/screenbook.js serve .
-# → http://127.0.0.1:4600  · live reload · manifests auto-regenerate · no cache, ever
-```
+A concrete example — a specialty-coffee ordering app (it ships in `examples/qahwa`, so you can
+open exactly this):
 
-`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.
+**1. You brief your agent, it builds screens.**
 
-For headless `validate` / `screenshot`, install the one dev dependency once:
+> *"Create an ordering feature: menu with our drinks from the seed data, a drink detail screen
+> with a size/milk customization sheet, a cart, and a live order-status screen. iPhone frames,
+> match our warm theme."*
 
-```bash
-cd engine && npm i        # playwright-core — drives your installed Chrome
-# no Chrome? use:  npm i -D playwright && npx playwright install chromium
-```
+The agent creates each screen as its own small HTML file. They appear in your studio's sidebar
+as they land — framed in an iPhone, styled by your design tokens, wired to your mock data.
 
-Try the shipped examples first:
+**2. You review like it's a real app.** Click through the flow. Flip the 🎭 scenario dropdown
+from *Regular morning* to *First visit* — the same screens now show the empty state honestly.
+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.
 
-```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
-```
+![Scenario-driven data on a real dashboard frame](docs/shots/web-dashboard-light.png)
 
-## 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>
-```
+**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,
+and the exact element under the cursor. Then:
 
-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.
+> *"Read the open review comments, apply the fixes, and resolve them."*
 
-**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:
+Your agent does exactly that — it has tools for reading pins and marking them resolved.
 
-![Theme Lab — live token editing](docs/shots/theme-lab.png)
+**4. The finished screen becomes the spec for the real app.** This is the step that pays for
+everything. When a screen survives review, it's a complete, self-contained HTML file: exact
+layout and spacing, your design tokens, final copy in both languages, all interaction states.
+Now point your agent at it:
 
-**3. States are data, not branches.** Add a scenario and the 🎭 dropdown demos your empty state:
+> *"Take `features/order/screens/030-cart.html` and build it as a SwiftUI view. Use our design
+> tokens for colors and spacing. Preserve the empty state exactly as the `first-visit` scenario
+> shows it."*
 
-```json
-{ "id": "first-visit", "icon": "🆕", "title": "First visit",
-  "remove": ["order"], "patch": { "user": { "isNew": true } } }
-```
+The prototype you approved *is* the design document — no Figma-to-code guesswork, no "it looked
+different in the mockup." The same works for Jetpack Compose, React Native, Flutter, or web
+components.
 
-**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`.
+![One toggle from LTR light to RTL dark](docs/shots/rtl-arabic-dark.png)
 
-**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.
+## Two commands to your own studio
 
-**6. The machine decides "done".**
+Requirements: Node ≥ 18. Nothing else — no cloning, no per-project installs. (The automated
+screen checks use your installed Chrome, or download a headless browser once by themselves.)
 
 ```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)
+npm install -g @cs4alhaider/screenbook    # once, ever
+
+cd any-project-you-are-working-on
+screenbook init                           # creates .screenbook/ — that's the whole setup
+screenbook serve                          # → http://127.0.0.1:4600 — live reload, no cache headaches
 ```
 
-## The agent workflow (the actual point)
+`init` creates a single **`.screenbook/`** folder in your project — the self-contained source
+of truth for the prototype: your **`brief.md`** (requirements — agents read it first), screens,
+mock data, scenarios, themes, review comments, and the agent authoring contract. Commit it or
+gitignore it; that's your call. The studio itself always runs from the installed package —
+your project never carries runtime code.
 
-Register the MCP server with your agent — for Claude Code:
+Connect your agent (Claude Code shown; any MCP client works):
 
 ```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**:
+Want to explore first? Complete demo projects ship inside the package:
 
 ```bash
-node engine/cli/screenbook.js app add legacy/index.html --device ios --chrome self
+screenbook serve "$(npm root -g)/@cs4alhaider/screenbook/examples/qahwa"       # ☕ iPhone + Android + web
+screenbook serve "$(npm root -g)/@cs4alhaider/screenbook/examples/tokens-lab"  # 🎨 two themes, edited live
 ```
 
-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.
+## What's in the box
+
+- **Device frames** — iPhone (Dynamic Island, status bar), Android (punch-hole), browser
+  chrome, or bare; scaled to fit, screenshot-ready.
+- **Data scenarios** — named states over your mock data (*brand-new user*, *mid-trip*,
+  *after close*) with date tokens like `{{today+3}}`, so time-based demos are always true.
+- **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-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
+  and resolves.
+- **Multilingual by design** — per-feature strings files with side-by-side translations;
+  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/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.
+- **CLI + 18 agent tools** — everything above is scriptable and agent-operable:
+  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 — or browse them on the website:
+**[cs4alhaider.github.io/screenbook](https://cs4alhaider.github.io/screenbook/)**.
+
+## The shape of a project
 
-![A sealed legacy app running inside the studio](docs/shots/app-mode.png)
-
-## Status
+```
+my-product/                          ← your real project, any stack, untouched
+└── .screenbook/                     ← everything ScreenBook, in one folder
+    ├── brief.md                     your requirements — agents read this FIRST
+    ├── app.config.json              product name · features · devices · themes · languages
+    ├── CLAUDE.md                    the authoring contract agents follow
+    ├── themes/default.json          design tokens (light + dark)
+    ├── features/
+    │   └── order/
+    │       ├── feature.json         title, icon, order
+    │       ├── flows.json           demo walkthroughs
+    │       ├── i18n.json            strings, side-by-side languages
+    │       ├── data/seed.json       mock data
+    │       ├── data/scenarios.json  named data states
+    │       └── screens/
+    │           ├── 010-menu.html    ← one file = one screen
+    │           └── 020-drink.html
+    └── review/comments.json         pinned feedback, read by your agent
+```
 
-**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.
+Everything is a plain file an intern could read. That's the whole trick: it's why agents stay
+fast and cheap (they touch one small file at a time), why git can review every change, why it
+works on a plane, and why the approved prototype can walk straight into production.
 
-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.
+## Status & license
 
-License: MIT.
+v0.2.0 — studio, frames, scenarios, themes, flows, review, i18n, app mode, self-test gate,
+CLI, MCP server, docs, and a 64-test suite; built and verified end-to-end with AI agents,
+reviewed by a human with taste. MIT © [Abdullah Alhaider](https://github.com/cs4alhaider).

package/bridge.js

@@ -12,7 +12,7 @@
 (function () {
   'use strict';
 
-  var VERSION = '0.1.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);