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/core/meta.js ADDED Viewed

@@ -0,0 +1,94 @@
+/* Screen meta block: parse / rewrite the
+   <script type="application/json" id="screen-meta">…</script> inside a
+   screen's HTML (EN-8 — metadata lives in the file; manifest is derived). */
+const META_RE = /(<script[^>]*\bid=["']screen-meta["'][^>]*>)([\s\S]*?)(<\/script>)/i;
+const BRIDGE_RE = /<script[^>]*\bsrc=["'][^"']*\bbridge\.js["'][^>]*>/i;
+export const DEVICES = ['ios', 'android', 'web', 'none'];
+export function hasBridgeInclude(html) {
+  return BRIDGE_RE.test(html);
+}
+/* → { meta, error } — meta null when missing/broken */
+export function parseMeta(html) {
+  const m = META_RE.exec(html);
+  if (!m) return { meta: null, error: 'no <script id="screen-meta"> block' };
+  try {
+    const meta = JSON.parse(m[2]);
+    if (typeof meta !== 'object' || meta === null || Array.isArray(meta)) {
+      return { meta: null, error: 'meta block is not a JSON object' };
+    }
+    return { meta, error: null };
+  } catch (err) {
+    return { meta: null, error: `meta block is not valid JSON: ${err.message}` };
+  }
+}
+/* Replace the meta block's JSON, preserving the surrounding tags. */
+export function withMeta(html, meta) {
+  const json = JSON.stringify(meta, null, 2)
+    .split('\n')
+    .map((line) => '  ' + line)
+    .join('\n');
+  return html.replace(META_RE, (_, open, _body, close) => `${open}\n${json}\n  ${close}`);
+}
+/*
+ * Stamp `updated` (EN-10): set to today on save, but respect a manual
+ * override — if the incoming HTML deliberately carries a different date
+ * than the previous version of the file, keep the author's value.
+ */
+export function stampUpdated(html, { previousUpdated, today }) {
+  const { meta } = parseMeta(html);
+  if (!meta) return html;
+  const incoming = meta.updated;
+  const manualOverride = incoming && previousUpdated && incoming !== previousUpdated;
+  if (manualOverride) return html;
+  meta.updated = today;
+  return withMeta(html, meta);
+}
+/* Validation used by add/update/validate. Returns array of problems. */
+export function lintScreen(html, { id } = {}) {
+  const problems = [];
+  const { meta, error } = parseMeta(html);
+  if (error) problems.push(error);
+  if (meta) {
+    if (!meta.title || typeof meta.title !== 'string') problems.push('meta.title is required');
+    if (meta.device && !DEVICES.includes(meta.device)) {
+      problems.push(`meta.device "${meta.device}" — must be one of ${DEVICES.join(' / ')}`);
+    }
+    if (meta.devices !== undefined) {
+      if (!Array.isArray(meta.devices) || !meta.devices.length) {
+        problems.push('meta.devices must be a non-empty array (device variants)');
+      } else {
+        for (const d of meta.devices) {
+          if (!DEVICES.includes(d)) problems.push(`meta.devices contains "${d}" — must be one of ${DEVICES.join(' / ')}`);
+        }
+      }
+    }
+    if (meta.order !== undefined && typeof meta.order !== 'number') problems.push('meta.order must be a number');
+    if (meta.tags !== undefined && !Array.isArray(meta.tags)) problems.push('meta.tags must be an array');
+  }
+  if (!hasBridgeInclude(html)) problems.push('missing <script src="…/engine/bridge.js"> include');
+  if (!/<!DOCTYPE html>/i.test(html)) problems.push('missing <!DOCTYPE html> (screens are full standalone documents)');
+  if (id && !/^[a-z0-9][a-z0-9-]*$/i.test(id)) problems.push(`screen id "${id}" — use letters, digits and dashes`);
+  return problems;
+}
+/* data-go="target" references, for cross-checking navigation. */
+export function dataGoTargets(html) {
+  const out = new Set();
+  const re = /\bdata-go=["']([^"']+)["']/g;
+  let m;
+  while ((m = re.exec(html))) out.add(m[1]);
+  return [...out];
+}
+/* Numeric filename prefix (EN-9) as order fallback: "010-home" → 10. */
+export function prefixOrder(id) {
+  const m = /^(\d+)/.exec(id);
+  return m ? parseInt(m[1], 10) : undefined;
+}

package/core/project.js ADDED Viewed

@@ -0,0 +1,482 @@
+/* Project API — the one shared core the CLI and MCP server both import
+   (EN-18). Scans consumer projects, derives manifests, does atomic screen
+   CRUD, and runs the static half of validation. */
+import path from 'node:path';
+import { exists, readText, readJSON, writeAtomic, writeJSON, listDir, remove, mkdirp, today } from './fsx.js';
+import { parseMeta, stampUpdated, lintScreen, dataGoTargets, prefixOrder, DEVICES } from './meta.js';
+const MANIFEST_FIELDS = ['title', 'description', 'order', 'device', 'devices', 'status', 'tags', 'group', 'updated', 'statusBar'];
+/* ---------------- roots + config ---------------- */
+export async function resolveRoot(dir) {
+  const root = path.resolve(dir || process.cwd());
+  if (await exists(path.join(root, 'app.config.json'))) return root;
+  /* convenience: running from inside engine/ of a project */
+  const parent = path.dirname(root);
+  if (await exists(path.join(parent, 'app.config.json'))) return parent;
+  return null;
+}
+export async function readConfig(root) {
+  return readJSON(path.join(root, 'app.config.json'), {});
+}
+export async function writeConfig(root, config) {
+  await writeJSON(path.join(root, 'app.config.json'), config);
+}
+export function featureDir(root, id) {
+  return path.join(root, 'features', id);
+}
+/* Feature ids: config order first, then any extra folders on disk. */
+export async function listFeatureIds(root) {
+  const config = await readConfig(root);
+  const configured = Array.isArray(config.features) ? [...config.features] : [];
+  const onDisk = (await listDir(path.join(root, 'features')))
+    .filter((d) => d.isDirectory() && !d.name.startsWith('.'))
+    .map((d) => d.name);
+  for (const id of onDisk.sort()) if (!configured.includes(id)) configured.push(id);
+  return configured.filter((id) => onDisk.includes(id));
+}
+/* ---------------- screens ---------------- */
+export function screenPath(root, feature, screen) {
+  return path.join(featureDir(root, feature), 'screens', `${screen}.html`);
+}
+export async function listScreenFiles(root, feature) {
+  const dir = path.join(featureDir(root, feature), 'screens');
+  return (await listDir(dir))
+    .filter((d) => d.isFile() && d.name.endsWith('.html'))
+    .map((d) => d.name.slice(0, -5))
+    .sort();
+}
+export async function scanFeature(root, id) {
+  const dir = featureDir(root, id);
+  const meta = await readJSON(path.join(dir, 'feature.json'), { id, title: id });
+  const screenIds = await listScreenFiles(root, id);
+  const screens = [];
+  const problems = [];
+  for (const sid of screenIds) {
+    const html = await readText(screenPath(root, id, sid));
+    const { meta: sMeta, error } = parseMeta(html);
+    if (error) problems.push({ screen: sid, error });
+    const entry = { id: sid, file: `screens/${sid}.html` };
+    if (sMeta) {
+      for (const f of MANIFEST_FIELDS) if (sMeta[f] !== undefined) entry[f] = sMeta[f];
+    }
+    if (entry.order === undefined) entry.order = prefixOrder(sid) ?? 999;
+    screens.push(entry);
+  }
+  screens.sort((a, b) => (a.order - b.order) || a.id.localeCompare(b.id));
+  return { id, meta, screens, problems };
+}
+export async function regenManifest(root, id) {
+  const featureMeta = await readJSON(path.join(featureDir(root, id), 'feature.json'), null);
+  if (featureMeta?.type === 'app') {
+    /* app features have no file screens — the live app reports them (EN-20) */
+    return { feature: id, title: featureMeta.title, written: false, screens: 0, appType: true, problems: [] };
+  }
+  const { meta, screens, problems } = await scanFeature(root, id);
+  const manifest = { feature: id, generated: today(), screens };
+  const manifestPath = path.join(featureDir(root, id), 'manifest.json');
+  /* stable compare ignoring the `generated` stamp so untouched features don't churn */
+  const existing = await readJSON(manifestPath, null);
+  const changed = !existing ||
+    JSON.stringify({ ...existing, generated: null }) !== JSON.stringify({ ...manifest, generated: null });
+  if (changed) await writeJSON(manifestPath, manifest);
+  return { feature: id, title: meta.title, written: changed, screens: screens.length, problems };
+}
+export async function regenAllManifests(root) {
+  const out = [];
+  for (const id of await listFeatureIds(root)) out.push(await regenManifest(root, id));
+  return out;
+}
+export async function getScreen(root, feature, screen) {
+  const p = screenPath(root, feature, screen);
+  if (!(await exists(p))) throw new Error(`screen not found: ${feature}/${screen}`);
+  const html = await readText(p);
+  const { meta } = parseMeta(html);
+  return { feature, screen, meta, html, path: p };
+}
+async function saveScreen(root, feature, screen, html, { mustExist, mustNotExist }) {
+  const p = screenPath(root, feature, screen);
+  const already = await exists(p);
+  if (mustExist && !already) throw new Error(`screen not found: ${feature}/${screen} — use add_screen to create it`);
+  if (mustNotExist && already) throw new Error(`screen already exists: ${feature}/${screen} — use update_screen to change it`);
+  if (!(await exists(featureDir(root, feature)))) {
+    throw new Error(`feature not found: ${feature} — use add_feature first`);
+  }
+  const problems = lintScreen(html, { id: screen });
+  if (problems.length) {
+    throw new Error(`screen ${feature}/${screen} rejected:\n  - ${problems.join('\n  - ')}`);
+  }
+  let previousUpdated;
+  if (already) {
+    const prev = parseMeta(await readText(p)).meta;
+    previousUpdated = prev?.updated;
+  }
+  const stamped = stampUpdated(html, { previousUpdated, today: today() });
+  await writeAtomic(p, stamped);
+  const manifest = await regenManifest(root, feature);
+  return { feature, screen, path: p, updated: parseMeta(stamped).meta?.updated, manifest };
+}
+export async function addScreen(root, feature, screen, html) {
+  return saveScreen(root, feature, screen, html, { mustNotExist: true });
+}
+export async function updateScreen(root, feature, screen, html) {
+  return saveScreen(root, feature, screen, html, { mustExist: true });
+}
+export async function removeScreen(root, feature, screen) {
+  const p = screenPath(root, feature, screen);
+  if (!(await exists(p))) throw new Error(`screen not found: ${feature}/${screen}`);
+  await remove(p);
+  const manifest = await regenManifest(root, feature);
+  return { removed: `${feature}/${screen}`, manifest };
+}
+/* ---------------- features ---------------- */
+export async function addFeature(root, { id, title, icon, description, order }) {
+  if (!/^[a-z0-9][a-z0-9-]*$/.test(id || '')) {
+    throw new Error(`feature id "${id}" — use lowercase letters, digits and dashes`);
+  }
+  const dir = featureDir(root, id);
+  if (await exists(dir)) throw new Error(`feature already exists: ${id}`);
+  const config = await readConfig(root);
+  const meta = {
+    id,
+    title: title || id,
+    icon: icon || '📄',
+    description: description || '',
+    order: order ?? ((config.features?.length || 0) + 1)
+  };
+  await mkdirp(path.join(dir, 'screens'));
+  await mkdirp(path.join(dir, 'data'));
+  await writeJSON(path.join(dir, 'feature.json'), meta);
+  await writeJSON(path.join(dir, 'data', 'seed.json'), {});
+  await writeJSON(path.join(dir, 'data', 'scenarios.json'), {
+    list: [{ id: 'default', icon: '🧪', title: 'Default', description: 'Baseline seed data, untouched.' }]
+  });
+  await writeJSON(path.join(dir, 'flows.json'), { list: [] });
+  config.features = [...(config.features || []), id];
+  if (!config.defaultFeature) config.defaultFeature = id;
+  await writeConfig(root, config);
+  await regenManifest(root, id);
+  return { feature: meta };
+}
+/* ---------------- app-type features (EN-20) ---------------- */
+/*
+ * Register an existing single-page app as an app-type feature. `src` is
+ * project-root-relative (e.g. "docs/mockups/ios/index.html"). When `driver`
+ * is true a starter driver.js is scaffolded — the injected adapter that lets
+ * the shell drive the app WITHOUT touching the app's own files.
+ */
+export async function addApp(root, { src, id, title, icon, description, device, chrome, driver, order }) {
+  if (!src) throw new Error('src required — project-relative path to the app\'s index.html');
+  const srcPath = path.join(root, src);
+  if (!(await exists(srcPath))) throw new Error(`app entry not found: ${src}`);
+  const appId = id || path.basename(path.dirname(srcPath)).toLowerCase().replace(/[^a-z0-9-]+/g, '-') || 'app';
+  if (!/^[a-z0-9][a-z0-9-]*$/.test(appId)) throw new Error(`app id "${appId}" — use lowercase letters, digits and dashes`);
+  const dir = featureDir(root, appId);
+  if (await exists(dir)) throw new Error(`feature already exists: ${appId}`);
+  const config = await readConfig(root);
+  const meta = {
+    id: appId,
+    title: title || appId,
+    icon: icon || '🧩',
+    description: description || `Embedded app — ${src}`,
+    order: order ?? ((config.features?.length || 0) + 1),
+    type: 'app',
+    src,
+    device: device || 'none',
+    chrome: chrome || 'self'
+  };
+  if (driver) meta.driver = 'driver.js';
+  await mkdirp(dir);
+  await writeJSON(path.join(dir, 'feature.json'), meta);
+  if (driver) {
+    await writeAtomic(path.join(dir, 'driver.js'), DRIVER_TEMPLATE(appId, src));
+  }
+  config.features = [...(config.features || []), appId];
+  await writeConfig(root, config);
+  return { feature: meta, driver: driver ? `features/${appId}/driver.js` : null };
+}
+const DRIVER_TEMPLATE = (id, src) => `/* ScreenBook driver for "${id}" (${src}).
+ * Injected into the app AFTER it loads — the app's own files stay untouched.
+ * Teach ScreenBook the app's internals, then register:                     */
+AppBridge.register({
+  title: document.title || '${id}',
+  /* REQUIRED — list the app's screens: [{ id, title, description?, group? }] */
+  screens: function () {
+    // TODO e.g.: return Object.keys(window.Screens).map(function (k) { return { id: k, title: k }; });
+    return [];
+  },
+  /* REQUIRED — navigate the app to a screen id */
+  go: function (id) {
+    // TODO e.g.: window.App.go(id);
+  },
+  /* optional — current screen id (call AppBridge.navigated(id) on in-app nav too) */
+  current: function () { return null; },
+  /* optional — apply environment changes live: { mode, dir, lang, scenario } */
+  set: function (env) {
+    // TODO e.g.: if (env.mode) document.body.classList.toggle('dark', env.mode === 'dark');
+  }
+  /* optional — map the app's own data scenarios into the 🎭 dropdown:
+  , scenarios: function () { return [{ id: 'default', title: 'Default' }]; }  */
+});
+`;
+/* ---------------- data / themes / flows ---------------- */
+export async function getData(root, feature) {
+  const dir = path.join(featureDir(root, feature), 'data');
+  return {
+    seed: await readJSON(path.join(dir, 'seed.json'), {}),
+    scenarios: await readJSON(path.join(dir, 'scenarios.json'), { list: [] }),
+    i18n: await readJSON(path.join(featureDir(root, feature), 'i18n.json'), null)
+  };
+}
+export async function setData(root, feature, { seed, scenarios, i18n }) {
+  if (!(await exists(featureDir(root, feature)))) throw new Error(`feature not found: ${feature}`);
+  const dir = path.join(featureDir(root, feature), 'data');
+  const written = [];
+  if (seed !== undefined) { await writeJSON(path.join(dir, 'seed.json'), seed); written.push('seed.json'); }
+  if (scenarios !== undefined) {
+    if (!Array.isArray(scenarios.list)) throw new Error('scenarios must be { "list": [...] }');
+    await writeJSON(path.join(dir, 'scenarios.json'), scenarios);
+    written.push('scenarios.json');
+  }
+  if (i18n !== undefined) {
+    for (const [key, entry] of Object.entries(i18n || {})) {
+      if (typeof entry !== 'object' || entry === null || Array.isArray(entry)) {
+        throw new Error(`i18n key "${key}" must map languages to strings (key-first shape)`);
+      }
+    }
+    await writeJSON(path.join(featureDir(root, feature), 'i18n.json'), i18n);
+    written.push('i18n.json');
+  }
+  return { feature, written };
+}
+export async function listThemes(root) {
+  const config = await readConfig(root);
+  const ids = config.themes?.length ? config.themes : ['default'];
+  const themes = [];
+  for (const id of ids) {
+    themes.push({ id, theme: await readJSON(path.join(root, 'themes', `${id}.json`), null) });
+  }
+  return themes;
+}
+export async function getTheme(root, id) {
+  const config = await readConfig(root);
+  const themeId = id || config.themes?.[0] || 'default';
+  const theme = await readJSON(path.join(root, 'themes', `${themeId}.json`), null);
+  if (!theme) throw new Error(`theme not found: themes/${themeId}.json`);
+  return { id: themeId, theme };
+}
+export async function setTheme(root, id, theme) {
+  if (!id) throw new Error('theme id required');
+  if (!theme?.modes?.light) throw new Error('theme must have modes.light (and usually modes.dark)');
+  await writeJSON(path.join(root, 'themes', `${id}.json`), theme);
+  const config = await readConfig(root);
+  if (!config.themes?.includes(id)) {
+    config.themes = [...(config.themes || []), id];
+    await writeConfig(root, config);
+  }
+  return { id, written: `themes/${id}.json` };
+}
+export async function getFlows(root, feature) {
+  return readJSON(path.join(featureDir(root, feature), 'flows.json'), { list: [] });
+}
+export async function setFlows(root, feature, flows) {
+  if (!(await exists(featureDir(root, feature)))) throw new Error(`feature not found: ${feature}`);
+  if (!Array.isArray(flows?.list)) throw new Error('flows must be { "list": [...] }');
+  await writeJSON(path.join(featureDir(root, feature), 'flows.json'), flows);
+  return { feature, written: 'flows.json' };
+}
+/* ---------------- review comments ---------------- */
+const commentsPath = (root) => path.join(root, 'review', 'comments.json');
+export async function getComments(root, { feature, unresolvedOnly } = {}) {
+  const box = await readJSON(commentsPath(root), { comments: [] });
+  let comments = box.comments || [];
+  if (feature) comments = comments.filter((c) => c.feature === feature);
+  if (unresolvedOnly) comments = comments.filter((c) => !c.resolved);
+  return { comments };
+}
+export async function setComments(root, comments) {
+  await writeJSON(commentsPath(root), { comments });
+  return { count: comments.length };
+}
+export async function resolveComment(root, id, resolved = true) {
+  const box = await readJSON(commentsPath(root), { comments: [] });
+  const c = (box.comments || []).find((x) => x.id === id);
+  if (!c) throw new Error(`comment not found: ${id}`);
+  c.resolved = resolved;
+  await writeJSON(commentsPath(root), box);
+  return { id, resolved };
+}
+/* ---------------- static validation ---------------- */
+export async function staticValidate(root) {
+  const errors = [];
+  const warnings = [];
+  const config = await readConfig(root);
+  if (!config.name) warnings.push('app.config.json has no "name"');
+  const featureIds = await listFeatureIds(root);
+  if (!featureIds.length) errors.push('no features found under features/');
+  for (const id of config.features || []) {
+    if (!featureIds.includes(id)) errors.push(`app.config.json lists feature "${id}" but features/${id}/ does not exist`);
+  }
+  if (config.defaultFeature && !featureIds.includes(config.defaultFeature)) {
+    errors.push(`defaultFeature "${config.defaultFeature}" does not exist`);
+  }
+  const themes = await listThemes(root);
+  for (const { id, theme } of themes) {
+    if (!theme) errors.push(`theme "${id}" listed in app.config.json but themes/${id}.json is missing or invalid`);
+    else if (!theme.modes?.light) errors.push(`theme "${id}" has no modes.light`);
+  }
+  for (const id of featureIds) {
+    /* app-type features: static half checks wiring only; the browser half
+       boots the app and visits every screen (EN-20 gate) */
+    const fMeta = await readJSON(path.join(featureDir(root, id), 'feature.json'), null);
+    if (fMeta?.type === 'app') {
+      if (!fMeta.src) errors.push(`${id}: app feature has no "src"`);
+      else if (!(await exists(path.join(root, fMeta.src)))) errors.push(`${id}: app src not found: ${fMeta.src}`);
+      if (fMeta.driver && !(await exists(path.join(featureDir(root, id), fMeta.driver)))) {
+        errors.push(`${id}: driver not found: features/${id}/${fMeta.driver}`);
+      }
+      continue;
+    }
+    const { screens, problems } = await scanFeature(root, id);
+    for (const p of problems) errors.push(`${id}/${p.screen}: ${p.error}`);
+    const ids = new Set(screens.map((s) => s.id));
+    for (const s of screens) {
+      const html = await readText(screenPath(root, id, s.id));
+      for (const lint of lintScreen(html, { id: s.id })) errors.push(`${id}/${s.id}: ${lint}`);
+      for (const target of dataGoTargets(html)) {
+        if (!ids.has(target)) warnings.push(`${id}/${s.id}: data-go="${target}" points at a screen that doesn't exist in this feature`);
+      }
+      if (s.device && !DEVICES.includes(s.device)) errors.push(`${id}/${s.id}: bad device "${s.device}"`);
+    }
+    /* manifest freshness */
+    const manifest = await readJSON(path.join(featureDir(root, id), 'manifest.json'), null);
+    if (!manifest) {
+      errors.push(`${id}: manifest.json missing — run: screenbook manifest`);
+    } else {
+      const fresh = { feature: id, generated: null, screens };
+      if (JSON.stringify({ ...manifest, generated: null }) !== JSON.stringify(fresh)) {
+        warnings.push(`${id}: manifest.json is stale — run: screenbook manifest`);
+      }
+    }
+    /* i18n checks (key-first shape; fallback+warning policy) */
+    const i18nPath = path.join(featureDir(root, id), 'i18n.json');
+    if (await exists(i18nPath)) {
+      let i18n = null;
+      try { i18n = await readJSON(i18nPath); }
+      catch (err) { errors.push(`${id}: ${err.message}`); }
+      const langs = config.languages || ['en'];
+      if (i18n) {
+      const missing = {};
+      const usedKeys = new Set();
+      for (const [key, entry] of Object.entries(i18n)) {
+        if (typeof entry !== 'object' || entry === null || Array.isArray(entry)) {
+          errors.push(`${id}: i18n key "${key}" is not a {lang: string} object`);
+          continue;
+        }
+        for (const lang of Object.keys(entry)) {
+          if (!langs.includes(lang)) warnings.push(`${id}: i18n key "${key}" has unknown language "${lang}" (not in app.config.json languages)`);
+        }
+        for (const lang of langs) {
+          if (entry[lang] == null) (missing[lang] = missing[lang] || []).push(key);
+        }
+      }
+      for (const [lang, keys] of Object.entries(missing)) {
+        warnings.push(`${id}: ${keys.length} i18n key(s) missing "${lang}": ${keys.slice(0, 4).join(', ')}${keys.length > 4 ? ', …' : ''}`);
+      }
+      /* keys referenced by screens but never defined */
+      for (const s of screens) {
+        const html = await readText(screenPath(root, id, s.id));
+        for (const m of html.matchAll(/Engine\.t\(\s*['"]([^'"]+)['"]/g)) usedKeys.add(m[1]);
+      }
+      try {
+        const sharedJs = await readText(path.join(featureDir(root, id), 'screens', 'shared.js'));
+        for (const m of sharedJs.matchAll(/Engine\.t\(\s*['"]([^'"]+)['"]/g)) usedKeys.add(m[1]);
+      } catch { /* no shared.js */ }
+      for (const key of usedKeys) {
+        if (!(key in i18n)) warnings.push(`${id}: Engine.t("${key}") has no entry in i18n.json`);
+      }
+      }
+    }
+    /* scenarios + flows cross-checks */
+    const { scenarios } = await getData(root, id);
+    const scenarioIds = new Set((scenarios.list || []).map((s) => s.id));
+    const seen = new Set();
+    for (const s of scenarios.list || []) {
+      if (seen.has(s.id)) errors.push(`${id}: duplicate scenario id "${s.id}"`);
+      seen.add(s.id);
+    }
+    const flows = await getFlows(root, id);
+    for (const flow of flows.list || []) {
+      for (const [i, step] of (flow.steps || []).entries()) {
+        if (step.screen && !ids.has(step.screen)) {
+          errors.push(`${id}: flow "${flow.id}" step ${i + 1} references missing screen "${step.screen}"`);
+        }
+        if (step.scenario && !scenarioIds.has(step.scenario)) {
+          errors.push(`${id}: flow "${flow.id}" step ${i + 1} references missing scenario "${step.scenario}"`);
+        }
+      }
+    }
+  }
+  return { ok: errors.length === 0, errors, warnings };
+}