@hienlh/ppm 0.22.11 → 0.23.1

package/src/services/design/export/design-standalone-html.ts

@@ -0,0 +1,167 @@
+import { posix } from "node:path";
+import { parse, type DefaultTreeAdapterMap } from "parse5";
+import { DesignError } from "../design-error.ts";
+import { decodeDesignText, MAX_DESIGN_SOURCE_BYTES } from "../source/design-source-file.ts";
+import { headInsertOffset } from "../preview/html-instrument.ts";
+import type { ReadAsset } from "./design-export-asset-reader.ts";
+import { inlineCssUrls, loadInlineAsset, resolveDesignRef, toDataUri, type InlineContext } from "./css-url-inline.ts";
+
+/**
+ * One design page as a single self-contained HTML file: local stylesheets, scripts, images
+ * and media become inline `<style>`/`<script>` or `data:` URIs; CDN references stay as they
+ * are (they are allowed and not local).
+ *
+ * Like the canvas instrumentation, this splices at parse5 source locations and never
+ * re-serialises the document, so everything not being inlined is byte-for-byte the source.
+ * An inlined script has `</script` escaped, and a `defer`/`async` script keeps its timing by
+ * becoming a `data:` `src` rather than inline text. Local ES-module imports are not bundled;
+ * they are reported. `readAsset` is injected so the whole thing is testable without a disk.
+ */
+
+type Node = DefaultTreeAdapterMap["node"];
+type Element = DefaultTreeAdapterMap["element"];
+
+export const STANDALONE_ASSET_LIMIT = 10 * 1024 * 1024;
+export const STANDALONE_TOTAL_LIMIT = 30 * 1024 * 1024;
+
+export interface StandaloneHtml {
+  html: string;
+  warnings: string[];
+}
+
+interface Edit {
+  start: number;
+  end: number;
+  text: string;
+}
+
+const isElement = (node: Node): node is Element => "tagName" in node;
+const attrOf = (el: Element, name: string): string | undefined => el.attrs.find((a) => a.name === name)?.value;
+const escapeAttr = (v: string): string => v.replace(/&/g, "&amp;").replace(/"/g, "&quot;");
+const LOCAL_IMPORT_RE = /\bimport\s*(?:[\w$*{}\s,]+\s*from\s*)?\(?\s*["'](\.{1,2}\/[^"']*)["']/g;
+
+export async function buildStandaloneHtml(
+  entryRel: string,
+  readAsset: ReadAsset,
+  limits: { perAsset: number; total: number } = { perAsset: STANDALONE_ASSET_LIMIT, total: STANDALONE_TOTAL_LIMIT },
+): Promise<StandaloneHtml> {
+  const entry = await readAsset(entryRel, MAX_DESIGN_SOURCE_BYTES);
+  if (!entry.ok) {
+    throw entry.reason === "missing" ? new DesignError(404, "ENOENT", `Page not found: ${entryRel}`)
+      : entry.reason === "too-large" ? new DesignError(413, "ETOOBIG", "Page too large to export")
+      : new DesignError(403, "EDESIGNPATH", "Page is not readable from the design folder");
+  }
+  const { text } = decodeDesignText(entry.bytes, { lossy: true });
+  const ctx: InlineContext = { readAsset, budget: { perAsset: limits.perAsset, remaining: limits.total }, warnings: [] };
+  const baseDir = posix.dirname(entryRel);
+  const edits: Edit[] = [];
+  const reportImports = (code: string, where: string): void => {
+    for (const m of code.matchAll(LOCAL_IMPORT_RE)) ctx.warnings.push(`${where}: imports ${m[1]}, which is not bundled`);
+  };
+  const localRef = (ref: string | undefined) => {
+    if (ref === undefined) return null;
+    const resolved = resolveDesignRef(ref, baseDir);
+    if (resolved && "outside" in resolved) {
+      ctx.warnings.push(`${ref}: outside the design folder, left linked`);
+      return null;
+    }
+    return resolved;
+  };
+  const inlineAttr = async (el: Element, name: string): Promise<void> => {
+    const loc = el.sourceCodeLocation?.attrs?.[name];
+    const ref = localRef(attrOf(el, name));
+    if (!loc || !ref) return;
+    const bytes = await loadInlineAsset(ref.rel, ctx);
+    if (bytes) edits.push({ start: loc.startOffset, end: loc.endOffset, text: `${name}="${toDataUri(ref.rel, bytes)}${ref.suffix}"` });
+  };
+
+  const doc = parse(text, { sourceCodeLocationInfo: true });
+  const stack: Node[] = [...doc.childNodes].reverse();
+  while (stack.length) {
+    const node = stack.pop()!;
+    if (!isElement(node)) continue;
+    const loc = node.sourceCodeLocation;
+    const tag = node.tagName;
+    const children = tag === "template" ? (node as DefaultTreeAdapterMap["template"]).content.childNodes : node.childNodes;
+    for (let i = children.length - 1; i >= 0; i--) stack.push(children[i]!);
+    if (!loc?.startTag) continue;
+
+    if (tag === "link" && (attrOf(node, "rel") ?? "").toLowerCase().split(/\s+/).includes("stylesheet")) {
+      const ref = localRef(attrOf(node, "href"));
+      const bytes = ref ? await loadInlineAsset(ref.rel, ctx) : null;
+      if (!ref || !bytes) continue;
+      const css = await inlineCssUrls(new TextDecoder().decode(bytes), posix.dirname(ref.rel), ctx);
+      const media = attrOf(node, "media");
+      edits.push({
+        start: loc.startTag.startOffset, end: loc.endTag?.endOffset ?? loc.startTag.endOffset,
+        text: `<style${media ? ` media="${escapeAttr(media)}"` : ""}>${css.replace(/<\/style/gi, "<\\/style")}</style>`,
+      });
+      continue;
+    }
+    if (tag === "script") {
+      const module = (attrOf(node, "type") ?? "").trim().toLowerCase() === "module";
+      const src = attrOf(node, "src");
+      if (src === undefined) {
+        if (module) reportImports(node.childNodes.map((c) => ("value" in c ? String(c.value) : "")).join(""), "inline module script");
+        continue;
+      }
+      const ref = localRef(src);
+      const bytes = ref ? await loadInlineAsset(ref.rel, ctx) : null;
+      if (!ref || !bytes) continue;
+      const code = new TextDecoder().decode(bytes);
+      if (module) reportImports(code, ref.rel);
+      const timed = !module && (attrOf(node, "defer") !== undefined || attrOf(node, "async") !== undefined);
+      const srcLoc = loc.attrs?.src;
+      if (timed && srcLoc) {
+        edits.push({ start: srcLoc.startOffset, end: srcLoc.endOffset, text: `src="${toDataUri(ref.rel, bytes)}"` });
+      } else if (loc.endTag) {
+        const kept = node.attrs.filter((a) => !["src", "integrity", "crossorigin", "charset", "defer", "async"].includes(a.name))
+          .map((a) => ` ${a.name}="${escapeAttr(a.value)}"`).join("");
+        edits.push({ start: loc.startTag.startOffset, end: loc.endTag.endOffset, text: `<script${kept}>${code.replace(/<\/script/gi, "<\\/script")}</script>` });
+      }
+      continue;
+    }
+    if (tag === "style") {
+      const first = node.childNodes[0];
+      const textLoc = first?.sourceCodeLocation;
+      if (first && "value" in first && textLoc) {
+        const css = await inlineCssUrls(String(first.value), baseDir, ctx);
+        if (css !== first.value) edits.push({ start: textLoc.startOffset, end: textLoc.endOffset, text: css });
+      }
+      continue;
+    }
+    const style = attrOf(node, "style");
+    const styleLoc = loc.attrs?.style;
+    if (style !== undefined && styleLoc && /url\(/i.test(style)) {
+      const css = await inlineCssUrls(style, baseDir, ctx);
+      if (css !== style) edits.push({ start: styleLoc.startOffset, end: styleLoc.endOffset, text: `style="${escapeAttr(css)}"` });
+    }
+    if (tag === "img" || tag === "source" || tag === "video" || tag === "audio" || tag === "track") await inlineAttr(node, "src");
+    if (tag === "video") await inlineAttr(node, "poster");
+    const srcset = attrOf(node, "srcset");
+    const srcsetLoc = loc.attrs?.srcset;
+    if ((tag === "img" || tag === "source") && srcset !== undefined && srcsetLoc && !/^\s*data:/i.test(srcset)) {
+      const candidates = srcset.split(/,\s+/).map((c) => c.trim()).filter(Boolean);
+      const [url, ...descriptor] = (candidates[0] ?? "").split(/\s+/);
+      const ref = localRef(url);
+      const bytes = ref ? await loadInlineAsset(ref.rel, ctx) : null;
+      if (ref && bytes) {
+        edits.push({ start: srcsetLoc.startOffset, end: srcsetLoc.endOffset, text: `srcset="${[toDataUri(ref.rel, bytes), ...descriptor].join(" ")}"` });
+        if (candidates.length > 1) ctx.warnings.push(`${ref.rel}: srcset keeps only its first image`);
+      }
+    }
+  }
+
+  // Without a declared charset a file opened from disk may be read as Windows-1252.
+  if (!/<meta\s[^>]*charset/i.test(text)) edits.push({ start: headInsertOffset(text), end: headInsertOffset(text), text: '<meta charset="utf-8">' });
+  edits.sort((a, b) => a.start - b.start || a.end - b.end);
+  const out: string[] = [];
+  let cursor = 0;
+  for (const edit of edits) {
+    if (edit.start < cursor) continue;
+    out.push(text.slice(cursor, edit.start), edit.text);
+    cursor = edit.end;
+  }
+  out.push(text.slice(cursor));
+  return { html: out.join(""), warnings: ctx.warnings };
+}

package/src/services/design/export/design-zip-export.ts

@@ -0,0 +1,106 @@
+import { join } from "node:path";
+import archiver from "archiver";
+import { isCredentialPath } from "../../fs-path-guard.service.ts";
+import { DesignError } from "../design-error.ts";
+import { lstatOrNull, resolveDesignDir, resolveDesignsRoot } from "../design-paths.ts";
+import { readDesignFileSafe, safeWalkDesignTree } from "../design-safe-walk.ts";
+
+/**
+ * A design as a zip: `<slug>/**` plus the project's `tokens.css` and `DESIGN.md`, rooted at
+ * `designs/` so every `../tokens.css` link still resolves after unzipping.
+ *
+ * Every file comes from the shared safe walker and is read through `readDesignFileSafe`: no
+ * symlink (a link to `ppm.db` or a key is never packed), no FIFO or device, nothing whose
+ * real path leaves the design, no credential path. The design's own `.design/` working data
+ * and every dotfile or dot-directory are left out. The tree is listed and sized before the
+ * first byte is sent, so an oversized design is a clean 413 rather than a truncated download;
+ * files are then read one at a time as the archive drains, so memory holds about one file.
+ */
+
+export const MAX_ZIP_FILES = 5000;
+export const MAX_ZIP_BYTES = 512 * 1024 * 1024;
+const SHARED_FILES = ["tokens.css", "DESIGN.md"];
+
+interface ZipEntry {
+  name: string;
+  abs: string;
+}
+
+async function listZipEntries(projectPath: string, slug: string): Promise<ZipEntry[]> {
+  const designDir = await resolveDesignDir(projectPath, slug);
+  const root = await resolveDesignsRoot(projectPath);
+  const entries: ZipEntry[] = [];
+  let bytes = 0;
+  const add = (name: string, abs: string, size: number): void => {
+    bytes += size;
+    if (entries.length >= MAX_ZIP_FILES || bytes > MAX_ZIP_BYTES) {
+      throw new DesignError(413, "ETOOBIG", "Design is too large to export as a zip");
+    }
+    entries.push({ name, abs });
+  };
+  for await (const entry of safeWalkDesignTree(designDir)) {
+    if (entry.rel.split("/").some((part) => part.startsWith("."))) continue;
+    add(`${slug}/${entry.rel}`, entry.abs, entry.size);
+  }
+  for (const name of root ? SHARED_FILES : []) {
+    const abs = join(root!, name);
+    const st = await lstatOrNull(abs);
+    // The same rule as the walker: a regular file or nothing, never a link followed out.
+    if (!st || st.isSymbolicLink() || !st.isFile() || isCredentialPath(abs)) continue;
+    add(name, abs, st.size);
+  }
+  return entries;
+}
+
+/** Waits for archiver to take in one entry, so the next file is read only once it has. */
+function entryDone(archive: archiver.Archiver): Promise<void> {
+  return new Promise((resolve, reject) => {
+    const onEntry = (): void => { archive.off("error", onError); resolve(); };
+    const onError = (e: Error): void => { archive.off("entry", onEntry); reject(e); };
+    archive.once("entry", onEntry);
+    archive.once("error", onError);
+  });
+}
+
+/** The zip as a byte stream. Throws (before streaming) when the design is missing or too big. */
+export async function createDesignZip(projectPath: string, slug: string): Promise<ReadableStream<Uint8Array>> {
+  const entries = await listZipEntries(projectPath, slug);
+  const archive = archiver("zip", { zlib: { level: 5 } });
+  let cancelled = false;
+
+  const feed = async (): Promise<void> => {
+    for (const entry of entries) {
+      if (cancelled) return;
+      const bytes = await readDesignFileSafe(entry.abs, MAX_ZIP_BYTES);
+      const done = entryDone(archive);
+      archive.append(bytes, { name: entry.name });
+      await done;
+    }
+    await archive.finalize();
+  };
+
+  return new ReadableStream<Uint8Array>({
+    start(controller) {
+      archive.on("data", (chunk: Buffer) => {
+        controller.enqueue(new Uint8Array(chunk));
+        // Stop compressing while the client is behind; `pull` resumes.
+        if ((controller.desiredSize ?? 1) <= 0) archive.pause();
+      });
+      archive.on("end", () => controller.close());
+      archive.on("error", (e: Error) => controller.error(e));
+      feed().catch((e: unknown) => {
+        if (cancelled) return;
+        console.error(`[design-export] zip ${slug}: ${(e as Error).message}`);
+        archive.abort();
+        controller.error(e);
+      });
+    },
+    pull() {
+      archive.resume();
+    },
+    cancel() {
+      cancelled = true;
+      archive.abort();
+    },
+  }, { highWaterMark: 1024 * 1024, size: (chunk) => chunk?.byteLength ?? 0 });
+}

package/src/services/design/mcp/design-mcp-access.ts

@@ -0,0 +1,16 @@
+import { localServerBaseUrl } from "../../server-listen-address.ts";
+import { designMcpTokens } from "./design-mcp-tokens.ts";
+import type { DesignMcpAccess } from "./design-mcp-tool.ts";
+
+export const DESIGN_MCP_PATH = "/api/design-mcp";
+
+/**
+ * How one design session's agent reaches `design_check`, or null when it cannot: a process
+ * that serves no HTTP (the CLI) has no endpoint to point at, and a session without a
+ * project has no design to check. The URL uses the port this server actually listens on.
+ */
+export function designMcpAccessFor(sessionId: string, projectPath: string | null | undefined, slug: string): DesignMcpAccess | null {
+  const base = localServerBaseUrl();
+  if (!base || !projectPath) return null;
+  return { url: `${base}${DESIGN_MCP_PATH}`, token: designMcpTokens.mint({ sessionId, projectPath, slug }) };
+}

package/src/services/design/mcp/design-mcp-endpoint.ts

@@ -0,0 +1,118 @@
+import type { Context } from "hono";
+import { formatCanvasCheck } from "../../../shared/design-canvas-check-format.ts";
+import { canvasCheckBroker, type CanvasCheckOutcome } from "../check/design-canvas-check-broker.ts";
+import { designMcpTokens, type DesignMcpBinding } from "./design-mcp-tokens.ts";
+import { DESIGN_CHECK_TOOL, DESIGN_CHECK_TOOL_DEFINITION } from "./design-mcp-tool.ts";
+
+/**
+ * `/api/design-mcp` — the smallest MCP server that speaks Streamable HTTP with plain JSON
+ * responses (`initialize`, `ping`, `tools/list`, `tools/call`), serving one tool,
+ * `design_check`, to one design session's own agent. Claude and Codex both take an HTTP MCP
+ * server by URL, so one endpoint serves both providers.
+ *
+ * Mounted before PPM's auth: the caller is a Claude or Codex subprocess with no PPM token.
+ * Its credential is the per-session capability token in `Authorization: Bearer`, which can
+ * do exactly one thing — check the canvas of the design it was minted for. A request that
+ * carries an `Origin` came from a browser, never from those subprocesses, and is refused.
+ */
+
+type Json = Record<string, unknown>;
+type Check = (projectPath: string, slug: string, options: { screenshot: boolean }) => Promise<CanvasCheckOutcome>;
+
+const PROTOCOL_VERSIONS = ["2025-06-18", "2025-03-26", "2024-11-05"];
+const MAX_BODY_BYTES = 64 * 1024;
+const MAX_IN_FLIGHT_PER_SESSION = 2;
+
+const rpcResult = (id: unknown, result: unknown) => ({ jsonrpc: "2.0", id, result });
+const rpcError = (id: unknown, code: number, message: string) => ({ jsonrpc: "2.0", id: id ?? null, error: { code, message } });
+
+export function createDesignMcpHandler(deps: {
+  resolveToken: (token: string | null) => DesignMcpBinding | null;
+  check: Check;
+}) {
+  const inFlight = new Map<string, number>();
+
+  async function callCheck(binding: DesignMcpBinding, args: unknown): Promise<Json> {
+    const screenshot = !(args && typeof args === "object" && (args as Json).screenshot === false);
+    const running = inFlight.get(binding.sessionId) ?? 0;
+    if (running >= MAX_IN_FLIGHT_PER_SESSION) {
+      return { content: [{ type: "text", text: "A canvas check is already running for this design; wait for it." }], isError: true };
+    }
+    inFlight.set(binding.sessionId, running + 1);
+    try {
+      const outcome = await deps.check(binding.projectPath, binding.slug, { screenshot });
+      if (!outcome.ok) return { content: [{ type: "text", text: outcome.error }], isError: true };
+      const content: Json[] = [{ type: "text", text: formatCanvasCheck(outcome.report, binding.slug) }];
+      const shot = outcome.report.screenshot;
+      if (shot) {
+        const comma = shot.dataUrl.indexOf(",");
+        const mimeType = shot.dataUrl.slice(5, shot.dataUrl.indexOf(";"));
+        content.push({ type: "image", data: shot.dataUrl.slice(comma + 1), mimeType });
+      }
+      return { content };
+    } finally {
+      const left = (inFlight.get(binding.sessionId) ?? 1) - 1;
+      if (left > 0) inFlight.set(binding.sessionId, left);
+      else inFlight.delete(binding.sessionId);
+    }
+  }
+
+  async function dispatch(binding: DesignMcpBinding, msg: Json): Promise<Json> {
+    const id = msg.id;
+    const params = (msg.params && typeof msg.params === "object" ? msg.params : {}) as Json;
+    switch (msg.method) {
+      case "initialize": {
+        const asked = typeof params.protocolVersion === "string" ? params.protocolVersion : "";
+        return rpcResult(id, {
+          protocolVersion: PROTOCOL_VERSIONS.includes(asked) ? asked : PROTOCOL_VERSIONS[0],
+          capabilities: { tools: { listChanged: false } },
+          serverInfo: { name: "ppm-design", version: "1.0.0" },
+        });
+      }
+      case "ping":
+        return rpcResult(id, {});
+      case "tools/list":
+        return rpcResult(id, { tools: [DESIGN_CHECK_TOOL_DEFINITION] });
+      case "tools/call":
+        if (params.name !== DESIGN_CHECK_TOOL) return rpcError(id, -32602, `Unknown tool: ${String(params.name).slice(0, 60)}`);
+        return rpcResult(id, await callCheck(binding, params.arguments));
+      default:
+        return rpcError(id, -32601, "Method not found");
+    }
+  }
+
+  return async function handle(c: Context): Promise<Response> {
+    if (c.req.header("origin")) return c.json({ error: "Browser requests are not accepted" }, 403);
+    const auth = c.req.header("authorization") ?? "";
+    const binding = deps.resolveToken(/^Bearer\s+(\S+)$/i.exec(auth)?.[1] ?? null);
+    if (!binding) return c.json({ error: "A design session token is required" }, 401);
+    if (c.req.method === "DELETE") return c.body(null, 204);
+    if (c.req.method !== "POST") return c.body(null, 405, { Allow: "POST, DELETE" });
+    if (Number(c.req.header("content-length") ?? "0") > MAX_BODY_BYTES) return c.json(rpcError(null, -32600, "Request too large"), 413);
+    let msg: unknown;
+    try {
+      const raw = await c.req.text();
+      if (raw.length > MAX_BODY_BYTES) return c.json(rpcError(null, -32600, "Request too large"), 413);
+      msg = JSON.parse(raw);
+    } catch {
+      return c.json(rpcError(null, -32700, "Parse error"), 400);
+    }
+    if (!msg || typeof msg !== "object" || Array.isArray(msg) || (msg as Json).jsonrpc !== "2.0" || typeof (msg as Json).method !== "string") {
+      return c.json(rpcError(null, -32600, "Expected one JSON-RPC 2.0 message"), 400);
+    }
+    const message = msg as Json;
+    // A notification (`notifications/initialized`) or a response to a request of ours: no body.
+    if (!("id" in message) || message.id === null) return c.body(null, 202);
+    try {
+      return c.json(await dispatch(binding, message));
+    } catch (e) {
+      console.warn(`[design-mcp] ${String(message.method)} failed: ${(e as Error).message}`);
+      return c.json(rpcError(message.id, -32603, "Internal error"));
+    }
+  };
+}
+
+export const designMcpHandler = createDesignMcpHandler({
+  resolveToken: (token) => designMcpTokens.resolve(token),
+  check: (projectPath, slug, options) => canvasCheckBroker.request(projectPath, slug, options),
+});

package/src/services/design/mcp/design-mcp-tokens.ts

@@ -0,0 +1,82 @@
+import { createHash, randomBytes, timingSafeEqual } from "node:crypto";
+
+/**
+ * Capability tokens for the design MCP endpoint, one per design session.
+ *
+ * The endpoint is called by the session's own Claude or Codex subprocess, which holds no
+ * PPM credentials, so the token is the whole authorization: it names one session, one
+ * project and one design, and nothing else can be reached with it. Tokens live in memory
+ * only — a restart revokes every one, and the next turn mints a fresh one — and are stored
+ * by their SHA-256, so neither a log line nor a heap dump of the map holds a usable secret.
+ */
+
+export interface DesignMcpBinding {
+  sessionId: string;
+  projectPath: string;
+  slug: string;
+}
+
+interface Entry extends DesignMcpBinding {
+  digest: Buffer;
+}
+
+/** Enough for every design session a server could plausibly keep alive at once. */
+export const MAX_DESIGN_MCP_TOKENS = 256;
+
+const digestOf = (token: string): Buffer => createHash("sha256").update(token, "utf8").digest();
+
+export function createDesignMcpTokenStore(max = MAX_DESIGN_MCP_TOKENS) {
+  const byDigest = new Map<string, Entry>();
+  const tokenBySession = new Map<string, string>();
+
+  function revoke(sessionId: string): void {
+    const token = tokenBySession.get(sessionId);
+    if (!token) return;
+    tokenBySession.delete(sessionId);
+    byDigest.delete(digestOf(token).toString("hex"));
+  }
+
+  /**
+   * The session's token, minted on first use. The same token comes back for as long as the
+   * binding holds, because a Claude query keeps the MCP config it started with for every
+   * later turn; a changed project or design replaces it.
+   */
+  function mint(binding: DesignMcpBinding): string {
+    const existing = tokenBySession.get(binding.sessionId);
+    if (existing) {
+      const entry = byDigest.get(digestOf(existing).toString("hex"));
+      if (entry && entry.projectPath === binding.projectPath && entry.slug === binding.slug) {
+        // Re-inserted so the map's order stays least-recently-used first.
+        tokenBySession.delete(binding.sessionId);
+        tokenBySession.set(binding.sessionId, existing);
+        return existing;
+      }
+      revoke(binding.sessionId);
+    }
+    while (tokenBySession.size >= max) {
+      const oldest = tokenBySession.keys().next().value;
+      if (oldest === undefined) break;
+      revoke(oldest);
+    }
+    const token = randomBytes(32).toString("base64url");
+    const digest = digestOf(token);
+    byDigest.set(digest.toString("hex"), { ...binding, digest });
+    tokenBySession.set(binding.sessionId, token);
+    return token;
+  }
+
+  /** The binding a presented token grants, or null. */
+  function resolve(token: string | null | undefined): DesignMcpBinding | null {
+    if (!token || token.length > 200) return null;
+    const digest = digestOf(token);
+    const entry = byDigest.get(digest.toString("hex"));
+    // The map lookup is by digest, which says nothing about the token; the compare is the
+    // constant-time confirmation that the digests really are equal.
+    if (!entry || !timingSafeEqual(entry.digest, digest)) return null;
+    return { sessionId: entry.sessionId, projectPath: entry.projectPath, slug: entry.slug };
+  }
+
+  return { mint, resolve, revoke, size: () => tokenBySession.size };
+}
+
+export const designMcpTokens = createDesignMcpTokenStore();

package/src/services/design/mcp/design-mcp-tool.ts

@@ -0,0 +1,41 @@
+/**
+ * The one tool the design MCP endpoint serves, and the names each provider knows it by.
+ *
+ * Claude addresses MCP tools as `mcp__<server>__<tool>`, which is the name its permission
+ * hooks see and the one pre-approved for design sessions. Codex takes the server name from
+ * its config key, where a hyphen is not a safe character, hence the separate name.
+ */
+
+export const DESIGN_CHECK_TOOL = "design_check";
+export const CLAUDE_DESIGN_MCP_SERVER = "ppm-design";
+export const CLAUDE_DESIGN_CHECK_TOOL = `mcp__${CLAUDE_DESIGN_MCP_SERVER}__${DESIGN_CHECK_TOOL}`;
+export const CODEX_DESIGN_MCP_SERVER = "ppm_design";
+/** Environment variable the Codex app-server reads the bearer token from. */
+export const CODEX_DESIGN_MCP_TOKEN_ENV = "PPM_DESIGN_MCP_TOKEN";
+/** A check waits up to 20 s for a browser; the providers' own tool timeout must exceed that. */
+export const DESIGN_CHECK_TOOL_TIMEOUT_MS = 45_000;
+
+/** How a provider reaches the endpoint for one session; built by `chatService` per turn. */
+export interface DesignMcpAccess {
+  url: string;
+  token: string;
+}
+
+export const DESIGN_CHECK_TOOL_DEFINITION = {
+  name: DESIGN_CHECK_TOOL,
+  title: "Check the design canvas",
+  description:
+    "Check the live design canvas open in the user's browser and report what is wrong with the rendered page: "
+    + "grid items pushed into implicit tracks, content overflowing the page or cut off by a parent, elements "
+    + "squeezed to nothing, blocks drawn over each other, and script or loading errors. Also returns the frame "
+    + "size and, unless screenshot is false, a screenshot. Call it after changing the design and fix every "
+    + "finding before saying you are done. Needs the design's tab to be open in PPM.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      screenshot: { type: "boolean", description: "Include a screenshot of the canvas (default true)." },
+    },
+    additionalProperties: false,
+  },
+  annotations: { readOnlyHint: true, openWorldHint: false },
+};

package/src/services/design/preview/design-csp.ts

@@ -0,0 +1,31 @@
+import { DESIGN_CDN_HOSTS } from "../../../shared/design-cdn-hosts.ts";
+
+/**
+ * The Content-Security-Policy every design document is served under.
+ *
+ * `source` is the capability's own prefix (`host/api/design-preview/content/<token>/`),
+ * scheme-less so it follows the document's real scheme through a tunnel. The boundary this
+ * policy draws is `connect-src`: only the design's own files, never a CDN and never `*`,
+ * because `fetch`/XHR/WebSocket are how a page would send data somewhere. `'unsafe-eval'` is
+ * allowed on purpose — `'unsafe-inline'` already runs any code written into the file, and
+ * common CDN setups (Alpine, Vue in-DOM templates, Babel standalone) need eval.
+ *
+ * `allowModals` is for the print view only, which needs `print()`; a canvas never gets it.
+ */
+export function buildDesignCsp(source: string, opts: { allowModals?: boolean } = {}): string {
+  const cdns = DESIGN_CDN_HOSTS.map((host) => `https://${host}`).join(" ");
+  return [
+    opts.allowModals ? "sandbox allow-scripts allow-modals" : "sandbox allow-scripts",
+    "default-src 'none'",
+    `script-src 'unsafe-inline' 'unsafe-eval' ${source} ${cdns}`,
+    `style-src 'unsafe-inline' ${source} ${cdns}`,
+    `font-src ${source} data: ${cdns}`,
+    `img-src ${source} data: blob: ${cdns}`,
+    `media-src ${source} blob:`,
+    `connect-src ${source}`,
+    "base-uri 'none'",
+    "form-action 'none'",
+    "frame-ancestors 'self'",
+    "object-src 'none'",
+  ].join("; ");
+}

package/src/services/design/preview/design-preview-html.ts

@@ -0,0 +1,98 @@
+import { posix } from "node:path";
+import { readDesignFileSafe } from "../design-safe-walk.ts";
+import { decodeDesignText, MAX_DESIGN_SOURCE_BYTES, readDesignSource, type DesignSource } from "../source/design-source-file.ts";
+import { bridgeTag } from "../bridge/bridge-script.ts";
+import { analyzeHtml, injectWithoutParsing, instrumentHtml } from "./html-instrument.ts";
+import { resolveScopedPath, type ScopedAsset } from "./design-preview-scope.ts";
+import type { DesignRef } from "./design-preview-tokens.ts";
+
+/**
+ * The body the preview route sends for one design HTML file.
+ *
+ * A canvas load gets element ids and the bridge. A file over {@link INSTRUMENT_MAX_BYTES},
+ * or one that is not valid UTF-8 (whose offsets could never be written back safely), gets
+ * the bridge alone and reports `instrumented: false`, so the canvas still hears `ready` and
+ * only the features that need ids switch off. Print and standalone loads get no bridge and
+ * no ids; `inject` (the print view's style and script) goes where the bridge would.
+ */
+
+export const INSTRUMENT_MAX_BYTES = 5 * 1024 * 1024;
+/** Local stylesheets whose gen travels with `ready`; more than this is not a real design. */
+const MAX_LINKED_STYLESHEETS = 32;
+
+export interface RenderedDesignHtml {
+  body: string;
+  gen: string;
+  instrumented: boolean;
+}
+
+/**
+ * Gen of every local stylesheet the page links, keyed by its path in the design folder.
+ * The shared `../tokens.css` is left out on purpose: nothing the canvas writes may target
+ * it, because a change there restyles every design in the project.
+ */
+export async function linkedStylesheetGens(design: DesignRef, htmlRel: string, hrefs: string[]): Promise<Record<string, string>> {
+  const gens: Record<string, string> = {};
+  const baseDir = posix.dirname(htmlRel);
+  for (const href of hrefs.slice(0, MAX_LINKED_STYLESHEETS)) {
+    let rel: string;
+    try {
+      rel = posix.normalize(posix.join(baseDir, decodeURIComponent(href.split(/[?#]/)[0]!)));
+    } catch {
+      continue;
+    }
+    if (rel === ".." || rel.startsWith("../") || rel.startsWith("/")) continue;
+    try {
+      const asset = await resolveScopedPath(design, `${design.slug}/${rel}`);
+      if (gens[asset.rel]) continue;
+      gens[asset.rel] = (await readDesignSource(asset.abs, { lossy: true, maxBytes: INSTRUMENT_MAX_BYTES })).gen;
+    } catch {
+      // Missing, refused or oversized: the page cannot load it either, so there is no gen to guard.
+    }
+  }
+  return gens;
+}
+
+/** `snippet` at the head insertion point, or after the doctype when the file is too big to parse. */
+function injectPlain(text: string, snippet: string): string {
+  if (text.length <= INSTRUMENT_MAX_BYTES) {
+    try {
+      const at = analyzeHtml(text).headOffset;
+      return text.slice(0, at) + snippet + text.slice(at);
+    } catch {
+      // Unparseable: fall through to the position that needs no parse.
+    }
+  }
+  return injectWithoutParsing(text, snippet);
+}
+
+export async function renderDesignHtml(
+  design: DesignRef,
+  asset: ScopedAsset,
+  opts: { nonce: string | null; withBridge: boolean; inject?: string },
+): Promise<RenderedDesignHtml> {
+  const bytes = await readDesignFileSafe(asset.abs, MAX_DESIGN_SOURCE_BYTES);
+  let source: DesignSource;
+  let utf8 = true;
+  try {
+    source = decodeDesignText(bytes);
+  } catch {
+    source = decodeDesignText(bytes, { lossy: true });
+    utf8 = false;
+  }
+  const { text, gen } = source;
+  if (!opts.withBridge) return { body: opts.inject ? injectPlain(text, opts.inject) : text, gen, instrumented: false };
+
+  const tag = (instrumented: boolean, cssGens: Record<string, string>): string =>
+    bridgeTag({ nonce: opts.nonce, gen, cssGens, file: asset.rel, instrumented });
+  if (utf8 && bytes.byteLength <= INSTRUMENT_MAX_BYTES) {
+    try {
+      const analysis = analyzeHtml(text);
+      const cssGens = await linkedStylesheetGens(design, asset.rel, analysis.stylesheetHrefs);
+      return { body: instrumentHtml(text, tag(true, cssGens), analysis), gen, instrumented: true };
+    } catch (e) {
+      console.warn(`[design-preview] instrumenting ${design.slug}/${asset.rel} failed: ${(e as Error).message}`);
+    }
+  }
+  return { body: injectWithoutParsing(text, tag(false, {})), gen, instrumented: false };
+}