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/examples/tokens-lab/themes/paper.json ADDED Viewed

@@ -0,0 +1,32 @@
+{
+  "id": "paper",
+  "title": "Paper",
+  "modes": {
+    "light": {
+      "color": {
+        "accent": "#2F6FED",
+        "bg": "#F7F6F3",
+        "card": "#FFFFFF",
+        "ink": "#1B1A17",
+        "ink-2": "#6E6A61",
+        "line": "#E6E2D8"
+      },
+      "font": {
+        "sans": "-apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif",
+        "serif": "ui-serif, 'New York', Georgia, serif"
+      },
+      "radius": { "card": "16px", "chip": "999px" },
+      "space": { "page": "20px" }
+    },
+    "dark": {
+      "color": {
+        "accent": "#6E9BFF",
+        "bg": "#15161A",
+        "card": "#1E2026",
+        "ink": "#EDEDF2",
+        "ink-2": "#9DA0AB",
+        "line": "#2E3138"
+      }
+    }
+  }
+}

package/index.html ADDED Viewed

@@ -0,0 +1,50 @@
+<!DOCTYPE html>
+<html lang="en" data-shell="light">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>ScreenBook</title>
+  <link rel="icon" href="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 100 100'%3E%3Crect x='8' y='8' width='84' height='84' rx='20' fill='%235B5BD6'/%3E%3Crect x='26' y='24' width='48' height='36' rx='6' fill='white'/%3E%3Crect x='26' y='66' width='48' height='8' rx='4' fill='white' opacity='.7'/%3E%3C/svg%3E">
+  <link rel="stylesheet" href="shell/shell.css">
+  <script>window.__SCREENBOOK_SHELL__ = true;</script>
+  <script src="bridge.js"></script>
+</head>
+<body>
+  <header class="topbar" id="topbar">
+    <div class="brand">
+      <span class="brand-mark">⧉</span>
+      <span class="brand-name">ScreenBook</span>
+      <span class="brand-sep">/</span>
+      <span class="brand-project" id="project-name">…</span>
+    </div>
+    <div class="topbar-controls" id="controls"></div>
+  </header>
+  <div class="workspace" id="workspace">
+    <aside class="sidebar" id="sidebar">
+      <div class="sidebar-feature" id="sidebar-feature"></div>
+      <div class="sidebar-search">
+        <input type="search" id="search" placeholder="Search screens…" autocomplete="off" spellcheck="false">
+      </div>
+      <nav class="screen-list" id="screen-list"></nav>
+      <footer class="sidebar-foot">
+        <span class="serve-badge" id="serve-badge" title="Static server — review comments stay in localStorage">○ static</span>
+        <a class="foot-link" id="selftest-link" href="?selftest=1">Self-test</a>
+      </footer>
+    </aside>
+    <main class="canvas" id="canvas">
+      <div class="stage" id="stage"></div>
+      <div class="flowbar" id="flowbar" hidden></div>
+    </main>
+    <aside class="theme-panel" id="theme-panel" hidden></aside>
+    <aside class="review-panel" id="review-panel" hidden></aside>
+  </div>
+  <div class="shell-toasts" id="shell-toasts"></div>
+  <div class="selftest-overlay" id="selftest-overlay" hidden></div>
+  <script type="module" src="shell/main.js"></script>
+</body>
+</html>

package/mcp/server.js ADDED Viewed

@@ -0,0 +1,366 @@
+#!/usr/bin/env node
+/* ScreenBook MCP server — stdio JSON-RPC 2.0, newline-delimited (EN-18).
+   Zero dependencies; shares engine/core/ with the CLI. Agents use these
+   tools to author screens without ever reading engine internals (EN-22).
+   Usage:  node engine/mcp/server.js [--root <project-dir>]                 */
+import path from 'node:path';
+import readline from 'node:readline';
+import { fileURLToPath } from 'node:url';
+import {
+  resolveRoot, readConfig, listFeatureIds, scanFeature,
+  getScreen, addScreen, updateScreen, removeScreen, addFeature, addApp,
+  getData, setData, getTheme, setTheme, getFlows, setFlows,
+  getComments, resolveComment, staticValidate
+} from '../core/project.js';
+const ENGINE_DIR = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const VERSION = '0.1.0';
+const rootFlagIx = process.argv.indexOf('--root');
+const rootArg = rootFlagIx > -1 ? process.argv[rootFlagIx + 1] : undefined;
+const ROOT = await resolveRoot(rootArg);
+if (!ROOT) {
+  console.error(`screenbook-mcp: no app.config.json found${rootArg ? ` under ${rootArg}` : ''} — pass --root <project-dir>`);
+  process.exit(2);
+}
+/* ---------------- tool definitions ---------------- */
+const SCREEN_CONTRACT =
+  'A screen is one full standalone HTML document: <!DOCTYPE html>, a required ' +
+  '<script type="application/json" id="screen-meta"> block ({title, description, order, ' +
+  'device: ios|android|web|none, status?, tags?, group?, statusBar?: light|dark, updated?}), and one ' +
+  '<script src="../../../engine/bridge.js"></script> include. Use CSS vars from the active theme ' +
+  '(--color-*, --font-*, --radius-*, --space-*, --safe-top, --safe-bottom), bind mock data with ' +
+  'Engine.ready(cb → cb(data)), navigate with data-go="<screen-id>" attributes, share state via ' +
+  'Engine.state.get/set/subscribe, notify with Engine.toast(msg). Screens must render sensibly ' +
+  'with empty data. The updated date is stamped automatically on save.';
+const TOOLS = [
+  {
+    name: 'list_features',
+    description: 'List all features (folders under features/) with their metadata and screen counts.',
+    inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+    run: async () => {
+      const out = [];
+      for (const id of await listFeatureIds(ROOT)) {
+        const { meta, screens } = await scanFeature(ROOT, id);
+        out.push({ id, ...meta, screens: screens.length });
+      }
+      return { features: out, config: await readConfig(ROOT) };
+    }
+  },
+  {
+    name: 'list_screens',
+    description: 'List the screens of one feature (id, title, description, order, device, status, tags, updated).',
+    inputSchema: {
+      type: 'object', required: ['feature'],
+      properties: { feature: { type: 'string', description: 'feature id (folder name)' } },
+      additionalProperties: false
+    },
+    run: async ({ feature }) => {
+      const { screens } = await scanFeature(ROOT, feature);
+      return { feature, screens };
+    }
+  },
+  {
+    name: 'get_screen',
+    description: 'Read one screen: parsed meta + the full HTML source.',
+    inputSchema: {
+      type: 'object', required: ['feature', 'screen'],
+      properties: { feature: { type: 'string' }, screen: { type: 'string' } },
+      additionalProperties: false
+    },
+    run: ({ feature, screen }) => getScreen(ROOT, feature, screen)
+  },
+  {
+    name: 'add_screen',
+    description: `Create a new screen file (fails if it exists). ${SCREEN_CONTRACT}`,
+    inputSchema: {
+      type: 'object', required: ['feature', 'screen', 'html'],
+      properties: {
+        feature: { type: 'string' },
+        screen: { type: 'string', description: 'screen id = filename without .html; numeric prefix orders the sidebar (e.g. 030-checkout)' },
+        html: { type: 'string', description: 'the complete standalone HTML document' }
+      },
+      additionalProperties: false
+    },
+    run: ({ feature, screen, html }) => addScreen(ROOT, feature, screen, html)
+  },
+  {
+    name: 'update_screen',
+    description: `Replace an existing screen's HTML (fails if missing; read-then-write). ${SCREEN_CONTRACT}`,
+    inputSchema: {
+      type: 'object', required: ['feature', 'screen', 'html'],
+      properties: {
+        feature: { type: 'string' },
+        screen: { type: 'string' },
+        html: { type: 'string', description: 'the complete new HTML document (send the whole file, not a diff)' }
+      },
+      additionalProperties: false
+    },
+    run: ({ feature, screen, html }) => updateScreen(ROOT, feature, screen, html)
+  },
+  {
+    name: 'remove_screen',
+    description: 'Delete a screen file and refresh the manifest. Check flows.json references afterwards.',
+    inputSchema: {
+      type: 'object', required: ['feature', 'screen'],
+      properties: { feature: { type: 'string' }, screen: { type: 'string' } },
+      additionalProperties: false
+    },
+    run: ({ feature, screen }) => removeScreen(ROOT, feature, screen)
+  },
+  {
+    name: 'add_feature',
+    description: 'Create a feature folder (feature.json, empty data/seed.json + scenarios.json + flows.json, screens/) and register it in app.config.json.',
+    inputSchema: {
+      type: 'object', required: ['id'],
+      properties: {
+        id: { type: 'string', description: 'lowercase-dashed folder name, e.g. trip-planning' },
+        title: { type: 'string' },
+        icon: { type: 'string', description: 'one emoji' },
+        description: { type: 'string' },
+        order: { type: 'number' }
+      },
+      additionalProperties: false
+    },
+    run: (args) => addFeature(ROOT, args)
+  },
+  {
+    name: 'add_app',
+    description: 'Register an existing single-page app as an embedded app-type feature (app mode). The shell will drive it over postMessage; a scaffolded driver.js (injected, project-owned) teaches ScreenBook the app\'s internals so the app\'s own files stay untouched. Fill in the driver\'s screens()/go()/set() afterwards, then run validate.',
+    inputSchema: {
+      type: 'object', required: ['src'],
+      properties: {
+        src: { type: 'string', description: 'project-relative path to the app\'s index.html' },
+        id: { type: 'string' },
+        title: { type: 'string' },
+        icon: { type: 'string' },
+        description: { type: 'string' },
+        device: { type: 'string', enum: ['ios', 'android', 'web', 'none'] },
+        chrome: { type: 'string', enum: ['self', 'engine'], description: 'self = app draws its own status/home bars (engine shows bezel only)' },
+        driver: { type: 'boolean', default: true, description: 'false for cooperative apps that include engine/app-bridge.js themselves' }
+      },
+      additionalProperties: false
+    },
+    run: (args) => addApp(ROOT, { ...args, driver: args.driver !== false })
+  },
+  {
+    name: 'get_data',
+    description: "Read a feature's mock data + strings: seed.json, scenarios.json (scenario = {id, icon, title, description, patch?, remove?}; patch deep-merges over seed, remove deletes dot-paths; {{today±N}} date tokens), and i18n.json (key-first: { \"key\": { \"en\": \"…\", \"ar\": \"…\" } } for Engine.t).",
+    inputSchema: {
+      type: 'object', required: ['feature'],
+      properties: { feature: { type: 'string' } },
+      additionalProperties: false
+    },
+    run: ({ feature }) => getData(ROOT, feature)
+  },
+  {
+    name: 'set_data',
+    description: "Write a feature's seed, scenarios and/or i18n strings. Scenarios: { list: [{id, icon, title, description, patch?, remove?}, …] } — keep an id:'default' baseline. i18n (key-first): { \"slide1.title\": { \"en\": \"…\", \"ar\": \"…\" } } — screens read them with Engine.t('slide1.title', {vars}); missing translations fall back defaultLanguage → key and surface as validate warnings.",
+    inputSchema: {
+      type: 'object', required: ['feature'],
+      properties: {
+        feature: { type: 'string' },
+        seed: { type: 'object', description: 'full replacement for seed.json (omit to keep)' },
+        scenarios: { type: 'object', description: 'full replacement for scenarios.json (omit to keep)' },
+        i18n: { type: 'object', description: 'full replacement for i18n.json, key-first shape (omit to keep)' }
+      },
+      additionalProperties: false
+    },
+    run: ({ feature, seed, scenarios, i18n }) => setData(ROOT, feature, { seed, scenarios, i18n })
+  },
+  {
+    name: 'get_theme',
+    description: 'Read a theme (design tokens JSON). Omit id for the default. Tokens flatten to CSS vars: color.ink-2 → --color-ink-2; modes.dark deep-merges over modes.light.',
+    inputSchema: {
+      type: 'object',
+      properties: { id: { type: 'string' } },
+      additionalProperties: false
+    },
+    run: ({ id } = {}) => getTheme(ROOT, id)
+  },
+  {
+    name: 'set_theme',
+    description: 'Write a theme JSON ({id, title, modes: {light: {color/font/radius/space…}, dark: {…}}}) and register it in app.config.json.',
+    inputSchema: {
+      type: 'object', required: ['id', 'theme'],
+      properties: { id: { type: 'string' }, theme: { type: 'object' } },
+      additionalProperties: false
+    },
+    run: ({ id, theme }) => setTheme(ROOT, id, theme)
+  },
+  {
+    name: 'get_flows',
+    description: "Read a feature's flows.json — named walkthroughs the shell can play: { list: [{id, title, icon, description, steps: [{screen, note?, scenario?}]}] }.",
+    inputSchema: {
+      type: 'object', required: ['feature'],
+      properties: { feature: { type: 'string' } },
+      additionalProperties: false
+    },
+    run: ({ feature }) => getFlows(ROOT, feature)
+  },
+  {
+    name: 'set_flows',
+    description: "Write a feature's flows.json (full replacement, same shape as get_flows). Steps may pin a scenario for that step.",
+    inputSchema: {
+      type: 'object', required: ['feature', 'flows'],
+      properties: { feature: { type: 'string' }, flows: { type: 'object' } },
+      additionalProperties: false
+    },
+    run: ({ feature, flows }) => setFlows(ROOT, feature, flows)
+  },
+  {
+    name: 'get_review_comments',
+    description: 'Read Review-Mode comments pinned by humans in the shell. Each carries note, reviewer, screen, scenario, theme, mode, dir, cssPath of the clicked element, created date, resolved flag.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        feature: { type: 'string', description: 'filter to one feature' },
+        unresolvedOnly: { type: 'boolean', default: false }
+      },
+      additionalProperties: false
+    },
+    run: (args = {}) => getComments(ROOT, args)
+  },
+  {
+    name: 'resolve_comment',
+    description: 'Mark a review comment resolved (or reopen with resolved:false) after addressing it.',
+    inputSchema: {
+      type: 'object', required: ['id'],
+      properties: { id: { type: 'string' }, resolved: { type: 'boolean', default: true } },
+      additionalProperties: false
+    },
+    run: ({ id, resolved = true }) => resolveComment(ROOT, id, resolved)
+  },
+  {
+    name: 'validate',
+    description: 'Validate the project. mode "static" = fast file/contract checks; "full" (default) also boots a headless browser and renders every screen × theme × light/dark × ltr/rtl asserting zero console errors. Run full validation before calling work done.',
+    inputSchema: {
+      type: 'object',
+      properties: { mode: { type: 'string', enum: ['static', 'full'], default: 'full' } },
+      additionalProperties: false
+    },
+    run: async ({ mode = 'full' } = {}) => {
+      const s = await staticValidate(ROOT);
+      if (mode === 'static' || !s.ok) return { ok: s.ok && mode === 'static', static: s, browser: mode === 'static' ? undefined : 'skipped — fix static errors first' };
+      const { runBrowserSelftest } = await import('../core/browser.js');
+      const b = await runBrowserSelftest({ root: ROOT, engineDir: ENGINE_DIR });
+      return {
+        ok: s.ok && b.ok,
+        static: s,
+        browser: {
+          ok: b.ok, total: b.total, passed: b.passed, failed: b.failed,
+          failures: b.rows.filter((r) => !r.ok).map((r) => ({ screen: `${r.feature}/${r.screen}`, combo: `${r.theme}·${r.mode}·${r.dir}`, fail: r.fail })),
+          shellErrors: b.shellErrors
+        }
+      };
+    }
+  },
+  {
+    name: 'screenshot',
+    description: 'Render a screen inside its device frame to a PNG (headless Chrome). Returns the file path; set return_image:true to also get the image inline.',
+    inputSchema: {
+      type: 'object', required: ['feature', 'screen'],
+      properties: {
+        feature: { type: 'string' },
+        screen: { type: 'string' },
+        mode: { type: 'string', enum: ['light', 'dark'], default: 'light' },
+        dir: { type: 'string', enum: ['ltr', 'rtl'], default: 'ltr' },
+        lang: { type: 'string' },
+        scenario: { type: 'string' },
+        theme: { type: 'string' },
+        return_image: { type: 'boolean', default: false }
+      },
+      additionalProperties: false
+    },
+    run: async (args, extra) => {
+      await getScreen(ROOT, args.feature, args.screen);
+      const { screenshot } = await import('../core/browser.js');
+      const outDir = path.join(ROOT, 'review', 'screenshots');
+      const files = await screenshot({
+        root: ROOT, engineDir: ENGINE_DIR, outDir,
+        combos: [{ feature: args.feature, screen: args.screen, mode: args.mode, dir: args.dir, lang: args.lang, scenario: args.scenario, theme: args.theme }]
+      });
+      if (args.return_image) extra.imagePath = files[0];
+      return { files };
+    }
+  }
+];
+/* ---------------- JSON-RPC over stdio ---------------- */
+function reply(id, result) {
+  process.stdout.write(JSON.stringify({ jsonrpc: '2.0', id, result }) + '\n');
+}
+function replyError(id, code, message) {
+  process.stdout.write(JSON.stringify({ jsonrpc: '2.0', id, error: { code, message } }) + '\n');
+}
+async function handle(msg) {
+  const { id, method, params } = msg;
+  const isRequest = id !== undefined && id !== null;
+  switch (method) {
+    case 'initialize':
+      reply(id, {
+        protocolVersion: typeof params?.protocolVersion === 'string' ? params.protocolVersion : '2024-11-05',
+        capabilities: { tools: { listChanged: false } },
+        serverInfo: { name: 'screenbook', version: VERSION },
+        instructions:
+          `ScreenBook prototype studio for the project at ${ROOT}. ` +
+          `Projects are convention-over-configuration: app.config.json, themes/<id>.json (design tokens), ` +
+          `features/<id>/{feature.json, flows.json, data/seed.json, data/scenarios.json, screens/*.html}. ` +
+          `${SCREEN_CONTRACT} ` +
+          `Typical loop: list_features → get_screen (steal an existing screen's shape) → add_screen/update_screen → validate. ` +
+          `Never edit manifest.json (derived) or anything under engine/.`
+      });
+      return;
+    case 'notifications/initialized':
+    case 'notifications/cancelled':
+      return;
+    case 'ping':
+      if (isRequest) reply(id, {});
+      return;
+    case 'tools/list':
+      reply(id, { tools: TOOLS.map(({ name, description, inputSchema }) => ({ name, description, inputSchema })) });
+      return;
+    case 'tools/call': {
+      const tool = TOOLS.find((t) => t.name === params?.name);
+      if (!tool) return replyError(id, -32602, `unknown tool: ${params?.name}`);
+      try {
+        const extra = {};
+        const result = await tool.run(params.arguments || {}, extra);
+        const content = [{ type: 'text', text: JSON.stringify(result, null, 2) }];
+        if (extra.imagePath) {
+          const { readFile } = await import('node:fs/promises');
+          content.push({ type: 'image', data: (await readFile(extra.imagePath)).toString('base64'), mimeType: 'image/png' });
+        }
+        reply(id, { content, isError: false });
+      } catch (err) {
+        reply(id, { content: [{ type: 'text', text: `Error: ${err.message}` }], isError: true });
+      }
+      return;
+    }
+    default:
+      if (isRequest) replyError(id, -32601, `method not found: ${method}`);
+  }
+}
+const rl = readline.createInterface({ input: process.stdin, terminal: false });
+rl.on('line', (line) => {
+  const text = line.trim();
+  if (!text) return;
+  let msg;
+  try { msg = JSON.parse(text); } catch { return replyError(null, -32700, 'parse error'); }
+  handle(msg).catch((err) => {
+    if (msg.id !== undefined) replyError(msg.id, -32603, `internal error: ${err.message}`);
+    else console.error('screenbook-mcp:', err);
+  });
+});
+rl.on('close', () => process.exit(0));
+console.error(`screenbook-mcp ready · root=${ROOT} · ${TOOLS.length} tools`);

package/package.json ADDED Viewed

@@ -0,0 +1,57 @@
+{
+  "name": "@cs4alhaider/screenbook",
+  "version": "0.1.0",
+  "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.",
+  "type": "module",
+  "bin": {
+    "screenbook": "cli/screenbook.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "MIT",
+  "author": "Abdullah Alhaider (cs4alhaider)",
+  "keywords": [
+    "prototyping",
+    "design",
+    "mockups",
+    "mcp",
+    "ai-agents",
+    "design-tokens",
+    "no-build",
+    "prototype-studio"
+  ],
+  "files": [
+    "bridge.js",
+    "app-bridge.js",
+    "index.html",
+    "shell/",
+    "core/",
+    "cli/",
+    "mcp/",
+    "skill/",
+    "examples/",
+    "docs/",
+    "CLAUDE.md",
+    "TESTING.md"
+  ],
+  "devDependencies": {
+    "playwright-core": "^1.45.0"
+  },
+  "scripts": {
+    "test": "node --test",
+    "serve": "node cli/screenbook.js serve ..",
+    "validate": "node cli/screenbook.js validate .."
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cs4alhaider/screenbook.git"
+  },
+  "homepage": "https://github.com/cs4alhaider/screenbook#readme",
+  "bugs": {
+    "url": "https://github.com/cs4alhaider/screenbook/issues"
+  }
+}

package/shell/flowplayer.js ADDED Viewed

@@ -0,0 +1,85 @@
+/* Flow player — plays named walkthroughs from a feature's flows.json (EN-26).
+   A step may pin a scenario; leaving the flow restores the previous scenario. */
+import { store, feature, set } from './store.js';
+const bar = document.getElementById('flowbar');
+let savedScenario = null;
+export function activeFlow() {
+  const f = feature();
+  if (!f || !store.ui.flow) return null;
+  return (f.flows.list || []).find((fl) => fl.id === store.ui.flow) || null;
+}
+export function startFlow(flowId) {
+  const f = feature();
+  const flow = (f?.flows.list || []).find((fl) => fl.id === flowId);
+  if (!flow || !flow.steps?.length) return;
+  savedScenario = store.ui.scenario;
+  set({ flow: flowId, flowStep: 0, ...stepPatch(flow, 0) });
+}
+export function stopFlow() {
+  if (!store.ui.flow) return;
+  const restore = savedScenario;
+  savedScenario = null;
+  set({ flow: null, flowStep: 0, ...(restore ? { scenario: restore } : {}) });
+}
+export function stepFlow(delta) {
+  const flow = activeFlow();
+  if (!flow) return;
+  const next = store.ui.flowStep + delta;
+  if (next < 0 || next >= flow.steps.length) return;
+  set({ flowStep: next, ...stepPatch(flow, next) });
+}
+function stepPatch(flow, index) {
+  const step = flow.steps[index] || {};
+  const patch = {};
+  if (step.screen) patch.screen = step.screen;
+  if (step.scenario) patch.scenario = step.scenario;
+  if (step.mode) patch.mode = step.mode;
+  return patch;
+}
+/* Re-sync flow state after a hash-driven boot (deep link into a flow). */
+export function resumeFromHash() {
+  const flow = activeFlow();
+  if (!flow) return;
+  savedScenario = savedScenario ?? store.ui.scenario;
+  const i = Math.min(store.ui.flowStep, flow.steps.length - 1);
+  set({ flowStep: i, ...stepPatch(flow, i) });
+}
+function esc(s) {
+  return String(s ?? '').replace(/[&<>"]/g, (c) => (
+    { '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;' }[c]
+  ));
+}
+export function renderFlowbar() {
+  const flow = activeFlow();
+  if (!flow) {
+    bar.hidden = true;
+    bar.innerHTML = '';
+    return;
+  }
+  const i = store.ui.flowStep;
+  const step = flow.steps[i] || {};
+  bar.hidden = false;
+  bar.innerHTML =
+    `<button class="fb-nav" data-nav="-1" ${i === 0 ? 'disabled' : ''}>←</button>` +
+    `<div class="fb-body">` +
+    `<div class="fb-title">${esc(flow.icon || '▶')} ${esc(flow.title || flow.id)}` +
+    `<span class="fb-count">${i + 1} / ${flow.steps.length}</span></div>` +
+    (step.note ? `<div class="fb-note">${esc(step.note)}</div>` : '') +
+    `</div>` +
+    `<button class="fb-nav" data-nav="1" ${i === flow.steps.length - 1 ? 'disabled' : ''}>→</button>` +
+    `<button class="fb-close" title="Exit flow">✕</button>`;
+  bar.querySelectorAll('.fb-nav').forEach((btn) =>
+    btn.addEventListener('click', () => stepFlow(parseInt(btn.dataset.nav, 10))));
+  bar.querySelector('.fb-close').addEventListener('click', stopFlow);
+}