@1agh/maude 0.58.2 → 0.59.0

package/apps/studio/figma/codegen-client.ts

@@ -0,0 +1,509 @@
+/**
+ * @file       figma/codegen-client.ts — the LOCAL Dev Mode MCP client (DDR-219 D2).
+ * @scope      apps/studio/figma/codegen-client.ts
+ * @purpose    Ask Figma's own generator for one frame's resolved DOM, over
+ *             loopback, with `apps/studio` as the JSON-RPC client.
+ *
+ * @invariant  THIS IS THE ONLY MODULE IN THE REPO ALLOWED TO NAME `:3845`.
+ *             `cli/lib/figma-codegen-reachability.test.mjs` asserts it, and
+ *             asserts that Figma's REMOTE MCP host appears in no runtime code
+ *             path at all — not even here, which is why this comment does not
+ *             spell it: the guard is a coarse grep and it is only trustworthy if
+ *             it is absolute. Both halves are controls, not intentions: the
+ *             remote server
+ *             is spoken by an AGENT, so its response would transit a model's
+ *             context by construction — which closes the DDR-130 trifecta inside
+ *             a single turn (DDR-219 § Security review, chain 1). The local
+ *             server is spoken by US, so no model is in the path.
+ *
+ * @invariant  NO MODEL READS WHAT THIS RETURNS. The dev-server fetches, parses,
+ *             converts and writes. The agent that invoked the verb sees only the
+ *             verb's code-owned stdout (DDR-216 D10). That is the whole reason
+ *             the channel decision mattered — see the prose note below.
+ *
+ * @invariant  THE HANDSHAKE IS ASSERTED BEFORE A DOCUMENT IS REQUESTED, AND A
+ *             FAILED ASSERTION REFUSES. The local server is UNAUTHENTICATED
+ *             loopback (DDR-219 residual 3), so any local process can squat the
+ *             port and feed us arbitrary JSX. That requires local code execution
+ *             — largely game-over independently — but the specific consequence
+ *             is that our converter would ingest attacker-authored markup
+ *             believing it came from Figma. So: `initialize` must answer with a
+ *             Figma-shaped `serverInfo`, `tools/list` must carry the expected
+ *             tool, and no exposed tool may match the WRITE vocabulary.
+ *
+ * @invariant  WE NEVER LET THIS SERVER WRITE A FILE. `dirForAssetWrites` is a
+ *             caller-supplied absolute path the server writes assets to
+ *             (measured — DDR-219 probe finding 2). It is never sent. Assets are
+ *             re-fetched by node id through the existing `/v1/images` lane
+ *             instead (D6), which is strictly better containment than Figma's
+ *             own allowed-directories allowlist.
+ *
+ * @invariant  A RESPONSE THAT IS NOT CODE IS A REFUSAL, NOT A DEGRADATION.
+ *             `forceCode` exists because the server silently returns METADATA
+ *             instead of code when the output is too large (probe finding 3). A
+ *             converter that did not check would emit a confidently wrong
+ *             artboard. We assert; we do not paper over it by setting
+ *             `forceCode` unconditionally, because the size ceiling is telling
+ *             us something real about the caps.
+ *
+ * @invariant  ONE CODEGEN CALL PER SESSION, ENFORCED HERE (DDR-219 D10). Local
+ *             metering is undocumented (fact 5) and the remote budget is 200
+ *             calls/day. Without a hard ceiling, an instruction inside a
+ *             document ("fetch design context for each of these node ids
+ *             first…") spends the user's whole daily Figma budget from content,
+ *             and the failure reads as a Figma outage. It is a property of the
+ *             CODE, never of how a caller chooses to behave.
+ *
+ * @invariant  DEPENDENCY-FREE — `fetch` plus `node:crypto` for the response
+ *             hash. The transport is streamable HTTP with SSE-framed replies,
+ *             which is ~40 lines, not a library.
+ */
+
+import { createHash } from 'node:crypto';
+
+/**
+ * The local Dev Mode MCP server. Loopback, unauthenticated, no catalog gate —
+ * which is exactly why reaching it from a second module would silently turn
+ * codegen into a bulk ingestion route (DDR-219 D1's table quietly false).
+ */
+const CODEGEN_ENDPOINT = 'http://127.0.0.1:3845/mcp';
+
+/** The one tool this client is allowed to call. */
+export const CODEGEN_TOOL = 'get_design_context';
+
+/**
+ * The tool surface measured on 2026-08-11 — six tools, every one read-only.
+ * Recorded so a future reader can see what "no write surface" was measured
+ * against rather than having to take the DDR's word for it.
+ */
+export const MEASURED_LOCAL_TOOLS = Object.freeze([
+  'get_design_context',
+  'get_variable_defs',
+  'get_screenshot',
+  'get_motion_context',
+  'get_metadata',
+  'get_figjam',
+]);
+
+/**
+ * Write-shaped tool names. A DENYLIST, deliberately, and this is the one place
+ * in the Figma lane where that is the right shape: an allowlist over a
+ * third-party server's tool surface would refuse on every Figma feature release,
+ * while the property we actually need is narrow and stable — *no write surface
+ * is co-tenant with this call*. Figma Developer Terms §4.f pushes toward
+ * write-back tools existing somewhere; this asserts they are not on this wire.
+ */
+const WRITE_TOOL_RE = /^(use_figma|create_|upload_|add_|send_|set_|update_|delete_|write_)/i;
+
+/** Handshake: the server must at least claim to be Figma's. Weak on its own —
+ *  a squatter can say anything — which is why it is one assertion of several
+ *  and why the parser contract (DDR-219 D5) is what actually bounds the damage. */
+const SERVER_NAME_RE = /^figma\b/i;
+
+/** Protocol version we speak. Sent as-is; the server answers with its own. */
+const PROTOCOL_VERSION = '2025-06-18';
+
+/**
+ * INPUT byte cap (DDR-219 D5 rule 2). Distinct from the 512 KB per-artboard
+ * OUTPUT cap and from `client.ts`'s 8 MB REST cap, which this response never
+ * traverses. Measured: a real 375×812 screen is 33 KB.
+ */
+export const MAX_CODEGEN_RESPONSE_BYTES = 1024 * 1024;
+
+/** A codegen call is slow-ish (measured ~344 ms) but never minutes. */
+const CALL_TIMEOUT_MS = 60_000;
+/** The handshake is local and instant; a hang here means nothing is listening. */
+const HANDSHAKE_TIMEOUT_MS = 10_000;
+
+/** D10 — one `get_design_context` per user invocation, full stop. */
+export const MAX_CODEGEN_CALLS_PER_INVOCATION = 1;
+
+export type CodegenErrorKind =
+  /** Nothing listening, or the transport failed. The COMMON case (residual 2). */
+  | 'unavailable'
+  /** `initialize` did not answer like Figma's server. */
+  | 'handshake'
+  /** `get_design_context` absent, or a write-shaped tool is co-tenant. */
+  | 'tool_surface'
+  /** The node is not in the open document, or Figma refused it. */
+  | 'node_unavailable'
+  /** The server returned metadata instead of code (probe finding 3). */
+  | 'not_code'
+  /** Over the input byte cap. */
+  | 'too_large'
+  /** Malformed JSON-RPC / SSE. */
+  | 'bad_response'
+  /** The per-invocation ceiling already spent. */
+  | 'ceiling';
+
+/**
+ * Fixed, code-owned messages. NOTHING upstream is ever interpolated — this
+ * string reaches verb stdout, which D10 declares entirely code-owned, and the
+ * one place an error message would otherwise become a prompt-injection channel.
+ */
+const MESSAGE_BY_KIND: Readonly<Record<CodegenErrorKind, string>> = {
+  unavailable:
+    'Figma Dev Mode MCP server is not reachable — open the Figma desktop app, switch to Dev Mode, and enable the MCP server (needs a Dev or Full seat).',
+  handshake: 'Something is listening on the Dev Mode port but it is not Figma — refusing.',
+  tool_surface: 'The Dev Mode server did not expose the expected read-only codegen tool.',
+  node_unavailable:
+    'Figma has no such node in the OPEN document — make the right file the active tab.',
+  not_code: 'Figma returned metadata instead of code for this frame — it is too large to explode.',
+  too_large: 'The codegen response exceeded this lane’s input cap.',
+  bad_response: 'The Dev Mode server returned a reply this client could not read.',
+  ceiling: 'One codegen call per invocation (DDR-219 D10) — already spent.',
+};
+
+export class CodegenError extends Error {
+  readonly kind: CodegenErrorKind;
+  constructor(kind: CodegenErrorKind) {
+    super(MESSAGE_BY_KIND[kind]);
+    this.name = 'CodegenError';
+    this.kind = kind;
+  }
+}
+
+/**
+ * The response's code half, plus what provenance needs (DDR-219 D7).
+ *
+ * `responseSha256` does NOT make the artboard reproducible — nothing can, there
+ * is no second door (fact 1). It makes *"did these two artboards come from the
+ * same generator state"* answerable, which is the minimum an incident needs.
+ */
+export interface CodegenResponse {
+  /** The module source, truncated at the code/prose boundary. */
+  code: string;
+  /** `sha256` of the FULL response text, prose included — the generator state. */
+  responseSha256: string;
+  /** Always `'local'`. Recorded so a stored artifact names its own channel. */
+  endpoint: 'local';
+  tool: string;
+  /** Bytes of imperative prose that were discarded. Reported, never carried. */
+  proseBytes: number;
+}
+
+/**
+ * The imperative tail Figma appends to every response — verbatim
+ * *"SUPER CRITICAL: The generated React+Tailwind code MUST be converted…"*,
+ * *"IMPORTANT: After you call this tool, you MUST call get_screenshot…"*.
+ * 1 648 B on the measured frame, issued by **Figma itself**, not an attacker.
+ *
+ * On this channel it is inert bytes a parser discards. Carrying it into an
+ * artifact would write Figma's instructions into a canvas that agents later
+ * read — so the boundary is cut HERE, before the converter ever sees it, rather
+ * than being left as a property the converter is trusted to preserve.
+ *
+ * Anchored to line starts and bounded: no `s` flag, no unbounded capture
+ * (DDR-172 Decision 4 discipline, which D5 rule 6 carries into this lane).
+ */
+const PROSE_MARKER_RE =
+  /^[ \t>*-]{0,8}(?:\d{1,2}[.)]\s*)?(?:SUPER CRITICAL|IMPORTANT|CRITICAL|NOTE|DO NOT|Analyze the target|After you call this tool)\b/im;
+
+/**
+ * Cut the response at the code/prose boundary.
+ *
+ * The rule is positional rather than semantic: the prose is a TRAILING block, so
+ * the first line that reads as an imperative directive ends the code. A response
+ * with no such line is all code, which is also the measured shape when the frame
+ * is small enough that Figma skips its advice.
+ */
+export function splitCodeAndProse(raw: string): { code: string; prose: string } {
+  const m = PROSE_MARKER_RE.exec(raw);
+  let cut = m ? m.index : -1;
+  if (cut < 0) {
+    // Secondary rule, so the boundary does not depend on Figma's current
+    // wording: a generated module ends with a `}` in column 0, and anything
+    // after the LAST such line is not part of it. Applied only when there is
+    // trailing content — otherwise the module already ends cleanly.
+    const lastBrace = raw.lastIndexOf('\n}');
+    if (lastBrace >= 0 && raw.slice(lastBrace + 2).trim().length > 0) cut = lastBrace + 2;
+  }
+  if (cut < 0) return { code: raw, prose: '' };
+  return { code: raw.slice(0, cut), prose: raw.slice(cut) };
+}
+
+/**
+ * Strip a fenced code block if the tool wrapped one. Figma returns bare source
+ * on the local channel, but a fence is cheap to tolerate and expensive to
+ * discover in production — and an unstripped ``` is a parse error, i.e. a
+ * refused frame, for a reason that has nothing to do with the frame.
+ */
+function unfence(text: string): string {
+  const fence = /^\s*```(?:[a-z]{0,16})\n([\s\S]*?)\n```\s*$/;
+  const m = fence.exec(text);
+  return m ? m[1] : text;
+}
+
+// ── Transport ───────────────────────────────────────────────────────────────
+
+interface JsonRpcReply {
+  result?: unknown;
+  error?: unknown;
+}
+
+/**
+ * The streamable-HTTP transport answers `event: message\ndata: {json}` even for
+ * a single reply, so pull the LAST `data:` line rather than assuming raw JSON.
+ * Measured on the live server 2026-08-11.
+ */
+export function parseRpcBody(text: string): JsonRpcReply {
+  if (!/^\s*(?:event|data):/m.test(text)) return JSON.parse(text) as JsonRpcReply;
+  const lines = text.split('\n').filter((l) => l.startsWith('data:'));
+  if (lines.length === 0) throw new CodegenError('bad_response');
+  return JSON.parse(lines[lines.length - 1].slice(5).trim()) as JsonRpcReply;
+}
+
+/** Injected so the client is testable with no server and no network. */
+export type FetchLike = (url: string, init: RequestInit) => Promise<Response>;
+
+export interface CodegenClientOptions {
+  fetchImpl?: FetchLike;
+  /** Overrides the per-invocation ceiling. Tests only — never a user flag. */
+  maxCalls?: number;
+}
+
+/**
+ * One invocation's worth of conversation with the local server.
+ *
+ * Deliberately a class with a spent-call counter rather than a free function:
+ * D10's ceiling is only real if it lives somewhere a second call has to get
+ * past. A module-level counter would leak across invocations in the long-lived
+ * dev-server process; a per-session one is scoped to exactly the unit the
+ * ceiling is defined over.
+ */
+export class CodegenSession {
+  private readonly fetchImpl: FetchLike;
+  private readonly maxCalls: number;
+  private sessionId: string | null = null;
+  private rpcId = 0;
+  private ready = false;
+  /** D10's ceiling, spent. */
+  private calls = 0;
+
+  constructor(opts: CodegenClientOptions = {}) {
+    this.fetchImpl = opts.fetchImpl ?? ((url, init) => fetch(url, init));
+    this.maxCalls = opts.maxCalls ?? MAX_CODEGEN_CALLS_PER_INVOCATION;
+  }
+
+  private async rpc(
+    method: string,
+    params: unknown,
+    { notify = false, timeoutMs = HANDSHAKE_TIMEOUT_MS } = {}
+  ): Promise<JsonRpcReply | null> {
+    const headers: Record<string, string> = {
+      'content-type': 'application/json',
+      accept: 'application/json, text/event-stream',
+    };
+    if (this.sessionId) headers['mcp-session-id'] = this.sessionId;
+    const body = notify
+      ? { jsonrpc: '2.0', method, params }
+      : { jsonrpc: '2.0', id: ++this.rpcId, method, params };
+
+    let res: Response;
+    try {
+      res = await this.fetchImpl(CODEGEN_ENDPOINT, {
+        method: 'POST',
+        headers,
+        body: JSON.stringify(body),
+        // Loopback never legitimately redirects, and following one would be the
+        // one way this call could leave the machine.
+        redirect: 'error',
+        signal: AbortSignal.timeout(timeoutMs),
+      });
+    } catch {
+      // Swallow the cause deliberately — a fetch error can carry the URL and,
+      // on some runtimes, request detail (D10: output is code-owned).
+      throw new CodegenError('unavailable');
+    }
+
+    const sid = res.headers.get('mcp-session-id');
+    if (sid) this.sessionId = sid;
+    if (notify) {
+      // A notification has no reply worth reading; drain so the socket closes.
+      await res.text().catch(() => '');
+      return null;
+    }
+    if (!res.ok) throw new CodegenError('unavailable');
+
+    const text = await readCapped(res);
+    try {
+      return parseRpcBody(text);
+    } catch (err) {
+      if (err instanceof CodegenError) throw err;
+      throw new CodegenError('bad_response');
+    }
+  }
+
+  /**
+   * `initialize` → assert → `tools/list` → assert. Runs once per session and
+   * REFUSES rather than falling through, because everything after it trusts the
+   * peer to be Figma's server (DDR-219 D2's named new threat).
+   */
+  async handshake(): Promise<void> {
+    if (this.ready) return;
+
+    const init = await this.rpc('initialize', {
+      protocolVersion: PROTOCOL_VERSION,
+      capabilities: {},
+      clientInfo: { name: 'maude', version: '1' },
+    });
+    const initResult = asRecord(init?.result);
+    const serverInfo = asRecord(initResult?.serverInfo);
+    const serverName = typeof serverInfo?.name === 'string' ? serverInfo.name : '';
+    if (!initResult || !SERVER_NAME_RE.test(serverName)) throw new CodegenError('handshake');
+
+    // The transport requires this before any other call.
+    await this.rpc('notifications/initialized', {}, { notify: true }).catch(() => null);
+
+    const list = await this.rpc('tools/list', {});
+    const listResult = asRecord(list?.result);
+    const tools = Array.isArray(listResult?.tools) ? listResult.tools : [];
+    const names: string[] = [];
+    for (const t of tools) {
+      const name = asRecord(t)?.name;
+      if (typeof name === 'string') names.push(name);
+    }
+    if (!names.includes(CODEGEN_TOOL)) throw new CodegenError('tool_surface');
+    // §4.f is answered by the CHANNEL, not by argument (DDR-219 D2): our code
+    // calls read tools only, and the write surface is measured absent from this
+    // endpoint. If it ever appears, that measurement has expired — refuse.
+    if (names.some((n) => WRITE_TOOL_RE.test(n))) throw new CodegenError('tool_surface');
+
+    this.ready = true;
+  }
+
+  /**
+   * The one call. Returns the CODE half of the response plus its provenance.
+   *
+   * `nodeId` is charset-checked by the caller (`^\d+[:-]\d+$` is the server's own
+   * pattern) and is the ONLY addressing parameter the tool takes — it reads the
+   * currently open document, with no file key anywhere (probe finding 1). The
+   * open-document coupling that follows from that is the caller's problem to
+   * close, not this module's: see `--explode`'s frame cross-check.
+   */
+  async fetchDesignContext(nodeId: string): Promise<CodegenResponse> {
+    if (this.calls >= this.maxCalls) throw new CodegenError('ceiling');
+    this.calls += 1;
+
+    await this.handshake();
+
+    const reply = await this.rpc(
+      'tools/call',
+      {
+        name: CODEGEN_TOOL,
+        arguments: {
+          nodeId,
+          clientLanguages: 'typescript',
+          clientFrameworks: 'react',
+          // `dirForAssetWrites` is DELIBERATELY ABSENT — see the file header.
+          // Every asset is re-fetched by node id through the REST lane (D6), so
+          // this server never writes a byte on this machine.
+        },
+      },
+      { timeoutMs: CALL_TIMEOUT_MS }
+    );
+
+    if (reply?.error) throw new CodegenError('node_unavailable');
+    const result = asRecord(reply?.result);
+    if (!result) throw new CodegenError('bad_response');
+    if (result.isError === true) throw new CodegenError('node_unavailable');
+
+    const raw = collectText(result.content);
+    if (raw === null) throw new CodegenError('bad_response');
+
+    // Hash the FULL response — prose included. The provenance question is "same
+    // generator state?", and the advice block is part of that state.
+    const responseSha256 = createHash('sha256').update(raw, 'utf8').digest('hex');
+
+    // The tool answers a missing node with a human sentence rather than an
+    // error object; that sentence is not code and must not become an artboard.
+    if (/No node could be found for the provided nodeId/i.test(raw)) {
+      throw new CodegenError('node_unavailable');
+    }
+
+    const { code, prose } = splitCodeAndProse(raw);
+    const source = unfence(code).trim();
+    if (!looksLikeCode(source)) throw new CodegenError('not_code');
+
+    return {
+      code: source,
+      responseSha256,
+      endpoint: 'local',
+      tool: CODEGEN_TOOL,
+      proseBytes: prose.length,
+    };
+  }
+}
+
+/**
+ * Probe finding 3, as a check rather than as a `forceCode: true` that would hide
+ * it. A code response always declares a component; a metadata response is XML-ish
+ * or prose and declares nothing.
+ */
+export function looksLikeCode(source: string): boolean {
+  if (source.length === 0) return false;
+  return /^\s*(?:export\s+default\s+)?function\s+[A-Za-z_$]/m.test(source);
+}
+
+/** MCP tool results are `content: [{ type: 'text', text }]`. Join the text parts. */
+function collectText(content: unknown): string | null {
+  if (typeof content === 'string') return content;
+  if (!Array.isArray(content)) return null;
+  const parts: string[] = [];
+  for (const item of content) {
+    const rec = asRecord(item);
+    if (rec?.type === 'text' && typeof rec.text === 'string') parts.push(rec.text);
+  }
+  return parts.length > 0 ? parts.join('\n') : null;
+}
+
+/**
+ * `Object.create(null)`-safe record narrowing. Nothing here indexes by an
+ * upstream key, but the shape check is the thing that keeps `result.isError`
+ * from throwing on a primitive (D5 rule 5's neighbourhood).
+ */
+function asRecord(v: unknown): Record<string, unknown> | null {
+  return v && typeof v === 'object' && !Array.isArray(v) ? (v as Record<string, unknown>) : null;
+}
+
+/**
+ * Read a body, aborting the moment it exceeds the INPUT cap. Streaming rather
+ * than `res.text()` so an unbounded body is never fully materialized before the
+ * check — the same rule `client.ts` states for the REST lane, for the same
+ * reason: a missing or lying `Content-Length` must not be what stands between a
+ * cap and the heap.
+ */
+async function readCapped(res: Response): Promise<string> {
+  const body = res.body;
+  if (!body) {
+    // Some fetch stubs (and `Response` in a few runtimes) expose no stream.
+    const text = await res.text();
+    if (text.length > MAX_CODEGEN_RESPONSE_BYTES) throw new CodegenError('too_large');
+    return text;
+  }
+  const reader = body.getReader();
+  const chunks: Uint8Array[] = [];
+  let total = 0;
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      if (!value) continue;
+      total += value.byteLength;
+      if (total > MAX_CODEGEN_RESPONSE_BYTES) {
+        await reader.cancel().catch(() => {});
+        throw new CodegenError('too_large');
+      }
+      chunks.push(value);
+    }
+  } finally {
+    reader.releaseLock?.();
+  }
+  const out = new Uint8Array(total);
+  let offset = 0;
+  for (const chunk of chunks) {
+    out.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  return new TextDecoder().decode(out);
+}

package/apps/studio/figma/codegen-fonts.test.ts

@@ -0,0 +1,103 @@
+// figma/codegen-fonts.ts — plan T18.
+//
+// The thing under test is not really the mapping, it is the REPORT. A font that
+// silently falls back looks fine and is not the design, and this import has
+// already shipped three "success" reports over lost content. So: every
+// substitution produces an entry, the entry is BOUNDED (DDR-219 D9), and a
+// family the project genuinely has produces none.
+
+import { describe, expect, test } from 'bun:test';
+
+import {
+  FontSubstitutions,
+  MAX_FAMILY_DETAIL,
+  resolveFontFamily,
+  SYSTEM_STACK,
+  splitFamilyAndStyle,
+  styleToWeight,
+} from './codegen-fonts.ts';
+import { ImportReport } from './sanitize.ts';
+
+const DS = [{ name: '--font-body', value: "'hanken grotesk','inter',sans-serif" }];
+
+describe('splitting Figma’s Family:Style', () => {
+  test.each([
+    ['SF Pro:Bold', 'SF Pro', 'Bold'],
+    ['SF Pro Display:Semibold', 'SF Pro Display', 'Semibold'],
+    ['Inter:Regular', 'Inter', 'Regular'],
+    ['Inter', 'Inter', null],
+  ])('%s', (raw, family, style) => {
+    expect(splitFamilyAndStyle(raw)).toEqual({ family, style });
+  });
+
+  test('the style half is a WEIGHT and must not become part of the family', () => {
+    expect(styleToWeight('Bold')).toBe(700);
+    expect(styleToWeight('Semibold')).toBe(600);
+    expect(styleToWeight('Regular')).toBe(400);
+    expect(styleToWeight('NotAWeight')).toBeNull();
+  });
+});
+
+describe('resolveFontFamily', () => {
+  test('a family the DS already declares resolves to the token, and is NOT a substitution', () => {
+    const r = resolveFontFamily('Inter:Regular', DS);
+    expect(r.css).toBe('var(--font-body)');
+    expect(r.substituted).toBe(false);
+  });
+
+  test('an absent family lands on the DS body token AND reports', () => {
+    // Measured on the dogfood machine: SF Pro is not installed, and the DS loads
+    // no webfont at all — so copying the name through lands on a serif fallback
+    // that looks fine and is not the design.
+    const r = resolveFontFamily('SF Pro:Bold', DS);
+    expect(r.css).toBe('var(--font-body)');
+    expect(r.substituted).toBe(true);
+    expect(r.requested).toBe('SF Pro');
+  });
+
+  test('with no DS at all it lands on a SANS stack, never a serif default', () => {
+    const r = resolveFontFamily('Nunito:Bold', []);
+    expect(r.css).toBe(SYSTEM_STACK);
+    expect(r.substituted).toBe(true);
+  });
+
+  test('the requested family NEVER reaches the artifact verbatim', () => {
+    const hostile = resolveFontFamily("Evil';}\n.x{color:red};:Bold", DS);
+    expect(hostile.css).not.toContain('color:red');
+    expect(hostile.requested).not.toContain(';');
+    expect(hostile.requested.length).toBeLessThanOrEqual(MAX_FAMILY_DETAIL);
+  });
+});
+
+describe('the report', () => {
+  test('one entry per FAMILY with a count — not one per element', () => {
+    const subs = new FontSubstitutions();
+    for (let i = 0; i < 40; i += 1) subs.note(resolveFontFamily('SF Pro:Bold', DS));
+    subs.note(resolveFontFamily('Nunito:Regular', DS));
+    const report = new ImportReport();
+    subs.flush(report, '425:2939');
+
+    // Forty identical entries would bury every other disposition and blow the
+    // summary's 200-line cap for no information.
+    expect(report.entries).toEqual([
+      { nodeId: '425:2939', type: 'FONT', disposition: 'font-substituted', detail: 'Nunito x1' },
+      { nodeId: '425:2939', type: 'FONT', disposition: 'font-substituted', detail: 'SF Pro x40' },
+    ]);
+  });
+
+  test('a family that survived produces NO entry', () => {
+    const subs = new FontSubstitutions();
+    subs.note(resolveFontFamily('Inter:Regular', DS));
+    const report = new ImportReport();
+    subs.flush(report, '1:1');
+    expect(report.entries).toEqual([]);
+  });
+
+  test('a hostile family cannot blow the detail bound — ImportReport would throw', () => {
+    const subs = new FontSubstitutions();
+    subs.note(resolveFontFamily(`${'A'.repeat(400)}:Bold`, DS));
+    const report = new ImportReport();
+    expect(() => subs.flush(report, '1:1')).not.toThrow();
+    expect(report.entries[0].detail?.length).toBeLessThanOrEqual(64);
+  });
+});