@1agh/maude 0.23.0 → 0.25.0

package/plugins/design/dev-server/input-router.tsx

@@ -63,9 +63,33 @@ export function crossedDragThreshold(
  * returns `no-op` for the corresponding pointer events so the SVG overlay
  * can grab them natively.
  */
-export type Tool = 'move' | 'hand' | 'comment' | 'pen' | 'rect' | 'ellipse' | 'arrow' | 'eraser';
-
-const ANNOTATION_TOOLS = new Set<Tool>(['pen', 'rect', 'ellipse', 'arrow', 'eraser']);
+export type Tool =
+  | 'move'
+  | 'hand'
+  | 'comment'
+  | 'pen'
+  // Phase 24 — `shape` is the single active draw tool that produces rect /
+  // ellipse / polygon strokes (the kind is chosen via the palette popover).
+  // `rect` / `ellipse` stay in the union as the stroke discriminants they
+  // always were, but are no longer directly selectable active tools.
+  | 'shape'
+  | 'rect'
+  | 'ellipse'
+  | 'arrow'
+  | 'sticky'
+  | 'text'
+  | 'eraser';
+
+const ANNOTATION_TOOLS = new Set<Tool>([
+  'pen',
+  'shape',
+  'rect',
+  'ellipse',
+  'arrow',
+  'sticky',
+  'text',
+  'eraser',
+]);
 
 export function isAnnotationTool(t: Tool): boolean {
   return ANNOTATION_TOOLS.has(t);
@@ -143,9 +167,15 @@ export function classify(input: ClassifyInput): RouterAction {
     if (k === 'h') return { kind: 'tool', tool: 'hand' };
     if (k === 'c') return { kind: 'tool', tool: 'comment' };
     if (k === 'b') return { kind: 'tool', tool: 'pen' };
-    if (k === 'r') return { kind: 'tool', tool: 'rect' };
-    if (k === 'o') return { kind: 'tool', tool: 'ellipse' };
+    // Phase 24 — R (and legacy O) both arm the single Shape tool; the specific
+    // primitive is picked from the palette's shape-kind popover.
+    if (k === 'r' || k === 'o') return { kind: 'tool', tool: 'shape' };
     if (k === 'a') return { kind: 'tool', tool: 'arrow' };
+    // Phase 21 — N = sticky Note ('S' is taken by the shell Design-system view
+    // + Shift-marquee); T = standalone Text. Both are bare letters the shell
+    // yields when focus is inside the canvas iframe (app.jsx onKey bail).
+    if (k === 'n') return { kind: 'tool', tool: 'sticky' };
+    if (k === 't') return { kind: 'tool', tool: 'text' };
     if (k === 'e') return { kind: 'tool', tool: 'eraser' };
     if (input.key === 'Escape') return { kind: 'escape' };
     return { kind: 'no-op' };

package/plugins/design/dev-server/participants-chrome.tsx

@@ -42,7 +42,7 @@ const CHROME_CSS = `
   line-height: 1;
   letter-spacing: 0.02em;
   color: var(--maude-hud-accent-fg, #fff);
-  border: 1.5px solid var(--bg-0, #fff);
+  border: 1.5px solid var(--maude-chrome-bg-0, #fff);
   margin-left: -6px;
   cursor: pointer;
   position: relative;
@@ -70,20 +70,20 @@ const CHROME_CSS = `
   right: 0;
   min-width: 168px;
   padding: 10px 12px;
-  background: var(--bg-1, #fff);
-  color: var(--fg-0, #111);
-  border: 1px solid var(--border-default, rgba(0,0,0,0.16));
+  background: var(--maude-chrome-bg-1, #fff);
+  color: var(--maude-chrome-fg-0, #111);
+  border: 1px solid var(--maude-chrome-border, rgba(0,0,0,0.16));
   border-radius: var(--radius-md, 4px);
   font-size: 12px;
   line-height: 1.35;
   white-space: nowrap;
-  box-shadow: 0 6px 18px rgba(0,0,0,0.10);
+  box-shadow: 0 6px 18px var(--maude-chrome-shadow, rgba(0,0,0,0.10));
   z-index: 11;
 }
 .dc-participant-popover__name {
   font-weight: 600;
   margin-bottom: 8px;
-  color: var(--fg-0, #111);
+  color: var(--maude-chrome-fg-0, #111);
   letter-spacing: 0.01em;
 }
 .dc-participant-popover__btn {
@@ -102,11 +102,11 @@ const CHROME_CSS = `
 }
 .dc-participant-popover__btn:hover { background: var(--maude-hud-accent-hover, var(--maude-hud-accent, oklch(50% 0.170 50))); }
 .dc-participant-popover__btn--stop {
-  background: var(--bg-3, #e5e5e5);
-  color: var(--fg-0, #111);
-  border: 1px solid var(--border-subtle, rgba(0,0,0,0.12));
+  background: color-mix(in oklab, var(--maude-chrome-fg-0, #111) 10%, transparent);
+  color: var(--maude-chrome-fg-0, #111);
+  border: 1px solid var(--maude-chrome-border, rgba(0,0,0,0.12));
 }
-.dc-participant-popover__btn--stop:hover { background: var(--bg-4, #d8d8d8); }
+.dc-participant-popover__btn--stop:hover { background: color-mix(in oklab, var(--maude-chrome-fg-0, #111) 16%, transparent); }
 @media (prefers-reduced-motion: reduce) {
   .dc-participant { transition: none; }
 }

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

@@ -36,6 +36,14 @@ await bootSelfHeal();
 
 const ctx = createContext();
 
+// Phase 9.2 (DDR-064) — `MAUDE_SHARED_DOC` feature flag. OPT-IN (default OFF),
+// the inverse of MAUDE_CANVAS_ORIGIN_SPLIT's opt-out parsing: only an explicit
+// truthy value enables the single-shared-doc path. OFF = the proven two-doc +
+// disk-reconcile path = byte-for-byte current behavior. The flag is threaded
+// onto ctx here (before createCollab / createSyncRuntime read it) so every
+// downstream consumer sees one source of truth.
+ctx.sharedDoc = /^(1|true|on|yes)$/i.test(process.env.MAUDE_SHARED_DOC ?? '');
+
 // Forward-declared so the api.commentsAdd/patch/delete/addReply callback can
 // reach into the collab registry (Phase 8 Task 3 bridge). collab is initialized
 // synchronously below; the callback only fires at runtime, by which point the
@@ -142,6 +150,87 @@ function startServer(port: number): BunServer {
   });
 }
 
+// T2 (9.1-A) — the segregated canvas-content origin. A second Bun.serve on its
+// own (OS-assigned) port, sharing this process's ctx / api / inspect / collab /
+// ws. Canvas iframes load from here; hub-pushed JSX that executes in a canvas
+// can therefore only reach THIS origin (locked further by the CSP on the shell
+// + an iframe sandbox), never the main origin's /_api/export, /_config,
+// /_sync-status, /_comments, or arbitrary repo files. Routes are a hard
+// allowlist: Bun matches `routes` before `fetch`, so we expose ONLY the two
+// gated API endpoints the runtime needs here and 403 everything else in fetch.
+function startCanvasServer(port: number): BunServer {
+  return Bun.serve<WsData, never>({
+    port,
+    hostname: '127.0.0.1',
+    development: process.env.NODE_ENV !== 'production',
+    // Hard allowlist of route-table endpoints (Bun matches `routes` before
+    // `fetch`). Only the collab/display-data endpoints the canvas runtime needs
+    // — see http.isCanvasSafeRoute for the trust rationale. The dynamic
+    // /_api/comments/<id>/reply POST is fetch-handled + gated there.
+    routes: {
+      '/_health': http.routes['/_health'],
+      '/_api/git-user': http.routes['/_api/git-user'],
+      '/_api/canvas-meta': http.routes['/_api/canvas-meta'],
+      '/_api/annotations': http.routes['/_api/annotations'],
+      '/_api/git-committers': http.routes['/_api/git-committers'],
+      '/_api/ai': http.routes['/_api/ai'],
+      '/_comments': http.routes['/_comments'],
+    },
+    async fetch(req, srv) {
+      const pathname = new URL(req.url).pathname;
+
+      // Collab WS — shared registry, loopback-only (same gate as the main origin).
+      const collabSlug = parseCollabSlug(pathname);
+      if (collabSlug !== null) {
+        if (!isLoopbackHost(req.headers.get('host'))) {
+          return new Response('cross-machine collab requires Phase 9 hub deploy', { status: 403 });
+        }
+        const ok = srv.upgrade(req, {
+          data: {
+            id: crypto.randomUUID(),
+            remote: req.headers.get('x-forwarded-for') ?? '127.0.0.1',
+            kind: 'collab',
+            slug: collabSlug,
+          },
+        });
+        if (ok) return undefined as unknown as Response;
+        return new Response('Upgrade failed', { status: 400 });
+      }
+
+      // HMR-only socket — canvas iframes listen for `canvas-hmr` here. Carries
+      // NO privileged inspector feed and ignores inbound messages (ws.ts).
+      if (pathname.startsWith('/_ws')) {
+        const ok = srv.upgrade(req, {
+          data: {
+            id: crypto.randomUUID(),
+            remote: req.headers.get('x-forwarded-for') ?? '127.0.0.1',
+            kind: 'canvas-hmr',
+          },
+        });
+        if (ok) return undefined as unknown as Response;
+        return new Response('Upgrade failed', { status: 400 });
+      }
+
+      // Canvas mount harness with the strict CSP ALWAYS on (F1 gate).
+      if (pathname === '/_canvas-shell.html' || pathname === '/_canvas-shell') {
+        return http.serveCanvasShell(true);
+      }
+
+      // Allowlist gate — runtime bundles, comment-mount, transpiled .tsx + CSS/
+      // assets under designRoot. Everything else is refused at the door.
+      if (!http.isCanvasSafeRoute(pathname)) {
+        return new Response('Forbidden (canvas origin)', { status: 403 });
+      }
+      return http.fetch(req);
+    },
+    websocket: ws.handler,
+    error(e) {
+      console.error('[bun.serve canvas-origin error]', e);
+      return new Response('Server error', { status: 500 });
+    },
+  });
+}
+
 function isAddrInUse(e: unknown): boolean {
   if (!e || typeof e !== 'object') return false;
   const err = e as { code?: string; errno?: number };
@@ -181,6 +270,30 @@ let server: BunServer;
   server = bound;
 }
 
+// T2 (9.1-A) — advertise the main origin so the canvas origin's CSP can
+// allowlist it in `frame-ancestors` (the legit embedder). Must be set before
+// the canvas listener serves its first shell.
+ctx.mainOrigin = `http://localhost:${server.port}`;
+
+// T2 (9.1-A) — segregated canvas-content origin. ON BY DEFAULT (opt-OUT) since
+// phase-9.1: a second listener binds an OS-assigned free port, advertised as
+// `canvasOrigin`, and the client loads canvas iframes cross-origin under the
+// strict CSP + sandbox + route-allowlist (the F1 containment). This is purely
+// protective — for a solo user it sandboxes their OWN canvas code (no untrusted
+// content, no exfil concern), and interactive-feature parity (selection,
+// comments, presence, motion) is verified. It does NOT by itself enable
+// untrusted `.tsx` sync — that still requires the per-canvas `syncable` opt-in
+// (sync/index.ts), so the WebRTC/self-nav exfil residual only applies to a
+// canvas explicitly opted into syncing (DDR-060 + the F1 re-audit report).
+// Set `MAUDE_CANVAS_ORIGIN_SPLIT=0` (or false/off/no) to fall back to the legacy
+// same-origin path.
+const CANVAS_ORIGIN_SPLIT = !/^(0|false|off|no)$/i.test(
+  process.env.MAUDE_CANVAS_ORIGIN_SPLIT ?? ''
+);
+const canvasServer = CANVAS_ORIGIN_SPLIT ? startCanvasServer(0) : null;
+const canvasOrigin = canvasServer ? `http://localhost:${canvasServer.port}` : undefined;
+if (canvasOrigin) ctx.canvasOrigin = canvasOrigin;
+
 await Bun.write(
   ctx.paths.serverInfoFile,
   JSON.stringify(
@@ -188,6 +301,7 @@ await Bun.write(
       pid: process.pid,
       port: server.port,
       url: `http://localhost:${server.port}`,
+      ...(canvasOrigin ? { canvasOrigin } : {}),
       started: new Date().toISOString(),
       project: ctx.cfg.name,
       config_source: ctx.cfg._source,
@@ -238,7 +352,10 @@ async function shutdown() {
     /* best-effort — provider sockets will be closed by process exit anyway */
   }
   try {
-    if (collab) await collab.registry.destroyAll();
+    if (collab) {
+      collab.dispose();
+      await collab.registry.destroyAll();
+    }
   } catch {
     /* best-effort flush; the JSON snapshot is the ground truth anyway */
   }
@@ -261,6 +378,11 @@ async function shutdown() {
     /* ignore */
   }
   server.stop();
+  try {
+    canvasServer?.stop();
+  } catch {
+    /* best-effort */
+  }
   process.exit(0);
 }
 

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

@@ -37,9 +37,14 @@ import {
   annotationsFromDoc,
   applyAnnotationsToDoc,
   applyCommentsToDoc,
+  applyCssToDoc,
   applyHtmlToDoc,
+  applyMetaToDoc,
   commentsFromDoc,
+  cssFromDoc,
   htmlFromDoc,
+  mergeSharedMetaIntoLocal,
+  metaFromDoc,
 } from './codec.ts';
 import { type EchoGuard, hashBytes } from './echo-guard.ts';
 
@@ -52,6 +57,14 @@ export interface CanvasSyncPaths {
   comments: string;
   /** Absolute path to <designRoot>/<slug>.annotations.svg. */
   annotations: string;
+  /** Absolute path to the canvas `.meta.json` (sibling of the body). Optional:
+   *  when set (always, in production wiring), shared meta keys (layout/artboards)
+   *  sync while per-user viewport stays local (Phase 9.1 Gap 2). Omitted in
+   *  older test constructions → meta sync is simply inert. */
+  meta?: string;
+  /** Absolute path to the canvas's sibling `.css` (Phase 9.1 Gap 3). Optional —
+   *  inline-CSS canvases have none; omitted/absent → css sync is inert. */
+  css?: string;
 }
 
 export interface CanvasSyncAgentOptions {
@@ -66,6 +79,14 @@ export interface CanvasSyncAgentOptions {
   flushMs?: number;
   /** Injected for tests — defaults to atomicWrite. */
   writer?: (path: string, bytes: string | Uint8Array) => void;
+  /**
+   * Called when a non-adopt reconcile (cold-start / post-git-pull) overwrites
+   * differing, non-empty local content with hub state — i.e. the local peer
+   * had divergent work that hub-wins discarded. Lets the runtime surface a
+   * "hub overwrote your local changes" notification (Phase 9 Task 8). v1.1
+   * resolution is always hub-wins; the interactive 3-way prompt is deferred.
+   */
+  onConflict?: (info: { slug: string; kind: 'cold-start-hub-wins' }) => void;
 }
 
 export interface CanvasSyncAgent {
@@ -105,6 +126,8 @@ export function createCanvasSyncAgent(opts: CanvasSyncAgentOptions): CanvasSyncA
   let lastHtml: string | null = null;
   let lastComments: string | null = null;
   let lastAnnotations: string | null = null;
+  let lastMeta: string | null = null;
+  let lastCss: string | null = null;
 
   function onDocUpdate(_update: Uint8Array, updateOrigin: unknown): void {
     if (stopped) return;
@@ -141,6 +164,8 @@ export function createCanvasSyncAgent(opts: CanvasSyncAgentOptions): CanvasSyncA
       writeHtmlIfChanged();
       writeCommentsIfChanged();
       writeAnnotationsIfChanged();
+      writeMetaIfChanged();
+      writeCssIfChanged();
     } catch (err) {
       dirty = true;
       console.error(`[sync/${slug}] flush failed:`, err);
@@ -186,6 +211,31 @@ export function createCanvasSyncAgent(opts: CanvasSyncAgentOptions): CanvasSyncA
     lastAnnotations = value;
   }
 
+  function writeMetaIfChanged(): void {
+    if (!paths.meta) return;
+    const shared = metaFromDoc(doc);
+    if (shared === lastMeta) return;
+    lastMeta = shared;
+    if (shared === null) return; // doc carries no shared meta yet — nothing to merge down
+    const local = readLocal(paths.meta);
+    const merged = mergeSharedMetaIntoLocal(local, shared);
+    if (merged === null || merged === local) return; // unparseable, or disk already matches
+    const hash = hashBytes(merged);
+    echoGuard.record(paths.meta, hash);
+    writer(paths.meta, merged);
+  }
+
+  function writeCssIfChanged(): void {
+    if (!paths.css) return;
+    const next = cssFromDoc(doc);
+    if (next === lastCss) return;
+    lastCss = next;
+    if (next === null) return; // doc carries no css yet — nothing to write
+    const hash = hashBytes(next);
+    echoGuard.record(paths.css, hash);
+    writer(paths.css, next);
+  }
+
   function applyFromFs(evt: { path: string; bytes: Uint8Array; hash: string }): boolean {
     if (stopped) return false;
     // Echo of our own atomicWrite — drop.
@@ -209,6 +259,18 @@ export function createCanvasSyncAgent(opts: CanvasSyncAgentOptions): CanvasSyncA
       if (changed) lastAnnotations = str;
       return changed;
     }
+    if (paths.meta && evt.path === paths.meta) {
+      // Local meta changed (canvas-meta PATCH / design:edit) → push its SHARED
+      // subset (layout/artboards, minus per-user viewport) into the doc.
+      const changed = applyMetaToDoc(doc, str, origin);
+      if (changed) lastMeta = metaFromDoc(doc);
+      return changed;
+    }
+    if (paths.css && evt.path === paths.css) {
+      const changed = applyCssToDoc(doc, str, origin);
+      if (changed) lastCss = str;
+      return changed;
+    }
     return false;
   }
 
@@ -217,12 +279,16 @@ export function createCanvasSyncAgent(opts: CanvasSyncAgentOptions): CanvasSyncA
     const localHtml = readLocal(paths.html);
     const localComments = readLocal(paths.comments);
     const localAnnotations = readLocal(paths.annotations);
+    const localMeta = paths.meta ? readLocal(paths.meta) : null;
+    const localCss = paths.css ? readLocal(paths.css) : null;
 
     const docHtml = htmlFromDoc(doc);
     const docComments = commentsFromDoc(doc);
     const docCommentsStr =
       docComments.length > 0 ? `${JSON.stringify(docComments, null, 2)}\n` : '';
     const docAnnotations = annotationsFromDoc(doc) ?? '';
+    const docMeta = metaFromDoc(doc);
+    const docCss = cssFromDoc(doc);
 
     if (adopt) {
       // Push local up: doc takes its values from disk. Hub becomes our
@@ -233,9 +299,13 @@ export function createCanvasSyncAgent(opts: CanvasSyncAgentOptions): CanvasSyncA
         if (parsed !== null) applyCommentsToDoc(doc, parsed, origin);
       }
       if (localAnnotations !== null) applyAnnotationsToDoc(doc, localAnnotations, origin);
+      if (paths.meta && localMeta !== null) applyMetaToDoc(doc, localMeta, origin);
+      if (paths.css && localCss !== null) applyCssToDoc(doc, localCss, origin);
       lastHtml = localHtml ?? '';
       lastComments = localComments ?? '';
       lastAnnotations = localAnnotations ?? '';
+      lastMeta = metaFromDoc(doc);
+      lastCss = cssFromDoc(doc);
       adopt = false;
       return;
     }
@@ -244,7 +314,15 @@ export function createCanvasSyncAgent(opts: CanvasSyncAgentOptions): CanvasSyncA
     lastHtml = docHtml;
     lastComments = docCommentsStr;
     lastAnnotations = docAnnotations;
+    lastMeta = docMeta;
+    lastCss = docCss;
     if (localHtml !== docHtml) {
+      // Local had divergent, non-empty content that hub-wins is discarding —
+      // notify so the user knows their local edits were overwritten (Task 8).
+      // An absent/empty local file is a clean first-sync, not a conflict.
+      if (localHtml !== null && localHtml.trim() !== '') {
+        opts.onConflict?.({ slug, kind: 'cold-start-hub-wins' });
+      }
       const hash = hashBytes(docHtml);
       echoGuard.record(paths.html, hash);
       writer(paths.html, docHtml);
@@ -259,6 +337,23 @@ export function createCanvasSyncAgent(opts: CanvasSyncAgentOptions): CanvasSyncA
       echoGuard.record(paths.annotations, hash);
       writer(paths.annotations, docAnnotations);
     }
+    // Meta: merge the doc's shared subset (layout/artboards) into local,
+    // preserving this machine's viewport + syncable. Only writes when the merge
+    // actually changes the file (a fresh peer with no local viewport, or an
+    // artboard layout the hub carries that local lacks).
+    if (paths.meta && docMeta !== null) {
+      const merged = mergeSharedMetaIntoLocal(localMeta, docMeta);
+      if (merged !== null && merged !== localMeta) {
+        const hash = hashBytes(merged);
+        echoGuard.record(paths.meta, hash);
+        writer(paths.meta, merged);
+      }
+    }
+    if (paths.css && docCss !== null && localCss !== docCss) {
+      const hash = hashBytes(docCss);
+      echoGuard.record(paths.css, hash);
+      writer(paths.css, docCss);
+    }
   }
 
   return {

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

@@ -33,6 +33,16 @@ import { Y_TYPES } from '../collab/persistence.ts';
 export const Y_SYNC_TYPES = {
   /** The canvas HTML body, as opaque Y.Text. */
   html: 'html',
+  /** The canvas's sibling `.css` (e.g. `Kanban App.css`), as opaque Y.Text.
+   *  Edited via files (design:edit), not a live browser surface, so it mirrors
+   *  wholesale like the body — no per-user keys, no room-clobber. Phase 9.1
+   *  Gap 3. */
+  css: 'css',
+  /** The canvas `.meta.json` SHARED subset (layout/artboards/structure) as an
+   *  opaque canonical-JSON Y.Text. Per-user keys (viewport pan/zoom) + the
+   *  security opt-in (syncable) are stripped before sync — see META_LOCAL_KEYS
+   *  + sharedMetaCanonical. Phase 9.1 Gap 2. */
+  meta: 'meta',
 } as const;
 
 /**
@@ -44,11 +54,26 @@ export const Y_SYNC_TYPES = {
 export const MAX_HTML_BYTES = 4 * 1024 * 1024;
 export const MAX_COMMENTS_BYTES = 1 * 1024 * 1024;
 export const MAX_ANNOTATIONS_BYTES = 1 * 1024 * 1024;
+export const MAX_META_BYTES = 1 * 1024 * 1024;
+export const MAX_CSS_BYTES = 4 * 1024 * 1024;
 
 function byteLengthUtf8(s: string): number {
   return Buffer.byteLength(s, 'utf8');
 }
 
+// DDR-054 §2g — strip dangerous keys at parse time so a hostile hub-pushed (or
+// planted-commit) payload can't seed `__proto__` / `constructor` / `prototype`
+// own-properties that yjs then serializes to other peers / writes to disk that
+// Claude reads. Mirrors the agent's comments reviver; applied to the `.meta.json`
+// parse paths (Phase D security re-audit finding A3 — the reviver had been
+// applied only to the comments lane, not the symmetric meta lane).
+function parseJsonSafe(s: string): unknown {
+  return JSON.parse(s, (key, value) => {
+    if (key === '__proto__' || key === 'constructor' || key === 'prototype') return undefined;
+    return value;
+  });
+}
+
 /* ---------------------------------------------------------------- HTML */
 
 export function htmlFromDoc(doc: Y.Doc): string {
@@ -167,3 +192,133 @@ export function applyAnnotationsToDoc(doc: Y.Doc, next: string | null, origin?:
   }, origin);
   return true;
 }
+
+/* ---------------------------------------------------------------- meta */
+
+/**
+ * Keys of a canvas `.meta.json` that are PER-MACHINE and MUST NOT cross the hub:
+ *   - `viewport`      — this user's pan/zoom; syncing it would yank a
+ *                        collaborator's camera around on every pan.
+ *   - `last_modified` — a local write timestamp; syncing it churns with no signal.
+ *   - `syncable`      — the security opt-in (DDR-054). A peer/hub must NEVER be
+ *                        able to flip another repo's sync gate, so it stays local
+ *                        and human-edited — same rationale that keeps it out of
+ *                        the /_api/canvas-meta PATCH whitelist.
+ * Everything else (title, sections/artboards, `layout` rects, css_mode, …) is
+ * shared canvas structure and DOES sync — that's how an artboard move on one
+ * machine reaches the other's disk.
+ */
+export const META_LOCAL_KEYS = ['viewport', 'last_modified', 'syncable'] as const;
+
+/** Canonical JSON of the SHARED subset of a parsed meta object: local keys
+ *  dropped, remaining keys sorted so equal content always serializes byte-equal
+ *  (stable → the no-op guards stay quiet and sync doesn't churn). */
+function sharedMetaCanonical(meta: Record<string, unknown>): string {
+  const out: Record<string, unknown> = {};
+  for (const k of Object.keys(meta).sort()) {
+    if ((META_LOCAL_KEYS as readonly string[]).includes(k)) continue;
+    out[k] = meta[k];
+  }
+  return JSON.stringify(out);
+}
+
+/** The synced shared-meta JSON string held in the doc, or null when unset. */
+export function metaFromDoc(doc: Y.Doc): string | null {
+  const s = doc.getText(Y_SYNC_TYPES.meta).toString();
+  return s.length > 0 ? s : null;
+}
+
+/**
+ * Apply a FULL `.meta.json` string to the doc as its shared subset: parse, strip
+ * per-user/security keys, store the canonical shared JSON in a Y.Text. Returns
+ * false on parse error / over-cap / no change.
+ */
+export function applyMetaToDoc(doc: Y.Doc, fullMetaJson: string, origin?: unknown): boolean {
+  let obj: unknown;
+  try {
+    obj = parseJsonSafe(fullMetaJson);
+  } catch {
+    return false;
+  }
+  if (!obj || typeof obj !== 'object' || Array.isArray(obj)) return false;
+  const shared = sharedMetaCanonical(obj as Record<string, unknown>);
+  if (byteLengthUtf8(shared) > MAX_META_BYTES) {
+    console.warn(
+      `[sync/codec] refusing meta apply > ${MAX_META_BYTES} bytes (got ${byteLengthUtf8(shared)}). DDR-054 §2d.`
+    );
+    return false;
+  }
+  const t = doc.getText(Y_SYNC_TYPES.meta);
+  if (t.toString() === shared) return false;
+  doc.transact(() => {
+    if (t.length > 0) t.delete(0, t.length);
+    t.insert(0, shared);
+  }, origin);
+  return true;
+}
+
+/**
+ * Merge the synced shared-meta into a local `.meta.json` string, PRESERVING the
+ * local per-user/security keys (META_LOCAL_KEYS). Shared keys become exactly
+ * what the doc holds (so a deletion on the source propagates); the local keys
+ * are layered back on top. Returns the merged JSON (2-space, trailing newline)
+ * ready to write, or null when the shared payload is unparseable.
+ */
+export function mergeSharedMetaIntoLocal(
+  localMetaJson: string | null,
+  sharedJson: string
+): string | null {
+  let shared: unknown;
+  try {
+    shared = parseJsonSafe(sharedJson);
+  } catch {
+    return null;
+  }
+  if (!shared || typeof shared !== 'object' || Array.isArray(shared)) return null;
+  let local: Record<string, unknown> = {};
+  if (localMetaJson) {
+    try {
+      const parsed = parseJsonSafe(localMetaJson);
+      if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+        local = parsed as Record<string, unknown>;
+      }
+    } catch {
+      /* unparseable local meta — treat as empty; the shared subset becomes the base */
+    }
+  }
+  const merged: Record<string, unknown> = { ...(shared as Record<string, unknown>) };
+  for (const k of META_LOCAL_KEYS) {
+    if (k in local) merged[k] = local[k];
+  }
+  return `${JSON.stringify(merged, null, 2)}\n`;
+}
+
+/* ---------------------------------------------------------------- css */
+
+/** The synced canvas CSS string held in the doc, or null when unset/empty. */
+export function cssFromDoc(doc: Y.Doc): string | null {
+  const s = doc.getText(Y_SYNC_TYPES.css).toString();
+  return s.length > 0 ? s : null;
+}
+
+/**
+ * Apply the canvas's `.css` to the doc as opaque Y.Text (wholesale replace).
+ * CSS round-trips byte-identically (we write exactly the doc string back), so a
+ * wholesale delete+insert can't churn; the equality short-circuit keeps it quiet
+ * when unchanged. Returns false on over-cap / no change.
+ */
+export function applyCssToDoc(doc: Y.Doc, next: string, origin?: unknown): boolean {
+  if (byteLengthUtf8(next) > MAX_CSS_BYTES) {
+    console.warn(
+      `[sync/codec] refusing CSS apply > ${MAX_CSS_BYTES} bytes (got ${byteLengthUtf8(next)}). DDR-054 §2d.`
+    );
+    return false;
+  }
+  const t = doc.getText(Y_SYNC_TYPES.css);
+  if (t.toString() === next) return false;
+  doc.transact(() => {
+    if (t.length > 0) t.delete(0, t.length);
+    t.insert(0, next);
+  }, origin);
+  return true;
+}