spectoflow 0.23.5 → 0.27.0

package/{templates/lib → lib}/custom-dashboard.js

@@ -1,6 +1,6 @@
 'use strict';
 /*
- * Pure helpers for user-generated custom dashboards (.spectoflow/dashboard/custom/<id>.json).
+ * Pure helpers for user-generated custom dashboards (.spectoflow/dashboards/<id>.json).
  *
  * A custom dashboard is a DECLARATIVE block spec, never raw HTML/CSS/JS: the generating agent picks
  * blocks from a fixed vocabulary (BLOCK_TYPES) that the dashboard already knows how to render, using
@@ -9,7 +9,7 @@
  * the user switches to later — with zero per-dashboard styling to keep in sync, and no arbitrary code
  * ever running in the dashboard.
  *
- * Zero dependency; consumed by templates/dashboard/server.js (Node) via readCustomDashboards() in
+ * Zero dependency; consumed by lib/dashboard/handlers.js (Node) via readCustomDashboards() in
  * store.js. The browser-side renderer (dashboard/public/app.js) re-implements the tiny `resolveBind`
  * walk independently — sharing code across the Node/browser boundary would need a build step, which
  * this project avoids on purpose (see CLAUDE.md's zero-runtime-dependency invariant).

package/{templates/lib → lib}/customize-prompts.js

@@ -1,6 +1,6 @@
 'use strict';
 // Builds the exact natural-language prompts the dashboard's Settings → Customize UI posts to
-// /api/run (see templates/dashboard/public/app.js's CZ_KINDS) — the single source of truth so the
+// /api/run (see lib/dashboard/public/app.js's CZ_KINDS) — the single source of truth so the
 // CLI (`spectoflow skill/agent/dashboard create`) and the dashboard button never drift apart. The
 // browser side can't require this Node module (no build step), so its literal strings are mirrored
 // there by hand; test/customize-prompts.test.js guards against the two falling out of sync.

package/lib/dashboard/connector.js

@@ -0,0 +1,193 @@
+'use strict';
+/*
+ * The local hub's outbound connector to an online dashboard (docs/online-dashboard-connector-design.md §2).
+ * One connection per machine; JSON frames, identical on both transports:
+ *   up:   auth {token,version} · hello {machineName,projects} · event {p,event} · snapshot {p,project} · reply {reqId,result|error} · pong
+ *   down: auth-ok {machineId} · op {reqId,p,op,args} · ping
+ * Transport 1 is Node's native WebSocket client (zero-dep, Node ≥ 22); transport 2 is HTTP long-poll
+ * (POST batches + GET held ≤ 25 s) for hosts that don't pass WebSockets (cPanel/Passenger). The hub
+ * decides nothing here: it hands in listPublished/readSnapshot/execOp and tees its emit into
+ * pushEvent/pushSnapshot. Reconnection: exponential backoff 1 s → 30 s with jitter; after an upgrade
+ * failure or 3 drops in 60 s the connector falls back to HTTP and retries WebSocket every 10 min.
+ * The token travels in-band (auth frame / Authorization header) — never in a URL, never logged.
+ */
+const DEFAULT_TIMING = { backoffMin: 1000, backoffMax: 30000, dropWindow: 60000, dropLimit: 3, wsRetryEvery: 600000, pollTimeout: 35000, wsOpenTimeout: 15000 };
+const REJECTED = 'token rejected by the server — run `spectoflow dashboard login` again';
+
+function createConnector(opts) {
+  const { token, machineName, listPublished, readSnapshot, execOp } = opts;
+  const version = opts.version || '0.0.0';
+  const base = String(opts.url || '').replace(/\/+$/, '');
+  const preferred = opts.transport === 'http' ? 'http' : 'ws';
+  const timing = { ...DEFAULT_TIMING, ...(opts.timing || {}) };
+  const log = opts.log || (() => {});
+
+  const state = { connected: false, lastError: null, machineId: null, attempts: 0, since: null };
+  let mode = preferred;          // transport in use ('ws' | 'http'); may fall back to 'http'
+  let stopped = true;
+  let active = null;             // the live transport: { send(frame), close() }
+  let generation = 0;            // bumps on every connect/stop so a stale transport's callbacks are ignored
+  const drops = [];
+  let reconnectTimer = null, wsRetryTimer = null;
+
+  function status() {
+    return { url: base, machineName, connected: state.connected, transport: mode, lastError: state.lastError, machineId: state.machineId, since: state.since };
+  }
+
+  // ---- frames ----
+  async function handleDownward(frame, send) {
+    if (!frame || typeof frame !== 'object') return;
+    if (frame.type === 'auth-ok') { state.machineId = frame.machineId || null; onConnected(); return; }
+    if (frame.type === 'ping') { send({ type: 'pong' }); return; }
+    if (frame.type === 'op') {
+      let reply;
+      try {
+        const result = await execOp(frame.p, frame.op, frame.args || {});
+        reply = { type: 'reply', reqId: frame.reqId, result: result === undefined ? {} : result };
+      } catch (e) {
+        reply = { type: 'reply', reqId: frame.reqId, error: { status: Number(e && e.status) || 500, message: String(e && e.message || e) } };
+      }
+      send(reply);
+    }
+  }
+  function onConnected() {
+    state.connected = true; state.lastError = null; state.attempts = 0; state.since = new Date().toISOString();
+    log(`online dashboard: connected to ${base} (${mode})`);
+    announce();
+  }
+  async function announce() {
+    const t = active;
+    if (!t || !state.connected) return;
+    const projects = listPublished();
+    t.send({ type: 'hello', machineName, projects });
+    for (const p of projects) {
+      try { const project = await readSnapshot(p.localId); if (project && t === active) t.send({ type: 'snapshot', p: p.localId, project }); }
+      catch (e) { log(`online dashboard: snapshot of ${p.localId} failed: ${e.message}`); }
+    }
+  }
+  function pushEvent(localId, event) { if (active && state.connected) active.send({ type: 'event', p: localId, event }); }
+  function pushSnapshot(localId, project) { if (active && state.connected) active.send({ type: 'snapshot', p: localId, project }); }
+
+  // ---- lifecycle ----
+  function onDisconnected(gen, err, { upgradeFailed = false } = {}) {
+    if (gen !== generation) return;           // a transport we already replaced
+    const was = state.connected;
+    state.connected = false; active = null;
+    if (err) state.lastError = String(err.message || err);
+    if (was) log(`online dashboard: disconnected from ${base}${err ? ' — ' + state.lastError : ''}`);
+    if (stopped) return;
+    if (mode === 'ws' && preferred === 'ws') {
+      const now = Date.now();
+      drops.push(now); while (drops.length && now - drops[0] > timing.dropWindow) drops.shift();
+      if (upgradeFailed || drops.length >= timing.dropLimit) {
+        mode = 'http'; drops.length = 0;
+        log('online dashboard: WebSocket unavailable, falling back to HTTP long-poll');
+        scheduleWsRetry();
+      }
+    }
+    scheduleReconnect();
+  }
+  function backoff() {
+    const exp = Math.min(timing.backoffMax, timing.backoffMin * 2 ** Math.min(state.attempts, 10));
+    state.attempts++;
+    return Math.round(exp * (0.75 + Math.random() * 0.5));
+  }
+  function scheduleReconnect() { clearTimeout(reconnectTimer); reconnectTimer = setTimeout(connect, backoff()); }
+  function scheduleWsRetry() {
+    clearTimeout(wsRetryTimer);
+    wsRetryTimer = setTimeout(() => { if (!stopped && mode === 'http') { mode = 'ws'; forceReconnect(); } }, timing.wsRetryEvery);
+  }
+  function connect() {
+    if (stopped) return;
+    clearTimeout(reconnectTimer);
+    const gen = ++generation;
+    active = mode === 'http' ? httpTransport(gen) : wsTransport(gen);
+  }
+  function start() { if (!stopped) return; stopped = false; mode = preferred; state.attempts = 0; connect(); }
+  function stop() {
+    stopped = true; generation++;
+    clearTimeout(reconnectTimer); clearTimeout(wsRetryTimer);
+    const t = active; active = null; state.connected = false;
+    if (t) t.close();
+  }
+  function forceReconnect() {
+    if (stopped) return;
+    const t = active; generation++; active = null; state.connected = false; state.attempts = 0;
+    if (t) t.close();
+    connect();
+  }
+
+  // ---- transport 1: native WebSocket ----
+  // A handshake that never resolves (no open/error/close at all — observed on some platforms when
+  // the server rejects the upgrade with a plain HTTP response) must still fail: wsOpenTimeout bounds
+  // it so the connector always falls back to HTTP instead of hanging forever in 'ws' mode.
+  function wsTransport(gen) {
+    let ws, opened = false, settled = false, lastErr = null;
+    const settle = (err, opts) => { if (settled) return; settled = true; clearTimeout(openTimer); onDisconnected(gen, err, opts); };
+    try { ws = new WebSocket(base.replace(/^http/, 'ws') + '/connector/ws'); }
+    catch (e) { setImmediate(() => settle(e, { upgradeFailed: true })); return { send() {}, close() {} }; }
+    const openTimer = setTimeout(() => {
+      try { ws.close(); } catch (_) {}
+      settle(new Error('WebSocket handshake timed out'), { upgradeFailed: true });
+    }, timing.wsOpenTimeout);
+    const send = (frame) => { if (ws.readyState === 1) ws.send(JSON.stringify(frame)); };
+    ws.addEventListener('open', () => { opened = true; clearTimeout(openTimer); send({ type: 'auth', token, version }); });
+    ws.addEventListener('message', (ev) => { let f; try { f = JSON.parse(String(ev.data)); } catch { return; } handleDownward(f, send); });
+    ws.addEventListener('error', (ev) => { lastErr = new Error((ev && ev.message) || 'websocket error'); });
+    ws.addEventListener('close', (ev) => {
+      const code = ev && ev.code;
+      const err = code === 4401 ? new Error(REJECTED) : lastErr || (code && code !== 1000 && code !== 1005 ? new Error(`connection closed (${code}${ev.reason ? ' ' + ev.reason : ''})`) : null);
+      settle(err, { upgradeFailed: !opened });
+    });
+    return { send, close: () => { clearTimeout(openTimer); try { ws.close(1000); } catch (_) {} } };
+  }
+
+  // ---- transport 2: HTTP long-poll ----
+  // Upward frames are POSTed in batches, strictly one batch in flight at a time (ordering). Downward
+  // frames arrive in the POST responses and through a GET loop the server holds open ≤ 25 s. The first
+  // batch carries `auth` so the frame sequence is the same as on WebSocket; the Authorization header is
+  // what actually authenticates every request.
+  function httpTransport(gen) {
+    const ac = new AbortController();
+    const headers = { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' };
+    let queue = [{ type: 'auth', token, version }];
+    let flushing = false, closed = false;
+    const alive = () => !closed && gen === generation;
+    const signal = () => AbortSignal.any([ac.signal, AbortSignal.timeout(timing.pollTimeout)]);
+    const fail = (e) => { if (!alive()) return; closed = true; ac.abort(); onDisconnected(gen, e); };
+    const check = (res, what) => {
+      if (res.status === 401) throw new Error(REJECTED);
+      if (!res.ok) throw new Error(`${what} /connector/frames → HTTP ${res.status}`);
+      return res.json();
+    };
+    async function flush() {
+      if (flushing) return;
+      flushing = true;
+      try {
+        while (alive() && queue.length) {
+          const batch = queue; queue = [];
+          const res = await fetch(base + '/connector/frames', { method: 'POST', headers, body: JSON.stringify(batch), signal: signal() });
+          const down = await check(res, 'POST');
+          for (const f of down) handleDownward(f, send);   // not awaited: a slow op must not stall the batch loop
+        }
+      } catch (e) { fail(e); } finally { flushing = false; }
+    }
+    async function poll() {
+      try {
+        while (alive()) {
+          const res = await fetch(base + '/connector/frames', { headers: { Authorization: headers.Authorization }, signal: signal() });
+          if (!alive()) return;
+          const down = await check(res, 'GET');
+          for (const f of down) handleDownward(f, send);   // not awaited: a slow op must not stall the batch loop
+        }
+      } catch (e) { fail(e); }
+    }
+    function send(frame) { if (!alive()) return; queue.push(frame); flush(); }
+    flush(); poll();
+    return { send, close: () => { closed = true; ac.abort(); } };
+  }
+
+  return { start, stop, status, announce, pushEvent, pushSnapshot, forceReconnect };
+}
+
+module.exports = { createConnector, DEFAULT_TIMING };

package/lib/dashboard/handlers.js

@@ -0,0 +1,53 @@
+'use strict';
+/*
+ * HTTP glue for one project: parse the request, pick the op, call it, serialize. Every operation
+ * lives in ops.js (pure, transport-agnostic) — nothing here decides anything about the project.
+ *
+ * createHandlers(root) returns what a listener-owning process (hub-server.js) needs:
+ *   - handleApi(req, res, u, emit): Promise<boolean> — true if this was an API route (handled).
+ *     Excludes /api/events: SSE registration stays with whoever owns the HTTP listener.
+ *   - watchDirs: dirs (relative to root) whose changes should emit {type:'change'}.
+ *   - onBoot(): once per project per process (creates the custom-views dir, clears a stale
+ *     in-flight orchestration).
+ */
+const fs = require('fs');
+const path = require('path');
+const { ops, OpError } = require('./ops');
+const orchestrator = require('./orchestrator');
+
+function sendJSON(res, code, obj) { res.writeHead(code, { 'Content-Type': 'application/json; charset=utf-8' }); res.end(JSON.stringify(obj)); }
+function body(req) { return new Promise((r) => { let b = ''; req.on('data', (c) => b += c); req.on('end', () => { try { r(JSON.parse(b || '{}')); } catch { r({}); } }); }); }
+
+const { ROUTES, findRoute } = require('./routes');
+
+function createHandlers(root) {
+  async function handleApi(req, res, u, emit) {
+    const p = u.pathname;
+    const route = findRoute(req.method, p);
+    if (!route) return false;
+    const [, , opName, args] = route;
+    const b = req.method === 'GET' ? {} : await body(req);
+    try {
+      const result = await ops[opName](root, args(u, b, p), { emit });
+      sendJSON(res, 200, result);
+    } catch (e) {
+      if (e instanceof OpError) sendJSON(res, e.status, { error: e.message });
+      else sendJSON(res, 500, { error: String(e && e.message || e) });
+    }
+    return true;
+  }
+  function onBoot() {
+    try { fs.mkdirSync(path.join(root, '.spectoflow', 'dashboards'), { recursive: true }); } catch (_) {}
+    // A process restart loses any in-flight orchestration; clear a stale 'running'/'awaiting_approval'
+    // so the 409 guard in orchestrate.start can't wedge forever. Not a resume — just un-wedging.
+    try { orchestrator.reconcileOnBoot(root); } catch (_) {}
+  }
+  return {
+    handleApi,
+    // The legacy custom-views dir is watched too, until `spectoflow update` migrates it (Task 4/8).
+    watchDirs: ['plans', 'specs', '.spectoflow', '.spectoflow/dashboards', '.spectoflow/dashboard/custom'],
+    onBoot,
+  };
+}
+
+module.exports = { createHandlers, ROUTES };

package/lib/{hub-server.js → dashboard/hub-server.js}

@@ -1,11 +1,11 @@
 'use strict';
 /*
  * The multi-project hub's server process — global (ships under lib/, never vendored into a
- * project's .spectoflow/). Registry-driven: resolves a project's root + route logic on demand from
+ * project's .spectoflow/). Registry-driven: resolves a project's root on demand from
  * ~/.spectoflow/projects.json (see lib/registry.js), keyed by the opaque id in /p/<id>/... URLs.
- * Each project's own vendored handlers.js is require()'d dynamically by absolute path — Node's
- * require cache keys by resolved path, so two different projects' identically-named handlers.js
- * files are cached and run completely independently (see docs/multi-project-hub-design.md).
+ * The route logic is THIS package's own handlers.js (./handlers.js), shared by every project (D64):
+ * nothing is ever require()'d from a project, so a project that has never run `spectoflow update`
+ * opens exactly like a fresh one (see docs/multi-project-hub-design.md).
  *
  * URL scheme (settled in the design doc): pages use a path prefix (/p/<id>/board, bookmarkable on
  * their own); every /api/* call instead takes a ?p=<id> query param (smaller client diff, and
@@ -21,74 +21,129 @@ const http = require('http');
 const fs = require('fs');
 const os = require('os');
 const path = require('path');
-const registry = require('./registry');
+const registry = require('../registry');
+const workspace = require('../workspace');
+const { createHandlers } = require('./handlers');
+const store = require('../store');
+const { createConnector } = require('./connector');
+const { ops, OpError } = require('./ops');
+const { injectDesign, DEFAULT_DESIGN } = require('./inject-design');
 
-const PORT = process.env.SPECTOFLOW_PORT ? Number(process.env.SPECTOFLOW_PORT) : 4319;
-const PUBLIC = path.join(__dirname, '..', 'templates', 'dashboard', 'public');
-const TEMPLATES = path.join(__dirname, '..', 'templates');
-const VERSION = require('../package.json').version;
+const migrated = workspace.migrateLegacyHome();
+if (!workspace.exists()) workspace.init({});
+const PORT = process.env.SPECTOFLOW_PORT ? Number(process.env.SPECTOFLOW_PORT) : workspace.settings().port;
+const PUBLIC = path.join(__dirname, 'public');
+const TEMPLATES = path.join(__dirname, '..', '..', 'templates');
+const VERSION = require('../../package.json').version;
 const MIME = { '.html':'text/html; charset=utf-8', '.css':'text/css; charset=utf-8', '.js':'application/javascript; charset=utf-8', '.png':'image/png', '.svg':'image/svg+xml', '.ico':'image/x-icon', '.woff2':'font/woff2', '.woff':'font/woff' };
 function sendJSON(res,code,obj){ res.writeHead(code,{'Content-Type':'application/json; charset=utf-8'}); res.end(JSON.stringify(obj)); }
 function body(req) { return new Promise((r) => { let b = ''; req.on('data', (c) => b += c); req.on('end', () => { try { r(JSON.parse(b || '{}')); } catch { r({}); } }); }); }
 
-// id -> { id, root, handlers, clients:Set, emit }, populated lazily on first request for that id and
-// kept alive for the process's life (registries are small; no need to tear down on last-tab-close).
+// id -> { id, root, handlers, clients:Set, emit, watchers:[] }. The route logic is THIS package's
+// handlers.js for every project (D64): nothing is ever require()'d from a project, so a project that
+// has never run `spectoflow update` opens exactly like a fresh one.
 const projects = new Map();
+
+// ---- online dashboard (C1): the connector role ----
+// One outbound connection to the online dashboard named in the workspace's remote.json (written by
+// `spectoflow dashboard login`). Only published projects (meta.json → published:true, cached here as
+// a Set so a chatty run-line stream never re-reads the file) are announced and relayed. Every project's
+// emit is teed: SSE clients first, then the connector — the same emit an op called from the relay
+// uses, so a local click and an online click hit one orchestrator, one pending gate, one state.
+let connector = null;
+let publishedIds = new Set();
+function refreshPublished() { publishedIds = new Set(workspace.listPublished().map((p) => p.id)); }
+const snapshotTimers = new Map();
+function scheduleSnapshot(id) {
+  clearTimeout(snapshotTimers.get(id));
+  snapshotTimers.set(id, setTimeout(async () => {
+    snapshotTimers.delete(id);
+    if (!connector || !publishedIds.has(id)) return;
+    try { const project = await readSnapshot(id); if (project) connector.pushSnapshot(id, project); } catch (_) {}
+  }, 500));
+}
+async function readSnapshot(id) {
+  const proj = getProject(id);
+  return proj ? ops['project.read'](proj.root, {}, { emit() {} }) : null;
+}
+function listPublishedForHello() {
+  return workspace.listPublished().map((p) => ({ localId: p.id, name: p.name, kind: p.kind || 'spectoflow', stats: projectStats(p.path) }));
+}
+async function execOp(localId, op, args) {
+  if (!publishedIds.has(localId)) throw new OpError(403, 'This project is not published.');
+  const proj = getProject(localId);
+  if (!proj) throw new OpError(404, projectErrorMessage(localId));
+  if (!Object.prototype.hasOwnProperty.call(ops, op)) throw new OpError(404, `Unknown operation "${op}".`);
+  return ops[op](proj.root, args || {}, { emit: proj.emit });
+}
+function startConnector() {
+  if (connector) { connector.stop(); connector = null; }
+  refreshPublished();
+  const remote = workspace.readRemote();
+  if (!remote) return;
+  connector = createConnector({
+    url: remote.url, token: remote.token, machineName: remote.machineName || os.hostname(), transport: remote.transport, version: VERSION,
+    listPublished: listPublishedForHello, readSnapshot, execOp, log: (m) => console.log(`spectoflow · ${m}`),
+  });
+  connector.start();
+}
+function remoteStatus() {
+  const remote = workspace.readRemote();
+  if (!remote) return { configured: false, url: null, machineName: null, connected: false, transport: null, lastError: null, since: null };
+  const s = connector ? connector.status() : { connected: false, transport: remote.transport, lastError: null, since: null };
+  return { configured: true, url: remote.url, machineName: remote.machineName, connected: s.connected, transport: s.transport, lastError: s.lastError, since: s.since };
+}
+
 function getProject(id) {
   if (projects.has(id)) return projects.get(id);
   const entry = registry.listProjects().find((p) => p.id === id);
-  if (!entry) return null;
-  const handlersPath = path.join(entry.path, '.spectoflow', 'dashboard', 'handlers.js');
-  let createHandlers;
-  try { ({ createHandlers } = require(handlersPath)); }
-  catch { return null; } // project's folder moved/deleted, or predates the handlers.js split
+  if (!entry || !fs.existsSync(entry.path)) return null;
   const handlers = createHandlers(entry.path);
   const clients = new Set();
-  const emit = (obj) => { const line = 'data: ' + JSON.stringify(obj) + '\n\n'; for (const res of clients) res.write(line); };
+  const emit = (obj) => {
+    const line = 'data: ' + JSON.stringify(obj) + '\n\n';
+    for (const res of clients) res.write(line);
+    if (connector && publishedIds.has(id)) { connector.pushEvent(id, obj); if (obj.type === 'change') scheduleSnapshot(id); }
+  };
   handlers.onBoot();
+  const watchers = [];
+  // A single logical write (e.g. store.js's write-then-rename) can fire an fs.watch directory
+  // listener several times in a row for one underlying change (worst on Windows, which also reports
+  // sibling-entry metadata churn) — coalesce any burst within 150ms into exactly one 'change' emit,
+  // so a published project's connector feed gets one 'event' frame per real change, not several.
+  let changeTimer = null;
+  const onDirChange = () => { clearTimeout(changeTimer); changeTimer = setTimeout(() => emit({ type: 'change' }), 150); };
   handlers.watchDirs.forEach((d) => {
     const dir = path.join(entry.path, d);
-    if (fs.existsSync(dir)) { try { fs.watch(dir, { recursive: false }, () => emit({ type: 'change' })); } catch (_) {} }
+    if (fs.existsSync(dir)) { try { watchers.push(fs.watch(dir, { recursive: false }, onDirChange)); } catch (_) {} }
   });
-  const proj = { id, root: entry.path, handlers, clients, emit };
+  const proj = { id, root: entry.path, handlers, clients, emit, watchers };
   projects.set(id, proj);
   return proj;
 }
 
-// Only called after getProject(id) already returned null — figures out WHY, so the 404 points the
-// user at the right fix instead of a bare "unknown project". The two common real causes: never
-// registered at all, vs. registered but this project predates handlers.js (needs `spectoflow
-// update`) or its folder moved/was deleted.
+// Only called after getProject(id) returned null. Two causes remain (D64 removed "needs an update").
 function projectErrorMessage(id) {
   const entry = registry.listProjects().find((p) => p.id === id);
   if (!entry) return 'Unknown project.';
-  if (!fs.existsSync(entry.path)) return `Project "${entry.name}" is registered, but its folder no longer exists at ${entry.path}.`;
-  const handlersPath = path.join(entry.path, '.spectoflow', 'dashboard', 'handlers.js');
-  if (!fs.existsSync(handlersPath)) return `Project "${entry.name}" needs an update — run \`spectoflow update\` inside it, then reload this page.`;
-  return `Project "${entry.name}" is registered, but its dashboard code failed to load — check its .spectoflow/dashboard/handlers.js for errors.`;
+  return `Project "${entry.name}" is registered, but its folder no longer exists at ${entry.path}.`;
 }
 
-// Clears every require.cache entry under this project's own .spectoflow/ tree (its vendored
-// handlers.js and everything IT requires — orchestrator.js, runner.js, files.js, summarize.js,
-// lib/store.js, lib/agents-registry.js) and drops its cached Map entry. The require cache keys by
-// absolute path, so this can never touch another project's identically-named files. Returns false
-// (a harmless no-op, not an error) if this id was never loaded — nothing to invalidate.
+// Re-opens a project: drops its cached entry and closes its watchers so the next request re-runs
+// onBoot and re-watches (a project's dirs may have changed after `spectoflow update`). Returns false
+// (a harmless no-op) if this id was never loaded.
 function reloadProject(id) {
   const proj = projects.get(id);
   if (!proj) return false;
-  const prefix = path.join(proj.root, '.spectoflow') + path.sep;
-  for (const key of Object.keys(require.cache)) {
-    if (key.startsWith(prefix)) delete require.cache[key];
-  }
+  proj.watchers.forEach((w) => { try { w.close(); } catch (_) {} });
+  require('./orchestrator').clearPending(proj.root);
   projects.delete(id);
   return true;
 }
 
 // ---- hub API: list/add/remove registered projects, browse the filesystem to find one ----
 function projectStats(root) {
-  // Best-effort — a moved/deleted/corrupt project must never break the whole listing.
   try {
-    const store = require(path.join(root, '.spectoflow', 'lib', 'store.js'));
     const plans = store.readPlans(root);
     let total = 0, done = 0;
     for (const pl of plans) for (const ph of pl.phases) for (const t of ph.tasks) { total++; if (t.status === 'done') done++; }
@@ -96,7 +151,7 @@ function projectStats(root) {
   } catch { return null; }
 }
 function listHubProjects() {
-  return registry.listProjects().map((p) => ({ ...p, stats: projectStats(p.path) }));
+  return registry.listProjects().map((p) => ({ ...p, stats: projectStats(p.path), published: publishedIds.has(p.id) }));
 }
 function listRoots() {
   const home = os.homedir();
@@ -130,15 +185,15 @@ function addHubProject(rawPath) {
   if (!fs.existsSync(abs) || !fs.statSync(abs).isDirectory()) return { error: 'That folder does not exist.' };
   const hasSpectoflow = fs.existsSync(path.join(abs, '.spectoflow'));
   if (!hasSpectoflow) {
-    const { runInit } = require('./init');
+    const { runInit } = require('../init');
     runInit({ target: abs, templatesDir: TEMPLATES, version: VERSION });
   }
-  const entry = registry.addProject(abs);
+  const entry = workspace.registerProject(abs);
   return { entry, initialized: !hasSpectoflow };
 }
 async function handleHubApi(req, res, u) {
   const p = u.pathname;
-  if (p === '/api/hub/projects' && req.method === 'GET') { sendJSON(res, 200, { projects: listHubProjects() }); return true; }
+  if (p === '/api/hub/projects' && req.method === 'GET') { sendJSON(res, 200, { projects: listHubProjects(), remote: remoteStatus() }); return true; }
   if (p === '/api/hub/projects' && req.method === 'POST') {
     const { path: rawPath } = await body(req);
     if (!rawPath || !String(rawPath).trim()) { sendJSON(res, 400, { error: 'A folder path is required.' }); return true; }
@@ -149,6 +204,7 @@ async function handleHubApi(req, res, u) {
   if (/^\/api\/hub\/projects\/[^/]+$/.test(p) && req.method === 'DELETE') {
     const id = decodeURIComponent(p.split('/')[4] || '');
     const ok = registry.removeProject(id);
+    if (ok) { refreshPublished(); if (connector) connector.announce(); }
     sendJSON(res, ok ? 200 : 404, ok ? { ok: true } : { error: 'No project registered with that id.' });
     return true;
   }
@@ -164,13 +220,38 @@ async function handleHubApi(req, res, u) {
     sendJSON(res, 200, { ok: true, reloaded });
     return true;
   }
+  if (p === '/api/hub/remote' && req.method === 'GET') { sendJSON(res, 200, remoteStatus()); return true; }
+  if (p === '/api/hub/remote/reconnect' && req.method === 'POST') { startConnector(); sendJSON(res, 200, { ok: true, ...remoteStatus() }); return true; }
+  if (/^\/api\/hub\/projects\/[^/]+\/publish$/.test(p) && req.method === 'POST') {
+    const id = decodeURIComponent(p.split('/')[4] || '');
+    const { published } = await body(req);
+    const meta = workspace.setPublished(id, published !== false);
+    if (!meta) { sendJSON(res, 404, { error: 'No project registered with that id.' }); return true; }
+    refreshPublished();
+    if (connector) connector.announce();
+    sendJSON(res, 200, { ok: true, id, published: meta.published });
+    return true;
+  }
   return false;
 }
 
+// A viewer's own localStorage choice (once one exists) always wins client-side (app.js's IIFE at the
+// top of the file, and the reconciliation in renderSettings()) — this is only filling the gap for a
+// visitor with nothing saved yet, so the very first paint already matches the project's own
+// configured design instead of flashing whatever static default shipped in the HTML file.
+function projectDesign(root) {
+  if (!root) return DEFAULT_DESIGN;
+  try { return (store.readConfig(root) || {}).design || DEFAULT_DESIGN; }
+  catch { return DEFAULT_DESIGN; }
+}
+
 // Serves one static asset (or the SPA index.html fallback for an extensionless path) from the
-// shared, globally-installed PUBLIC dir — identical logic to templates/dashboard/server.js's own,
-// just factored into a function since both the root-level and /p/<id>/-prefixed requests need it.
-function serveStatic(reqPath, req, res) {
+// shared, globally-installed PUBLIC dir — factored into a function since both the root-level and
+// /p/<id>/-prefixed requests need it. `root` (the specific project's folder), when known, is used to
+// stamp the served HTML's <html data-design="..."> synchronously with that project's own
+// config.design, before the file ever reaches the browser — avoiding a flash of the wrong theme on a
+// viewer's very first-ever page load (no localStorage value saved yet to reconcile against).
+function serveStatic(reqPath, req, res, root) {
   const file = reqPath === '/' ? '/index.html' : reqPath;
   const full = path.join(PUBLIC, path.normalize(file).replace(/^(\.\.[/\\])+/, ''));
   if (!full.startsWith(PUBLIC)) { res.writeHead(403); return res.end('Forbidden'); }
@@ -180,24 +261,26 @@ function serveStatic(reqPath, req, res) {
       if (req.method === 'GET' && !path.extname(reqPath)) {
         return fs.readFile(path.join(PUBLIC, 'index.html'), (e2, d2) => {
           if (e2) { res.writeHead(404); return res.end('Not found'); }
-          res.writeHead(200, Object.assign({ 'Content-Type': MIME['.html'] }, noCache)); res.end(d2);
+          const html = root ? injectDesign(d2.toString('utf8'), projectDesign(root)) : d2;
+          res.writeHead(200, Object.assign({ 'Content-Type': MIME['.html'] }, noCache)); res.end(html);
         });
       }
       res.writeHead(404); return res.end('Not found');
     }
     const ext = path.extname(full);
     const headers = ext === '.woff2' || ext === '.woff' ? { 'Cache-Control': 'public, max-age=604800' } : noCache;
-    res.writeHead(200, Object.assign({ 'Content-Type': MIME[ext] || 'application/octet-stream' }, headers)); res.end(data);
+    const payload = (root && ext === '.html') ? injectDesign(data.toString('utf8'), projectDesign(root)) : data;
+    res.writeHead(200, Object.assign({ 'Content-Type': MIME[ext] || 'application/octet-stream' }, headers)); res.end(payload);
   });
 }
 
 const PROJECT_PREFIX = /^\/p\/([0-9a-f]{6})(\/.*)?$/;
 
-const LOCK = registry.hubLockPath();
+const LOCK = workspace.lockPath();
 function writeLock(){ try{ fs.mkdirSync(path.dirname(LOCK),{recursive:true}); fs.writeFileSync(LOCK, JSON.stringify({ pid:process.pid, port:PORT, url:`http://localhost:${PORT}`, startedAt:new Date().toISOString() })+'\n'); }catch{} }
 function clearLock(){ try{ const l=JSON.parse(fs.readFileSync(LOCK,'utf8')); if(l.pid===process.pid) fs.unlinkSync(LOCK); }catch{} }
 process.on('exit', clearLock);
-['SIGINT','SIGTERM'].forEach((s)=> process.on(s, ()=>{ clearLock(); process.exit(0); }));
+['SIGINT','SIGTERM'].forEach((s)=> process.on(s, ()=>{ if (connector) connector.stop(); clearLock(); process.exit(0); }));
 
 const server = http.createServer(async (req, res) => {
   const u = new URL(req.url, `http://localhost:${PORT}`);
@@ -235,7 +318,7 @@ const server = http.createServer(async (req, res) => {
       const proj = getProject(id);
       if (!proj) { res.writeHead(404); return res.end(projectErrorMessage(id)); }
       registry.touchProject(id);
-      return serveStatic(m[2] || '/', req, res);
+      return serveStatic(m[2] || '/', req, res, proj.root);
     }
 
     if (p === '/') {
@@ -255,4 +338,4 @@ const server = http.createServer(async (req, res) => {
   } catch (e) { sendJSON(res, 500, { error: String(e && e.message || e) }); }
 });
 
-server.listen(PORT, () => { writeLock(); console.log(`spectoflow · hub → http://localhost:${PORT}`); });
+server.listen(PORT, () => { writeLock(); console.log(`spectoflow · hub → http://localhost:${PORT}${migrated.movedRegistry ? '  (moved your project list into the workspace)' : ''}`); startConnector(); });

package/lib/dashboard/inject-design.js

@@ -0,0 +1,41 @@
+'use strict';
+/*
+ * Shared by both dashboard surfaces — the local hub (hub-server.js) and the online relay
+ * (server/src/app.js) — so a project's own configured design (config.design) is stamped onto the
+ * served index.html's <html data-design="..."> attribute BEFORE the file ever reaches the browser.
+ * Design is a shared, project-level setting (not a per-viewer choice, Sous-projet B) — this is the
+ * ONLY place the design attribute is ever set for first paint; app.js has no localStorage fallback
+ * or reconciliation for it any more, it only reflects P.config.design once the client boots.
+ */
+
+// Mirrors app.js's currentDesign() own default ('console') when the attribute is absent — same
+// fallback a project with no design saved yet (or an unresolvable project) would land on anyway.
+const DEFAULT_DESIGN = 'console';
+
+// The real, live registry of selectable designs (lib/dashboard/public/designs.js) — required, not
+// re-declared here, so an id added/removed there is instantly reflected here with zero drift risk.
+const DESIGNS = require('./public/designs.js');
+const KNOWN_IDS = new Set(DESIGNS.map((d) => d.id));
+
+// Only ever accept a value that is one of the real, currently-registered design ids — never trust an
+// arbitrary stored/cached string into the HTML (that would be an injection risk), and never trust a
+// shape-valid but unregistered id either (a stale/typo'd/removed design would silently produce an
+// unstyled page instead of falling back to the same default a missing value gets).
+function sanitizeDesign(d) {
+  return (typeof d === 'string' && KNOWN_IDS.has(d)) ? d : DEFAULT_DESIGN;
+}
+
+// Rewrites (or adds) the <html> tag's data-design attribute to the given value — leaves everything
+// else in the file untouched, including data-theme (config.theme is applied client-side once app.js
+// boots, same as before — this injector was only ever built to solve design's first-paint flash).
+function injectDesign(html, design) {
+  const safe = sanitizeDesign(design);
+  return html.replace(/<html([^>]*)>/i, (full, attrs) => {
+    const newAttrs = /\bdata-design=/.test(attrs)
+      ? attrs.replace(/data-design="[^"]*"/, `data-design="${safe}"`)
+      : `${attrs} data-design="${safe}"`;
+    return `<html${newAttrs}>`;
+  });
+}
+
+module.exports = { injectDesign, sanitizeDesign, DEFAULT_DESIGN };