@1agh/maude 0.22.2 → 0.24.0

package/plugins/design/dev-server/test/sync-status.test.ts

@@ -0,0 +1,80 @@
+// Sync status store tests — Phase 9 Task 8.
+
+import { describe, expect, test } from 'bun:test';
+
+import type { SyncStatusSnapshot } from '../sync/connection-state.ts';
+import { type SyncStatusPayload, createSyncStatusStore } from '../sync/status.ts';
+
+function snap(partial: Partial<SyncStatusSnapshot> = {}): SyncStatusSnapshot {
+  return {
+    state: 'online',
+    queuedOps: 0,
+    lastSyncAt: null,
+    offlineSince: null,
+    flash: null,
+    updatedAt: 1,
+    ...partial,
+  };
+}
+
+function makeStore() {
+  const writes: SyncStatusPayload[] = [];
+  const broadcasts: SyncStatusPayload[] = [];
+  const store = createSyncStatusStore({
+    url: 'https://hub.example.com',
+    canvases: 3,
+    write: (p) => writes.push(p),
+    broadcast: (p) => broadcasts.push(p),
+    now: () => 42,
+  });
+  return { store, writes, broadcasts };
+}
+
+describe('sync status store', () => {
+  test('update() writes + broadcasts the merged payload', () => {
+    const { store, writes, broadcasts } = makeStore();
+    store.update(snap({ state: 'offline', queuedOps: 2 }));
+    expect(writes).toHaveLength(1);
+    expect(broadcasts).toHaveLength(1);
+    expect(writes[0].state).toBe('offline');
+    expect(writes[0].queuedOps).toBe(2);
+    expect(writes[0].url).toBe('https://hub.example.com');
+    expect(writes[0].canvases).toBe(3);
+    expect(writes[0].conflicts).toEqual([]);
+  });
+
+  test('addConflict() appends a stamped conflict + reflects in get()', () => {
+    const { store } = makeStore();
+    store.addConflict({ slug: 'screen', kind: 'cold-start-hub-wins' });
+    const p = store.get();
+    expect(p.conflicts).toHaveLength(1);
+    expect(p.conflicts[0]).toEqual({ slug: 'screen', kind: 'cold-start-hub-wins', at: 42 });
+  });
+
+  test('conflict list is capped at maxConflicts (drops oldest)', () => {
+    const writes: SyncStatusPayload[] = [];
+    const store = createSyncStatusStore({
+      url: 'https://h',
+      canvases: 1,
+      write: (p) => writes.push(p),
+      maxConflicts: 2,
+      now: () => 1,
+    });
+    store.addConflict({ slug: 'a', kind: 'git-pull' });
+    store.addConflict({ slug: 'b', kind: 'git-pull' });
+    store.addConflict({ slug: 'c', kind: 'git-pull' });
+    const p = store.get();
+    expect(p.conflicts.map((c) => c.slug)).toEqual(['b', 'c']);
+  });
+
+  test('a throwing writer never propagates into the caller', () => {
+    const store = createSyncStatusStore({
+      url: 'https://h',
+      canvases: 1,
+      write: () => {
+        throw new Error('disk full');
+      },
+    });
+    expect(() => store.update(snap({ state: 'offline' }))).not.toThrow();
+  });
+});

package/plugins/design/dev-server/test/sync-untrusted.test.ts

@@ -0,0 +1,104 @@
+// T4.5 (DDR-054 §3 F3) — untrusted-marker for sync-written files. Verifies the
+// `_untrusted/INDEX.json` marker + the managed `.claudeignore` block: written
+// for the syncable set, cleared when empty, stale entries dropped on re-write,
+// and user-authored `.claudeignore` content outside the block preserved.
+
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
+
+import type { Context } from '../context.ts';
+import type { CanvasDescriptor } from '../sync/index.ts';
+import { clearUntrustedMarkers, writeUntrustedMarkers } from '../sync/untrusted.ts';
+
+let repoRoot: string;
+let designRoot: string;
+
+beforeEach(() => {
+  repoRoot = mkdtempSync(join(tmpdir(), 'untrusted-'));
+  designRoot = join(repoRoot, '.design');
+  mkdirSync(designRoot, { recursive: true });
+});
+afterEach(() => {
+  /* tmpdir — left for the OS to reap */
+});
+
+function ctxOf(): Context {
+  return { paths: { repoRoot, designRoot } } as unknown as Context;
+}
+
+function desc(slug: string, body: string): CanvasDescriptor {
+  return {
+    slug,
+    html: join(designRoot, body),
+    comments: join(designRoot, '_comments', `${slug}.json`),
+    annotations: join(designRoot, `${slug}.annotations.svg`),
+    meta: join(designRoot, body.replace(/\.(tsx|html)$/i, '.meta.json')),
+    css: join(designRoot, body.replace(/\.(tsx|html)$/i, '.css')),
+  };
+}
+
+const HUB = 'https://hub.example.com';
+
+describe('writeUntrustedMarkers — T4.5', () => {
+  test('writes INDEX.json + a managed .claudeignore block for the synced set', () => {
+    const ctx = ctxOf();
+    writeUntrustedMarkers(ctx, [desc('ui-a', 'ui/a.tsx')], HUB);
+
+    const indexAbs = join(designRoot, '_untrusted', 'INDEX.json');
+    expect(existsSync(indexAbs)).toBe(true);
+    const index = JSON.parse(readFileSync(indexAbs, 'utf8'));
+    expect(index.hubUrl).toBe(HUB);
+    expect(index.canvases[0].slug).toBe('ui-a');
+    expect(index.canvases[0].body).toBe('.design/ui/a.tsx');
+    expect(index.canvases[0].meta).toBe('.design/ui/a.meta.json'); // Gap 2: meta is untrusted too
+    expect(index.canvases[0].css).toBe('.design/ui/a.css'); // Gap 3: css too
+    expect(index.note.toLowerCase()).toContain('untrusted');
+
+    const ci = readFileSync(join(repoRoot, '.claudeignore'), 'utf8');
+    expect(ci).toContain('maude:sync-untrusted begin');
+    expect(ci).toContain('.design/ui/a.tsx');
+    expect(ci).toContain('.design/ui-a.annotations.svg');
+    expect(ci).toContain('.design/ui/a.meta.json');
+    expect(ci).toContain('.design/ui/a.css');
+    expect(ci).toContain('maude:sync-untrusted end');
+  });
+
+  test('re-write with a smaller set drops the stale entry', () => {
+    const ctx = ctxOf();
+    writeUntrustedMarkers(ctx, [desc('ui-a', 'ui/a.tsx'), desc('ui-b', 'ui/b.tsx')], HUB);
+    writeUntrustedMarkers(ctx, [desc('ui-a', 'ui/a.tsx')], HUB);
+    const ci = readFileSync(join(repoRoot, '.claudeignore'), 'utf8');
+    expect(ci).toContain('.design/ui/a.tsx');
+    expect(ci).not.toContain('.design/ui/b.tsx');
+    // Only one managed block (no accumulation).
+    expect(ci.match(/maude:sync-untrusted begin/g)?.length).toBe(1);
+  });
+
+  test('empty set clears INDEX.json + the .claudeignore block', () => {
+    const ctx = ctxOf();
+    writeUntrustedMarkers(ctx, [desc('ui-a', 'ui/a.tsx')], HUB);
+    writeUntrustedMarkers(ctx, [], HUB);
+    expect(existsSync(join(designRoot, '_untrusted', 'INDEX.json'))).toBe(false);
+    // .claudeignore had only our block → removed entirely.
+    expect(existsSync(join(repoRoot, '.claudeignore'))).toBe(false);
+  });
+
+  test('preserves user-authored .claudeignore content outside the block', () => {
+    writeFileSync(join(repoRoot, '.claudeignore'), 'secrets/\n*.key\n');
+    const ctx = ctxOf();
+    writeUntrustedMarkers(ctx, [desc('ui-a', 'ui/a.tsx')], HUB);
+    let ci = readFileSync(join(repoRoot, '.claudeignore'), 'utf8');
+    expect(ci).toContain('secrets/');
+    expect(ci).toContain('*.key');
+    expect(ci).toContain('.design/ui/a.tsx');
+    // Clearing leaves the user content intact.
+    clearUntrustedMarkers(ctx);
+    ci = readFileSync(join(repoRoot, '.claudeignore'), 'utf8');
+    expect(ci).toContain('secrets/');
+    expect(ci).not.toContain('.design/ui/a.tsx');
+    expect(ci).not.toContain('maude:sync-untrusted');
+  });
+});

package/plugins/design/dev-server/test/use-tool-mode.test.tsx

@@ -12,7 +12,7 @@ import {
 } from '../use-tool-mode.tsx';
 
 describe('use-tool-mode / static', () => {
-  test('DEFAULT_TOOLS exposes V/H/C + Phase 5.1 draw set B/R/O/A/E', () => {
+  test('DEFAULT_TOOLS exposes V/H/C + draw set B/R/O/N/A/T/E (Phase 21 sticky+text)', () => {
     expect(DEFAULT_TOOLS.map((t) => t.id)).toEqual([
       'move',
       'hand',
@@ -20,26 +20,54 @@ describe('use-tool-mode / static', () => {
       'pen',
       'rect',
       'ellipse',
+      'sticky',
       'arrow',
+      'text',
       'eraser',
     ]);
-    expect(DEFAULT_TOOLS.map((t) => t.shortcut)).toEqual(['V', 'H', 'C', 'B', 'R', 'O', 'A', 'E']);
+    expect(DEFAULT_TOOLS.map((t) => t.shortcut)).toEqual([
+      'V',
+      'H',
+      'C',
+      'B',
+      'R',
+      'O',
+      'N',
+      'A',
+      'T',
+      'E',
+    ]);
   });
 
   test('DEFAULT_TOOLS is immutable (Object.freeze applied)', () => {
     expect(Object.isFrozen(DEFAULT_TOOLS)).toBe(true);
   });
 
-  test('default cursors per tool', () => {
+  test('default cursors per tool (Phase 21 — custom SVG cursors + native fallback)', () => {
     const byId = Object.fromEntries(DEFAULT_TOOLS.map((t) => [t.id, t.cursor]));
+    // Move keeps the system arrow; every other tool ships a data-URI SVG cursor
+    // that falls back to the right native cursor if the image is rejected.
     expect(byId.move).toBe('default');
-    expect(byId.hand).toBe('grab');
-    expect(byId.comment).toBe('crosshair');
-    expect(byId.pen).toBe('crosshair');
-    expect(byId.rect).toBe('crosshair');
-    expect(byId.ellipse).toBe('crosshair');
-    expect(byId.arrow).toBe('crosshair');
-    expect(byId.eraser).toBe('cell');
+    for (const id of [
+      'hand',
+      'comment',
+      'pen',
+      'rect',
+      'ellipse',
+      'sticky',
+      'arrow',
+      'text',
+      'eraser',
+    ]) {
+      expect(byId[id]).toContain('url("data:image/svg+xml,');
+      expect(byId[id]).toContain('32'); // 32×32 cursor
+    }
+    // Native fallbacks are preserved after the custom URL.
+    expect(byId.hand).toMatch(/, grab$/);
+    expect(byId.text).toMatch(/, text$/);
+    expect(byId.eraser).toMatch(/, cell$/);
+    expect(byId.pen).toMatch(/, crosshair$/);
+    expect(byId.rect).toMatch(/, crosshair$/);
   });
 });
 

package/plugins/design/dev-server/tool-palette.tsx

@@ -35,13 +35,13 @@ const PALETTE_CSS = `
   transform: translateX(-50%);
   display: flex;
   align-items: stretch;
-  background: var(--u-bg-0, var(--bg-0, #ffffff));
-  border: 1px solid var(--u-fg-0, #1c1917);
+  background: var(--maude-chrome-bg-0, #ffffff);
+  border: 1px solid var(--maude-chrome-fg-0, #1c1917);
   border-radius: 8px;
-  box-shadow: 0 6px 24px color-mix(in oklab, var(--u-fg-0, #1c1917) 10%, transparent);
-  font-family: var(--u-font-mono, ui-monospace, SFMono-Regular, Menlo, monospace);
+  box-shadow: 0 6px 24px var(--maude-chrome-shadow, color-mix(in oklab, #1c1917 10%, transparent));
+  font-family: var(--maude-chrome-font-mono, ui-monospace, SFMono-Regular, Menlo, monospace);
   font-size: 12px;
-  color: var(--u-fg-0, var(--fg-0, #1a1a1a));
+  color: var(--maude-chrome-fg-0, #1a1a1a);
   z-index: 6;
   user-select: none;
   /* Intentionally NO overflow:hidden — the zoom popover (.dc-tp-popover) is
@@ -56,7 +56,7 @@ const PALETTE_CSS = `
 }
 .dc-tool-palette .dc-tp-sep {
   width: 1px;
-  background: var(--u-border-subtle, rgba(0,0,0,0.08));
+  background: var(--maude-chrome-border, rgba(0,0,0,0.08));
   margin: 6px 0;
 }
 .dc-tool-palette button {
@@ -70,14 +70,14 @@ const PALETTE_CSS = `
   display: inline-flex;
   align-items: center;
   justify-content: center;
-  color: var(--fg-1, rgba(40,30,20,0.75));
+  color: var(--maude-chrome-fg-1, rgba(40,30,20,0.75));
   cursor: pointer;
   position: relative;
   transition: background-color 80ms linear, color 80ms linear;
 }
 .dc-tool-palette button:hover {
   background: color-mix(in oklab, var(--maude-hud-accent, #d63b1f) 8%, transparent);
-  color: var(--fg-0, #1a1a1a);
+  color: var(--maude-chrome-fg-0, #1a1a1a);
 }
 .dc-tool-palette button:focus-visible {
   outline: 2px solid var(--maude-hud-accent, #d63b1f);
@@ -117,7 +117,7 @@ const PALETTE_CSS = `
   height: 6px;
   background: var(--maude-hud-accent, #d63b1f);
   border-radius: 1px;
-  box-shadow: 0 0 0 1px var(--bg-0, #ffffff);
+  box-shadow: 0 0 0 1px var(--maude-chrome-bg-0, #ffffff);
   opacity: 0;
   transition: opacity 50ms linear 50ms;
   pointer-events: none;
@@ -132,7 +132,7 @@ const PALETTE_CSS = `
   min-width: 56px;
   padding: 0 8px;
   font-variant-numeric: tabular-nums;
-  font-family: var(--u-font-mono, ui-monospace, SFMono-Regular, Menlo, monospace);
+  font-family: var(--maude-chrome-font-mono, ui-monospace, SFMono-Regular, Menlo, monospace);
   font-size: 11px;
   letter-spacing: 0.04em;
   border-radius: 6px;
@@ -145,16 +145,16 @@ const PALETTE_CSS = `
   position: absolute;
   right: 4px;
   bottom: 44px;
-  background: var(--u-bg-0, var(--bg-0, #ffffff));
-  border: 1px solid var(--u-fg-0, #1c1917);
+  background: var(--maude-chrome-bg-0, #ffffff);
+  border: 1px solid var(--maude-chrome-fg-0, #1c1917);
   border-radius: 8px;
-  box-shadow: 0 6px 24px color-mix(in oklab, var(--u-fg-0, #1c1917) 10%, transparent);
+  box-shadow: 0 6px 24px var(--maude-chrome-shadow, color-mix(in oklab, #1c1917 10%, transparent));
   display: flex;
   flex-direction: column;
   padding: 4px;
   min-width: 160px;
   z-index: 7;
-  font-family: var(--u-font-mono, ui-monospace, SFMono-Regular, Menlo, monospace);
+  font-family: var(--maude-chrome-font-mono, ui-monospace, SFMono-Regular, Menlo, monospace);
 }
 .dc-tp-popover button {
   appearance: none;
@@ -171,7 +171,7 @@ const PALETTE_CSS = `
   gap: 16px;
   width: 100%;
 }
-.dc-tp-popover button:hover { background: rgba(0,0,0,0.04); }
+.dc-tp-popover button:hover { background: color-mix(in oklab, var(--maude-chrome-fg-0, #1c1917) 5%, transparent); }
 .dc-tp-popover .dc-tp-kbd {
   font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
   font-size: 11px;
@@ -189,7 +189,9 @@ function ensurePaletteStyles(): void {
 }
 
 const NAV_TOOLS = ['move', 'hand', 'comment'] as const;
-const DRAW_TOOLS = ['pen', 'rect', 'ellipse', 'arrow', 'eraser'] as const;
+// Phase 21 — sticky clusters with the paper primitives (after ellipse); text
+// sits at the constructive end before the destructive eraser, which stays last.
+const DRAW_TOOLS = ['pen', 'rect', 'ellipse', 'sticky', 'arrow', 'text', 'eraser'] as const;
 
 // ─────────────────────────────────────────────────────────────────────────────
 // Component

package/plugins/design/dev-server/undo-hud.tsx

@@ -23,11 +23,11 @@ const HUD_CSS = `
   z-index: 7;
   pointer-events: none;
   padding: 6px 10px;
-  background: var(--bg-2, rgba(20, 20, 20, 0.85));
-  color: var(--fg-1, rgba(255, 255, 255, 0.85));
-  border: 1px solid var(--border-subtle, rgba(255, 255, 255, 0.08));
+  background: var(--maude-chrome-bg-2, rgba(20, 20, 20, 0.85));
+  color: var(--maude-chrome-fg-1, rgba(255, 255, 255, 0.85));
+  border: 1px solid var(--maude-chrome-border, rgba(255, 255, 255, 0.08));
   border-radius: 6px;
-  font: 11px var(--font-mono, ui-monospace, SFMono-Regular, Menlo, monospace);
+  font: 11px var(--maude-chrome-font-mono, ui-monospace, SFMono-Regular, Menlo, monospace);
   letter-spacing: 0.02em;
   user-select: none;
   opacity: 0;

package/plugins/design/dev-server/undo-stack.ts

@@ -203,14 +203,30 @@ interface StoreHost {
 
 /**
  * Prefer `window.top` so all canvas iframes (children of the dev-server
- * shell) read + write the same Map. Falls back to `window` (when top is
- * cross-origin — shouldn't happen in our same-origin setup), then to
- * `globalThis` (Node / Bun test runtime where window is absent).
+ * shell) read + write the same Map. Falls back to `window` when top is
+ * cross-origin — which IS the case under the T2 (9.1-A) segregated canvas
+ * origin: the canvas iframe and the shell are different origins, so any
+ * PROPERTY access on `window.top` throws SecurityError. Then `globalThis`
+ * (Node / Bun test runtime where window is absent).
+ *
+ * Note: merely reading `window.top` (the reference) never throws — only
+ * touching a property of a cross-origin window does. So the guard MUST poke a
+ * property inside the try, or the cross-origin throw escapes into React render
+ * (it did: the UndoStackProvider's useRef initializer crashed the whole canvas
+ * mount to 0 children). Under A1 each iframe falls back to its own `window`
+ * store — undo works per-session; cross-close/reopen sharing via window.top is
+ * intentionally dropped for the origin isolation (see DDR-0xx / phase-9.1).
  */
 function getStoreHost(): StoreHost {
   if (typeof window !== 'undefined') {
     try {
-      return (window.top ?? window) as unknown as StoreHost;
+      const top = window.top;
+      if (top && top !== window) {
+        // Poke a property — throws if `top` is a cross-origin window.
+        void (top as unknown as StoreHost).__maude_undo_stacks;
+        return top as unknown as StoreHost;
+      }
+      return window as unknown as StoreHost;
     } catch {
       return window as unknown as StoreHost;
     }

package/plugins/design/dev-server/use-annotation-resize.tsx

@@ -22,6 +22,7 @@ import {
   type EllipseStroke,
   type PenStroke,
   type RectStroke,
+  type StickyStroke,
   type Stroke,
   type StrokesStoreValue,
   strokeBBox,
@@ -58,9 +59,17 @@ function ensureResizeStyles(): void {
 
 type Corner = 'nw' | 'ne' | 'sw' | 'se' | 'ep1' | 'ep2';
 
-/** Stroke types that expose resize handles in v1. Text inherits anchor bbox. */
-function isResizable(s: Stroke): s is RectStroke | EllipseStroke | ArrowStroke | PenStroke {
-  return s.tool === 'rect' || s.tool === 'ellipse' || s.tool === 'arrow' || s.tool === 'pen';
+/** Stroke types that expose resize handles. Text inherits its anchor bbox. */
+function isResizable(
+  s: Stroke
+): s is RectStroke | EllipseStroke | ArrowStroke | PenStroke | StickyStroke {
+  return (
+    s.tool === 'rect' ||
+    s.tool === 'ellipse' ||
+    s.tool === 'arrow' ||
+    s.tool === 'pen' ||
+    s.tool === 'sticky'
+  );
 }
 
 /**
@@ -75,7 +84,9 @@ function resizeStroke(
   wx: number,
   wy: number
 ): Partial<Stroke> | null {
-  if (start.tool === 'rect') {
+  if (start.tool === 'rect' || start.tool === 'sticky') {
+    // Sticky resizes exactly like a rect — it shares x / y / w / h. Text
+    // re-wraps inside the foreignObject automatically (no special handling).
     const bbox = { x: start.x, y: start.y, w: start.w, h: start.h };
     const left = corner === 'nw' || corner === 'sw' ? wx : bbox.x;
     const right = corner === 'ne' || corner === 'se' ? wx : bbox.x + bbox.w;
@@ -86,7 +97,7 @@ function resizeStroke(
       y: Math.min(top, bottom),
       w: Math.abs(right - left),
       h: Math.abs(bottom - top),
-    } as Partial<RectStroke>;
+    } as Partial<RectStroke | StickyStroke>;
   }
   if (start.tool === 'ellipse') {
     // Treat the four corners as the bbox of the ellipse. Drag any corner →

package/plugins/design/dev-server/use-collab.tsx

@@ -111,11 +111,164 @@ export interface CollabAwarenessState {
 
 export type ForeignAwareness = Omit<CollabAwarenessState, '__connId'> & { clientID: number };
 
+// ─────────────────────────────────────────────────────────────────────────────
+// Untrusted-input sanitization at the awareness trust boundary.
+//
+// Phase 8 awareness was loopback-only — every state came from a trusted local
+// tab. Phase 9 (Task 5) bridges awareness through a SEMI-TRUSTED hub (DDR-054),
+// so foreign states are now attacker-influenceable. `useForeignAwareness` is
+// the single chokepoint where remote state is read before it reaches the
+// cursor / participant render sinks, so all validation lives here. Fields are
+// validated for VALUE, not just type:
+//   - color: re-derived locally from the (sanitized) name and the wire value
+//     is DISCARDED — a hub-chosen `color` string would otherwise flow into an
+//     inline `style` and a `url(...)` value beacons every viewer's browser.
+//     The palette is deterministic, so re-derivation is visually identical.
+//   - name: control / bidi / zero-width chars stripped, length-capped — blocks
+//     identity spoofing + render bloat.
+//   - cursor / viewport: finite-number gated — a NaN/Infinity would poison the
+//     CSS transform / the local viewport controller during Follow mode.
+//   - selection.cssPath: charset + length allowlist before it reaches
+//     `querySelector` — blocks selector-complexity DoS + arbitrary DOM probing.
+//   - annotationSelection: per-id token + array-length capped — blocks a
+//     querySelector render-storm.
+//   - peer count capped — blocks an unbounded-clients memory/render DoS.
+
+const MAX_FOREIGN_PEERS = 64;
+const MAX_NAME_LEN = 64;
+const MAX_CSSPATH_LEN = 512;
+const MAX_ANNOTATION_IDS = 256;
+const MAX_ANNOTATION_ID_LEN = 128;
+
+// Charset of every selector the canvas-shell `cssPath()` emits
+// (`[data-*="..."]`, `#id`, `tag.cls:nth-child(N)`, ` > ` combinators).
+const CSSPATH_ALLOWED = /^[A-Za-z0-9 ._#>:[\]="'()-]+$/;
+// `cssPath()` only ever emits `:nth-child(N)` as a parenthesised construct.
+// Functional pseudo-classes (`:has()`, `:is()`, `:where()`, `:not()`) trigger
+// per-render subtree walks → a malicious hub peer could publish a deeply
+// nested `:has()` selector and pin every viewer's main thread (querySelector
+// re-runs each render). So after stripping the legit `:nth-child/of-type(N)`
+// forms, any residual paren means a functional pseudo — reject. The charset
+// allowlist alone was wider than the generator (the original DoS hole).
+const CSSPATH_NTH = /:nth-(child|of-type)\(\d{1,4}\)/g;
+const ANNOTATION_ID_ALLOWED = /^[A-Za-z0-9._:-]+$/;
+
+function isSafeCssPath(p: string): boolean {
+  if (p.length > MAX_CSSPATH_LEN || !CSSPATH_ALLOWED.test(p)) return false;
+  const stripped = p.replace(CSSPATH_NTH, '');
+  return !stripped.includes('(') && !stripped.includes(')');
+}
+
+function isFiniteNum(v: unknown): v is number {
+  return typeof v === 'number' && Number.isFinite(v);
+}
+
+// Control (C0/C1), zero-width, and bidi-override code points get stripped from
+// displayed strings so a remote peer can't spoof another's identity or hide
+// payloads in labels. A charCode scan (not a regex literal with raw control
+// chars) sidesteps biome's noControlCharactersInRegex while keeping the same
+// semantics — same approach as the hub's sanitizeForLog (DDR-053).
+function isUnsafeCodePoint(cp: number): boolean {
+  return (
+    cp <= 0x1f ||
+    (cp >= 0x7f && cp <= 0x9f) ||
+    (cp >= 0x200b && cp <= 0x200f) ||
+    (cp >= 0x202a && cp <= 0x202e) ||
+    (cp >= 0x2066 && cp <= 0x2069) ||
+    cp === 0xfeff
+  );
+}
+
+function sanitizeName(raw: unknown): string {
+  if (typeof raw !== 'string') return 'anonymous';
+  let cleaned = '';
+  for (const ch of raw) {
+    if (!isUnsafeCodePoint(ch.codePointAt(0) ?? 0)) cleaned += ch;
+  }
+  cleaned = cleaned.trim().slice(0, MAX_NAME_LEN);
+  return cleaned || 'anonymous';
+}
+
+function sanitizeCursor(raw: unknown): { x: number; y: number } | null {
+  if (!raw || typeof raw !== 'object') return null;
+  const c = raw as { x?: unknown; y?: unknown };
+  return isFiniteNum(c.x) && isFiniteNum(c.y) ? { x: c.x, y: c.y } : null;
+}
+
+function sanitizeViewport(raw: unknown): { x: number; y: number; zoom: number } {
+  const fallback = { x: 0, y: 0, zoom: 1 };
+  if (!raw || typeof raw !== 'object') return fallback;
+  const v = raw as { x?: unknown; y?: unknown; zoom?: unknown };
+  if (!isFiniteNum(v.x) || !isFiniteNum(v.y) || !isFiniteNum(v.zoom) || v.zoom <= 0)
+    return fallback;
+  return { x: v.x, y: v.y, zoom: v.zoom };
+}
+
+function sanitizeSelection(raw: unknown): CollabAwarenessState['selection'] {
+  if (!raw || typeof raw !== 'object') return null;
+  const s = raw as { cssPath?: unknown; bounds?: unknown };
+  const b = s.bounds as { x?: unknown; y?: unknown; w?: unknown; h?: unknown } | undefined;
+  const bounds =
+    b && isFiniteNum(b.x) && isFiniteNum(b.y) && isFiniteNum(b.w) && isFiniteNum(b.h)
+      ? { x: b.x, y: b.y, w: b.w, h: b.h }
+      : null;
+  // Only keep cssPath if it matches the locator grammar — otherwise drop it and
+  // let the renderer fall back to the (validated) bounds.
+  const cssPath = typeof s.cssPath === 'string' && isSafeCssPath(s.cssPath) ? s.cssPath : '';
+  if (!cssPath && !bounds) return null;
+  return { cssPath, bounds: bounds ?? { x: 0, y: 0, w: 0, h: 0 } };
+}
+
+function sanitizeAnnotationSelection(raw: unknown): string[] {
+  if (!Array.isArray(raw)) return [];
+  const out: string[] = [];
+  for (const id of raw) {
+    if (out.length >= MAX_ANNOTATION_IDS) break;
+    if (
+      typeof id === 'string' &&
+      id.length <= MAX_ANNOTATION_ID_LEN &&
+      ANNOTATION_ID_ALLOWED.test(id)
+    )
+      out.push(id);
+  }
+  return out;
+}
+
+/**
+ * Validate + normalize one foreign awareness state at the trust boundary.
+ * Returns null for states that can't be a peer (no usable name). `color` is
+ * always re-derived locally from the sanitized name — the wire value is never
+ * trusted, which is what closes the hub CSS-`url()` exfil channel. Exported so
+ * the hostile-input matrix can exercise it without a React harness.
+ */
+export function sanitizeForeignState(clientID: number, state: unknown): ForeignAwareness | null {
+  if (!state || typeof state !== 'object') return null;
+  const s = state as Partial<CollabAwarenessState>;
+  if (typeof s.name !== 'string') return null;
+  const name = sanitizeName(s.name);
+  return {
+    clientID,
+    name,
+    color: colorForName(name),
+    cursor: sanitizeCursor(s.cursor),
+    selection: sanitizeSelection(s.selection),
+    annotationSelection: sanitizeAnnotationSelection(s.annotationSelection),
+    viewport: sanitizeViewport(s.viewport),
+  };
+}
+
 // ─────────────────────────────────────────────────────────────────────────────
 // Context.
 
 interface CollabValue {
   doc: Y.Doc;
+  /**
+   * SECURITY INVARIANT: in linked mode this Awareness carries states relayed
+   * from a SEMI-TRUSTED hub (DDR-054). Foreign states are untrusted input —
+   * read them ONLY through `useForeignAwareness`, which sanitizes every field
+   * at the trust boundary (`sanitizeForeignState`). Do NOT call
+   * `awareness.getStates()` directly in render code; that bypasses the gate.
+   */
   awareness: Awareness;
   /** Local peer's session-stable color (derived from git user.name). */
   myColor: string;
@@ -158,19 +311,10 @@ export function useForeignAwareness(): ForeignAwareness[] {
       const myId = awareness.clientID;
       for (const [clientID, state] of awareness.getStates() as Map<number, unknown>) {
         if (clientID === myId) continue;
-        if (!state || typeof state !== 'object') continue;
-        const s = state as Partial<CollabAwarenessState>;
-        // Guard against partial states from stale peers / older protocol versions.
-        if (typeof s.name !== 'string' || typeof s.color !== 'string') continue;
-        out.push({
-          clientID,
-          name: s.name,
-          color: s.color,
-          cursor: s.cursor ?? null,
-          selection: s.selection ?? null,
-          annotationSelection: Array.isArray(s.annotationSelection) ? s.annotationSelection : [],
-          viewport: s.viewport ?? { x: 0, y: 0, zoom: 1 },
-        });
+        if (out.length >= MAX_FOREIGN_PEERS) break; // bound DoS via unbounded peers
+        // Sanitize every now-remote field at this trust boundary (Task 5).
+        const peer = sanitizeForeignState(clientID, state);
+        if (peer) out.push(peer);
       }
       return out;
     }