@cs4alhaider/screenbook 0.1.0

package/shell/frames.js

@@ -0,0 +1,108 @@
+/* Device frames — engine-owned hardware chrome around the screen iframe.
+   Screens never draw the hardware (EN §4.6). */
+
+const SIZES = {
+  ios: { w: 393, h: 852 },
+  android: { w: 412, h: 915 },
+  web: { w: 1280, h: 800 },
+  none: { w: 900, h: 640 }
+};
+
+function el(tag, className, html) {
+  const node = document.createElement(tag);
+  if (className) node.className = className;
+  if (html !== undefined) node.innerHTML = html;
+  return node;
+}
+
+/* Build the frame for a device. Returns { root, viewport, urlPill } —
+   the iframe gets appended into `viewport` by the screen host. */
+export function buildFrame(device) {
+  const dev = SIZES[device] ? device : 'none';
+  const root = el('div', `device dev-${dev}`);
+  let viewport;
+  let urlPill = null;
+
+  if (dev === 'ios') {
+    viewport = el('div', 'dev-viewport');
+    viewport.append(
+      el('div', 'dev-island'),
+      statusBar('dev-statusbar'),
+      el('div', 'dev-homebar')
+    );
+    root.append(viewport);
+  } else if (dev === 'android') {
+    viewport = el('div', 'dev-viewport');
+    viewport.append(
+      el('div', 'dev-punch'),
+      statusBar('dev-statusbar-android'),
+      el('div', 'dev-gesturebar')
+    );
+    root.append(viewport);
+  } else if (dev === 'web') {
+    const bar = el('div', 'dev-browserbar');
+    const dots = el('div', 'bb-dots', '<i></i><i></i><i></i>');
+    urlPill = el('div', 'bb-url');
+    bar.append(dots, urlPill, el('div', 'bb-spacer'));
+    viewport = el('div', 'dev-viewport');
+    root.append(bar, viewport);
+  } else {
+    viewport = el('div', 'dev-viewport');
+    root.append(viewport);
+  }
+
+  return { root, viewport, urlPill, device: dev, size: SIZES[dev] };
+}
+
+function statusBar(cls) {
+  const bar = el('div', cls);
+  const time = el('span', 'sb-time', '9:41');
+  const icons = el('span', 'sb-icons');
+  icons.innerHTML = signalSvg() + wifiSvg() + batterySvg();
+  bar.append(time, icons);
+  return bar;
+}
+
+function signalSvg() {
+  return `<svg width="17" height="11" viewBox="0 0 17 11" fill="currentColor"><rect x="0" y="7" width="3" height="4" rx="1"/><rect x="4.5" y="5" width="3" height="6" rx="1"/><rect x="9" y="2.5" width="3" height="8.5" rx="1"/><rect x="13.5" y="0" width="3" height="11" rx="1"/></svg>`;
+}
+function wifiSvg() {
+  return `<svg width="15" height="11" viewBox="0 0 15 11" fill="currentColor"><path d="M7.5 9.2a1.4 1.4 0 1 0 0 2.8 1.4 1.4 0 0 0 0-2.8z" transform="translate(0,-1.2)"/><path d="M7.5 6.2c1.4 0 2.7.5 3.7 1.4l-1.1 1.2a3.9 3.9 0 0 0-5.2 0L3.8 7.6a5.5 5.5 0 0 1 3.7-1.4z"/><path d="M7.5 2.8c2.3 0 4.4.9 6 2.3l-1.1 1.2a7.1 7.1 0 0 0-9.8 0L1.5 5.1a8.7 8.7 0 0 1 6-2.3z"/></svg>`;
+}
+function batterySvg() {
+  return `<svg width="25" height="12" viewBox="0 0 25 12" fill="none"><rect x="0.5" y="0.5" width="21" height="11" rx="3" stroke="currentColor" opacity=".4"/><rect x="2" y="2" width="18" height="8" rx="1.8" fill="currentColor"/><path d="M23 4v4c1-.3 1.6-1 1.6-2S24 4.3 23 4z" fill="currentColor" opacity=".4"/></svg>`;
+}
+
+/* Scale-to-fit: shrink the frame when the stage is smaller than the device.
+   Never scales above 1. Returns a cleanup fn. */
+export function fitFrame(stage, fitWrap, frame) {
+  const outer = fitWrap.querySelector('.frame-outer');
+  const { w, h } = frame.size;
+
+  function apply() {
+    const pad = 18;
+    const availW = stage.clientWidth - pad * 2;
+    const availH = stage.clientHeight - pad * 2;
+    if (availW <= 0 || availH <= 0) return;
+    const scale = frame.device === 'none'
+      ? Math.min(1, availW / w, availH / h)
+      : Math.min(1, availW / w, availH / h);
+    outer.style.setProperty('--frame-scale', String(scale));
+    /* the wrapper reserves the scaled footprint so centering stays true */
+    fitWrap.style.width = `${Math.round(w * scale)}px`;
+    fitWrap.style.height = `${Math.round((frame.root.offsetHeight || h) * scale)}px`;
+  }
+
+  const ro = new ResizeObserver(apply);
+  ro.observe(stage);
+  apply();
+  requestAnimationFrame(apply);
+  return () => ro.disconnect();
+}
+
+export const DEVICE_LABELS = {
+  ios: { icon: '', title: 'iPhone' },
+  android: { icon: '🤖', title: 'Android' },
+  web: { icon: '🖥', title: 'Web' },
+  none: { icon: '▦', title: 'Bare' }
+};

package/shell/main.js

@@ -0,0 +1,397 @@
+/* ScreenBook shell — boot + orchestration. */
+
+import { store, set, subscribe, feature, applyHash } from './store.js';
+import { loadProject, reloadFeature, fetchJSON, detectServe, connectEvents } from './net.js';
+import { renderSidebar, visibleScreens, scrollActiveIntoView } from './sidebar.js';
+import { showScreen, pushUpdate, reloadScreen, onScreenMessage, clearVariant } from './screenhost.js';
+import { dropdown, toggle, action, divider } from './toolbar.js';
+import { DEVICE_LABELS } from './frames.js';
+import { startFlow, stopFlow, stepFlow, renderFlowbar, resumeFromHash, activeFlow } from './flowplayer.js';
+import { initReview, renderReviewPanel, pushPinsToScreen, handlePinRequest, handlePinOpen } from './review.js';
+import { renderThemeLab, themeLabDirty } from './themelab.js';
+import { runSelftest } from './selftest.js';
+import { toast } from './toast.js';
+
+const params = new URLSearchParams(location.search);
+const SELFTEST = params.get('selftest') === '1';
+const SOLO = params.get('solo') === '1';
+
+const controlsBox = document.getElementById('controls');
+const widgets = [];
+let flowWidget = null;
+let themeWidget = null;
+let langWidget = null;
+let deviceWidget = null;
+
+const RTL_LANGS = new Set(['ar', 'he', 'fa', 'ur']);
+
+/* ---------------- toolbar ---------------- */
+
+function buildControls() {
+  const featureDD = dropdown({
+    icon: '⧉', title: 'Feature',
+    value: () => feature()?.meta.title || '—',
+    head: 'Features',
+    empty: 'No features in app.config.json',
+    items: () => {
+      const items = [];
+      let lastGroup;
+      for (const f of store.project.features.values()) {
+        const group = f.meta.group || null;
+        if (group && group !== lastGroup) items.push({ head: true, title: group });
+        lastGroup = group;
+        items.push({
+          id: f.id,
+          icon: f.meta.icon || '📄',
+          title: f.meta.title || f.id,
+          desc: f.meta.description,
+          checked: f.id === store.ui.feature
+        });
+      }
+      return items;
+    },
+    onPick: (id) => set({ feature: id, flow: null })
+  });
+
+  deviceWidget = dropdown({
+    icon: '📱', title: 'Device',
+    value: () => store.ui.deviceFilter === 'all' ? 'All' : (DEVICE_LABELS[store.ui.deviceFilter]?.title || store.ui.deviceFilter),
+    head: 'Filter screens by device',
+    items: () => {
+      const devices = store.project.config.devices || ['ios', 'android', 'web'];
+      return [
+        { id: 'all', icon: '✳︎', title: 'All devices', checked: store.ui.deviceFilter === 'all' },
+        ...devices.map((d) => ({
+          id: d,
+          icon: DEVICE_LABELS[d]?.icon || '▦',
+          title: DEVICE_LABELS[d]?.title || d,
+          checked: store.ui.deviceFilter === d
+        }))
+      ];
+    },
+    onPick: (id) => set({ deviceFilter: id })
+  });
+
+  const scenarioDD = dropdown({
+    icon: '🎭', title: 'Scenario',
+    value: () => {
+      const s = (feature()?.scenarios.list || []).find((x) => x.id === store.ui.scenario);
+      return s ? s.title : 'Default';
+    },
+    head: 'Data scenarios',
+    empty: 'This feature has no scenarios.json',
+    items: () => (feature()?.scenarios.list || []).map((s) => ({
+      id: s.id,
+      icon: s.icon || '🎭',
+      title: s.title || s.id,
+      desc: s.description,
+      checked: s.id === store.ui.scenario
+    })),
+    onPick: (id) => set({ scenario: id })
+  });
+
+  themeWidget = toggle({
+    icon: '🎨', tooltip: 'Theme Lab — view + edit design tokens live',
+    label: () => store.project.themes.size > 1
+      ? (store.project.themes.get(store.ui.theme)?.title || store.ui.theme)
+      : '',
+    is: () => store.ui.themeLab,
+    onToggle: () => set({ themeLab: !store.ui.themeLab, ...(store.ui.themeLab ? {} : { review: false }) })
+  });
+
+  const modeToggle = toggle({
+    icon: '☾', iconOn: '☀︎', tooltip: 'Dark / light',
+    is: () => store.ui.mode === 'dark',
+    onToggle: () => set({ mode: store.ui.mode === 'dark' ? 'light' : 'dark' })
+  });
+
+  const dirToggle = toggle({
+    icon: '⇄', tooltip: 'LTR / RTL',
+    label: () => store.ui.dir.toUpperCase(),
+    is: () => store.ui.dir === 'rtl',
+    onToggle: () => set({ dir: store.ui.dir === 'rtl' ? 'ltr' : 'rtl' })
+  });
+
+  langWidget = dropdown({
+    icon: '🌐', tooltip: 'Language',
+    value: () => store.ui.lang,
+    head: 'Language (sets Engine.env.lang)',
+    items: () => (store.project.config.languages || ['en']).map((l) => ({
+      id: l, icon: '🌐', title: l, checked: l === store.ui.lang
+    })),
+    onPick: (id) => {
+      const patch = { lang: id };
+      patch.dir = RTL_LANGS.has(id) ? 'rtl' : 'ltr';
+      set(patch);
+    }
+  });
+
+  flowWidget = dropdown({
+    icon: '▶', tooltip: 'Play a flow',
+    value: () => activeFlow()?.title || null,
+    head: 'Flows',
+    empty: 'This feature has no flows.json',
+    items: () => (feature()?.flows.list || []).map((fl) => ({
+      id: fl.id,
+      icon: fl.icon || '▶',
+      title: fl.title || fl.id,
+      desc: fl.description,
+      checked: fl.id === store.ui.flow
+    })),
+    onPick: (id) => (id === store.ui.flow ? stopFlow() : startFlow(id))
+  });
+
+  const reviewToggle = toggle({
+    icon: '📌', tooltip: 'Review Mode — pin comments on screens',
+    danger: true,
+    is: () => store.ui.review,
+    onToggle: () => set({ review: !store.ui.review, ...(store.ui.review ? {} : { themeLab: false }) })
+  });
+
+  const resetBtn = action({
+    icon: '↺', tooltip: 'Reset shared Engine.state',
+    onClick: () => {
+      const keys = [];
+      for (let i = 0; i < localStorage.length; i++) {
+        const k = localStorage.key(i);
+        if (k && k.startsWith('sb:state:')) keys.push(k);
+      }
+      keys.forEach((k) => localStorage.removeItem(k));
+      reloadScreen();
+      toast(`State cleared (${keys.length} key${keys.length === 1 ? '' : 's'})`);
+    }
+  });
+
+  widgets.push(featureDD, deviceWidget, scenarioDD, divider(), themeWidget, modeToggle, dirToggle, langWidget, divider(), flowWidget, reviewToggle, resetBtn);
+  for (const w of widgets) controlsBox.append(w.el);
+}
+
+function refreshControls() {
+  for (const w of widgets) w.refresh();
+  const cfg = store.project.config;
+  langWidget.el.style.display = (cfg.languages || []).length > 1 ? '' : 'none';
+  deviceWidget.el.style.display = (cfg.devices || []).length > 1 ? '' : 'none';
+  flowWidget.el.style.display = (feature()?.flows.list || []).length ? '' : 'none';
+}
+
+/* ---------------- rendering ---------------- */
+
+function ensureValidSelection() {
+  const p = store.project;
+  if (!p.features.size) return;
+  if (!p.features.has(store.ui.feature)) {
+    store.ui.feature = p.config.defaultFeature && p.features.has(p.config.defaultFeature)
+      ? p.config.defaultFeature
+      : [...p.features.keys()][0];
+  }
+  const f = feature();
+  const screens = f.type === 'app' ? (f.appScreens || []) : (f.manifest.screens || []);
+  if (!screens.find((s) => s.id === store.ui.screen)) {
+    /* for apps, keep a deep-linked screen until the live list arrives */
+    if (f.type !== 'app' || f.appScreens !== null) {
+      store.ui.screen = screens[0]?.id || (f.type === 'app' ? store.ui.screen : null);
+    }
+  }
+  if (store.ui.scenario !== 'default' &&
+      !(f.scenarios.list || []).find((s) => s.id === store.ui.scenario)) {
+    store.ui.scenario = 'default';
+  }
+  if (!p.themes.has(store.ui.theme)) {
+    store.ui.theme = [...p.themes.keys()][0] || null;
+  }
+}
+
+function renderAll() {
+  document.documentElement.setAttribute('data-shell', store.ui.mode);
+  document.getElementById('project-name').textContent = store.project.config.name || 'Untitled project';
+  refreshControls();
+  renderSidebar();
+  showScreen();
+  renderFlowbar();
+  renderReviewPanel();
+  renderThemeLab();
+}
+
+function onChange(changed) {
+  if (changed.has('feature')) {
+    ensureValidSelection();
+    renderAll();
+    pushPinsToScreen();
+    return;
+  }
+  if (changed.has('mode')) document.documentElement.setAttribute('data-shell', store.ui.mode);
+  if (changed.has('screen')) {
+    clearVariant();
+    renderSidebar();
+    showScreen();
+    scrollActiveIntoView();
+    pushPinsToScreen();
+  }
+  if (changed.has('scenario')) {
+    if (feature()?.type === 'app') pushUpdate();   // apps map scenarios live, no remount
+    else reloadScreen();
+  }
+  if (changed.has('mode') || changed.has('dir') || changed.has('theme')) pushUpdate();
+  if (changed.has('lang')) {
+    /* Engine.t strings bind at ready-time — reload file screens on language
+       switch (same semantics as scenario changes); apps take env live */
+    if (feature()?.type === 'app') pushUpdate();
+    else reloadScreen();
+  }
+  if (changed.has('search') || changed.has('deviceFilter')) renderSidebar();
+  if (changed.has('flow') || changed.has('flowStep')) renderFlowbar();
+  if (changed.has('review')) { renderReviewPanel(); pushPinsToScreen(); }
+  if (changed.has('themeLab') || ((changed.has('mode') || changed.has('theme')) && store.ui.themeLab)) renderThemeLab();
+  refreshControls();
+}
+
+/* ---------------- screen events ---------------- */
+
+onScreenMessage({
+  onGo(id) {
+    const f = feature();
+    const pool = f?.type === 'app' ? (f.appScreens || []) : (f?.manifest.screens || []);
+    const target = pool.find((s) => s.id === id);
+    if (target) set({ screen: id, ...(f?.type === 'app' ? {} : { flow: null }) });
+    else if (f?.type === 'app') set({ screen: id });   // trust the app's own navigation
+    else toast(`No screen “${id}” in this feature`);
+  },
+  onAppUpdate() {
+    ensureValidSelection();
+    renderSidebar();
+    refreshControls();
+    showScreen();
+  },
+  onReady() { pushPinsToScreen(); },
+  onConsoleError(message) {
+    if (!SELFTEST) console.warn(`[screen] ${message}`);
+  },
+  onPinRequest: (msg) => { if (store.ui.review) handlePinRequest(msg); },
+  onPinOpen: (id) => handlePinOpen(id)
+});
+
+/* ---------------- keyboard ---------------- */
+
+function wireKeyboard() {
+  document.addEventListener('keydown', (e) => {
+    const inField = /^(INPUT|TEXTAREA|SELECT)$/.test(document.activeElement?.tagName || '');
+    if (inField) return;
+    if (e.key === '/') {
+      e.preventDefault();
+      document.getElementById('search').focus();
+      return;
+    }
+    if (store.ui.flow && (e.key === 'ArrowRight' || e.key === 'ArrowLeft')) {
+      e.preventDefault();
+      const rtl = store.ui.dir === 'rtl';
+      stepFlow((e.key === 'ArrowRight') !== rtl ? 1 : -1);
+      return;
+    }
+    if (['ArrowDown', 'ArrowUp', 'j', 'k'].includes(e.key)) {
+      const screens = visibleScreens();
+      if (!screens.length) return;
+      e.preventDefault();
+      const i = screens.findIndex((s) => s.id === store.ui.screen);
+      const delta = (e.key === 'ArrowDown' || e.key === 'j') ? 1 : -1;
+      const next = screens[Math.min(screens.length - 1, Math.max(0, i + delta))];
+      if (next && next.id !== store.ui.screen) set({ screen: next.id, flow: null });
+    }
+  });
+}
+
+/* ---------------- live reload (engine serve) ---------------- */
+
+function wireLiveReload() {
+  let pending = new Set();
+  let timer = null;
+
+  connectEvents((evt) => {
+    pending.add(JSON.stringify(evt));
+    clearTimeout(timer);
+    timer = setTimeout(async () => {
+      const events = [...pending].map((s) => JSON.parse(s));
+      pending = new Set();
+      let touchedThemes = false;
+      const touchedFeatures = new Set();
+      for (const e of events) {
+        if (e.area === 'theme' || e.area === 'config') touchedThemes = true;
+        if (e.feature) touchedFeatures.add(e.feature);
+      }
+      try {
+        if (touchedThemes && !(store.ui.themeLab && themeLabDirty())) {
+          /* skip while the Theme Lab holds unsaved edits — disk must not clobber them */
+          const cfg = await fetchJSON('app.config.json', { optional: true });
+          if (cfg) store.project.config = cfg;
+          for (const id of cfg?.themes || [...store.project.themes.keys()]) {
+            const t = await fetchJSON(`themes/${id}.json`, { optional: true });
+            if (t) store.project.themes.set(id, t);
+          }
+        }
+        for (const id of touchedFeatures) await reloadFeature(store.project, id);
+      } catch { /* transient mid-write reads are fine; next event refreshes */ }
+      ensureValidSelection();
+      renderSidebar();
+      refreshControls();
+      renderFlowbar();
+      if (touchedFeatures.has(store.ui.feature) || touchedThemes) {
+        reloadScreen({ bust: true });
+        pushUpdate();
+      }
+      toast('↻ Live-reloaded');
+    }, 160);
+  });
+}
+
+/* ---------------- boot ---------------- */
+
+async function boot() {
+  if (SOLO) {
+    document.body.classList.add('solo');
+    store.ui.solo = true;
+  }
+
+  store.project = await loadProject();
+
+  const cfg = store.project.config;
+  store.ui.theme = cfg.themes?.[0] || [...store.project.themes.keys()][0] || null;
+  store.ui.lang = cfg.defaultLanguage || (cfg.languages || ['en'])[0] || 'en';
+  store.ui.feature = cfg.defaultFeature || [...store.project.features.keys()][0] || null;
+
+  applyHash();
+  ensureValidSelection();
+
+  if (SELFTEST) {
+    document.getElementById('sidebar').style.pointerEvents = 'none';
+    await runSelftest();
+    return;
+  }
+
+  store.ui.serveLive = await detectServe();
+  const badge = document.getElementById('serve-badge');
+  if (store.ui.serveLive) {
+    badge.textContent = '● live';
+    badge.classList.add('is-live');
+    badge.title = 'engine serve — live reload + review comments sync to disk';
+    wireLiveReload();
+  }
+
+  await initReview();
+  buildControls();
+  subscribe(onChange);
+  if (store.ui.flow) resumeFromHash();   // deep link into a flow: sync step → screen/scenario
+  renderAll();
+  wireKeyboard();
+
+  window.addEventListener('hashchange', () => {
+    applyHash();
+    if (store.ui.flow) resumeFromHash();
+  });
+}
+
+boot().catch((err) => {
+  const stage = document.getElementById('stage');
+  stage.innerHTML = `<div class="stage-empty"><h2>ScreenBook could not load this project</h2>
+    <p>${String(err?.message || err).replace(/</g, '&lt;')}</p>
+    <p>Expected layout: <code>app.config.json</code> + <code>features/&lt;id&gt;/manifest.json</code> next to <code>engine/</code>.</p></div>`;
+  console.error(err);
+});

package/shell/net.js

@@ -0,0 +1,126 @@
+/* Project loading + live-serve detection. The shell lives at <project>/engine/,
+   so the project root is always one level up from this page. */
+
+export const PROJECT_ROOT = new URL('..', location.href).href;
+
+export function url(path) {
+  return new URL(path.replace(/^\//, ''), PROJECT_ROOT).href;
+}
+
+export async function fetchJSON(path, { optional = false } = {}) {
+  try {
+    const res = await fetch(url(path), { cache: 'no-store' });
+    if (!res.ok) throw new Error(`${res.status} ${path}`);
+    return await res.json();
+  } catch (err) {
+    if (optional) return null;
+    throw err;
+  }
+}
+
+async function loadFeature(id) {
+  const meta = await fetchJSON(`features/${id}/feature.json`, { optional: true });
+
+  /* app-type feature (EN-20): screens come from the live app, not from files */
+  if (meta?.type === 'app') {
+    const flows = await fetchJSON(`features/${id}/flows.json`, { optional: true });
+    return {
+      id,
+      type: 'app',
+      meta,
+      manifest: { screens: [] },
+      appScreens: null,          // filled by sba:screens after the app says hello
+      appTitle: null,
+      seed: {},
+      scenarios: { list: [] },   // may be filled from sba:hello (driver-mapped 🎭)
+      flows: flows || { list: [] }
+    };
+  }
+
+  const [manifest, seed, scenarios, flows, i18n] = await Promise.all([
+    fetchJSON(`features/${id}/manifest.json`, { optional: true }),
+    fetchJSON(`features/${id}/data/seed.json`, { optional: true }),
+    fetchJSON(`features/${id}/data/scenarios.json`, { optional: true }),
+    fetchJSON(`features/${id}/flows.json`, { optional: true }),
+    fetchJSON(`features/${id}/i18n.json`, { optional: true })
+  ]);
+  return {
+    id,
+    meta: meta || { id, title: id, icon: '📄', order: 999 },
+    manifest: manifest || { screens: [] },
+    seed: seed || {},
+    scenarios: scenarios || { list: [] },
+    flows: flows || { list: [] },
+    i18n: i18n || null
+  };
+}
+
+export async function loadProject() {
+  const config = await fetchJSON('app.config.json', { optional: true }) || {};
+  const featureIds = config.features || [];
+  const themeIds = config.themes?.length ? config.themes : ['default'];
+
+  const [featureList, themeList] = await Promise.all([
+    Promise.all(featureIds.map(loadFeature)),
+    Promise.all(themeIds.map((id) => fetchJSON(`themes/${id}.json`, { optional: true })))
+  ]);
+
+  featureList.sort((a, b) => (a.meta.order ?? 999) - (b.meta.order ?? 999) || a.id.localeCompare(b.id));
+
+  const features = new Map(featureList.map((f) => [f.id, f]));
+  const themes = new Map();
+  themeIds.forEach((id, i) => { if (themeList[i]) themes.set(id, themeList[i]); });
+  if (!themes.size) themes.set('fallback', window.EngineKit.FALLBACK_THEME);
+
+  return { config, features, themes };
+}
+
+export async function reloadFeature(project, id) {
+  const fresh = await loadFeature(id);
+  project.features.set(id, fresh);
+  return fresh;
+}
+
+/* ---------------- live serve (engine serve) ---------------- */
+
+export async function detectServe() {
+  try {
+    const res = await fetch(url('__sb/health'), { cache: 'no-store' });
+    if (!res.ok) return false;
+    const body = await res.json();
+    return body?.screenbook === true;
+  } catch {
+    return false;
+  }
+}
+
+/* Server-sent events → change callbacks. Events: {kind, feature?, screen?, path?} */
+export function connectEvents(onChange) {
+  let source;
+  try {
+    source = new EventSource(url('__sb/events'));
+  } catch {
+    return () => {};
+  }
+  source.onmessage = (e) => {
+    try { onChange(JSON.parse(e.data)); } catch { /* ignore malformed */ }
+  };
+  source.onerror = () => { /* EventSource auto-reconnects */ };
+  return () => source.close();
+}
+
+/* ---------------- review comment persistence ---------------- */
+
+export async function fetchComments() {
+  return fetchJSON('__sb/review/comments', { optional: true });
+}
+
+export async function saveComments(comments) {
+  const res = await fetch(url('__sb/review/comments'), {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ comments }, null, 2)
+  });
+  if (!res.ok) throw new Error(`save failed: ${res.status}`);
+  return res.json();
+}