@1agh/maude 0.60.4 → 0.60.6

package/apps/studio/sync/codec.ts

@@ -186,6 +186,25 @@ export function annotationsFromDoc(doc: Y.Doc): string | null {
   return typeof svg === 'string' ? svg : null;
 }
 
+/**
+ * True when an annotations value carries ZERO strokes: null, `''`, or the bare
+ * serialized wrapper `<svg …></svg>` with no child elements (what
+ * `strokesToSvg([])` emits — 72 bytes, constant across peers).
+ *
+ * This distinction is load-bearing for cold start (the 2026-08-14 annotations
+ * eraser): the wrapper is a non-empty STRING, so every `!== ''` emptiness
+ * guard let a stale hub wrapper overwrite a peer's real strokes — and with the
+ * strokes went the `assets/<sha8>` references `asset-pull` scans, so freshly
+ * dropped images never crossed machines. Live delete-all still materializes
+ * the wrapper through `writeAnnotationsIfChanged` (deletes must propagate);
+ * only COLD-START decisions treat it as emptiness.
+ */
+export function isEmptyAnnotationsSvg(svg: string | null): boolean {
+  if (svg === null) return true;
+  if (svg.trim() === '') return true;
+  return /^\s*<svg\b[^>]*>\s*<\/svg>\s*$/i.test(svg);
+}
+
 export function applyAnnotationsToDoc(doc: Y.Doc, next: string | null, origin?: unknown): boolean {
   if (next !== null && byteLengthUtf8(next) > MAX_ANNOTATIONS_BYTES) {
     console.warn(
@@ -344,6 +363,34 @@ export function bodyEditAtFromDoc(doc: Y.Doc): number | null {
   return typeof v === 'number' && Number.isFinite(v) ? v : null;
 }
 
+/**
+ * Stamp `syncMeta.annotationsEditAt` — the annotations lane's own newest-wins
+ * timestamp (extends DDR-102's `bodyEditAt` per-lane). Call in the SAME
+ * transaction + origin as every local→doc annotations apply (agent applyFromFs
+ * annotations branch, cold-start local-wins seed, adopt) so peers receive ONE
+ * update. Before this stamp existed, cold start resolved annotations by the
+ * BODY winner — but annotation edits don't move the body's edit time, so a
+ * hub with a newer body and a stale (empty) annotations lane erased newer
+ * local strokes (the 2026-08-14 annotations eraser).
+ *
+ * `nowMs` override: cold-start seeding passes the local FILE's mtime so stale
+ * content can't claim apply-time freshness.
+ */
+export function stampAnnotationsEdit(doc: Y.Doc, origin?: unknown, nowMs?: number): void {
+  const map = doc.getMap<unknown>(Y_SYNC_TYPES.syncMeta);
+  doc.transact(() => {
+    map.set('annotationsEditAt', nowMs ?? Date.now());
+  }, origin);
+}
+
+/** The doc-side annotations-edit stamp, or null when no peer ever stamped
+ *  (pre-annotationsEditAt docs → callers fall back to the body-winner
+ *  coupling, interop-safe). */
+export function annotationsEditAtFromDoc(doc: Y.Doc): number | null {
+  const v = doc.getMap<unknown>(Y_SYNC_TYPES.syncMeta).get('annotationsEditAt');
+  return typeof v === 'number' && Number.isFinite(v) ? v : null;
+}
+
 /**
  * Record THIS doc's clientID as the seeder in `syncMeta.seededBy` (F1). Call it
  * in the SAME transaction + origin as a `seed-local-up` body apply. The value is

package/apps/studio/sync/cold-start.ts

@@ -196,3 +196,99 @@ export function decideColdStart(input: ColdStartInput): ColdStartDecision {
         : 'diverged — timestamps tied, falling back to hub-wins (recoverable: both sides snapshotted)',
   };
 }
+
+/* ------------------------------------------------- annotations (per-lane) */
+
+export interface AnnotationsColdStartInput {
+  /** Local `.annotations.svg` content, or null when the file doesn't exist. */
+  local: string | null;
+  /** Annotations currently held by the doc (`''` when the lane is unset). */
+  doc: string;
+  /** True when the value carries zero strokes — callers pass
+   *  `isEmptyAnnotationsSvg` (codec.ts) so this table stays Y-free. */
+  isEmpty: (svg: string | null) => boolean;
+  /** Local annotations file mtime (ms epoch), or null when unavailable. */
+  localMtimeMs: number | null;
+  /** Doc-side syncMeta.annotationsEditAt stamp, or null when no peer ever
+   *  stamped (pre-stamp interop). */
+  docEditAtMs: number | null;
+  /** The body lane's resolved winner — the legacy coupling, used only as the
+   *  fallback when both sides are non-empty and neither is stamped. */
+  bodyWinner: 'local' | 'hub';
+}
+
+export interface AnnotationsColdStartDecision {
+  winner: 'local' | 'hub' | 'none';
+  reason: string;
+}
+
+/**
+ * Per-lane cold-start resolution for annotations (extends DDR-102 to the
+ * annotations lane; the 2026-08-14 annotations eraser).
+ *
+ * Annotations used to blindly follow the body winner — but annotation edits
+ * don't move the body's edit time, so a hub with a newer body and a STALE
+ * (empty-wrapper) annotations lane erased newer local strokes on every cold
+ * start, and with the strokes went the `assets/<sha8>` references the asset
+ * pull scans. The one load-bearing rule here: **unstamped emptiness never
+ * beats content.** A STAMPED emptiness that is provably newer is a deliberate
+ * delete-all and is honored; everything else prefers the side with strokes.
+ */
+export function decideAnnotationsColdStart(
+  input: AnnotationsColdStartInput
+): AnnotationsColdStartDecision {
+  const { local, doc, isEmpty, localMtimeMs, docEditAtMs, bodyWinner } = input;
+  const localEmpty = isEmpty(local);
+  const docEmpty = isEmpty(doc === '' ? null : doc);
+
+  if (localEmpty && docEmpty) return { winner: 'none', reason: 'both sides empty' };
+
+  if (docEmpty && !localEmpty) {
+    // A stamped hub emptiness NEWER than the local file is a deliberate
+    // delete-all made while this peer was offline — honor it.
+    if (docEditAtMs !== null && localMtimeMs !== null && docEditAtMs > localMtimeMs) {
+      return {
+        winner: 'hub',
+        reason: `hub delete-all is newer than local strokes (annotationsEditAt ${new Date(docEditAtMs).toISOString()} > local mtime ${new Date(localMtimeMs).toISOString()})`,
+      };
+    }
+    return {
+      winner: 'local',
+      reason:
+        'hub annotations are empty but local has strokes — keeping local + seeding it up (unstamped emptiness never beats content)',
+    };
+  }
+
+  if (!docEmpty && localEmpty) {
+    // Symmetric: a local delete-all (empty wrapper on disk) newer than the
+    // doc's stamp is honored; an absent/stale local file materializes the hub.
+    if (
+      local !== null &&
+      localMtimeMs !== null &&
+      docEditAtMs !== null &&
+      localMtimeMs > docEditAtMs
+    ) {
+      return {
+        winner: 'local',
+        reason: `local delete-all is newer than hub strokes (local mtime ${new Date(localMtimeMs).toISOString()} > annotationsEditAt ${new Date(docEditAtMs).toISOString()})`,
+      };
+    }
+    return { winner: 'hub', reason: 'local annotations empty/absent — materializing hub strokes' };
+  }
+
+  // Both non-empty.
+  if (doc === local) return { winner: 'none', reason: 'both sides equal' };
+  if (docEditAtMs !== null && localMtimeMs !== null && docEditAtMs !== localMtimeMs) {
+    const winner = localMtimeMs > docEditAtMs ? 'local' : 'hub';
+    return {
+      winner,
+      reason: `diverged — newest wins: local mtime ${new Date(localMtimeMs).toISOString()} ${
+        winner === 'local' ? '>' : '<'
+      } doc annotationsEditAt ${new Date(docEditAtMs).toISOString()}`,
+    };
+  }
+  return {
+    winner: bodyWinner,
+    reason: `diverged — no per-lane stamp on one side, following the body winner (${bodyWinner})`,
+  };
+}

package/apps/studio/sync/migrate-seed.ts

@@ -36,16 +36,19 @@ import type * as Y from 'yjs';
 
 import { Y_TYPES } from '../collab/persistence.ts';
 import {
+  annotationsEditAtFromDoc,
   applyAnnotationsToDoc,
   applyCommentsToDoc,
   applyCssToDoc,
   applyHtmlToDoc,
   applyMetaToDoc,
   bodyEditAtFromDoc,
+  isEmptyAnnotationsSvg,
+  stampAnnotationsEdit,
   stampBodyEdit,
   Y_SYNC_TYPES,
 } from './codec.ts';
-import { decideColdStart, unionCommentsById } from './cold-start.ts';
+import { decideAnnotationsColdStart, decideColdStart, unionCommentsById } from './cold-start.ts';
 import { hashBytes } from './echo-guard.ts';
 import type { SyncJournal } from './journal.ts';
 import { ORIGINS } from './origins.ts';
@@ -133,7 +136,17 @@ export async function migrateSeed(opts: MigrateSeedOptions): Promise<MigrateSeed
         const parsed = tryParseJsonArray(localComments);
         if (parsed) applyCommentsToDoc(doc, parsed, ORIGINS.MIGRATION);
       }
-      if (localAnnotations) applyAnnotationsToDoc(doc, localAnnotations, ORIGINS.MIGRATION);
+      if (localAnnotations) {
+        if (applyAnnotationsToDoc(doc, localAnnotations, ORIGINS.MIGRATION)) {
+          // Stamp with the FILE's mtime — adopt seeds pre-existing content,
+          // which must not claim apply-time freshness over a newer peer.
+          stampAnnotationsEdit(
+            doc,
+            ORIGINS.MIGRATION,
+            localMtimeMs(paths.annotations) ?? undefined
+          );
+        }
+      }
       if (paths.meta && localMeta) applyMetaToDoc(doc, localMeta, ORIGINS.MIGRATION);
       if (paths.css && localCss) applyCssToDoc(doc, localCss, ORIGINS.MIGRATION);
     }, ORIGINS.MIGRATION);
@@ -164,17 +177,16 @@ export async function migrateSeed(opts: MigrateSeedOptions): Promise<MigrateSeed
 
   let result: MigrateSeedResult = 'hub-wins';
 
-  /** Rebuild body (+ visually-coupled css/annotations) from local, in ONE
-   *  MIGRATION transaction — one source per type, never a two-history merge. */
+  /** Rebuild body (+ visually-coupled css) from local, in ONE MIGRATION
+   *  transaction — one source per type, never a two-history merge.
+   *  Annotations are deliberately NOT here any more: they resolve per-lane
+   *  below (decideAnnotationsColdStart), independent of the body winner. */
   const rebuildBodyFromLocal = (): void => {
     doc.transact(() => {
       if (applyHtmlToDoc(doc, localHtml as string, ORIGINS.MIGRATION)) {
         stampBodyEdit(doc, ORIGINS.MIGRATION);
       }
       if (paths.css && localCss !== null) applyCssToDoc(doc, localCss, ORIGINS.MIGRATION);
-      if (localAnnotations !== null) {
-        applyAnnotationsToDoc(doc, localAnnotations, ORIGINS.MIGRATION);
-      }
     }, ORIGINS.MIGRATION);
     opts.journal?.record(slug, {
       bodyHash: hashBytes(localHtml as string),
@@ -246,6 +258,39 @@ export async function migrateSeed(opts: MigrateSeedOptions): Promise<MigrateSeed
     }
   }
 
+  // ---- annotations: PER-LANE newest-wins (the 2026-08-14 eraser fix; the
+  // same table as agent.ts reconcile). Under sharedDoc the collab room's
+  // persistJson materializes the doc's annotations to disk, so a stale hub
+  // EMPTY WRAPPER (non-'' but zero strokes) in the doc erased local strokes
+  // right after this seed ran. Resolve the lane here, before the room
+  // materializes: unstamped emptiness never beats content.
+  {
+    const docSvg = doc.getMap<unknown>(Y_TYPES.annotations).get('svg');
+    const docAnnotations = typeof docSvg === 'string' ? docSvg : '';
+    const annDecision = decideAnnotationsColdStart({
+      local: localAnnotations,
+      doc: docAnnotations,
+      isEmpty: isEmptyAnnotationsSvg,
+      localMtimeMs: localMtimeMs(paths.annotations),
+      docEditAtMs: annotationsEditAtFromDoc(doc),
+      bodyWinner: result === 'body-seed-up' || result === 'conflict-local-wins' ? 'local' : 'hub',
+    });
+    if (annDecision.winner === 'local' && localAnnotations !== null) {
+      console.warn(`[sync/${slug}] shared-doc cold-start annotations: ${annDecision.reason}`);
+      doc.transact(() => {
+        if (applyAnnotationsToDoc(doc, localAnnotations, ORIGINS.MIGRATION)) {
+          stampAnnotationsEdit(
+            doc,
+            ORIGINS.MIGRATION,
+            localMtimeMs(paths.annotations) ?? undefined
+          );
+        }
+      }, ORIGINS.MIGRATION);
+    }
+    // winner 'hub' → nothing to write here: the collab room owns the
+    // annotations doc→file half and materializes it (persistJson).
+  }
+
   // Comments id-union (DDR-102): rebuild from merged JSON via the
   // delete-then-insert codec — same-id entries keep the doc's version, so the
   // duplication trap stays closed; local-only comments survive.

package/apps/studio/sync/projection.ts

@@ -39,6 +39,7 @@ import {
   htmlFromDoc,
   mergeSharedMetaIntoLocal,
   metaFromDoc,
+  stampAnnotationsEdit,
   stampBodyEdit,
 } from './codec.ts';
 import { type EchoGuard, hashBytes } from './echo-guard.ts';
@@ -354,7 +355,15 @@ export function createDocProjection(opts: DocProjectionOptions): DocProjection {
     }
     if (evt.path === paths.annotations) {
       clearStrike(evt.path);
-      return applyAnnotationsToDoc(doc, str, importOrigin);
+      // Apply + per-lane stamp in ONE transaction (mirrors agent.applyFromFs)
+      // so a deliberate delete-all (empty wrapper) carries its freshness and
+      // survives cold start on other peers (the 2026-08-14 eraser fix).
+      let changed = false;
+      doc.transact(() => {
+        changed = applyAnnotationsToDoc(doc, str, importOrigin);
+        if (changed) stampAnnotationsEdit(doc, importOrigin);
+      }, importOrigin);
+      return changed;
     }
     return false;
   }

package/apps/studio/test/canvas-meta-api.test.ts

@@ -115,7 +115,7 @@ describe('/_api/canvas-meta — GET/PATCH (DDR-115 camera split)', () => {
     }
   });
 
-  test('PATCH clamps zoom to [0.1, 4.0]', async () => {
+  test('PATCH clamps zoom to [0.02, 4.0]', async () => {
     const { root, designRoot } = makeSandbox();
     const port = nextPort();
     const proc = await bootServer(root, port);
@@ -137,10 +137,45 @@ describe('/_api/canvas-meta — GET/PATCH (DDR-115 camera split)', () => {
       const r2 = await fetch(`http://localhost:${port}/_api/canvas-meta`, {
         method: 'PATCH',
         headers: { 'content-type': 'application/json' },
-        body: JSON.stringify({ file, patch: { viewport: { x: 0, y: 0, zoom: 0.001 } } }),
+        body: JSON.stringify({ file, patch: { viewport: { x: 0, y: 0, zoom: 0.0001 } } }),
       });
       const m2 = (await r2.json()) as MetaShape;
-      expect(m2.viewport?.zoom).toBe(0.1);
+      expect(m2.viewport?.zoom).toBe(0.02);
+    } finally {
+      await killProc(proc);
+    }
+  });
+
+  // Issue #91 — a board wider than ~10x the viewport needs a zoom below the
+  // OLD 0.1 floor to ever be framed whole ("fit to screen") or dragged across
+  // in one motion. Before the fix, this value was silently re-clamped up to
+  // 0.1 on save, so even a client that could reach 0.05 lost it on reload.
+  test('PATCH preserves a deep zoom-out that the old [0.1, 4.0] floor used to clamp away (issue #91)', async () => {
+    const { root, designRoot } = makeSandbox();
+    const port = nextPort();
+    const proc = await bootServer(root, port);
+    try {
+      mkdirSync(join(designRoot, 'ui'), { recursive: true });
+      const tsxAbs = join(designRoot, 'ui', 'DeepZoom.tsx');
+      writeFileSync(tsxAbs, 'export default function D(){return <main/>}\n');
+      writeFileSync(tsxAbs.replace(/\.tsx$/, '.meta.json'), '{"title":"DeepZoom"}');
+      const file = repoRel(designRoot, tsxAbs);
+
+      const r = await fetch(`http://localhost:${port}/_api/canvas-meta`, {
+        method: 'PATCH',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ file, patch: { viewport: { x: 0, y: 0, zoom: 0.05 } } }),
+      });
+      const m = (await r.json()) as MetaShape;
+      expect(m.viewport?.zoom).toBe(0.05);
+
+      // Round-trips through a fresh GET too (the persisted view file, not just
+      // the PATCH response) — this is what a page reload would read back.
+      const g = await fetch(
+        `http://localhost:${port}/_api/canvas-meta?file=${encodeURIComponent(file)}`
+      );
+      const gm = (await g.json()) as MetaShape;
+      expect(gm.viewport?.zoom).toBe(0.05);
     } finally {
       await killProc(proc);
     }
@@ -317,6 +352,82 @@ describe('/_api/canvas-meta — GET/PATCH (DDR-115 camera split)', () => {
     }
   });
 
+  // Security follow-up to issue #91 — `layout.artboards[]` is reachable from
+  // the untrusted canvas origin (DDR-054) and previously had no count/magnitude
+  // bound. Now that the zoom-floor fix lets `fit()` correctly frame whatever
+  // bounding box a synced layout describes, an unbounded artboard count could
+  // promote hundreds/thousands of simultaneous GPU layers on the viewer's
+  // client (a DoS). Caps mirror the existing overlays/locked lanes.
+  test('PATCH layout rejects an oversized artboards array as a silent no-op', async () => {
+    const { root, designRoot } = makeSandbox();
+    const port = nextPort();
+    const proc = await bootServer(root, port);
+    try {
+      mkdirSync(join(designRoot, 'ui'), { recursive: true });
+      const tsxAbs = join(designRoot, 'ui', 'Oversized.tsx');
+      writeFileSync(tsxAbs, 'export default function O(){return <main/>}\n');
+      const metaAbs = tsxAbs.replace(/\.tsx$/, '.meta.json');
+      writeFileSync(metaAbs, JSON.stringify({ title: 'Oversized', sections: [] }));
+      const file = repoRel(designRoot, tsxAbs);
+
+      // Seed a valid, small layout first.
+      await fetch(`http://localhost:${port}/_api/canvas-meta`, {
+        method: 'PATCH',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ file, patch: { layout: { artboards: [{ id: 'a', x: 0, y: 0 }] } } }),
+      });
+
+      // A crafted, oversized layout (2001 > the 2000-entry cap) must not land.
+      const huge = Array.from({ length: 2001 }, (_, i) => ({ id: `a${i}`, x: i, y: 0 }));
+      const r = await fetch(`http://localhost:${port}/_api/canvas-meta`, {
+        method: 'PATCH',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ file, patch: { layout: { artboards: huge } } }),
+      });
+      expect(r.status).toBe(200);
+      const merged = (await r.json()) as MetaShape;
+      // Silent no-op — the prior small, valid layout is still what's live.
+      const arts = merged.layout?.artboards as Array<Record<string, unknown>> | undefined;
+      expect(arts).toEqual([{ id: 'a', x: 0, y: 0 }]);
+
+      const onDisk = JSON.parse(readFileSync(metaAbs, 'utf8')) as MetaShape;
+      const diskArts = onDisk.layout?.artboards as Array<Record<string, unknown>> | undefined;
+      expect(diskArts).toEqual([{ id: 'a', x: 0, y: 0 }]);
+    } finally {
+      await killProc(proc);
+    }
+  });
+
+  test('PATCH layout rejects an out-of-range artboard coordinate as a silent no-op', async () => {
+    const { root, designRoot } = makeSandbox();
+    const port = nextPort();
+    const proc = await bootServer(root, port);
+    try {
+      mkdirSync(join(designRoot, 'ui'), { recursive: true });
+      const tsxAbs = join(designRoot, 'ui', 'OutOfRange.tsx');
+      writeFileSync(tsxAbs, 'export default function R(){return <main/>}\n');
+      writeFileSync(
+        tsxAbs.replace(/\.tsx$/, '.meta.json'),
+        JSON.stringify({ title: 'OutOfRange' })
+      );
+      const file = repoRel(designRoot, tsxAbs);
+
+      const r = await fetch(`http://localhost:${port}/_api/canvas-meta`, {
+        method: 'PATCH',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({
+          file,
+          patch: { layout: { artboards: [{ id: 'a', x: 50_000_000, y: 0 }] } },
+        }),
+      });
+      expect(r.status).toBe(200);
+      const merged = (await r.json()) as MetaShape;
+      expect(merged.layout).toBeUndefined();
+    } finally {
+      await killProc(proc);
+    }
+  });
+
   test('PATCH viewport on a non-existent canvas is refused (404) and mints no file (DDR-115 F-A2)', async () => {
     const { root, designRoot } = makeSandbox();
     const port = nextPort();

package/apps/studio/test/canvas-wheel-delta.test.ts

@@ -0,0 +1,42 @@
+// canvas-wheel-delta — issue #94 dogfood report: mouse-wheel panning in the
+// canvas is very slow. Root cause: `onWheel` fed raw `WheelEvent.deltaX`/
+// `deltaY` straight into `panBy` as CSS pixels, but the Wheel Events spec
+// lets a browser report deltas in pixel/line/page units (`deltaMode`).
+// Physical mice on Firefox (and some browser/OS combos elsewhere) report
+// LINE-mode deltas — a single integer like 3 per notch — which, read as
+// pixels, panned the canvas only a few px per wheel notch. Trackpads report
+// pixel-mode deltas already, so trackpad panning felt fine while mouse-wheel
+// panning felt frozen. See .ai/logs/rca/issue-94-wheel-pan-slow.md.
+//
+// `wheelDeltaToPixels` is a pure function (no DOM needed) so this test
+// doesn't need happy-dom, unlike canvas-zoom-floor.test.ts's computeFit case.
+
+import { describe, expect, test } from 'bun:test';
+
+import { wheelDeltaToPixels } from '../canvas-lib.tsx';
+
+describe('wheelDeltaToPixels — normalizes WheelEvent units (issue #94)', () => {
+  test('pixel mode (deltaMode 0) passes the value through unchanged', () => {
+    expect(wheelDeltaToPixels(100, 0, 800)).toBe(100);
+    expect(wheelDeltaToPixels(-42.5, 0, 800)).toBe(-42.5);
+  });
+
+  test('line mode (deltaMode 1) scales a small per-notch delta up to a pixel-range step', () => {
+    // The regression: before the fix, `onWheel` fed the raw delta straight
+    // into `panBy`, so a line-mode notch of 3 panned only 3 CSS pixels —
+    // reproducing the "very slow" mouse-wheel report. This asserts the FIXED
+    // behavior: scaled up to a magnitude comparable to a trackpad's
+    // pixel-mode delta (~100 per gesture step). Pre-fix, `wheelDeltaToPixels`
+    // didn't exist and `onWheel` used the raw `3` — this assertion fails
+    // against that old code path (3 !== 48).
+    const raw = 3;
+    const scaled = wheelDeltaToPixels(raw, 1, 800);
+    expect(scaled).toBe(48);
+    expect(scaled).not.toBe(raw);
+  });
+
+  test('page mode (deltaMode 2) scales by the supplied page size', () => {
+    expect(wheelDeltaToPixels(1, 2, 800)).toBe(800);
+    expect(wheelDeltaToPixels(-2, 2, 600)).toBe(-1200);
+  });
+});

package/apps/studio/test/canvas-zoom-floor.test.ts

@@ -0,0 +1,73 @@
+// canvas-zoom-floor — issue #91 dogfood report: dragging an artboard across a
+// large board, the user can't zoom out far enough to complete the move in one
+// motion. Root cause: `clampZoom` applies a single hard-coded floor to every
+// viewport write, including the programmatic `fit()` path — a board wider
+// than ~10x the viewport could never be framed whole. See
+// .ai/logs/rca/issue-91-canvas-zoom-floor.md.
+//
+// canvas-lib.tsx pulls in a React/DOM dependency graph, so we register
+// happy-dom for this file (like camera-reveal.test.tsx) before importing.
+
+import { afterAll, beforeAll, describe, expect, test } from 'bun:test';
+import { GlobalRegistrator } from '@happy-dom/global-registrator';
+
+beforeAll(() => {
+  GlobalRegistrator.register();
+});
+afterAll(() => {
+  GlobalRegistrator.unregister();
+});
+
+import { clampZoom, computeFit } from '../canvas-lib.tsx';
+
+function fakeHost(clientWidth: number, clientHeight: number): HTMLElement {
+  const el = document.createElement('div');
+  Object.defineProperty(el, 'clientWidth', { value: clientWidth });
+  Object.defineProperty(el, 'clientHeight', { value: clientHeight });
+  return el;
+}
+
+describe('clampZoom — the interactive zoom floor (issue #91)', () => {
+  test('a deep zoom-out below the OLD 0.1 floor is no longer clamped', () => {
+    expect(clampZoom(0.05)).toBe(0.05);
+    expect(clampZoom(0.02)).toBe(0.02);
+  });
+
+  test('still clamps below the new floor', () => {
+    expect(clampZoom(0.0001)).toBe(0.02);
+    expect(clampZoom(-5)).toBe(0.02);
+  });
+
+  test('still clamps above the max and normalizes non-finite input', () => {
+    expect(clampZoom(99)).toBe(4);
+    expect(clampZoom(Number.NaN)).toBe(1);
+    expect(clampZoom(Number.POSITIVE_INFINITY)).toBe(1);
+  });
+});
+
+describe('computeFit → clampZoom — fit() can now frame a wide board (issue #91)', () => {
+  test('a board ~20x the viewport width computes a zoom the old floor would have clamped up', () => {
+    // Viewport 1000x800; board 20000 wide — the exact "more than a screenful
+    // of artboards" shape from the report. Ideal fit zoom is well under 0.1.
+    const host = fakeHost(1000, 800);
+    const fit = computeFit([{ x: 0, y: 0, w: 20000, h: 800 }], host, 24);
+
+    expect(fit.zoom).toBeLessThan(0.1); // the bug: old floor would have clamped this
+    expect(fit.zoom).toBeGreaterThanOrEqual(0.02); // still within the new interactive floor
+
+    // The regression proper: applying the viewport funnel's clamp must be a
+    // no-op for this value now — before the fix (ZOOM_MIN = 0.1) this would
+    // have raised fit.zoom back up to 0.1, cropping the board.
+    expect(clampZoom(fit.zoom)).toBe(fit.zoom);
+  });
+
+  test('an extremely wide board (>50x viewport) still bottoms out at the interactive floor', () => {
+    const host = fakeHost(1000, 800);
+    const fit = computeFit([{ x: 0, y: 0, w: 100000, h: 800 }], host, 24);
+
+    // The ideal fit zoom is far below even the new floor — clampZoom must
+    // still protect the interactive floor for pathological board sizes.
+    expect(fit.zoom).toBeLessThan(0.02);
+    expect(clampZoom(fit.zoom)).toBe(0.02);
+  });
+});

package/apps/studio/test/comment-mount.test.ts

@@ -39,7 +39,16 @@ describe('comment-mount / MaybeToolProvider dedup', () => {
     const html = renderToStaticMarkup(
       createElement(MaybeToolProvider, null, createElement(ToolReader))
     );
-    // feature-4 (browse/move split) — the default boot tool is `browse`.
+    // DDR-223 — the default boot tool is `move` (edit mode).
+    expect(html).toContain('data-tool="move"');
+  });
+
+  test('forwards initial="browse" — the comment-mount specimen posture (DDR-223)', () => {
+    // buildCanvasTree passes this explicitly so bare DS specimens keep the
+    // DDR-187 alive posture + native cursors.
+    const html = renderToStaticMarkup(
+      createElement(MaybeToolProvider, { initial: 'browse' }, createElement(ToolReader))
+    );
     expect(html).toContain('data-tool="browse"');
   });
 });

package/apps/studio/test/dom-selection.test.ts

@@ -19,7 +19,7 @@ afterAll(() => {
   GlobalRegistrator.unregister();
 });
 
-import { resolveByDomPath } from '../dom-selection.ts';
+import { buildComposeSelection, openCommentComposer, resolveByDomPath } from '../dom-selection.ts';
 
 function setArtboard(html: string): void {
   document.body.innerHTML = `<div data-dc-screen="art1">${html}</div>`;
@@ -128,3 +128,71 @@ describe('resolveByDomPath', () => {
     expect(found?.getAttribute('data-cd-id')).toBe('aaa11111');
   });
 });
+
+// issue-90 — right-click "Add comment" on empty canvas background or an
+// artboard's chrome/border (neither carries a `data-cd-id`) used to have no
+// menu entry at all, and even where the entry DID exist (on an element) it
+// never actually opened the composer (see `openCommentComposer` below).
+// `buildComposeSelection` is the shared builder canvas-shell.tsx's
+// context-menu registry now calls for all three target kinds.
+describe('buildComposeSelection', () => {
+  test('with an element under the cursor — delegates to hoverTargetToSelection (same anchor a comment-tool click gets)', () => {
+    setArtboard(`<button class="cta" data-cd-id="aaa11111">Buy now</button>`);
+    const el = document.querySelector('[data-cd-id="aaa11111"]');
+    const sel = buildComposeSelection({ el, cdId: 'aaa11111', artboardId: 'art1' }, 100, 200);
+    expect(sel.selector).toBe('[data-dc-screen="art1"] [data-cd-id="aaa11111"]');
+    expect(sel.id).toBe('aaa11111');
+    expect(sel.tag).toBe('button');
+  });
+
+  test('with no element (empty canvas background) — a FLOATING selection anchored to the click point', () => {
+    document.body.innerHTML = '';
+    const sel = buildComposeSelection({ el: null, cdId: null, artboardId: null }, 100, 200);
+    expect(sel.selector).toBe('');
+    expect(sel.tag).toBe('');
+    expect(sel.artboardId).toBeNull();
+    expect(sel.bounds).toEqual({ x: 88, y: 188, w: 24, h: 24 });
+  });
+
+  test('with no element but INSIDE an artboard (right-click on its chrome/border) — floating, but keeps the artboardId', () => {
+    document.body.innerHTML = '';
+    const sel = buildComposeSelection({ el: null, cdId: null, artboardId: 'art1' }, 50, 60);
+    expect(sel.selector).toBe('');
+    expect(sel.artboardId).toBe('art1');
+    expect(sel.bounds).toEqual({ x: 38, y: 48, w: 24, h: 24 });
+  });
+});
+
+describe('openCommentComposer', () => {
+  // The regression: canvas-shell.tsx's context-menu "Add comment" used to
+  // ONLY postMessage the parent shell (which merely mirrors the target for
+  // the StatusBar/sidebar) and never dispatched `cm:open-composer` — the one
+  // event `comments-overlay.tsx` listens on to actually render the composer.
+  // Selecting the menu item silently did nothing.
+  test('dispatches cm:open-composer carrying the selection + click point', () => {
+    let detail: { selection?: unknown; clientX?: number; clientY?: number } | null = null;
+    const onOpen = (e: Event) => {
+      detail = (e as CustomEvent).detail;
+    };
+    document.addEventListener('cm:open-composer', onOpen);
+    const sel = {
+      selector: '',
+      artboardId: null,
+      tag: '',
+      classes: '',
+      text: '',
+      dom_path: [],
+      bounds: { x: 30, y: 40, w: 24, h: 24 },
+      html: '',
+    };
+    try {
+      openCommentComposer(sel, 42, 52);
+    } finally {
+      document.removeEventListener('cm:open-composer', onOpen);
+    }
+    expect(detail).not.toBeNull();
+    expect(detail?.selection).toBe(sel);
+    expect(detail?.clientX).toBe(42);
+    expect(detail?.clientY).toBe(52);
+  });
+});

package/apps/studio/test/hmr-broadcast.test.ts

@@ -60,14 +60,16 @@ describe('hmr-broadcast / classification', () => {
     h.stop();
   });
 
-  test('unrelated extensions are dropped', async () => {
+  test('unrelated extensions are dropped; media becomes an asset heal', async () => {
     const ctx = mkCtx();
     const got: HmrMessage[] = [];
     const h = createHmrBroadcaster(ctx, (m) => got.push(m));
-    ctx.bus.emit('fs:any', 'ui/screenshot.png');
-    ctx.bus.emit('fs:any', '_locator.json');
+    ctx.bus.emit('fs:any', 'ui/screenshot.png'); // media → asset heal (2026-08-15 RCA)
+    ctx.bus.emit('fs:any', '_locator.json'); // runtime state → dropped
     await awaitNextFlush();
-    expect(got).toHaveLength(0);
+    expect(got).toHaveLength(1);
+    expect(got[0]?.mode).toBe('asset');
+    expect(got[0]?.file).toBe('ui/screenshot.png');
     h.stop();
   });
 });