@1agh/maude 0.23.0 → 0.24.0

package/plugins/design/dev-server/sync/index.ts

@@ -24,11 +24,21 @@ import path from 'node:path';
 import type { Awareness } from 'y-protocols/awareness';
 import * as Y from 'yjs';
 
+import { Y_TYPES } from '../collab/persistence.ts';
 import type { Context } from '../context.ts';
 import { type CanvasSyncAgent, createCanvasSyncAgent } from './agent.ts';
+import {
+  type ConnectionMonitor,
+  type ProviderStatus,
+  createConnectionMonitor,
+} from './connection-state.ts';
 import { type EchoGuard, createEchoGuard } from './echo-guard.ts';
 import { type FsReader, createFsReader } from './fs-mirror.ts';
 import { getHubToken } from './hubs-config.ts';
+import { migrateSeed } from './migrate-seed.ts';
+import { type DocProjection, createDocProjection } from './projection.ts';
+import { type SyncStatusStore, createSyncStatusStore } from './status.ts';
+import { writeUntrustedMarkers } from './untrusted.ts';
 
 /** A minimum-surface stand-in for the HocuspocusProvider's runtime API. */
 export interface SyncProvider {
@@ -42,6 +52,12 @@ export interface SyncProvider {
   readonly awareness?: Awareness;
   /** Resolves when the first hub sync handshake completes. */
   onceSynced(): Promise<void>;
+  /**
+   * Subscribe to WS connection-status transitions (Phase 9 Task 8 offline
+   * mode). Returns an unsubscribe fn. Optional — a test stub or a provider
+   * without status events just isn't monitored (treated as always-online).
+   */
+  onStatus?(cb: (status: ProviderStatus) => void): () => void;
   destroy(): void;
 }
 
@@ -52,6 +68,23 @@ export interface SyncProvider {
  */
 export interface AwarenessRegistry {
   attachHubAwareness(slug: string, awareness: Awareness): () => void;
+  /** Phase 9.1 — relay a hub-pushed comment/annotation snapshot into a live
+   *  room (wholesale, in-process) so the peer's canvas reflects it immediately
+   *  and the room's own debounced persist can't clobber the synced state back.
+   *  Optional so file-sync-only tests can pass a minimal registry. */
+  syncRoomFromComments?(slug: string, comments: readonly unknown[]): void;
+  syncRoomFromAnnotations?(slug: string, svg: string): void;
+  /**
+   * Phase 9.2 (DDR-064) — the single cached `Y.Doc` for a slug. When present
+   * AND `ctx.sharedDoc` is set, the runtime attaches the HocuspocusProvider to
+   * THIS doc instead of a fresh one (the convergence: one doc, both providers).
+   * Optional so file-sync-only tests can pass a minimal registry.
+   */
+  getDoc?(slug: string): Y.Doc;
+  /** Keep a shared-doc room alive while its provider is attached (drop guard). */
+  pin?(slug: string): void;
+  /** Release the shared-doc pin on runtime stop. */
+  unpin?(slug: string): void;
 }
 
 /** Factory the runtime calls per discovered canvas. Default uses Hocuspocus. */
@@ -59,6 +92,13 @@ export type ProviderFactory = (args: {
   url: string;
   token: string;
   documentName: string;
+  /**
+   * Phase 9.2 (DDR-064) — when set, the provider MUST attach to this existing
+   * `Y.Doc` (the shared room doc) instead of creating its own. The runtime
+   * passes it only when `ctx.sharedDoc` is on and the registry exposes
+   * `getDoc`. Default factory: `args.document ?? new Y.Doc()`.
+   */
+  document?: Y.Doc;
 }) => SyncProvider | Promise<SyncProvider>;
 
 export interface SyncRuntime {
@@ -68,6 +108,8 @@ export interface SyncRuntime {
   size(): number;
   /** Test inspection — get the agent for a slug if one was created. */
   agentFor(slug: string): CanvasSyncAgent | undefined;
+  /** Current offline/sync status payload (Task 8), or null when unlinked. */
+  status(): import('./status.ts').SyncStatusPayload | null;
 }
 
 export interface CreateSyncRuntimeOptions {
@@ -83,6 +125,14 @@ export interface CreateSyncRuntimeOptions {
    * unit tests that only exercise the file-sync path.
    */
   registry?: AwarenessRegistry;
+  /**
+   * Override the offline-mode connection monitor (Task 8 test injection —
+   * lets tests pass injectable timers/clock). Defaults to a real monitor that
+   * writes `_sync.json` + broadcasts 'sync:status' on the bus.
+   */
+  connectionMonitor?: ConnectionMonitor;
+  /** Override the status store (Task 8 test injection). */
+  statusStore?: SyncStatusStore;
 }
 
 /**
@@ -95,6 +145,11 @@ export interface CanvasDescriptor {
   html: string;
   comments: string;
   annotations: string;
+  /** The canvas `.meta.json` sidecar (sibling of the body). Phase 9.1 Gap 2 —
+   *  shared keys (layout/artboards) sync; per-user viewport stays local. */
+  meta: string;
+  /** The canvas's sibling `.css` (Phase 9.1 Gap 3), synced as opaque text. */
+  css: string;
 }
 
 /**
@@ -143,36 +198,93 @@ export function createSyncRuntime(
   const providerFactory = opts.providerFactory ?? defaultProviderFactory;
   const echoGuard = createEchoGuard();
   const agents = new Map<string, CanvasSyncAgent>();
+  // Phase 9.2 (DDR-064) — under sharedDoc the disk handler is a loop-free
+  // projection (sole owner of html/css/meta doc→file + all-types file→doc),
+  // created INSTEAD of an agent. Exactly one of agents/projections is populated
+  // per run (chosen by useSharedDoc).
+  const projections = new Map<string, DocProjection>();
   const providers = new Map<string, SyncProvider>();
   const awarenessDetaches: Array<() => void> = [];
+  const statusDetaches: Array<() => void> = [];
+  // Phase 9.2 (DDR-064) — slugs pinned in the registry because a provider is
+  // attached to their shared doc; released on stop(). Empty unless sharedDoc.
+  const pinnedSlugs = new Set<string>();
+  // The shared-doc convergence path is active only when the flag is ON AND the
+  // registry can hand us the canvas's single doc. Flag OFF / no registry / a
+  // minimal test registry without getDoc → the proven two-doc path, unchanged.
+  const useSharedDoc = !!ctx.sharedDoc && typeof opts.registry?.getDoc === 'function';
   let fsReader: FsReader | null = null;
   let busUnsub: (() => void) | null = null;
   let started = false;
   let stopped = false;
 
+  // Task 8 — offline-mode status surface, initialized in start() once the
+  // canvas count is known. The store writes `_sync.json` + broadcasts
+  // 'sync:status' on the bus; the monitor aggregates provider WS status into
+  // online/offline/escalated and feeds every change to the store.
+  let statusStore: SyncStatusStore | null = null;
+  let monitor: ConnectionMonitor | null = null;
+
   async function start(): Promise<void> {
     if (started || stopped) return;
     started = true;
 
-    const canvases = opts.canvases ?? (await discoverCanvases(ctx));
+    const scan = opts.canvases ? { canvases: opts.canvases, tsxCount: 0 } : await scanCanvases(ctx);
+    const canvases = scan.canvases;
+    // T4.5 (DDR-054 §3 F3) — every syncable canvas can receive hub-pushed
+    // content, so the whole set is untrusted Claude-context. Mark it (writes
+    // `_untrusted/INDEX.json` + a managed `.claudeignore` block; clears both
+    // when the set is empty). Best-effort — never throws into boot.
+    writeUntrustedMarkers(ctx, canvases, linkedHub.url);
     if (canvases.length === 0) {
-      console.log(
-        `[sync] linked to ${linkedHub.url} — no canvases discovered under ${ctx.paths.designRoot}.`
-      );
+      // DDR-060 / 9.1-D — the silent early-return made linked mode look healthy
+      // while syncing nothing (TSX-only projects: discovery admits .html only,
+      // .tsx needs the opt-in + sandbox gate that 9.1-A/B ship). Surface the gap
+      // loudly: a warn, a `_sync.json` the CLI + browser banner read, and a bus
+      // broadcast so open tabs render it immediately.
+      surfaceNoSyncable(ctx, linkedHub.url, scan.tsxCount);
       return;
     }
 
+    statusStore =
+      opts.statusStore ??
+      createSyncStatusStore({
+        url: linkedHub.url,
+        canvases: canvases.length,
+        sharedDoc: useSharedDoc,
+        write: (payload) => {
+          const file = path.join(ctx.paths.designRoot, '_sync.json');
+          writeFileSync(file, `${JSON.stringify(payload, null, 2)}\n`, 'utf8');
+        },
+        broadcast: (payload) => ctx.bus.emit('sync:status', payload),
+      });
+    const store = statusStore;
+    monitor =
+      opts.connectionMonitor ?? createConnectionMonitor({ onChange: (snap) => store.update(snap) });
+    const mon = monitor;
+
     const reader = createFsReader({
       rootDir: ctx.paths.designRoot,
       accept: (rel) => {
         const ext = path.extname(rel).toLowerCase();
-        return ext === '.html' || ext === '.json' || ext === '.svg';
+        // `.tsx` added in T3 (9.1-B) so local edits to an opted-in syncable
+        // `.tsx` body propagate. Non-syncable `.tsx` changes still notify but
+        // match no agent in onRead (descriptor-scoped) → harmless no-op.
+        // `.css` added in Gap 3 so the canvas's sibling stylesheet syncs.
+        return (
+          ext === '.html' || ext === '.tsx' || ext === '.json' || ext === '.svg' || ext === '.css'
+        );
       },
       onRead: (evt) => {
+        const abs = path.join(ctx.paths.designRoot, evt.path);
+        // Dispatch to whichever disk handler owns this path. Only one of
+        // agents/projections is populated (useSharedDoc decides); the projector
+        // exposes the same applyFromFs(evt) shape as the agent.
         for (const agent of agents.values()) {
-          const abs = path.join(ctx.paths.designRoot, evt.path);
-          const changed = agent.applyFromFs({ path: abs, bytes: evt.bytes, hash: evt.hash });
-          if (changed) break; // a path belongs to at most one canvas
+          if (agent.applyFromFs({ path: abs, bytes: evt.bytes, hash: evt.hash })) return;
+        }
+        for (const proj of projections.values()) {
+          if (proj.applyFromFs({ path: abs, bytes: evt.bytes, hash: evt.hash })) return;
         }
       },
     });
@@ -188,25 +300,82 @@ export function createSyncRuntime(
 
     for (const canvas of canvases) {
       try {
+        // Phase 9.2 (DDR-064) — when sharedDoc is on, the provider attaches to
+        // the collab room's single Y.Doc (registry.getDoc) instead of a fresh
+        // one, so browser edits flow straight into the doc that syncs to the
+        // hub — no disk hop, no relay, no clobber. Pin the room so the
+        // last-browser-leaves drop can't destroy the doc out from under the
+        // provider. NB: cold-start seeding of a divergent local+hub doc is the
+        // duplication trap (Risk 1) — made safe by Phase E (migrate-seed); the
+        // flag stays OFF until then.
+        const sharedYDoc = useSharedDoc ? opts.registry?.getDoc?.(canvas.slug) : undefined;
+        if (useSharedDoc && sharedYDoc) {
+          opts.registry?.pin?.(canvas.slug);
+          pinnedSlugs.add(canvas.slug);
+        }
         const provider = await providerFactory({
           url: linkedHub.url,
           token,
           documentName: canvas.slug,
+          document: sharedYDoc,
         });
         providers.set(canvas.slug, provider);
-        const agent = createCanvasSyncAgent({
-          slug: canvas.slug,
-          doc: provider.document,
-          paths: {
-            html: canvas.html,
-            comments: canvas.comments,
-            annotations: canvas.annotations,
-          },
-          echoGuard,
-          adopt: adoptOnce,
-        });
-        agent.start();
-        agents.set(canvas.slug, agent);
+        const canvasPaths = {
+          html: canvas.html,
+          comments: canvas.comments,
+          annotations: canvas.annotations,
+          meta: canvas.meta,
+          css: canvas.css,
+        };
+        // Phase 9.2 (DDR-064) — the disk handler. Under sharedDoc it's a
+        // loop-free projection (html/css/meta doc→file + all-types file→doc;
+        // the collab room keeps comments/annotations doc→file, so no
+        // double-write). Flag-OFF keeps the proven two-doc agent.
+        let agent: CanvasSyncAgent | undefined;
+        let projection: DocProjection | undefined;
+        if (useSharedDoc && sharedYDoc) {
+          projection = createDocProjection({
+            slug: canvas.slug,
+            doc: provider.document,
+            paths: canvasPaths,
+            echoGuard,
+          });
+          projection.start();
+          projections.set(canvas.slug, projection);
+        } else {
+          agent = createCanvasSyncAgent({
+            slug: canvas.slug,
+            doc: provider.document,
+            paths: canvasPaths,
+            echoGuard,
+            adopt: adoptOnce,
+            onConflict: (info) => store.addConflict(info),
+          });
+          agent.start();
+          agents.set(canvas.slug, agent);
+        }
+
+        // Task 8 — feed this provider's WS status into the offline monitor.
+        if (provider.onStatus) {
+          statusDetaches.push(provider.onStatus((s) => mon.noteProviderStatus(canvas.slug, s)));
+        } else {
+          // No status events (test stub) — treat as connected so the monitor
+          // doesn't sit in the boot 'connecting' state forever.
+          mon.noteProviderStatus(canvas.slug, 'connected');
+        }
+        // Count local edits (agent-origin doc updates) toward queuedOps while
+        // the hub is unreachable — the banner's "N edits queued" figure. Under
+        // sharedDoc there is no agent origin to key off (browser edits carry a
+        // RoomConn origin); queued-edit counting in that mode is a known gap
+        // (offline-banner accuracy only, not data) deferred past Phase C.
+        if (agent) {
+          const agentOrigin = agent.origin;
+          const onLocalUpdate = (_u: Uint8Array, origin: unknown) => {
+            if (origin === agentOrigin) mon.noteLocalEdit();
+          };
+          provider.document.on('update', onLocalUpdate);
+          statusDetaches.push(() => provider.document.off('update', onLocalUpdate));
+        }
 
         // Task 5 — bridge the provider's hub-synced Awareness to the Room so
         // browser cursors relay cross-machine. No-op when the provider exposes
@@ -215,8 +384,74 @@ export function createSyncRuntime(
           awarenessDetaches.push(opts.registry.attachHubAwareness(canvas.slug, provider.awareness));
         }
 
+        // Relay hub-pushed comment/annotation changes straight into the live
+        // room — IN-PROCESS + synchronous, so the room's in-memory doc is
+        // updated BEFORE its 800ms persist timer can flush stale pre-sync state
+        // back over the file (the disk-mediated re-seed in createCollab loses
+        // that race under an actively-edited peer; this is the tight path that
+        // actually closes the "comment reverts" clobber). Wholesale-replace via
+        // syncRoomFrom* → no duplication. Skip agent-origin updates (our own
+        // disk→doc apply — the file is authoritative there; a local design:edit
+        // reaches the room via createCollab's fs hook instead).
+        //
+        // CRITICAL: observe the comment + annotation Y-types SEPARATELY, not the
+        // whole-doc update. A whole-doc relay re-applies BOTH types on every
+        // change, so a comment sync would re-push the (stale) annotation and
+        // clobber an annotation the peer just drew but hasn't synced yet — and
+        // vice versa. Per-type observers keep the two lanes independent.
+        //
+        // Phase 9.2 (DDR-064): under sharedDoc the provider IS attached to the
+        // room's doc, so there is no second doc to relay into — the room already
+        // has every change. Skipping the relay is what RETIRES the
+        // wholesale-replace clobber path (the Phase 9.1 ceiling): with one doc,
+        // CRDT merge handles concurrency, no last-writer-wins blob copy.
+        const reg = opts.registry;
+        if (!useSharedDoc && agent && reg?.syncRoomFromComments) {
+          const agentOrigin = agent.origin;
+          const slug = canvas.slug;
+          const provComments = provider.document.getArray(Y_TYPES.comments);
+          const provAnn = provider.document.getMap(Y_TYPES.annotations);
+          const onComments = (_e: unknown, tx: { origin: unknown }) => {
+            if (tx.origin === agentOrigin) return;
+            reg.syncRoomFromComments?.(slug, provComments.toArray());
+          };
+          const onAnn = (_e: unknown, tx: { origin: unknown }) => {
+            if (tx.origin === agentOrigin) return;
+            const svg = provAnn.get('svg');
+            if (typeof svg === 'string') reg.syncRoomFromAnnotations?.(slug, svg);
+          };
+          provComments.observe(onComments);
+          provAnn.observe(onAnn);
+          statusDetaches.push(() => {
+            provComments.unobserve(onComments);
+            provAnn.unobserve(onAnn);
+          });
+        }
+
         // Cold-start reconcile fires once the provider has hub state.
         void provider.onceSynced().then(async () => {
+          if (projection) {
+            // Phase E (DDR-064 Task 9) — one-time authoritative seed BEFORE
+            // materializing: escapes the duplication trap by picking ONE source
+            // (hub-wins if the synced doc holds state; adopt local files only
+            // when the hub was empty), inside a MIGRATION transaction. The room
+            // file-seed is disabled for this pinned slug (createCollab
+            // shouldSeed), so no duplicate items can be introduced afterward.
+            const result = migrateSeed({
+              slug: canvas.slug,
+              doc: provider.document,
+              paths: canvasPaths,
+              historyDir: path.join(ctx.paths.historyDir, canvas.slug),
+            });
+            if (result === 'local-adopt') {
+              console.log(`[sync/${canvas.slug}] shared-doc: adopted local state (hub was empty).`);
+            }
+            // Then materialize the converged doc to disk (safe — never clobbers
+            // non-empty local with an empty doc value).
+            projection.reconcile();
+            return;
+          }
+          if (!agent) return;
           await agent.reconcile();
           if (adoptOnce) {
             adoptReconciled++;
@@ -232,8 +467,17 @@ export function createSyncRuntime(
       }
     }
 
+    // Persist an initial status snapshot so `_sync.json` exists — and `maude
+    // design status` + the browser banner report "agent running" — from the
+    // moment serve boots. The ConnectionMonitor only emits on *transitions* and
+    // starts in 'online', so on a clean fast localhost connect (provider
+    // reaches 'connected' at/before subscribe → no transition fires) nothing
+    // would otherwise be written, and status would read "idle / sync agent not
+    // running" while sync is in fact healthy. This was the observed bug.
+    store.update(mon.snapshot());
+
     console.log(
-      `[sync] linked to ${linkedHub.url} — ${agents.size}/${canvases.length} canvas(es) syncing${adoptOnce ? ' (adopt mode — pushing local up)' : ''}.`
+      `[sync] linked to ${linkedHub.url} — ${agents.size + projections.size}/${canvases.length} canvas(es) syncing${useSharedDoc ? ' (shared-doc)' : ''}${adoptOnce ? ' (adopt mode — pushing local up)' : ''}.`
     );
   }
 
@@ -248,6 +492,25 @@ export function createSyncRuntime(
       }
     }
     awarenessDetaches.length = 0;
+    // Phase 9.2 (DDR-064) — release shared-doc pins so the rooms can be dropped
+    // / destroyed normally on shutdown. Empty unless sharedDoc was active.
+    for (const slug of pinnedSlugs) {
+      try {
+        opts.registry?.unpin?.(slug);
+      } catch {
+        /* best-effort */
+      }
+    }
+    pinnedSlugs.clear();
+    for (const detach of statusDetaches) {
+      try {
+        detach();
+      } catch {
+        /* best-effort */
+      }
+    }
+    statusDetaches.length = 0;
+    monitor?.stop();
     busUnsub?.();
     busUnsub = null;
     fsReader?.stop();
@@ -261,6 +524,19 @@ export function createSyncRuntime(
       }
     }
     agents.clear();
+    // Phase 9.2 (DDR-064) — final doc→file flush + stop the projectors BEFORE
+    // tearing down providers (so the converged doc lands on disk). The shared
+    // doc itself is owned by the collab room and destroyed by registry teardown,
+    // not here.
+    for (const proj of projections.values()) {
+      try {
+        await proj.flush();
+        proj.stop();
+      } catch {
+        /* best-effort */
+      }
+    }
+    projections.clear();
     for (const provider of providers.values()) {
       try {
         provider.destroy();
@@ -274,8 +550,11 @@ export function createSyncRuntime(
   return {
     start,
     stop,
-    size: () => agents.size,
+    // Under sharedDoc the per-canvas handler is a projection, not an agent;
+    // count both so size() reflects the synced-canvas count in either mode.
+    size: () => agents.size + projections.size,
     agentFor: (slug) => agents.get(slug),
+    status: () => statusStore?.get() ?? null,
   };
 }
 
@@ -287,21 +566,70 @@ export function createSyncRuntime(
  * specialised for the sync runtime (we only need the three paths per canvas,
  * not the full metadata).
  *
- * DDR-054 §2b — `.tsx` canvases are deliberately EXCLUDED from sync. The
- * dev-server transpiles `.tsx` to JavaScript and serves it as
+ * DDR-054 §2b / DDR-060 — `.tsx` canvases are deliberately EXCLUDED from sync.
+ * The dev-server transpiles `.tsx` to JavaScript and serves it as
  * `application/javascript` in iframe same-origin; a hostile hub pushing
- * arbitrary TypeScript source would result in RCE. `.tsx` stays editable in
- * solo mode; per-canvas opt-in via `.meta.json.syncable: true` is deferred to
- * Task 8 (alongside CSP + iframe sandbox).
+ * arbitrary TypeScript source would result in RCE (the audit's CRITICAL F1).
+ * Since Phase 3.6 made `.tsx` the ONLY canvas format, this means real projects
+ * discover zero syncable canvases — surfaced loudly by `surfaceNoSyncable`
+ * (9.1-D) rather than silently. The per-canvas opt-in (`.meta.json.syncable:
+ * true`) + CSP/sandbox gate that make `.tsx` syncable land in 9.1-A/B.
  */
 export async function discoverCanvases(ctx: Context): Promise<CanvasDescriptor[]> {
+  return (await scanCanvases(ctx)).canvases;
+}
+
+/** Result of a canvas-group scan: syncable descriptors + a tally of the .tsx
+ *  canvases that exist but are NOT yet syncable (DDR-060 — they need the
+ *  per-canvas opt-in + sandbox gate). The tsx count feeds 9.1-D's loud
+ *  zero-syncable surface so the message can say *why* nothing syncs. */
+export interface CanvasScan {
+  canvases: CanvasDescriptor[];
+  tsxCount: number;
+}
+
+export async function scanCanvases(ctx: Context): Promise<CanvasScan> {
   const out: CanvasDescriptor[] = [];
+  const counter = { tsx: 0 };
+  // T3 (9.1-B) — LOAD-BEARING coupling (the plan's "two locks flip together"
+  // invariant): a `.tsx` body is admitted to sync ONLY when the cross-origin
+  // CSP/sandbox containment is active (`ctx.canvasOrigin` is set — Lock 2). The
+  // sandbox is now ON BY DEFAULT, but a user can opt out with
+  // MAUDE_CANVAS_ORIGIN_SPLIT=0; if they do, `canvasOrigin` is undefined and NO
+  // `.tsx` syncs — the per-canvas opt-in is inert without the sandbox, and
+  // decoupling them would re-open the CRITICAL F1 RCE (DDR-060, DDR-054 §F1).
+  const splitActive = !!ctx.canvasOrigin;
   for (const group of ctx.cfg.canvasGroups) {
     const groupAbs = path.join(ctx.paths.designRoot, group.path);
     if (!existsSync(groupAbs)) continue;
-    await walk(groupAbs, ctx.paths.designRoot, ctx.paths.commentsDir, ctx.paths.designRel, out);
+    await walk(
+      groupAbs,
+      ctx.paths.designRoot,
+      ctx.paths.commentsDir,
+      ctx.paths.designRel,
+      out,
+      counter,
+      splitActive
+    );
+  }
+  return { canvases: out, tsxCount: counter.tsx };
+}
+
+/**
+ * T3 (9.1-B) — per-canvas sync opt-in. A `.tsx` canvas is syncable only if its
+ * sibling `<name>.meta.json` declares `"syncable": true`. The flag is set by a
+ * human editing the sidecar; it is deliberately NOT in the untrusted
+ * `/_api/canvas-meta` PATCH whitelist (api.ts), so a hostile canvas/hub cannot
+ * flip its own body into the sync set. Missing sidecar / parse error → false.
+ */
+function readSyncableFlag(bodyAbs: string): boolean {
+  const metaAbs = bodyAbs.replace(/\.(tsx|html)$/i, '.meta.json');
+  try {
+    const obj = JSON.parse(readFileSync(metaAbs, 'utf8'));
+    return obj && typeof obj === 'object' && obj.syncable === true;
+  } catch {
+    return false;
   }
-  return out;
 }
 
 async function walk(
@@ -309,7 +637,9 @@ async function walk(
   designRoot: string,
   commentsDir: string,
   designRel: string,
-  acc: CanvasDescriptor[]
+  acc: CanvasDescriptor[],
+  counter: { tsx: number },
+  splitActive: boolean
 ): Promise<void> {
   let entries: import('node:fs').Dirent[];
   try {
@@ -322,22 +652,101 @@ async function walk(
     if (entry.isDirectory()) {
       // Skip plugin runtime dirs.
       if (entry.name.startsWith('_')) continue;
-      await walk(abs, designRoot, commentsDir, designRel, acc);
+      await walk(abs, designRoot, commentsDir, designRel, acc, counter, splitActive);
       continue;
     }
     const ext = path.extname(entry.name).toLowerCase();
-    // DDR-054 §2b — refuse .tsx; only .html canvases sync.
-    if (ext !== '.html') continue;
+    // T3 (9.1-B) — a `.tsx` syncs ONLY when the sandbox is active AND the
+    // sidecar opts in (see readSyncableFlag + the splitActive coupling above).
+    // Otherwise tally it for 9.1-D's loud zero-syncable surface so the message
+    // can explain *why* it isn't syncing.
+    if (ext === '.tsx') {
+      if (!(splitActive && readSyncableFlag(abs))) {
+        counter.tsx += 1;
+        continue;
+      }
+      // falls through to descriptor push (body = the .tsx file)
+    } else if (ext !== '.html') {
+      continue;
+    }
     const slug = slugFor(abs, designRoot, designRel);
     acc.push({
+      // `html` is the canvas BODY path — `.html` or an opted-in `.tsx`. The
+      // sync codec treats the body as opaque Y.Text, so the field name is
+      // historical; both formats round-trip identically (DDR-060).
       slug,
       html: abs,
       comments: path.join(commentsDir, `${slug}.json`),
       annotations: path.join(designRoot, `${slug}.annotations.svg`),
+      // The `.meta.json` sidecar sits next to the body: `Foo.tsx` → `Foo.meta.json`.
+      meta: abs.replace(/\.(tsx|html)$/i, '.meta.json'),
+      // The `.css` sibling: `Foo.tsx` → `Foo.css` (absent for inline-CSS canvases).
+      css: abs.replace(/\.(tsx|html)$/i, '.css'),
     });
   }
 }
 
+/**
+ * The shape written to `<designRoot>/_sync.json` (and broadcast on the
+ * 'sync:status' bus) when the project is linked but has zero syncable
+ * canvases. DDR-060 / 9.1-D. Distinct from the live SyncStatusPayload — the
+ * `notSyncable` discriminator lets the CLI status line and the browser banner
+ * render the "linked but nothing syncs" state instead of a healthy one.
+ */
+export interface NoSyncablePayload {
+  linked: true;
+  notSyncable: true;
+  url: string;
+  reason: string;
+  /** Count of .tsx canvases present (syncable once 9.1-A/B land). */
+  tsxCount: number;
+  canvases: 0;
+  updatedAt: number;
+}
+
+/** Build the zero-syncable payload (exported for the CLI + tests). */
+export function buildNoSyncablePayload(
+  url: string,
+  tsxCount: number,
+  designRoot: string
+): NoSyncablePayload {
+  const reason =
+    tsxCount > 0
+      ? `${tsxCount} TSX canvas(es) found but none are syncable — a TSX body syncs only when the canvas opts in (.meta.json "syncable": true). The canvas sandbox is on by default; MAUDE_CANVAS_ORIGIN_SPLIT=0 disables it (and TSX sync with it). See DDR-060.`
+      : `no canvases found under ${designRoot}.`;
+  return {
+    linked: true,
+    notSyncable: true,
+    url,
+    reason,
+    tsxCount,
+    canvases: 0,
+    updatedAt: Date.now(),
+  };
+}
+
+/**
+ * 9.1-D — replace the silent zero-canvas early-return with a loud surface:
+ * a warn line, a `_sync.json` the CLI + browser read, and a bus broadcast.
+ * Best-effort on the write/broadcast — a failure there must never throw into
+ * the boot path (solo mode for unlinked projects is unaffected either way).
+ */
+function surfaceNoSyncable(ctx: Context, url: string, tsxCount: number): void {
+  const payload = buildNoSyncablePayload(url, tsxCount, ctx.paths.designRoot);
+  console.warn(`[sync] linked to ${url} but 0 syncable canvases — ${payload.reason}`);
+  try {
+    const file = path.join(ctx.paths.designRoot, '_sync.json');
+    writeFileSync(file, `${JSON.stringify(payload, null, 2)}\n`, 'utf8');
+  } catch {
+    /* best-effort — never throw into boot */
+  }
+  try {
+    ctx.bus.emit('sync:status', payload);
+  } catch {
+    /* best-effort */
+  }
+}
+
 function slugFor(absPath: string, designRoot: string, designRel: string): string {
   let rel = path.relative(designRoot, absPath);
   rel = rel.replace(/\\/g, '/');
@@ -362,6 +771,7 @@ async function defaultProviderFactory(args: {
   url: string;
   token: string;
   documentName: string;
+  document?: Y.Doc;
 }): Promise<SyncProvider> {
   // biome-ignore lint/suspicious/noExplicitAny: dynamic import of optional dep.
   let mod: any;
@@ -376,7 +786,9 @@ async function defaultProviderFactory(args: {
   // the scheme. The provider also accepts http(s):// and upgrades internally
   // in newer versions, but ws:// is explicit + portable.
   const wsUrl = toWsUrl(args.url);
-  const document = new Y.Doc();
+  // Phase 9.2 (DDR-064) — attach to the shared room doc when the runtime
+  // injected one; otherwise own a fresh doc (the legacy two-doc path).
+  const document = args.document ?? new Y.Doc();
   // biome-ignore lint/suspicious/noExplicitAny: provider runtime is typed at the call site.
   const provider: any = new mod.HocuspocusProvider({
     url: wsUrl,
@@ -384,12 +796,44 @@ async function defaultProviderFactory(args: {
     token: args.token,
     document,
     connect: true,
+    // Make a rejected handshake LOUD instead of an invisible reconnect loop.
+    // The most common cause is a scope-bound token (DDR-053 default scope =
+    // label) that can't authorize this canvas's flat-slug documentName — that
+    // failure mode previously looked identical to "hub unreachable / offline".
+    onAuthenticationFailed: (data: { reason?: string }) => {
+      const reason = (data?.reason ?? 'unknown reason').replace(/[\r\n]/g, ' ').slice(0, 200);
+      console.warn(
+        `[sync] hub REJECTED auth for documentName="${args.documentName}": ${reason}.
+       If this is "token not authorized for this documentName", the token's scope
+       does not cover this canvas — mint a hub-wide token (\`maude hub token generate
+       --scope '*'\` or an admin-UI invite) and re-link. The peer keeps retrying until then.`
+      );
+    },
   });
   return {
     document,
     // HocuspocusProvider creates a hub-synced Awareness by default; expose it
     // so the runtime can bridge it to the collab Room (Task 5).
     awareness: provider.awareness as Awareness | undefined,
+    onStatus(cb: (status: ProviderStatus) => void): () => void {
+      // HocuspocusProvider emits 'status' with { status: 'connected' |
+      // 'connecting' | 'disconnected' } on every WS transition (Task 8).
+      const handler = (evt: { status?: string }) => {
+        const s = evt?.status;
+        if (s === 'connected' || s === 'connecting' || s === 'disconnected') cb(s);
+      };
+      provider.on('status', handler);
+      // Seed the subscriber with the provider's CURRENT status immediately. On
+      // localhost the WS can reach 'connected'/synced inside the constructor —
+      // before this listener attaches — so waiting for the *next* transition
+      // would leave the connection monitor un-seeded and `_sync.json` never
+      // written (status reads "idle / sync agent not running" while sync is in
+      // fact healthy). Reading provider.status closes that race; it always
+      // reflects the true current state, so a missed event can't strand us.
+      const cur = provider.status;
+      if (cur === 'connected' || cur === 'connecting' || cur === 'disconnected') cb(cur);
+      return () => provider.off('status', handler);
+    },
     onceSynced(): Promise<void> {
       return new Promise<void>((resolve) => {
         if (provider.synced) {