@1agh/maude 0.58.2 → 0.59.0

package/apps/studio/test/video-encode-lib.test.ts

@@ -0,0 +1,63 @@
+// video-encode-lib — frame-clearing contract (feature-fast-video-export Task 6e).
+//
+// `addVideoFrame`/`addGifFrame` run INSIDE the capture Chromium (real
+// OffscreenCanvas + WebCodecs), so the actual pixel behavior needs a live
+// browser — not a `bun:test` concern, mirroring video-render-bridge.test.ts's
+// split between pure routing (tested here at the source level) and live
+// canvas/codec work (manual/agent-browser verification).
+//
+// What IS worth pinning: the DECISION itself. `drawImage` is called with no
+// preceding `clearRect`/`fillRect` reset, so a transparent frame draws OVER
+// whatever the encoder canvas already held — a transparent artboard would
+// ghost the previous frame's pixels through. This was flagged as a "decide
+// deliberately, don't let it drift" item rather than a bug: every capture
+// path today feeds `page.screenshot()` output, which Chromium always
+// composites onto an opaque background (no `omitBackground` capture exists in
+// this codebase), so the ghost case cannot currently occur in practice. If
+// that stops being true — a future capture path starts passing genuinely
+// transparent frames — this test must be touched, which is the point: an
+// accidental `clearRect` add/removal should force a conscious look at this
+// comment, not slip through unnoticed.
+
+import { describe, expect, test } from 'bun:test';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+const SRC = readFileSync(join(import.meta.dir, '..', 'exporters', 'video-encode-lib.ts'), 'utf8');
+
+function body(fnName: string): string {
+  const start = SRC.indexOf(`async ${fnName}(`);
+  const openBrace = SRC.indexOf('{', start);
+  // Cheap brace match — good enough for this file's flat function bodies.
+  let depth = 0;
+  let end = openBrace;
+  for (let i = openBrace; i < SRC.length; i += 1) {
+    if (SRC[i] === '{') depth += 1;
+    else if (SRC[i] === '}') {
+      depth -= 1;
+      if (depth === 0) {
+        end = i;
+        break;
+      }
+    }
+  }
+  return SRC.slice(start, end + 1);
+}
+
+describe('video-encode-lib — frame-clearing decision (pinned, not a bug)', () => {
+  test('addVideoFrame draws without clearing the encoder canvas first', () => {
+    const fn = body('addVideoFrame');
+    expect(fn).toMatch(
+      /ctx\.drawImage\(bmp, 0, 0, vstate\.canvas\.width, vstate\.canvas\.height\)/
+    );
+    expect(fn).not.toMatch(/clearRect|fillRect/);
+  });
+
+  test('addGifFrame draws without clearing the gif canvas first', () => {
+    const fn = body('addGifFrame');
+    expect(fn).toMatch(
+      /ctx\.drawImage\(bmp, 0, 0, gstate\.canvas\.width, gstate\.canvas\.height\)/
+    );
+    expect(fn).not.toMatch(/clearRect|fillRect/);
+  });
+});

package/apps/studio/test/workspace-containment.test.ts

@@ -233,6 +233,7 @@ describe('the vocabulary itself', () => {
       '/_api/debug-bundle',
       '/_api/design',
       '/_api/export',
+      '/_api/figma',
       '/_api/generate',
       '/_api/github',
       '/_api/hub',

package/apps/studio/use-artboard-drag.tsx

@@ -268,8 +268,16 @@ export interface UseArtboardDragOptions {
   rectFor: (id: string) => Rect | null;
   /** Every artboard's rect in render order. */
   allRects: Rect[];
-  /** Live viewport — `null` before first layout. */
+  /** Published viewport — `null` before first layout. Settle-cadence. */
   viewport: { zoom: number } | null;
+  /**
+   * Current zoom, read imperatively at event time. Supplied by the canvas so
+   * this hook never imports canvas-lib (which imports it — that would be a
+   * cycle). Load-bearing: `viewport` above only updates when a gesture settles,
+   * so a drag started inside the settle window would divide its deltas by the
+   * pre-gesture zoom and track the cursor at the wrong speed.
+   */
+  liveZoom?: () => number;
   /** False short-circuits all event handling (e.g. activeTool !== "move"). */
   enabled: boolean;
   /** Called on drop with final positions for leader + followers. */
@@ -293,6 +301,7 @@ export function useArtboardDrag(opts: UseArtboardDragOptions): UseArtboardDragHa
     rectFor,
     allRects,
     viewport,
+    liveZoom,
     enabled,
     onCommit,
     gridSize = DEFAULT_GRID_SIZE,
@@ -304,8 +313,28 @@ export function useArtboardDrag(opts: UseArtboardDragOptions): UseArtboardDragHa
   // Keep stable refs for callbacks that close over fast-changing inputs.
   const stateRef = useRef<DragState>(dragState);
   stateRef.current = dragState;
-  const zoomRef = useRef<number>(viewport?.zoom ?? 1);
-  zoomRef.current = viewport?.zoom ?? 1;
+  // The zoom a drag divides by must be the CURRENT one. `viewport` here is the
+  // published (settle-cadence) value, so mirroring it alone would leave this
+  // ref a gesture behind: pan, then grab an artboard within the settle window,
+  // and every delta would be divided by the pre-pan zoom — the board would
+  // track the cursor at the wrong speed. getLiveViewport() is the imperative
+  // mirror the viewport controller writes every frame; the prop is the fallback
+  // for mounts that have no controller (bare DS specimens).
+  // Stable identity across renders (useMemo, empty deps): recreating the object
+  // every render would make it look like a changing dependency to anything that
+  // closed over it. It reads through refs, so it never goes stale.
+  const liveZoomRef = useRef(liveZoom);
+  liveZoomRef.current = liveZoom;
+  const viewportRef = useRef(viewport);
+  viewportRef.current = viewport;
+  const zoomRef = useMemo(
+    () => ({
+      get current(): number {
+        return liveZoomRef.current?.() ?? viewportRef.current?.zoom ?? 1;
+      },
+    }),
+    []
+  );
   const onCommitRef = useRef(onCommit);
   onCommitRef.current = onCommit;
   const enabledRef = useRef(enabled);
@@ -392,6 +421,11 @@ export function useArtboardDrag(opts: UseArtboardDragOptions): UseArtboardDragHa
 
   // Global pointermove / pointerup while a drag is in flight. Bound at the
   // window level so a fast drag past any element still feeds the reducer.
+  //
+  // biome-ignore lint/correctness/useExhaustiveDependencies: `zoomRef` is a live
+  // getter (stable identity, reads through refs), not state — the handlers must
+  // read the CURRENT zoom at event time. Listing it would re-subscribe these
+  // listeners whenever zoom changed, tearing the pointer stream down mid-drag.
   useEffect(() => {
     if (dragState.kind === 'idle') return;
     if (typeof window === 'undefined') return;

package/apps/studio/video-comp.tsx

@@ -41,6 +41,16 @@ export interface VideoCompMeta {
 /** A live registration — the Player handle + its meta, keyed by artboard id. */
 interface CompEntry extends VideoCompMeta {
   id: string;
+  /** The enclosing DCArtboard's id (`data-dc-screen`), resolved by DOM
+   *  containment at mount. The VideoComp's own `compId` is usually an
+   *  author-omitted `videocomp-N` mount slug, so this is the ONLY reliable way
+   *  for the shell to map "the artboard the user is looking at" → "the comp the
+   *  transport must drive" (rca/issue-timeline-drives-wrong-artboard). Null on a
+   *  comp mounted outside an artboard (bare preview / test harness). */
+  artboardId: string | null;
+  /** The artboard's visible label — shown in the Timeline head so the user can
+   *  see WHICH artboard the rows + transport belong to. */
+  artboardLabel: string | null;
   ref: React.RefObject<PlayerRef | null>;
   /** The Remotion composition component + its props — carried so the export
    *  capture's renderMediaOnWeb path (DDR-148 addendum, audio export) can
@@ -55,6 +65,9 @@ interface CompEntry extends VideoCompMeta {
 /** Serializable meta the capture shim + Timeline panel read (no functions). */
 export interface CompSnapshot extends VideoCompMeta {
   id: string;
+  /** Enclosing DCArtboard id + label — see CompEntry. */
+  artboardId: string | null;
+  artboardLabel: string | null;
 }
 
 /** Result contract for `__maude_render_video__` — see exporters/video-render-lib.ts. */
@@ -81,7 +94,20 @@ interface MaudeSeekWindow {
   __maudeVideoComps?: Map<string, CompEntry>;
   /** Seek every registered comp to `frame` (paused). Ordinary artboards fall
    *  back to a time-based WAAPI seek. Resolves once the frame has painted. */
-  __maude_seek__?: (frame: number, opts?: { fps?: number }) => Promise<void>;
+  __maude_seek__?: (
+    frame: number,
+    opts?: {
+      fps?: number;
+      /** Capture mode: throw when a seek never lands, instead of only counting it. */
+      strict?: boolean;
+    }
+  ) => Promise<void>;
+  /**
+   * Count of seeks that never landed. The capture shim reads this and refuses
+   * to ship the export rather than encoding a stale frame — a silent wrong
+   * frame is worse than a loud failure.
+   */
+  __maude_seek_failures__?: number;
   /** Serializable comp list for the capture shim / Timeline panel. */
   __maude_comps__?: () => CompSnapshot[];
   /**
@@ -140,6 +166,36 @@ function afterPaint(): Promise<void> {
   });
 }
 
+/** How many paint-spaced attempts a cold Player gets before a seek is a failure. */
+const SEEK_ATTEMPTS = 3;
+
+/**
+ * Seek one comp, giving a not-yet-mounted Player a bounded number of chances.
+ *
+ * Returns whether the seek actually landed. The retry replaces the old silent
+ * swallow: a Player that is genuinely mid-mount settles within a paint or two,
+ * and one that never settles is a real fault the caller must not paper over.
+ */
+async function seekEntryWithRetry(
+  ref: { current: { pause?: () => void; seekTo: (f: number) => void } | null },
+  frame: number
+): Promise<boolean> {
+  for (let attempt = 0; attempt < SEEK_ATTEMPTS; attempt += 1) {
+    try {
+      const player = ref.current;
+      if (player) {
+        player.pause?.();
+        player.seekTo(frame);
+        return true;
+      }
+    } catch {
+      /* fall through to the retry — the next paint may settle it */
+    }
+    if (attempt < SEEK_ATTEMPTS - 1) await afterPaint();
+  }
+  return false;
+}
+
 /**
  * Install the singleton seek bridge on `window`. Idempotent — the first
  * VideoComp to mount wins; later mounts reuse the same functions. The bridge
@@ -156,11 +212,32 @@ export function installMaudeSeekBridge(): void {
     if (entries.length > 0) {
       for (const e of entries) {
         const f = clamp(Math.round(frame), 0, Math.max(0, e.durationInFrames - 1));
-        try {
-          e.ref.current?.pause();
-          e.ref.current?.seekTo(f);
-        } catch {
-          /* Player not yet ready — a later seek settles it */
+        // This used to be a bare try/catch with an empty body and the comment
+        // "Player not yet ready — a later seek settles it". That made a seek
+        // that COMPLETELY FAILED resolve as success: `afterPaint()` proves a
+        // paint happened, not that the right content was in it. Serially it was
+        // benign — frame N+1 repaired frame N's miss, and only frame 0 was ever
+        // exposed — which is exactly why it survived. It is not benign the
+        // moment anything captures ranges in parallel: every range boundary is a
+        // first seek on a cold page, so "a later seek settles it" would be
+        // invoked once per worker instead of once per export, and a stale frame
+        // is a valid-looking file with wrong pixels, not a crash.
+        //
+        // So the hope becomes an explicit bounded retry, and exhausting it is a
+        // real failure the capture shim can see and refuse to ship.
+        if (!(await seekEntryWithRetry(e.ref, f))) {
+          // ALWAYS recorded, so the capture shim can refuse the export even on
+          // the non-strict path. Only THROWN under `strict`, which the shim
+          // passes: a live UI scrub of a still-mounting comp should stay
+          // resilient, but a capture must never proceed on a seek that did not
+          // happen. The old code did neither — it just resolved.
+          w.__maude_seek_failures__ = (w.__maude_seek_failures__ ?? 0) + 1;
+          if (opts?.strict) {
+            throw new Error(
+              `__maude_seek__: comp did not accept frame ${f} after ${SEEK_ATTEMPTS} attempts ` +
+                '(Player never became ready) — refusing to report a seek that did not happen'
+            );
+          }
         }
       }
       await afterPaint();
@@ -191,6 +268,8 @@ export function installMaudeSeekBridge(): void {
       durationInFrames: e.durationInFrames,
       width: e.width,
       height: e.height,
+      artboardId: e.artboardId ?? null,
+      artboardLabel: e.artboardLabel ?? null,
     }));
 
   w.__maude_render_video__ = async (compId, opts) => {
@@ -224,6 +303,35 @@ export function findCompIdIn(container: Element): string | null {
   return container.querySelector('[data-comp-id]')?.getAttribute('data-comp-id') ?? null;
 }
 
+/** The inverse of `findCompIdIn` — walk UP from a mounted comp to the artboard
+ *  that contains it, and read its id + visible label. Same rationale (the two
+ *  ids are independent), used at registration time so every announced comp
+ *  carries the artboard the user actually sees it on. */
+export function findArtboardOf(el: Element | null): {
+  artboardId: string | null;
+  artboardLabel: string | null;
+} {
+  const board = el?.closest?.('[data-dc-screen]') ?? null;
+  if (!board) return { artboardId: null, artboardLabel: null };
+  // DIRECT children only, and only the two tags canvas-lib actually renders the
+  // label as (`<header>` unpositioned / `<button>` positioned). A subtree-wide
+  // `querySelector('.dc-artboard-label')` would take the first match in document
+  // order anywhere below the artboard — including a hidden node planted ahead of
+  // the real header, or one belonging to a nested artboard — and `textContent`
+  // reads hidden nodes happily. The label is shell chrome the user reads to know
+  // which artboard the transport moves, so it must come from the element
+  // canvas-lib owns, not from whatever matches the class first.
+  const header = Array.from(board.children).find(
+    (c) =>
+      (c.tagName === 'HEADER' || c.tagName === 'BUTTON') &&
+      c.classList.contains('dc-artboard-label')
+  );
+  return {
+    artboardId: board.getAttribute('data-dc-screen'),
+    artboardLabel: header?.textContent?.trim() || null,
+  };
+}
+
 // ─────────────────────────────────────────────────────────────────────────────
 // VideoComp — the canvas-lib wrapper
 
@@ -297,6 +405,7 @@ export function VideoComp({
   autoPlay,
 }: VideoCompProps) {
   const ref = useRef<PlayerRef | null>(null);
+  const hostRef = useRef<HTMLDivElement | null>(null);
   // Stable id across re-renders; unique per mount when the author omits one.
   const [autoId] = useState(() => id ?? `videocomp-${++mountCounter}`);
   const compId = id ?? autoId;
@@ -326,8 +435,13 @@ export function VideoComp({
   // Register with the seek bridge for the lifetime of this mount.
   useEffect(() => {
     installMaudeSeekBridge();
+    // Resolved here (not at render) because the wrapper is only in the DOM once
+    // the effect runs — that's also when the enclosing DCArtboard exists.
+    const { artboardId, artboardLabel } = findArtboardOf(hostRef.current);
     const entry: CompEntry = {
       id: compId,
+      artboardId,
+      artboardLabel,
       fps,
       durationInFrames,
       width,
@@ -443,6 +557,7 @@ export function VideoComp({
   return (
     <div
       className="dc-video-comp"
+      ref={hostRef}
       data-comp-id={compId}
       style={{ width, height, maxWidth: '100%' }}
     >

package/apps/studio/whats-new.json

@@ -1,6 +1,104 @@
 {
   "$schema": "./whats-new.schema.json",
   "entries": [
+    {
+      "id": "cloud-asset-push-completes",
+      "version": "0.59.0",
+      "date": "2026-08-12",
+      "kind": "fix",
+      "title": "Every asset reaches the cloud, in one go",
+      "summary": "A project with a lot of images, fonts and video used to trickle a handful of files to the cloud per boot and never catch up. Now the whole set uploads in one pass, and a file the hub refuses is named with the real reason instead of a bare error code.",
+      "surface": "design-ui"
+    },
+    {
+      "id": "figma-explode-artboard",
+      "version": "0.59.0",
+      "date": "2026-08-12",
+      "kind": "feature",
+      "title": "Make an imported Figma artboard editable",
+      "summary": "A Figma page imports as faithful pictures of your frames. Now you can pick one artboard and turn it into real, editable layout — Maude asks Figma's own Dev Mode for that frame's resolved design and converts it locally, so you get flex boxes and live text instead of an image. Needs the Figma desktop app open on the same file, with Dev Mode on.",
+      "surface": "design-ui"
+    },
+    {
+      "id": "figma-import-fidelity-fixes",
+      "version": "0.59.0",
+      "date": "2026-08-12",
+      "kind": "fix",
+      "title": "Figma imports keep their fonts and their board",
+      "summary": "Three things a real migration surfaced: text in imported frames fell back to a serif when the font wasn't installed, an imported FigJam board landed dark inside screen chrome instead of on white paper, and a slow render check could quietly drop every image in a large import. Imported files now look like the ones you imported.",
+      "surface": "design-ui"
+    },
+    {
+      "id": "canvas-perf-benchmark",
+      "version": "0.59.0",
+      "date": "2026-08-12",
+      "kind": "improvement",
+      "title": "Measure a canvas's pan/zoom performance",
+      "summary": "A new `maude design perf` command drives a scripted pan and zoom over a canvas and reports frame timings plus how much React work the gesture caused — with a delta against your previous run, so a change is either faster or it isn't. It can measure Chrome or Safari (WebKit, the engine the desktop app uses), and `/design:smoke --perf` folds it into a smoke sweep. Under the hood, pan and zoom no longer re-render the canvas tree while you're moving: on a 128-artboard canvas that removed about 90% of the renders a gesture used to trigger.",
+      "surface": "design-ui"
+    },
+    {
+      "id": "video-export-degraded-visible",
+      "version": "0.59.0",
+      "date": "2026-08-12",
+      "kind": "fix",
+      "title": "A video export tells you when it's missing audio",
+      "summary": "If an MP4/WebM export can't get audio — an unsupported media element, or the fast renderer had to fall back to a frame-by-frame capture — the export no longer quietly reports \"done\" with a clean checkmark. The Exports panel now shows a degraded pill and a completion toast explaining exactly what was dropped and how to fix it, and it's recorded in your export history too.",
+      "surface": "design-ui"
+    },
+    {
+      "id": "sync-panel-per-file",
+      "version": "0.59.0",
+      "date": "2026-08-12",
+      "kind": "feature",
+      "title": "Watch your project sync, file by file",
+      "summary": "Click the hub sync chip in the status bar to open the new Sync panel: every canvas with its own live state (syncing, synced, or refused and why), plus your images and fonts as they upload to the cloud. “Is my work actually up there?” now has a per-file answer.",
+      "surface": "design-ui",
+      "tour": [
+        {
+          "target": "[data-testid=\"open-sync\"]",
+          "title": "Per-file sync progress",
+          "body": "The hub sync chip is now a button — click it to see every canvas and asset move to the cloud, and which ones need attention.",
+          "placement": "top"
+        }
+      ]
+    },
+    {
+      "id": "cloud-brand-assets-and-steady-link",
+      "version": "0.59.0",
+      "date": "2026-08-12",
+      "kind": "fix",
+      "title": "Brand logos load in the cloud (and a steadier status bar)",
+      "summary": "Your design system's own logos, signs, fonts and photos now show up in the cloud copy instead of grey placeholders — the last piece of \"the cloud copy matches your desktop\". And the desktop status bar no longer flickers to \"reconnecting\" when you step away for a minute; an idle link stays live.",
+      "surface": "design-ui"
+    },
+    {
+      "id": "cloud-sync-matches-your-desktop",
+      "version": "0.58.3",
+      "date": "2026-08-11",
+      "kind": "fix",
+      "title": "The cloud copy matches your desktop",
+      "summary": "A project you connect to the cloud now looks exactly like it does on your machine: no duplicated files, every canvas opens instead of breaking, and your images show up instead of grey boxes. The cloud picker says \"Connected\" for the project this folder is linked to, with a Disconnect right there — and once you're connected, the cloud saves every change automatically, so there's one place your work is saved, not two.",
+      "surface": "design-ui"
+    },
+    {
+      "id": "cloud-link-self-renews",
+      "version": "0.58.3",
+      "date": "2026-08-11",
+      "kind": "fix",
+      "title": "Cloud sync keeps itself signed in",
+      "summary": "A workspace you connect to the cloud stays synced — the session refreshes itself in the background instead of quietly expiring after a few hours and stranding your canvases on \"connecting…\". If a link ever can't sync for a few minutes it now says so and points you to reconnect, instead of spinning forever.",
+      "surface": "design-ui"
+    },
+    {
+      "id": "figma-import",
+      "version": "0.58.3",
+      "date": "2026-08-11",
+      "kind": "feature",
+      "title": "Bring your Figma work in",
+      "summary": "Paste a Figma link and get the real thing, not a picture of it: design frames become editable canvases, a FigJam board becomes your whiteboard with its sticky notes and arrows still attached, and your colour and text styles become design tokens. Add a Figma access token once in Settings to get started.",
+      "surface": "design-ui"
+    },
     {
       "id": "sync-carries-the-path",
       "version": "0.58.2",

package/apps/studio/workspace-mode.ts

@@ -66,6 +66,10 @@ export const FORBIDDEN_ROUTE_PREFIXES: ReadonlyArray<{ prefix: string; why: stri
       prefix: '/_api/generate',
       why: 'media generation runs tenant-authored prompts against a provider key held here',
     },
+    {
+      prefix: '/_api/figma',
+      why: 'the Figma lane STORES and SPENDS a user personal access token, and imports write the design root — a cell must hold no provider credential (DDR-216 D2/D3, same class as /_api/generate)',
+    },
     {
       prefix: '/_api/shell-shot',
       why: 'the shell screenshot spawns a headless browser against the studio — the same evaluation `/_api/export` is forbidden for',

package/cli/commands/design.mjs

@@ -69,6 +69,14 @@ const BIN_VERBS = new Set([
   // contract, and patches (theme-block-scoped) or scaffolds the target
   // design system. CLI-only — no HTTP route, no in-app panel.
   'import-tokens',
+  // DDR-216 (feature-figma-import, Phase 2 / T6). `import-figma` is the REST
+  // door: pulls a real Figma/FigJam document over the API and translates it
+  // with DETERMINISTIC code — no vision model, no agent anywhere in the
+  // ingestion path. That is the structural difference from
+  // `/design:import --reconstruct` (DDR-174), whose whole orchestrator/agent
+  // split exists because an LLM reads its input; do not copy that architecture
+  // into this one, it would close nothing here.
+  'import-figma',
   // DDR-173 (Phase 3 / T12). `import-brand` extracts typed palette/font
   // cues + a hardened logo asset from an already-DDR-167-sanitized SVG for
   // `/design:setup-ds --from-brand` — never re-reads or re-sanitizes the
@@ -118,6 +126,13 @@ const BIN_VERBS = new Set([
   // host — see DDR-185's rejected alternatives). No dev server dependency —
   // pure Node, no `<designRoot>` involvement.
   'curl-local',
+  // feature-canvas-render-performance (Task 1 + 11). `perf` drives a scripted
+  // pan/zoom against a live canvas and reports frame-time percentiles plus the
+  // React render count during the gesture, delta'd against the previous run of
+  // the same (canvas, engine) pair. It is a benchmark a human reads, never a CI
+  // gate — headless frame timings swing with GPU load, so an absolute threshold
+  // would go red for reasons unrelated to the code.
+  'perf',
   // DDR-185 security addendum. `agent-browser-safe` replaces the bare
   // `Bash(agent-browser:*)` allow-list entry a security review found was a
   // zero-confirmation session-hijack primitive (agent-browser's own bundled

package/cli/commands/kg.mjs

@@ -406,7 +406,14 @@ async function verbRecordLog(state, args, pkgRoot) {
   // Temp file + `kg ingest --file`, matching the importer: the same plumbing
   // that ingested 310 decisions during migration, so no new stdin path to get
   // wrong (and a verdict body is far past comfortable argv size anyway).
-  const tmp = join(tmpdir(), `kg-record-${kind}-${built.slug}.json`);
+  // `built.slug` is `${scope.repo}/<slug>` under this store's per-repo
+  // namespacing convention (scopedSlug) — a bare join() with that slash reads
+  // as an implied subdirectory `writeFileSync` never creates, so every call
+  // in a repo-namespaced store failed ENOENT before it ever reached `kg
+  // ingest`. This is a filesystem staging path, not the graph identity, so
+  // sanitizing it here doesn't touch what actually gets recorded.
+  const tmpSlug = built.slug.replace(/\//g, '_');
+  const tmp = join(tmpdir(), `kg-record-${kind}-${tmpSlug}.json`);
   writeFileSync(tmp, JSON.stringify({ decisions: [built.decision] }));
   const status = runKg(state, ['ingest', '--file', tmp], {
     timeoutMs: 30000,

package/cli/commands/kg.test.mjs

@@ -116,3 +116,27 @@ test('passthrough strips the maude-owned --root flag from the kg argv', () => {
   assert.match(r.stdout, /ARGV:context --about x/);
   assert.doesNotMatch(r.stdout, /--root/);
 });
+
+test('record-log succeeds when the scoped slug contains a slash (repo-namespaced store)', () => {
+  // scopedSlug() prefixes the log's slug with `${scope.repo}/` under this
+  // store's per-repo namespacing convention, so `built.slug` is e.g.
+  // "acme/foo" — a temp filename built by bare string interpolation reads
+  // that slash as an implied subdirectory writeFileSync never creates, and
+  // every record-log call in a repo-namespaced store failed ENOENT before it
+  // ever reached `kg ingest`.
+  const root = repoWith({ mode: 'on', scope: { repo: 'acme', dept: 'dev' } });
+  const logDir = join(root, '.ai', 'logs', 'rca');
+  mkdirSync(logDir, { recursive: true });
+  writeFileSync(join(logDir, 'foo.md'), '# RCA: something broke\n\nbody text\n');
+  const stub = join(root, 'kg-stub.sh');
+  writeFileSync(stub, '#!/usr/bin/env bash\nexit 0\n');
+  spawnSync('chmod', ['+x', stub]);
+  const r = spawnSync(
+    'node',
+    [MAUDE_BIN, 'kg', 'record-log', '--file', '.ai/logs/rca/foo.md', '--root', root],
+    { cwd: root, encoding: 'utf8', env: { ...process.env, NO_COLOR: '1', KGAI_BIN: stub } }
+  );
+  assert.equal(r.status ?? 0, 0, r.stderr);
+  assert.doesNotMatch(r.stderr, /ENOENT/);
+  assert.match(r.stdout, /\[kg\] recorded rca:acme\/foo/);
+});

package/cli/lib/figma-codegen-reachability.test.mjs

@@ -0,0 +1,104 @@
+// DDR-219 D2 regression guard — the codegen channel is a CONTROL, not an intent.
+//
+// The first draft of DDR-219 routed Figma Dev Mode codegen through the REMOTE
+// MCP (`https://mcp.figma.com/mcp`) and treated our own code's inability to
+// reach it as the safety property. The design-stage review took that apart:
+//
+//   - the remote catalog "allowlist" is enforced on a self-reported OAuth
+//     `client_name`, and a public bypass for it exists — so it is a waitlist,
+//     not a boundary;
+//   - the LOCAL Dev Mode server (`http://127.0.0.1:3845/mcp`) takes plain
+//     loopback HTTP with NO credential and no catalog gate at all, so nothing
+//     but intent stands between a future contributor and `fetch(...)` inside
+//     `apps/studio/figma/`;
+//   - DDR-185's `curl-local` *permits* that endpoint by construction (its rule
+//     is "every resolved address is loopback", and 127.0.0.1 is), and an ACP
+//     session auto-approves `Bash(maude:*)` — so the one egress control the
+//     session trusts is, for this specific service, an allow rule.
+//
+// Reaching the remote endpoint from product code would put a third-party model's
+// output into an ingestion path that DDR-216 D1 says is deterministic end to
+// end. Reaching the local one from anywhere except the single designated client
+// would make codegen a bulk ingestion route by accident — DDR-219 D1's table
+// silently false, its fallback never firing, and nothing in CI noticing.
+//
+// So both halves are asserted here rather than described in a decision record.
+
+import assert from 'node:assert/strict';
+import { execSync } from 'node:child_process';
+import { test } from 'node:test';
+
+/** The ONE module allowed to name the local Dev Mode endpoint (DDR-219 D2). */
+const CODEGEN_CLIENT = 'apps/studio/figma/codegen-client.ts';
+
+/**
+ * Tests under the Figma lane may name it too, and the widening is narrow on
+ * purpose. `codegen-client.test.ts` asserts the endpoint constant — that IS the
+ * control ("the URL is never influenced by input"), and a guard that forbids
+ * asserting the thing it guards would push the assertion out of the repo.
+ * `from-codegen.test.ts` carries a captured response fixture whose asset
+ * constants are loopback URLs, and the property under test is that the converter
+ * DISCARDS them — which can only be asserted against a fixture that has them.
+ *
+ * Neither executes anything against the port. What stays absolutely banned is a
+ * second non-test module reaching it, which is the shape that would make codegen
+ * a bulk ingestion route by accident.
+ */
+const TEST_FILE_RE = /^apps\/studio\/figma\/[a-z-]+\.test\.ts$/;
+
+/** Trees that ship or execute. Prose (`.ai/`, `docs/`, `site/`) may name both. */
+const RUNTIME_TREES = ['apps/studio', 'cli', 'plugins'];
+
+/** Source only. `node_modules` vendors binaries that contain arbitrary strings
+ *  (the bundled agent-sdk `claude` matched `mcp.figma.com` on the first run),
+ *  and `dist/` is build output, not a code path anyone edits. `-I` drops binary
+ *  files outright so a vendored blob can never turn this guard into noise —
+ *  a guard that cries wolf gets deleted, which would be worse than not having it. */
+function grep(pattern, trees) {
+  // `|| true` because grep exits 1 on no-match, which is the passing case.
+  const out = execSync(
+    `grep -rlIE --exclude-dir=node_modules --exclude-dir=dist --exclude-dir=.git ${JSON.stringify(pattern)} ${trees.join(' ')} 2>/dev/null || true`,
+    { encoding: 'utf8', cwd: new URL('../../', import.meta.url).pathname }
+  );
+  return out
+    .trim()
+    .split('\n')
+    .filter(Boolean)
+    .filter((f) => !f.endsWith('figma-codegen-reachability.test.mjs'));
+}
+
+test('no runtime code names the REMOTE Figma MCP endpoint', () => {
+  const offenders = grep('mcp\\.figma\\.com', RUNTIME_TREES);
+  assert.deepEqual(
+    offenders,
+    [],
+    `These files name the remote Figma MCP endpoint. It is banned from every runtime code path (DDR-219 D2, and \`feature-figma-import\` § Out of scope before it): it is reachable only by a catalog-listed agent client, so any use here means a model is in the ingestion path. Codegen goes over the LOCAL server, with apps/studio as the client:\n  ${offenders.join('\n  ')}`
+  );
+});
+
+test('only the designated client names the LOCAL Dev Mode endpoint', () => {
+  // Match the endpoint shape, not a bare `3845`, which could legitimately occur
+  // as a byte count or a hash fragment.
+  const offenders = grep('(localhost|127\\.0\\.0\\.1|:)3845', RUNTIME_TREES).filter(
+    (f) => f !== CODEGEN_CLIENT && !TEST_FILE_RE.test(f)
+  );
+  assert.deepEqual(
+    offenders,
+    [],
+    `Only ${CODEGEN_CLIENT} may reach the local Figma Dev Mode MCP server (DDR-219 D2). A second caller makes codegen an ingestion route by accident — and the local server is UNAUTHENTICATED loopback, so there is no credential step to notice it. If codegen is genuinely needed elsewhere, route it through the client:\n  ${offenders.join('\n  ')}`
+  );
+});
+
+test('no canvas-reachable codegen route exists', () => {
+  // A canvas-origin codegen route would hand the untrusted iframe (DDR-054) a
+  // primitive that reads the user's open Figma document. It belongs in NEITHER
+  // allowlist — the same standing rule DDR-088 sets for every privileged route.
+  const offenders = grep('CANVAS_SAFE_API[^\\n]*codegen|codegen[^\\n]*CANVAS_SAFE_API', [
+    'apps/studio',
+  ]);
+  assert.deepEqual(
+    offenders,
+    [],
+    `A codegen route appears near CANVAS_SAFE_API. Codegen is privileged-origin only (DDR-219 D2):\n  ${offenders.join('\n  ')}`
+  );
+});