paper-mono 0.62.0

package/bin/chunks/chunk-UHVY2TIH.js

@@ -0,0 +1,3264 @@
+import {
+  getAgentDir,
+  getPackageDir
+} from "./chunk-BGKLQ5Y6.js";
+
+// src/tool-contract.ts
+import { createHash as createHash2 } from "node:crypto";
+import { join as join2, resolve as resolve2 } from "node:path";
+
+// ../../node_modules/@creative-int/mono/dist/tool-contract.js
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+var MONO_TOOLS_CONTRACT_VERSION = "mono-tools.v1";
+var MONO_TOOL_SAFETY_MODES = [
+  "mock",
+  "dry_run",
+  "sandbox",
+  "confirm-gate"
+];
+function validateMonoToolContract(value) {
+  const errors = [];
+  if (!isRecord(value)) {
+    return { valid: false, errors: ["contract must be a JSON object"] };
+  }
+  if (value.schemaVersion !== MONO_TOOLS_CONTRACT_VERSION) {
+    errors.push(`schemaVersion must be ${MONO_TOOLS_CONTRACT_VERSION}`);
+  }
+  requireNonEmptyString(value, "specialist", errors);
+  requireNonEmptyString(value, "ownerCommand", errors);
+  requireNonEmptyString(value, "agentHome", errors);
+  if (!Array.isArray(value.tools)) {
+    errors.push("tools must be an array");
+  } else {
+    value.tools.forEach((tool, index) => {
+      validateToolContractEntry(tool, `tools[${index}]`, errors);
+    });
+    const ids = value.tools.filter(isRecord).map((tool) => tool.id).filter((id) => typeof id === "string");
+    const duplicates = duplicateValues(ids);
+    if (duplicates.length > 0) {
+      errors.push(`tools contains duplicate ids: ${duplicates.join(", ")}`);
+    }
+  }
+  if (value.domain !== void 0) {
+    if (!isRecord(value.domain)) {
+      errors.push("domain must be an object when provided");
+    } else {
+      if (typeof value.domain.comment !== "string" || !value.domain.comment.startsWith("REQ:")) {
+        errors.push("domain.comment must start with REQ:");
+      }
+      if (!isStringArray(value.domain.toolIds)) {
+        errors.push("domain.toolIds must be an array of strings");
+      } else if (Array.isArray(value.tools)) {
+        const ids = new Set(value.tools.filter(isRecord).map((tool) => tool.id).filter((id) => typeof id === "string"));
+        const unknown = value.domain.toolIds.filter((id) => !ids.has(id));
+        if (unknown.length > 0) {
+          errors.push(`domain.toolIds references undeclared tools: ${unknown.join(", ")}`);
+        }
+      }
+    }
+  }
+  return { valid: errors.length === 0, errors };
+}
+function assertMonoToolContract(value) {
+  const validation = validateMonoToolContract(value);
+  if (!validation.valid) {
+    throw new Error(["Invalid mono tool contract.", ...validation.errors].join("\n"));
+  }
+}
+function parseMonoToolContract(source) {
+  let value;
+  try {
+    value = JSON.parse(source);
+  } catch (error) {
+    throw new Error(`Invalid mono tool contract JSON: ${error instanceof Error ? error.message : String(error)}`);
+  }
+  assertMonoToolContract(value);
+  return value;
+}
+function hashMonoToolContractSource(source) {
+  return `sha256:${createHash("sha256").update(source).digest("hex")}`;
+}
+function loadMonoToolContract(filePath) {
+  const contractPath = resolve(filePath);
+  const source = readFileSync(contractPath, "utf8");
+  return {
+    contract: parseMonoToolContract(source),
+    contractPath,
+    source,
+    hash: hashMonoToolContractSource(source)
+  };
+}
+function renderMonoToolPromptInventory(contract) {
+  assertMonoToolContract(contract);
+  return contract.tools.map((tool) => {
+    const fallback = tool.cliFallback ? `<cli_fallback>${escapeXml(tool.cliFallback)}</cli_fallback>` : "<cli_fallback>none; call the registered tool directly</cli_fallback>";
+    return [
+      `<tool id="${escapeXml(tool.id)}" safety="${tool.safety}">`,
+      `  <description>${escapeXml(tool.description)}</description>`,
+      `  ${fallback}`,
+      ...tool.guidelines.map((guideline) => `  <guideline>${escapeXml(guideline)}</guideline>`),
+      "</tool>"
+    ].join("\n");
+  }).join("\n    ");
+}
+function extractMonoPromptToolIds(prompt) {
+  return [...prompt.matchAll(/<tool id="([^"]+)"\s+safety=/g)].map((match) => match[1] ?? "");
+}
+function assertMonoToolContractHandshake(input) {
+  const contractToolIds = input.contract.tools.map((tool) => tool.id);
+  const registeredToolIds = [...input.registeredToolIds];
+  const customDefinitionToolIds = input.customDefinitionToolIds ? [...input.customDefinitionToolIds] : void 0;
+  const promptToolIds = input.promptToolIds ? [...input.promptToolIds] : extractMonoPromptToolIds(input.prompt ?? "");
+  const activeToolIds = input.activeToolIds ? [...input.activeToolIds] : void 0;
+  const agentHome = resolveMonoAgentHome(input.contract, input.agentHome, input.cwd);
+  const comparisons = [
+    ["registered", registeredToolIds],
+    ["prompt", promptToolIds]
+  ];
+  if (customDefinitionToolIds) {
+    comparisons.push(["custom-definitions", customDefinitionToolIds]);
+  }
+  if (activeToolIds)
+    comparisons.push(["active-session", activeToolIds]);
+  const failures = comparisons.flatMap(([label, ids]) => setDiff(contractToolIds, ids, label));
+  const duplicateFailures = [
+    ...duplicateDiff(contractToolIds, "contract"),
+    ...duplicateDiff(registeredToolIds, "registered"),
+    ...duplicateDiff(promptToolIds, "prompt"),
+    ...customDefinitionToolIds ? duplicateDiff(customDefinitionToolIds, "custom-definitions") : [],
+    ...activeToolIds ? duplicateDiff(activeToolIds, "active-session") : []
+  ];
+  if (failures.length > 0 || duplicateFailures.length > 0) {
+    throw new Error([
+      `${titleCase(input.contract.specialist)} tool-contract handshake failed.`,
+      `contractHash: ${input.contractHash}`,
+      `agentHome: ${agentHome}`,
+      ...failures,
+      ...duplicateFailures
+    ].join("\n"));
+  }
+  return {
+    contractHash: input.contractHash,
+    agentHome,
+    contractToolIds,
+    registeredToolIds,
+    ...customDefinitionToolIds ? { customDefinitionToolIds } : {},
+    promptToolIds,
+    ...activeToolIds ? { activeToolIds } : {}
+  };
+}
+function resolveMonoAgentHome(contract, requested, cwd = process.cwd()) {
+  const canonical = resolvePath(contract.agentHome, cwd);
+  if (!requested)
+    return canonical;
+  const resolved = resolvePath(requested, cwd);
+  if (resolved !== canonical) {
+    throw new Error([
+      `${titleCase(contract.specialist)} agent-home handshake failed.`,
+      `contract: ${canonical}`,
+      `requested: ${resolved}`,
+      "The owner command, direct runtime, and workflow entrypoints must use one agent home."
+    ].join("\n"));
+  }
+  return canonical;
+}
+function resolveMonoContractRef(contractPath, reference) {
+  const [relativePath] = reference.split("#", 1);
+  if (!relativePath) {
+    throw new Error(`Invalid mono contract reference: ${reference}`);
+  }
+  return resolve(dirname(contractPath), relativePath);
+}
+function assertMonoContractFixturesExist(loaded) {
+  const missing = loaded.contract.tools.flatMap((tool) => [...tool.cases, ...tool.safetyContract?.fixtureRefs ?? []].map((reference) => resolveMonoContractRef(loaded.contractPath, reference)).filter((filePath) => !existsSync(filePath)).map((filePath) => `${tool.id}: ${filePath}`));
+  if (missing.length > 0) {
+    throw new Error(["Mono tool-contract fixture references are missing.", ...missing].join("\n"));
+  }
+}
+function validateToolContractEntry(value, path, errors) {
+  if (!isRecord(value)) {
+    errors.push(`${path} must be an object`);
+    return;
+  }
+  for (const key of [
+    "id",
+    "label",
+    "description",
+    "handlerRef",
+    "inputSchemaRef",
+    "doctorProbe"
+  ]) {
+    requireNonEmptyString(value, key, errors, path);
+  }
+  if (!Number.isInteger(value.version) || Number(value.version) < 1) {
+    errors.push(`${path}.version must be a positive integer`);
+  }
+  if (value.sourcePack !== null && typeof value.sourcePack !== "string") {
+    errors.push(`${path}.sourcePack must be a string or null`);
+  }
+  if (value.safety !== "read" && value.safety !== "mutate") {
+    errors.push(`${path}.safety must be read or mutate`);
+  }
+  if (value.safetyContract !== void 0) {
+    validateToolSafetyContract(value.safetyContract, value.output, path, errors);
+  }
+  for (const key of ["demandRefs", "cases", "guidelines"]) {
+    if (!isStringArray(value[key]) || value[key].length === 0) {
+      errors.push(`${path}.${key} must be a non-empty array of strings`);
+    }
+  }
+  if (value.cliFallback !== null && typeof value.cliFallback !== "string") {
+    errors.push(`${path}.cliFallback must be a string or null`);
+  }
+  if (!isRecord(value.requires)) {
+    errors.push(`${path}.requires must be an object`);
+  } else {
+    for (const key of ["allOf", "anyOf", "cli", "endpoint"]) {
+      if (!isStringArray(value.requires[key])) {
+        errors.push(`${path}.requires.${key} must be an array of strings`);
+      }
+    }
+    if (typeof value.requires.optional !== "boolean") {
+      errors.push(`${path}.requires.optional must be boolean`);
+    }
+  }
+  if (!isRecord(value.output)) {
+    errors.push(`${path}.output must be an object`);
+  } else {
+    if (value.output.envelope !== "mono-tool-result.v1") {
+      errors.push(`${path}.output.envelope must be mono-tool-result.v1`);
+    }
+    for (const key of ["maxBytes", "maxItems"]) {
+      if (!Number.isFinite(value.output[key]) || Number(value.output[key]) <= 0) {
+        errors.push(`${path}.output.${key} must be a positive number`);
+      }
+    }
+  }
+}
+function validateToolSafetyContract(value, output, path, errors) {
+  if (!isRecord(value)) {
+    errors.push(`${path}.safetyContract must be an object`);
+    return;
+  }
+  if (!isStringArray(value.modes) || value.modes.length === 0) {
+    errors.push(`${path}.safetyContract.modes must be a non-empty array of strings`);
+    return;
+  }
+  const modes = value.modes;
+  const invalidModes = modes.filter((mode) => !MONO_TOOL_SAFETY_MODES.includes(mode));
+  if (invalidModes.length > 0) {
+    errors.push(`${path}.safetyContract.modes contains invalid modes: ${invalidModes.join(", ")}`);
+  }
+  const duplicateModes = duplicateValues(modes);
+  if (duplicateModes.length > 0) {
+    errors.push(`${path}.safetyContract.modes contains duplicates: ${duplicateModes.join(", ")}`);
+  }
+  if (!isRecord(value.guarantees)) {
+    errors.push(`${path}.safetyContract.guarantees must be an object`);
+  } else {
+    for (const mode of modes) {
+      validateToolSafetyGuarantee(value.guarantees[mode], mode, `${path}.safetyContract.guarantees.${mode}`, errors);
+    }
+  }
+  if (!isStringArray(value.fixtureRefs) || value.fixtureRefs.length === 0) {
+    errors.push(`${path}.safetyContract.fixtureRefs must be a non-empty array of strings`);
+  }
+  if (!isRecord(value.outputBudget)) {
+    errors.push(`${path}.safetyContract.outputBudget must be an object`);
+  } else {
+    for (const key of ["maxBytes", "maxLines"]) {
+      if (!Number.isInteger(value.outputBudget[key]) || Number(value.outputBudget[key]) <= 0) {
+        errors.push(`${path}.safetyContract.outputBudget.${key} must be a positive integer`);
+      }
+    }
+    if (isRecord(output) && Number.isFinite(output.maxBytes) && Number.isFinite(value.outputBudget.maxBytes) && Number(value.outputBudget.maxBytes) > Number(output.maxBytes)) {
+      errors.push(`${path}.safetyContract.outputBudget.maxBytes must not exceed output.maxBytes`);
+    }
+  }
+}
+function validateToolSafetyGuarantee(value, mode, path, errors) {
+  if (!isRecord(value)) {
+    errors.push(`${path} must be an object`);
+    return;
+  }
+  if (value.networkSpend !== "forbidden" && value.networkSpend !== "declared") {
+    errors.push(`${path}.networkSpend must be forbidden or declared`);
+  }
+  if (value.filesystemWrites !== "none" && value.filesystemWrites !== "declared-roots") {
+    errors.push(`${path}.filesystemWrites must be none or declared-roots`);
+  }
+  if (!isStringArray(value.filesystemRoots)) {
+    errors.push(`${path}.filesystemRoots must be an array of strings`);
+  } else if (value.filesystemWrites === "declared-roots" && value.filesystemRoots.length === 0) {
+    errors.push(`${path}.filesystemRoots must declare at least one root`);
+  } else if (value.filesystemWrites === "none" && value.filesystemRoots.length > 0) {
+    errors.push(`${path}.filesystemRoots must be empty when writes are none`);
+  }
+  if (value.externalMutations !== "forbidden" && value.externalMutations !== "confirm-gated") {
+    errors.push(`${path}.externalMutations must be forbidden or confirm-gated`);
+  }
+  if (typeof value.requiresConfirmation !== "boolean") {
+    errors.push(`${path}.requiresConfirmation must be boolean`);
+  }
+  if (mode === "confirm-gate" && (value.externalMutations !== "confirm-gated" || value.requiresConfirmation !== true)) {
+    errors.push(`${path} must require confirmation and declare confirm-gated mutations`);
+  }
+  if ((mode === "mock" || mode === "dry_run" || mode === "sandbox") && value.networkSpend !== "forbidden") {
+    errors.push(`${path}.networkSpend must be forbidden for ${mode}`);
+  }
+}
+function requireNonEmptyString(value, key, errors, path = "contract") {
+  if (typeof value[key] !== "string" || value[key].trim() === "") {
+    errors.push(`${path}.${key} must be a non-empty string`);
+  }
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isStringArray(value) {
+  return Array.isArray(value) && value.every((item) => typeof item === "string");
+}
+function resolvePath(value, cwd) {
+  if (value === "~")
+    return homedir();
+  if (value.startsWith("~/"))
+    return join(homedir(), value.slice(2));
+  if (isAbsolute(value))
+    return resolve(value);
+  return resolve(cwd, value);
+}
+function setDiff(contractIds, candidateIds, label) {
+  const contract = new Set(contractIds);
+  const candidate = new Set(candidateIds);
+  const missing = contractIds.filter((id) => !candidate.has(id));
+  const extra = candidateIds.filter((id) => !contract.has(id));
+  return [
+    ...missing.length > 0 ? [`${label} missing: ${missing.join(", ")}`] : [],
+    ...extra.length > 0 ? [`${label} extra: ${extra.join(", ")}`] : []
+  ];
+}
+function duplicateDiff(values, label) {
+  const duplicates = duplicateValues(values);
+  return duplicates.length > 0 ? [`${label} duplicates: ${duplicates.join(", ")}`] : [];
+}
+function duplicateValues(values) {
+  const seen = /* @__PURE__ */ new Set();
+  const duplicates = /* @__PURE__ */ new Set();
+  for (const value of values) {
+    if (seen.has(value))
+      duplicates.add(value);
+    seen.add(value);
+  }
+  return [...duplicates];
+}
+function titleCase(value) {
+  return value.split(/[-_\s]+/).filter(Boolean).map((segment) => `${segment[0]?.toUpperCase() ?? ""}${segment.slice(1)}`).join(" ");
+}
+function escapeXml(value) {
+  return value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll('"', "&quot;").replaceAll("'", "&apos;");
+}
+
+// src/core/tools/paper-mcp.ts
+import { existsSync as existsSync2, mkdirSync, writeFileSync } from "node:fs";
+import { dirname as dirname2, isAbsolute as isAbsolute2 } from "node:path";
+import { Type } from "@sinclair/typebox";
+var PAPER_MCP_URL = "http://127.0.0.1:29979/mcp";
+var TIMEOUT_MS = 3e4;
+var PAPER_DESKTOP_TOOL_NAMES = {
+  paper_get_basic_info: "get_basic_info",
+  paper_get_selection: "get_selection",
+  paper_get_node_info: "get_node_info",
+  paper_get_children: "get_children",
+  paper_get_tree_summary: "get_tree_summary",
+  paper_get_screenshot: "get_screenshot",
+  paper_get_jsx: "get_jsx",
+  paper_get_computed_styles: "get_computed_styles",
+  paper_get_fill_image: "get_fill_image",
+  paper_find_nodes: "find_nodes",
+  paper_get_font_family_info: "get_font_family_info",
+  paper_get_guide: "get_guide",
+  paper_find_placement: "find_placement",
+  paper_get_tokens: "get_tokens",
+  paper_create_tokens: "create_tokens",
+  paper_set_tokens: "set_tokens",
+  paper_create_artboard: "create_artboard",
+  paper_write_html: "write_html",
+  paper_set_text_content: "set_text_content",
+  paper_rename_nodes: "rename_nodes",
+  paper_duplicate_nodes: "duplicate_nodes",
+  paper_update_styles: "update_styles",
+  paper_delete_nodes: "delete_nodes",
+  paper_move_nodes: "move_nodes",
+  paper_finish_working_on_nodes: "finish_working_on_nodes",
+  paper_create_page: "create_page",
+  paper_open_page: "open_file"
+};
+function resolvePaperDesktopToolName(toolName) {
+  return PAPER_DESKTOP_TOOL_NAMES[toolName] ?? toolName;
+}
+var requestId = 1;
+var PaperPageOperationError = class extends Error {
+  constructor(operation, code, message, diagnostic) {
+    super(message);
+    this.operation = operation;
+    this.code = code;
+    this.diagnostic = diagnostic;
+    this.name = "PaperPageOperationError";
+  }
+};
+async function callPaperMcp(toolName, args, signal, timeoutMs = TIMEOUT_MS) {
+  const id = requestId++;
+  const desktopToolName = resolvePaperDesktopToolName(toolName);
+  const body = JSON.stringify({
+    jsonrpc: "2.0",
+    method: "tools/call",
+    params: { name: desktopToolName, arguments: args },
+    id
+  });
+  let endpointReached = false;
+  try {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), timeoutMs);
+    if (signal) {
+      signal.addEventListener("abort", () => controller.abort(), { once: true });
+    }
+    let resp;
+    try {
+      resp = await fetch(PAPER_MCP_URL, {
+        method: "POST",
+        headers: { "Content-Type": "application/json", Accept: "application/json, text/event-stream" },
+        body,
+        signal: controller.signal
+      });
+      endpointReached = true;
+    } finally {
+      clearTimeout(timeout);
+    }
+    if (!resp.ok) {
+      return {
+        ok: false,
+        error: `Paper MCP returned ${resp.status} ${resp.statusText}`,
+        failure: "contract",
+        desktopToolName
+      };
+    }
+    const text = await resp.text();
+    let json;
+    const dataMatch = text.match(/^data: (.+)$/m);
+    if (dataMatch) {
+      json = JSON.parse(dataMatch[1]);
+    } else {
+      json = JSON.parse(text);
+    }
+    if (json.error) {
+      return {
+        ok: false,
+        error: `Paper MCP error calling ${desktopToolName}: ${json.error.message}`,
+        failure: "contract",
+        desktopToolName
+      };
+    }
+    const providerError = getMcpProviderError(json.result);
+    if (providerError) {
+      return {
+        ok: false,
+        error: `Paper MCP tool ${desktopToolName} failed: ${providerError}`,
+        failure: "contract",
+        desktopToolName
+      };
+    }
+    return { ok: true, result: json.result, desktopToolName };
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    if (!endpointReached) {
+      return {
+        ok: false,
+        error: "Paper Desktop is not running. Open a file in Paper Desktop to start the MCP server (http://127.0.0.1:29979/mcp).",
+        failure: "unreachable",
+        desktopToolName
+      };
+    }
+    return {
+      ok: false,
+      error: `Paper MCP contract error calling ${desktopToolName}: ${message}`,
+      failure: "contract",
+      desktopToolName
+    };
+  }
+}
+var PAPER_HIGH_VOLUME_RESPONSE_LIMITS = {
+  maxTextUtf8Bytes: 160 * 1024,
+  maxDecodedImageBytes: 6 * 1024 * 1024
+};
+function formatMcpResult(result) {
+  if (!result || typeof result !== "object") {
+    return [{ type: "text", text: JSON.stringify(result, null, 2) }];
+  }
+  const r = result;
+  const content = r.content;
+  if (!Array.isArray(content)) {
+    return [{ type: "text", text: JSON.stringify(result, null, 2) }];
+  }
+  const parts = [];
+  for (const item of content) {
+    if (typeof item !== "object" || item === null) continue;
+    const entry = item;
+    if (entry.type === "text" && typeof entry.text === "string") {
+      parts.push({ type: "text", text: entry.text });
+    } else if (entry.type === "image" && typeof entry.data === "string") {
+      parts.push({
+        type: "image",
+        data: entry.data,
+        mimeType: typeof entry.mimeType === "string" ? entry.mimeType : "image/png"
+      });
+    }
+  }
+  if (parts.length === 0) {
+    return [{ type: "text", text: JSON.stringify(result, null, 2) }];
+  }
+  return parts;
+}
+function decodedBase64ByteLength(data) {
+  if (data.length === 0) return 0;
+  const paddingBytes = data.endsWith("==") ? 2 : data.endsWith("=") ? 1 : 0;
+  return Math.max(0, Math.floor(data.length * 3 / 4) - paddingBytes);
+}
+function formatMcpResultWithinBudget(def, result) {
+  const parts = formatMcpResult(result);
+  const budget = def.responseBudget;
+  if (!budget) return parts;
+  const observedTextBytes = parts.reduce(
+    (total, part) => total + (part.type === "text" ? Buffer.byteLength(part.text, "utf8") : 0),
+    0
+  );
+  const observedImageBytes = parts.reduce(
+    (total, part) => total + (part.type === "image" ? decodedBase64ByteLength(part.data) : 0),
+    0
+  );
+  if (observedTextBytes <= budget.maxTextUtf8Bytes && observedImageBytes <= budget.maxDecodedImageBytes) {
+    return parts;
+  }
+  const retained = [];
+  let retainedTextBytes = 0;
+  let retainedImageBytes = 0;
+  let suppressedTextParts = 0;
+  let suppressedImageParts = 0;
+  for (const part of parts) {
+    if (part.type === "text") {
+      const bytes2 = Buffer.byteLength(part.text, "utf8");
+      if (retainedTextBytes + bytes2 > budget.maxTextUtf8Bytes) {
+        suppressedTextParts += 1;
+        continue;
+      }
+      retainedTextBytes += bytes2;
+      retained.push(part);
+      continue;
+    }
+    const bytes = decodedBase64ByteLength(part.data);
+    if (retainedImageBytes + bytes > budget.maxDecodedImageBytes) {
+      suppressedImageParts += 1;
+      continue;
+    }
+    retainedImageBytes += bytes;
+    retained.push(part);
+  }
+  const receiptSuffix = `Nothing was truncated or returned partially. ${budget.retryGuidance}`;
+  if (suppressedTextParts > 0) {
+    retained.push({
+      type: "text",
+      text: `Paper suppressed ${suppressedTextParts} over-budget text content part${suppressedTextParts === 1 ? "" : "s"} from ${def.name} (observed ${observedTextBytes} UTF-8 bytes; configured limit ${budget.maxTextUtf8Bytes} bytes). ${receiptSuffix}`
+    });
+  }
+  if (suppressedImageParts > 0) {
+    retained.push({
+      type: "text",
+      text: `Paper suppressed ${suppressedImageParts} over-budget image content part${suppressedImageParts === 1 ? "" : "s"} from ${def.name} (observed ${observedImageBytes} decoded bytes; configured limit ${budget.maxDecodedImageBytes} bytes). ${receiptSuffix}`
+    });
+  }
+  return retained;
+}
+function parseMcpTextContent(result) {
+  const parts = formatMcpResult(result);
+  const textParts = parts.filter((p) => p.type === "text").map((p) => p.text);
+  return textParts.length > 0 ? textParts.join("\n") : void 0;
+}
+var PaperMaterializationError = class extends Error {
+  constructor(stage, message, artboardId) {
+    super(`Paper materialization stopped at ${stage}: ${message}`);
+    this.stage = stage;
+    this.artboardId = artboardId;
+    this.code = "PAPER_MATERIALIZATION_FAILED";
+    this.name = "PaperMaterializationError";
+  }
+};
+var MATERIALIZATION_STEPS = [
+  "paper_create_artboard",
+  "paper_write_html",
+  "paper_get_screenshot",
+  "paper_finish_working_on_nodes"
+];
+function unwrapMcpTextJson(result) {
+  const text = parseMcpTextContent(result);
+  if (!text) return result;
+  try {
+    return JSON.parse(text);
+  } catch {
+    return result;
+  }
+}
+function findFirstStringByKeys(value, keys) {
+  const queue = [unwrapMcpTextJson(value)];
+  let visited = 0;
+  while (queue.length > 0 && visited < 500) {
+    visited += 1;
+    const current = queue.shift();
+    if (Array.isArray(current)) {
+      queue.push(...current);
+      continue;
+    }
+    if (!current || typeof current !== "object") continue;
+    for (const [key, entry] of Object.entries(current)) {
+      if (keys.has(key) && typeof entry === "string" && entry.trim()) return entry.trim();
+      if (entry && typeof entry === "object") queue.push(entry);
+    }
+  }
+  return void 0;
+}
+function findFirstNumberByKey(value, key) {
+  const queue = [unwrapMcpTextJson(value)];
+  let visited = 0;
+  while (queue.length > 0 && visited < 500) {
+    visited += 1;
+    const current = queue.shift();
+    if (Array.isArray(current)) {
+      queue.push(...current);
+      continue;
+    }
+    if (!current || typeof current !== "object") continue;
+    for (const [entryKey, entry] of Object.entries(current)) {
+      if (entryKey === key && typeof entry === "number" && Number.isFinite(entry)) return entry;
+      if (entry && typeof entry === "object") queue.push(entry);
+    }
+  }
+  return void 0;
+}
+function normalizeMaterializationInput(input) {
+  const name = input.name.trim();
+  const html = input.html.trim();
+  if (!name) throw new TypeError("materializeDirection requires a non-empty artboard name.");
+  if (!Number.isFinite(input.width) || input.width < 1) {
+    throw new TypeError("materializeDirection requires a positive finite width.");
+  }
+  if (!Number.isFinite(input.height) || input.height < 1) {
+    throw new TypeError("materializeDirection requires a positive finite height.");
+  }
+  if (!html) throw new TypeError("materializeDirection requires non-empty literal inline-CSS HTML.");
+  if (/\bclass\s*=/i.test(html) || /var\s*\(/i.test(html) || /<script\b/i.test(html)) {
+    throw new TypeError(
+      "materializeDirection accepts literal inline-CSS HTML only (no class attributes, CSS variables, or scripts)."
+    );
+  }
+  return {
+    name,
+    width: input.width,
+    height: input.height,
+    html,
+    confirm: input.confirm === true,
+    dryRun: input.dryRun === true
+  };
+}
+async function callMaterializationStage(callTool, stage, toolName, args, artboardId) {
+  try {
+    return await callTool(toolName, args);
+  } catch (error) {
+    throw new PaperMaterializationError(stage, error instanceof Error ? error.message : String(error), artboardId);
+  }
+}
+function buildMaterializationReceipt(payload) {
+  const materialized = payload.status === "materialized";
+  const evidence = materialized ? [
+    {
+      kind: "paper-artboard",
+      locator: `paper://node/${payload.artboardId}`,
+      accessClass: "private-corpus"
+    },
+    {
+      kind: "paper-screenshot",
+      locator: `paper://node/${payload.artboardId}/screenshot`,
+      accessClass: "private-corpus"
+    }
+  ] : [
+    {
+      kind: "paper-materialization-preview",
+      locator: `paper://materialize-direction/${encodeURIComponent(payload.name)}`,
+      accessClass: "private"
+    }
+  ];
+  return {
+    workflowId: "paper.materializeDirection.v1",
+    summary: materialized ? `Created and screenshot-verified adjacent artboard \u201C${payload.name}\u201D.` : `Previewed an adjacent ${payload.width}\xD7${payload.height} artboard named \u201C${payload.name}\u201D; no Paper mutation ran.`,
+    evidence,
+    sourceNotes: [
+      "Paper Desktop remains the source of truth for canvas state.",
+      "The operation uses literal inline-CSS HTML and inserts children only into the newly created artboard."
+    ],
+    riskNotes: [
+      "A live write requires confirm=true and dryRun!=true.",
+      "The operation never deletes, replaces, renames, or updates source artboards."
+    ],
+    nextActions: materialized ? ["Inspect the returned screenshot before treating the direction as accepted."] : ["Review the preview and rerun with confirm=true to create the adjacent artboard."],
+    payload: { ...payload, steps: MATERIALIZATION_STEPS, sourceArtboardsMutated: false }
+  };
+}
+async function materializeDirection(input, io) {
+  const normalized = normalizeMaterializationInput(input);
+  if (!normalized.confirm || normalized.dryRun) {
+    return {
+      receipt: buildMaterializationReceipt({
+        status: "dry-run",
+        artboardId: null,
+        name: normalized.name,
+        width: normalized.width,
+        height: normalized.height,
+        placement: { x: null, y: null },
+        verifiedBy: null
+      }),
+      screenshot: []
+    };
+  }
+  const createResult = await callMaterializationStage(io.callTool, "create-artboard", "paper_create_artboard", {
+    name: normalized.name,
+    styles: { width: `${normalized.width}px`, height: `${normalized.height}px` }
+  });
+  const artboardId = findFirstStringByKeys(createResult, /* @__PURE__ */ new Set(["nodeId", "artboardId", "id"]));
+  if (!artboardId) {
+    throw new PaperMaterializationError(
+      "create-artboard",
+      "Paper created the artboard but returned no node ID, so writing and verification stopped safely."
+    );
+  }
+  await callMaterializationStage(
+    io.callTool,
+    "write-html",
+    "paper_write_html",
+    { targetNodeId: artboardId, html: normalized.html, mode: "insert-children" },
+    artboardId
+  );
+  const screenshotResult = await callMaterializationStage(
+    io.callTool,
+    "screenshot",
+    "paper_get_screenshot",
+    { nodeId: artboardId, scale: 1 },
+    artboardId
+  );
+  await callMaterializationStage(
+    io.callTool,
+    "finish-working",
+    "paper_finish_working_on_nodes",
+    { nodeIds: [artboardId] },
+    artboardId
+  );
+  return {
+    receipt: buildMaterializationReceipt({
+      status: "materialized",
+      artboardId,
+      name: normalized.name,
+      width: normalized.width,
+      height: normalized.height,
+      placement: {
+        x: findFirstNumberByKey(createResult, "worldX") ?? findFirstNumberByKey(createResult, "x") ?? null,
+        y: findFirstNumberByKey(createResult, "worldY") ?? findFirstNumberByKey(createResult, "y") ?? null
+      },
+      verifiedBy: "paper_get_screenshot"
+    }),
+    screenshot: formatMcpResult(screenshotResult).filter((part) => part.type === "image").map(({ data, mimeType }) => ({ data, mimeType }))
+  };
+}
+function collectUniqueValues(styles, property) {
+  const values = /* @__PURE__ */ new Set();
+  for (const nodeStyles of Object.values(styles)) {
+    if (typeof nodeStyles !== "object" || nodeStyles === null) continue;
+    const ns = nodeStyles;
+    const value = ns[property];
+    if (typeof value === "string" && value.trim()) {
+      values.add(value);
+    }
+  }
+  return Array.from(values);
+}
+function extractColorTokens(styles) {
+  const colorProps = ["color", "backgroundColor", "borderColor", "fill"];
+  const buckets = {};
+  for (const prop of colorProps) {
+    buckets[prop] = collectUniqueValues(styles, prop);
+  }
+  return buckets;
+}
+var PAPER_TREE_DEFAULT_DEPTH = 4;
+var PAPER_TREE_MIN_DEPTH = 1;
+var PAPER_TREE_MAX_DEPTH = 8;
+var PAPER_COMPUTED_STYLES_MAX_NODE_IDS = 50;
+function highVolumeReadBudget(retryGuidance) {
+  return { ...PAPER_HIGH_VOLUME_RESPONSE_LIMITS, retryGuidance };
+}
+var optionalFileIdSchema = Type.Optional(
+  Type.String({
+    minLength: 1,
+    description: "Explicit Paper file ID. Pass this whenever multiple files may be open; omitting it follows this MCP session's most recently opened file."
+  })
+);
+var requiredFileIdSchema = Type.String({
+  minLength: 1,
+  description: "Explicit Paper file ID. Live Paper mutations refuse to infer the frontmost file."
+});
+function optionalFileId(value) {
+  if (value === void 0) return void 0;
+  if (typeof value !== "string" || !value.trim()) {
+    throw new TypeError("Paper fileId must be a non-empty string when provided.");
+  }
+  return value.trim();
+}
+function boundedTreeSummaryDepth(value) {
+  if (value === void 0) return PAPER_TREE_DEFAULT_DEPTH;
+  if (typeof value !== "number" || !Number.isInteger(value) || value < PAPER_TREE_MIN_DEPTH || value > PAPER_TREE_MAX_DEPTH) {
+    throw new TypeError(
+      `paper_get_tree_summary depth must be an integer from ${PAPER_TREE_MIN_DEPTH} through ${PAPER_TREE_MAX_DEPTH}; the default is ${PAPER_TREE_DEFAULT_DEPTH}.`
+    );
+  }
+  return value;
+}
+function boundedComputedStyleNodeIds(value) {
+  if (!Array.isArray(value) || value.length < 1 || value.length > PAPER_COMPUTED_STYLES_MAX_NODE_IDS || value.some((id) => typeof id !== "string" || id.length === 0)) {
+    throw new TypeError(
+      `paper_get_computed_styles accepts between 1 and ${PAPER_COMPUTED_STYLES_MAX_NODE_IDS} node IDs per call. Retry with a smaller targeted batch.`
+    );
+  }
+  return value;
+}
+function providerArgsForTool(def, args) {
+  const { _fixture: _ignoredFixture, dryRun: _ignoredDryRun, fileId: rawFileId, ...toolArgs } = args;
+  const mappedArgs = def.mapArgs ? def.mapArgs(toolArgs) : toolArgs;
+  const fileId = optionalFileId(rawFileId);
+  return fileId && def.fileIdPassthrough !== false ? { ...mappedArgs, fileId } : mappedArgs;
+}
+function createDryRunResult(def, args) {
+  const mappedArgs = providerArgsForTool(def, args);
+  const desktopToolName = resolvePaperDesktopToolName(def.name);
+  return {
+    content: [
+      {
+        type: "text",
+        text: `Dry run for ${desktopToolName}: would execute with arguments ${JSON.stringify(mappedArgs, null, 2)}. Pass dryRun=false to apply.`
+      }
+    ],
+    details: { dryRun: true, mcpTool: desktopToolName, arguments: mappedArgs }
+  };
+}
+function createPaperTool(def) {
+  return {
+    name: def.name,
+    label: def.label,
+    description: def.description,
+    parameters: def.parameters,
+    async execute(_toolCallId, params, signal) {
+      const args = params && typeof params === "object" ? params : {};
+      const desktopToolName = resolvePaperDesktopToolName(def.name);
+      const fixture = args._fixture;
+      if (fixture !== void 0 && !args.dryRun) {
+        return {
+          content: formatMcpResultWithinBudget(def, fixture),
+          details: { mcpTool: desktopToolName, fixture: true }
+        };
+      }
+      if (def.supportsDryRun && args.dryRun === true) {
+        return createDryRunResult(def, args);
+      }
+      let providerArgs;
+      try {
+        providerArgs = providerArgsForTool(def, args);
+        const fileId = optionalFileId(args.fileId);
+        if (fileId && def.fileIdPassthrough === false) {
+          await verifyPaperFileTarget(fileId, signal);
+        }
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+          content: [{ type: "text", text: message }],
+          details: { error: message }
+        };
+      }
+      const result = def.name === "paper_get_screenshot" ? await callPaperScreenshotWithReadiness(providerArgs, signal) : await callPaperMcp(def.name, providerArgs, signal);
+      if (!result.ok) {
+        return {
+          content: [{ type: "text", text: result.error }],
+          details: { error: result.error }
+        };
+      }
+      return {
+        content: formatMcpResultWithinBudget(def, result.result),
+        details: {
+          mcpTool: desktopToolName,
+          fileId: optionalFileId(args.fileId) ?? null
+        }
+      };
+    }
+  };
+}
+var dryRunSchema = Type.Optional(
+  Type.Boolean({ description: "If true, preview the operation without modifying the Paper file." })
+);
+var SOURCE_ACKNOWLEDGEMENTS = {
+  rename: "rename-source",
+  revise: "revise-source",
+  delete: "delete-source",
+  write: "write-source",
+  setTokens: "set-source-tokens",
+  move: "move-source"
+};
+var sessionCreatedNodeIds = /* @__PURE__ */ new Set();
+var sessionFileKey = null;
+function parseMcpJsonValue(result) {
+  const text = parseMcpTextContent(result);
+  if (text) {
+    try {
+      return JSON.parse(text);
+    } catch {
+      return void 0;
+    }
+  }
+  return result;
+}
+function parseMcpJsonObject(result) {
+  const parsed = parseMcpJsonValue(result);
+  return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : void 0;
+}
+function getMcpProviderError(result) {
+  if (!result || typeof result !== "object" || Array.isArray(result)) return void 0;
+  const record = result;
+  if (record.isError !== true) return void 0;
+  return parseMcpTextContent(result) ?? "Paper MCP reported an error.";
+}
+async function callRequiredPaperMcp(toolName, args, signal) {
+  const response = await callPaperMcp(toolName, args, signal);
+  if (!response.ok) throw new Error(response.error);
+  const providerError = getMcpProviderError(response.result);
+  if (providerError) throw new Error(`${toolName}: ${providerError}`);
+  return response.result;
+}
+var SCREENSHOT_RETRY_DELAYS_MS = [100, 200, 400, 800];
+function mcpResultHasImage(result) {
+  return formatMcpResult(result).some((part) => part.type === "image" && part.data.length > 0);
+}
+async function waitForPaperReadiness(delayMs, signal) {
+  if (signal?.aborted) throw new Error("Paper screenshot readiness wait was aborted.");
+  await new Promise((resolve3, reject) => {
+    const timeout = setTimeout(resolve3, delayMs);
+    if (!signal) return;
+    signal.addEventListener(
+      "abort",
+      () => {
+        clearTimeout(timeout);
+        reject(new Error("Paper screenshot readiness wait was aborted."));
+      },
+      { once: true }
+    );
+  });
+}
+async function callPaperScreenshotWithReadiness(args, signal) {
+  for (let attempt = 0; attempt <= SCREENSHOT_RETRY_DELAYS_MS.length; attempt += 1) {
+    const response = await callPaperMcp("paper_get_screenshot", args, signal);
+    if (!response.ok || mcpResultHasImage(response.result)) return response;
+    if (attempt < SCREENSHOT_RETRY_DELAYS_MS.length) {
+      try {
+        await waitForPaperReadiness(SCREENSHOT_RETRY_DELAYS_MS[attempt], signal);
+      } catch (error) {
+        return {
+          ok: false,
+          error: error instanceof Error ? error.message : String(error),
+          failure: "contract",
+          desktopToolName: response.desktopToolName
+        };
+      }
+      continue;
+    }
+    return {
+      ok: false,
+      error: "Paper screenshot page not ready: get_screenshot returned no image after 5 readiness attempts. Retry after the requested file/page finishes opening.",
+      failure: "contract",
+      desktopToolName: response.desktopToolName
+    };
+  }
+  throw new Error("Paper screenshot readiness loop ended unexpectedly.");
+}
+async function verifyPaperFileTarget(fileId, signal) {
+  const result = await callRequiredPaperMcp("paper_get_basic_info", { fileId }, signal);
+  const parsed = parseMcpJsonObject(result);
+  const target = typeof parsed?.url === "string" ? parsed.url.trim() : typeof parsed?.fileId === "string" ? parsed.fileId.trim() : "";
+  const expectedFileId = fileIdFromPaperTarget(fileId);
+  const returnedFileId = fileIdFromPaperTarget(target);
+  if (!parsed || !expectedFileId || returnedFileId !== expectedFileId) {
+    throw new Error(`Paper did not prove that explicit fileId ${fileId} was targeted.`);
+  }
+  return parsed;
+}
+function maskProviderArguments(args) {
+  return Object.fromEntries(
+    Object.entries(args).map(([key, value]) => [
+      key,
+      /(?:api.?key|authorization|password|secret|token)/i.test(key) ? "[REDACTED]" : value
+    ])
+  );
+}
+function pageDiagnostic(providerTool, args) {
+  return { providerTool, arguments: maskProviderArguments(args) };
+}
+function normalizeRequiredPageValue(value, label) {
+  if (typeof value !== "string" || !value.trim()) {
+    throw new TypeError(`An explicit non-empty Paper ${label} is required.`);
+  }
+  return value.trim();
+}
+function pageOperationError(operation, code, message, providerTool, args) {
+  return new PaperPageOperationError(operation, code, message, pageDiagnostic(providerTool, args));
+}
+function providerFailureCode(result) {
+  return result.failure === "unreachable" ? "PROVIDER_UNREACHABLE" : "PROVIDER_ERROR";
+}
+function pageIdFromProviderResult(result) {
+  const parsed = parseMcpJsonObject(result);
+  const pageId = typeof parsed?.pageId === "string" ? parsed.pageId.trim() : typeof parsed?.id === "string" ? parsed.id.trim() : "";
+  return pageId;
+}
+function fileIdFromPaperTarget(target) {
+  const routeMatch = target.match(/(?:^|\/)file\/([^/?#]+)/);
+  if (routeMatch?.[1]) return routeMatch[1];
+  return target.includes("/") || target.includes(":") ? void 0 : target;
+}
+function toPaperPageFailureReceipt(error) {
+  return {
+    status: "failed",
+    operation: error.operation,
+    error: { code: error.code, message: error.message },
+    diagnostic: error.diagnostic
+  };
+}
+async function createPaperPage(input, signal) {
+  const rawArgs = { fileId: input?.fileId, name: input?.name };
+  let fileId;
+  let name;
+  try {
+    fileId = normalizeRequiredPageValue(input?.fileId, "file ID");
+    name = normalizeRequiredPageValue(input?.name, "page name");
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw pageOperationError("create", "INVALID_INPUT", message, "create_page", rawArgs);
+  }
+  const providerArgs = { fileId, name };
+  const result = await callPaperMcp("paper_create_page", providerArgs, signal);
+  if (!result.ok) {
+    throw pageOperationError("create", providerFailureCode(result), result.error, "create_page", providerArgs);
+  }
+  const parsed = parseMcpJsonObject(result.result);
+  const pageId = pageIdFromProviderResult(result.result);
+  const returnedName = typeof parsed?.name === "string" ? parsed.name.trim() : void 0;
+  if (!pageId) {
+    throw pageOperationError(
+      "create",
+      "PROVIDER_SCHEMA_DRIFT",
+      "Paper MCP tool create_page succeeded but returned no usable page ID.",
+      "create_page",
+      providerArgs
+    );
+  }
+  return { fileId, pageId, name: returnedName || name, created: true };
+}
+async function openPaperPage(input, signal) {
+  const rawArgs = { fileId: input?.fileId, pageId: input?.pageId };
+  let fileId;
+  let pageId;
+  try {
+    fileId = normalizeRequiredPageValue(input?.fileId, "file ID");
+    pageId = normalizeRequiredPageValue(input?.pageId, "page ID");
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw pageOperationError("open", "INVALID_INPUT", message, "open_file", rawArgs);
+  }
+  const providerArgs = { fileId, pageId };
+  const result = await callPaperMcp("paper_open_page", providerArgs, signal);
+  if (!result.ok) {
+    throw pageOperationError("open", providerFailureCode(result), result.error, "open_file", providerArgs);
+  }
+  const parsed = parseMcpJsonObject(result.result);
+  const activePageId = typeof parsed?.pageId === "string" ? parsed.pageId.trim() : "";
+  const activeUrl = typeof parsed?.url === "string" ? parsed.url.trim() : "";
+  const expectedFileId = fileIdFromPaperTarget(fileId);
+  const activeFileId = fileIdFromPaperTarget(activeUrl);
+  if (!activePageId || activePageId !== pageId || !expectedFileId || activeFileId !== expectedFileId) {
+    throw pageOperationError(
+      "open",
+      "PROVIDER_SCHEMA_DRIFT",
+      "Paper MCP tool open_file did not prove the requested file and page became active.",
+      "open_file",
+      providerArgs
+    );
+  }
+  return { fileId, pageId, opened: true };
+}
+function pageOperationToolResult(receipt) {
+  return {
+    content: [{ type: "text", text: JSON.stringify(receipt, null, 2) }],
+    details: { receipt }
+  };
+}
+function pageOperationToolError(error) {
+  if (error instanceof PaperPageOperationError) {
+    const receipt = toPaperPageFailureReceipt(error);
+    return {
+      content: [{ type: "text", text: JSON.stringify(receipt, null, 2) }],
+      details: { receipt, code: error.code, error: error.message }
+    };
+  }
+  const message = error instanceof Error ? error.message : String(error);
+  return { content: [{ type: "text", text: message }], details: { error: message } };
+}
+async function readNodeSnapshot(id, fileId, signal) {
+  const result = await callRequiredPaperMcp("paper_get_node_info", { fileId, nodeId: id }, signal);
+  const parsed = parseMcpJsonObject(result);
+  const parsedId = typeof parsed?.id === "string" ? parsed.id.trim() : "";
+  const name = typeof parsed?.name === "string" ? parsed.name.trim() : void 0;
+  if (!parsed || parsedId !== id || name === void 0) {
+    throw new Error(`Paper returned no usable node snapshot for ${id}.`);
+  }
+  return {
+    id: parsedId,
+    name,
+    parentId: typeof parsed.parentId === "string" ? parsed.parentId : null,
+    artboardId: typeof parsed.artboardId === "string" ? parsed.artboardId : null
+  };
+}
+async function readPaperFileKey(fileId, signal) {
+  const parsed = await verifyPaperFileTarget(fileId, signal);
+  const url = typeof parsed?.url === "string" ? parsed.url.trim() : "";
+  const rootNodeId = typeof parsed?.rootNodeId === "string" ? parsed.rootNodeId.trim() : "";
+  if (!url || !rootNodeId) throw new Error("Paper returned no stable file identity for session provenance.");
+  return `${url}#${rootNodeId}`;
+}
+async function beginMaterializationScope(fileId, signal) {
+  const currentFileKey = await readPaperFileKey(fileId, signal);
+  if (sessionFileKey && sessionFileKey !== currentFileKey) sessionCreatedNodeIds.clear();
+  sessionFileKey = currentFileKey;
+}
+async function reconcileSessionFileScope(fileId, signal) {
+  if (sessionCreatedNodeIds.size === 0) return;
+  const currentFileKey = await readPaperFileKey(fileId, signal);
+  if (sessionFileKey !== currentFileKey) sessionCreatedNodeIds.clear();
+  sessionFileKey = currentFileKey;
+}
+async function verifyNodeAbsent(id, fileId, signal) {
+  const response = await callPaperMcp("paper_get_node_info", { fileId, nodeId: id }, signal);
+  if (!response.ok) {
+    if (response.failure === "contract" && /not found|deleted/i.test(response.error)) return;
+    throw new Error(response.error);
+  }
+  const providerError = getMcpProviderError(response.result);
+  if (providerError && /not found|deleted/i.test(providerError)) return;
+  throw new Error(`Paper still returned node ${id} after deletion.`);
+}
+function normalizeNodeIds(value) {
+  if (!Array.isArray(value)) throw new TypeError("At least one Paper node ID is required.");
+  if (value.some((entry) => typeof entry !== "string" || !entry.trim())) {
+    throw new TypeError("Every Paper node ID must be a non-empty string.");
+  }
+  const ids = value.map((entry) => entry.trim());
+  if (ids.length === 0) throw new TypeError("At least one Paper node ID is required.");
+  if (ids.length > 50) throw new TypeError("Operator mutations are limited to 50 Paper nodes per call.");
+  if (new Set(ids).size !== ids.length) throw new TypeError("Each Paper node ID may appear only once per call.");
+  return ids;
+}
+function normalizeRenameUpdates(value) {
+  if (!Array.isArray(value) || value.length === 0) {
+    throw new TypeError("At least one Paper rename update is required.");
+  }
+  if (value.length > 50) throw new TypeError("Operator mutations are limited to 50 Paper nodes per call.");
+  const updates = value.map((entry) => {
+    if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
+      throw new TypeError("Each rename update requires a node id and a non-empty name.");
+    }
+    const record = entry;
+    const id = typeof record.id === "string" ? record.id.trim() : "";
+    const name = typeof record.name === "string" ? record.name.trim() : "";
+    if (!id || !name) throw new TypeError("Each rename update requires a node id and a non-empty name.");
+    return { id, name };
+  });
+  if (new Set(updates.map((update) => update.id)).size !== updates.length) {
+    throw new TypeError("Each Paper node may appear only once in a rename call.");
+  }
+  return updates;
+}
+function normalizeLiteralHtml(value) {
+  const html = typeof value === "string" ? value.trim() : "";
+  if (!html) throw new TypeError("Revision requires non-empty literal inline-CSS HTML.");
+  if (!/<[a-z][^>]*\sstyle\s*=/i.test(html)) {
+    throw new TypeError("Revision HTML must use explicit inline style attributes.");
+  }
+  if (/\bclass(?:Name)?\s*=/i.test(html) || /var\s*\(/i.test(html) || /<(?:script|style)\b/i.test(html)) {
+    throw new TypeError(
+      "Revision accepts literal inline-CSS HTML only (no classes, CSS variables, style blocks, or scripts)."
+    );
+  }
+  const relativeDimension = /(?:^|;)\s*(?:width|height|min-width|max-width|min-height|max-height|top|right|bottom|left|margin(?:-[a-z]+)?|padding(?:-[a-z]+)?|gap|font-size|line-height|letter-spacing)\s*:[^;"]*(?:-?(?:\d+(?:\.\d+)?|\.\d+)(?:%|em|rem|vw|vh|vmin|vmax))(?=\s|;|$)/i;
+  for (const match of html.matchAll(/\bstyle\s*=\s*(["'])(.*?)\1/gis)) {
+    if (relativeDimension.test(match[2] ?? "")) {
+      throw new TypeError(
+        "Revision layout and typography values must be concrete pixels, numbers, or literal colors."
+      );
+    }
+  }
+  return html;
+}
+function normalizeIncrementalHtml(value) {
+  const html = typeof value === "string" ? value.trim() : "";
+  if (!html) throw new TypeError("paper_write_html requires non-empty HTML.");
+  if (!/<[a-z][^>]*\sstyle\s*=/i.test(html)) {
+    throw new TypeError(
+      "paper_write_html requires inline style attributes so Paper does not create invisible 0\xD70 nodes."
+    );
+  }
+  if (/<(?:script|style)\b/i.test(html)) {
+    throw new TypeError("paper_write_html does not accept script or style blocks; use literal inline styles.");
+  }
+  return html;
+}
+var PAPER_TOKEN_TYPES = [
+  "breakpoint",
+  "color",
+  "container",
+  "fontFamily",
+  "fontSize",
+  "fontWeight",
+  "letterSpacing",
+  "lineHeight",
+  "radius",
+  "spacing"
+];
+var paperTokenTypeSet = new Set(PAPER_TOKEN_TYPES);
+var TOKEN_NAME_PATTERN = /^--[a-zA-Z0-9_-]+$/;
+var TOKEN_ALIAS_REJECTED_TYPES = /* @__PURE__ */ new Set(["fontSize", "radius", "spacing"]);
+function normalizeTokenName(value, label) {
+  const name = typeof value === "string" ? value.trim() : "";
+  if (!TOKEN_NAME_PATTERN.test(name)) {
+    throw new TypeError(`${label} must be a CSS custom-property name such as --color-primary.`);
+  }
+  return name;
+}
+function normalizeTokenDescription(value) {
+  if (value === void 0) return void 0;
+  if (typeof value !== "string" || value.length > 1024) {
+    throw new TypeError("Paper token descriptions must be strings no longer than 1024 characters.");
+  }
+  return value;
+}
+function validatePaperTokenValue(type, value) {
+  if (typeof value !== "string" && typeof value !== "number") {
+    throw new TypeError(`Paper token ${type} values must be strings or numbers.`);
+  }
+  if (typeof value === "string" && /color-mix\s*\(/i.test(value)) {
+    throw new TypeError(
+      "Paper Desktop currently rejects color-mix() token values. Precompute a literal and preserve the original expression in description; upstream support is required to retain live provenance."
+    );
+  }
+  if (typeof value === "string" && /var\s*\(/i.test(value) && TOKEN_ALIAS_REJECTED_TYPES.has(type)) {
+    throw new TypeError(
+      `Paper Desktop currently rejects var() aliases for ${type} tokens despite its schema text. Use a computed literal plus an expression note until the provider fixes alias support.`
+    );
+  }
+  return value;
+}
+function normalizeCreateTokens(value) {
+  if (!Array.isArray(value) || value.length === 0) {
+    throw new TypeError("paper_create_tokens requires at least one token.");
+  }
+  if (value.length > 500) throw new TypeError("Paper token mutations are limited to 500 entries per call.");
+  return value.map((entry) => {
+    if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
+      throw new TypeError("Each Paper token requires type, name, and value.");
+    }
+    const record = entry;
+    if (typeof record.type !== "string" || !paperTokenTypeSet.has(record.type)) {
+      throw new TypeError(
+        `Unsupported Paper token type ${JSON.stringify(record.type)}. Supported types: ${PAPER_TOKEN_TYPES.join(", ")}. Shadow, duration, easing, and theme dimensions are not available upstream.`
+      );
+    }
+    const type = record.type;
+    return {
+      type,
+      name: normalizeTokenName(record.name, "Paper token name"),
+      value: validatePaperTokenValue(type, record.value),
+      ...record.description !== void 0 ? { description: normalizeTokenDescription(record.description) } : {}
+    };
+  });
+}
+function normalizeSetTokens(value) {
+  if (!Array.isArray(value) || value.length === 0) {
+    throw new TypeError("paper_set_tokens requires at least one token update.");
+  }
+  if (value.length > 500) throw new TypeError("Paper token mutations are limited to 500 entries per call.");
+  return value.map((entry) => {
+    if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
+      throw new TypeError("Each Paper token update requires a token name.");
+    }
+    const record = entry;
+    const name = normalizeTokenName(record.name, "Paper token name");
+    const newName = record.newName === void 0 ? void 0 : normalizeTokenName(record.newName, "New token name");
+    const description = normalizeTokenDescription(record.description);
+    const deleting = record.delete === true;
+    if (record.delete !== void 0 && typeof record.delete !== "boolean") {
+      throw new TypeError("Paper token delete must be a boolean when provided.");
+    }
+    if (deleting && (newName !== void 0 || record.value !== void 0 || description !== void 0)) {
+      throw new TypeError(`Delete update for ${name} cannot also rename or change its value/description.`);
+    }
+    if (!deleting && newName === void 0 && record.value === void 0 && description === void 0) {
+      throw new TypeError(`Token update for ${name} must set newName, value, description, or delete=true.`);
+    }
+    if (typeof record.value === "string" && /(?:color-mix|var)\s*\(/i.test(record.value)) {
+      throw new TypeError(
+        `Paper Desktop may reject expression value ${record.value} without exposing the token type through set_tokens. Use a computed literal and preserve the source expression in description.`
+      );
+    }
+    if (record.value !== void 0 && typeof record.value !== "string" && typeof record.value !== "number") {
+      throw new TypeError(`Paper token value for ${name} must be a string or number.`);
+    }
+    return {
+      name,
+      ...newName !== void 0 ? { newName } : {},
+      ...record.value !== void 0 ? { value: record.value } : {},
+      ...description !== void 0 ? { description } : {},
+      ...deleting ? { delete: true } : {}
+    };
+  });
+}
+function nonEmptyString(value, label) {
+  if (typeof value !== "string" || !value.trim()) throw new TypeError(`${label} must be a non-empty string.`);
+  return value.trim();
+}
+function normalizeMoves(value) {
+  if (!Array.isArray(value) || value.length === 0) throw new TypeError("paper_move_nodes requires at least one move.");
+  if (value.length > 50) throw new TypeError("Paper move batches are limited to 50 entries.");
+  const moves = value.map((entry) => {
+    if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
+      throw new TypeError("Each Paper move must be an object.");
+    }
+    const record = entry;
+    const nodeId = nonEmptyString(record.nodeId, "Move nodeId");
+    const shapes = [record.before !== void 0, record.after !== void 0, record.parentId !== void 0].filter(
+      Boolean
+    );
+    if (shapes.length !== 1) {
+      throw new TypeError(`Move for ${nodeId} must use exactly one of before, after, or parentId.`);
+    }
+    if (record.before !== void 0) return { nodeId, before: nonEmptyString(record.before, "Move before") };
+    if (record.after !== void 0) return { nodeId, after: nonEmptyString(record.after, "Move after") };
+    const parentId = nonEmptyString(record.parentId, "Move parentId");
+    if (record.index !== void 0 && (!Number.isInteger(record.index) || record.index < 0)) {
+      throw new TypeError(`Move index for ${nodeId} must be a non-negative integer.`);
+    }
+    return {
+      nodeId,
+      parentId,
+      ...record.index !== void 0 ? { index: record.index } : {}
+    };
+  });
+  if (new Set(moves.map((move) => move.nodeId)).size !== moves.length) {
+    throw new TypeError("Each Paper node may appear only once in a guarded move batch.");
+  }
+  return moves;
+}
+function extractCreatedNodes(result) {
+  const parsed = parseMcpJsonValue(result);
+  const record = parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : {};
+  const entries = Array.isArray(record.createdNodes) ? record.createdNodes : [];
+  return entries.flatMap((entry) => {
+    if (typeof entry === "string" && entry.trim()) return [{ id: entry.trim() }];
+    if (!entry || typeof entry !== "object" || Array.isArray(entry)) return [];
+    const node = entry;
+    const id = typeof node.id === "string" ? node.id.trim() : typeof node.nodeId === "string" ? node.nodeId.trim() : "";
+    if (!id) return [];
+    return [{ id, ...typeof node.name === "string" && node.name.trim() ? { name: node.name.trim() } : {} }];
+  });
+}
+function providerMutationEntries(result) {
+  const parsed = parseMcpJsonValue(result);
+  if (Array.isArray(parsed)) {
+    return parsed.filter((entry) => Boolean(entry && typeof entry === "object"));
+  }
+  if (!parsed || typeof parsed !== "object") return [];
+  const record = parsed;
+  const entries = Array.isArray(record.results) ? record.results : Array.isArray(record.tokens) ? record.tokens : [];
+  return entries.filter((entry) => Boolean(entry && typeof entry === "object"));
+}
+function mutationEntryFailed(entry) {
+  return entry.result === "error" || entry.status === "error" || entry.ok === false || typeof entry.error === "string";
+}
+function captureRouteSlug(route) {
+  const slug = route.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+  return slug || "root";
+}
+function buildCaptureArtboardName(input) {
+  const suffix = `__${input.width}x${input.height}__${captureRouteSlug(input.theme)}__${input.date}`;
+  const routeBudget = Math.max(1, 50 - suffix.length);
+  return `${captureRouteSlug(input.route).slice(0, routeBudget)}${suffix}`;
+}
+function classifyTargets(ids) {
+  const sessionCreatedTargetIds = ids.filter((id) => sessionCreatedNodeIds.has(id));
+  return {
+    sessionCreatedTargetIds,
+    sourceTargetIds: ids.filter((id) => !sessionCreatedNodeIds.has(id))
+  };
+}
+function createOperatorReceipt(options) {
+  const locatorSuffix = options.targetIds.length > 0 ? options.targetIds.map(encodeURIComponent).join(",") : "none";
+  const evidence = options.status === "applied" ? options.targetIds.map((id) => ({
+    kind: `paper-${options.action}`,
+    locator: `paper://node/${encodeURIComponent(id)}`,
+    accessClass: "private-corpus"
+  })) : [
+    {
+      kind: `paper-${options.action}-${options.status}`,
+      locator: `paper://operator-control/${options.action}/${locatorSuffix}`,
+      accessClass: "private"
+    }
+  ];
+  return {
+    workflowId: options.workflowId,
+    summary: options.summary,
+    evidence,
+    sourceNotes: options.sourceNotes,
+    riskNotes: options.riskNotes,
+    nextActions: options.nextActions,
+    payload: options.payload
+  };
+}
+function operatorReceiptResult(receipt, images = []) {
+  return {
+    content: [
+      { type: "text", text: `${receipt.summary}
+${JSON.stringify(receipt, null, 2)}` },
+      ...images.map((image) => ({ type: "image", ...image }))
+    ],
+    details: { receipt }
+  };
+}
+function operatorReceiptError(receipt, code, message) {
+  const result = operatorReceiptResult(receipt);
+  return { ...result, details: { receipt, code, error: message } };
+}
+function createRenameReceipt(summary, payload) {
+  return createOperatorReceipt({
+    workflowId: "paper.renameNodes.v1",
+    action: "rename-nodes",
+    status: payload.status,
+    summary,
+    targetIds: payload.updates.map((update) => update.id),
+    sourceNotes: [
+      "Paper Desktop remains the source of truth for node names.",
+      "This operation can rename only the listed node IDs; it cannot change styles, content, hierarchy, or delete nodes.",
+      "Session provenance is process- and file-local; after a restart or file switch, every target is treated as source work."
+    ],
+    riskNotes: [
+      "A live rename requires confirm=true.",
+      `Targets not created in this session and active file also require sourceAcknowledgement="${SOURCE_ACKNOWLEDGEMENTS.rename}".`
+    ],
+    nextActions: payload.status === "dry-run" ? ["Review the exact IDs and names, then rerun with the required confirmation fields."] : payload.status === "applied" ? ["Use the returned pre/post names as the rename verification record."] : ["Resolve the named gate or error before retrying; do not assume any unverified rename occurred."],
+    payload
+  });
+}
+function createReviseReceipt(summary, payload) {
+  return createOperatorReceipt({
+    workflowId: "paper.reviseArtboard.v1",
+    action: "revise-artboard",
+    status: payload.status,
+    summary,
+    targetIds: payload.artboardId ? [payload.artboardId] : [],
+    sourceNotes: [
+      "Paper Desktop remains the source of truth for artboard structure.",
+      "This operation can replace only the children of the named artboard from validated literal inline-CSS HTML.",
+      "It cannot replace the artboard root, touch siblings, use Tailwind classes, resolve CSS variables, or accept relative layout units.",
+      "Session provenance is process- and file-local; after a restart or file switch, every target is treated as source work."
+    ],
+    riskNotes: [
+      "A live revision requires confirm=true and screenshots the resulting artboard.",
+      `Artboards not created in this session and active file also require sourceAcknowledgement="${SOURCE_ACKNOWLEDGEMENTS.revise}".`
+    ],
+    nextActions: payload.status === "dry-run" ? ["Review the literal HTML, target artboard, and source-protection gate before confirming."] : payload.status === "applied" ? ["Inspect the returned screenshot before accepting the revised artboard."] : [
+      "Inspect the target artboard before retrying because a failed provider stage may have partially changed its children."
+    ],
+    payload
+  });
+}
+function createDeleteReceipt(summary, payload) {
+  return createOperatorReceipt({
+    workflowId: "paper.deleteNodes.v1",
+    action: "delete-nodes",
+    status: payload.status,
+    summary,
+    targetIds: payload.requestedIds,
+    sourceNotes: [
+      "Paper Desktop remains the source of truth for canvas state.",
+      "This operation can delete only the listed node IDs and their descendants; it cannot delete a root or page node.",
+      "Session provenance is process- and file-local; after a restart or file switch, every target is treated as source work."
+    ],
+    riskNotes: [
+      "A live delete requires confirm=true and cannot be reversed through this tool.",
+      `Nodes not created in this session and active file also require sourceAcknowledgement="${SOURCE_ACKNOWLEDGEMENTS.delete}".`
+    ],
+    nextActions: payload.status === "dry-run" ? ["Review the exact node IDs before confirming deletion."] : payload.status === "applied" ? ["Retain this receipt as the exact removed-node and absence-verification record."] : [
+      "Inspect Paper before retrying; do not assume a failed or unverified delete left every target unchanged."
+    ],
+    payload
+  });
+}
+function createWriteHtmlReceipt(summary, payload) {
+  return createOperatorReceipt({
+    workflowId: "paper.writeHtml.v1",
+    action: "write-html",
+    status: payload.status,
+    summary,
+    targetIds: payload.createdNodes.length > 0 ? payload.createdNodes.map((node) => node.id) : [payload.targetId],
+    sourceNotes: [
+      "Paper Desktop remains the source of truth for created nodes.",
+      "This guarded tool exposes insert-children only; destructive replacement stays behind paper_revise_artboard.",
+      "The receipt preserves write_html.createdNodes so callers never have to guess nodeIds or orphan untracked layers."
+    ],
+    riskNotes: [
+      "A live write requires an explicit fileId, dry-run review, and confirm=true.",
+      `Writing into a source target also requires sourceAcknowledgement="write-source".`
+    ],
+    nextActions: payload.status === "dry-run" ? ["Review the exact file, parent ID, and HTML before confirming."] : payload.status === "applied" ? ["Use payload.createdNodes as the only authoritative IDs for follow-up work."] : [
+      "Inspect the named provider failure before retrying; do not assume any unreceipted nodes are safe to ignore."
+    ],
+    payload
+  });
+}
+function createTokenMutationReceipt(summary, payload) {
+  return createOperatorReceipt({
+    workflowId: `paper.${payload.operation}Tokens.v1`,
+    action: `${payload.operation}-tokens`,
+    status: payload.status,
+    summary,
+    targetIds: [],
+    sourceNotes: [
+      "Paper Desktop stores one flat, file-scoped token namespace with no light/dark dimension.",
+      "Provider per-entry results are preserved verbatim in payload.providerResults."
+    ],
+    riskNotes: [
+      "A live token mutation requires an explicit fileId, dry-run review, and confirm=true.",
+      'set_tokens changes or deletes existing source tokens and also requires sourceAcknowledgement="set-source-tokens".'
+    ],
+    nextActions: payload.status === "dry-run" ? ["Review supported types, computed literals, descriptions, and exact token names before confirming."] : payload.status === "applied" ? ["Read back the affected names with paper_get_tokens in the same explicit file."] : ["Review every provider result; partial batches may already contain successful entries."],
+    payload
+  });
+}
+function createMoveNodesReceipt(summary, payload) {
+  return createOperatorReceipt({
+    workflowId: "paper.moveNodes.v1",
+    action: "move-nodes",
+    status: payload.status,
+    summary,
+    targetIds: payload.moves.map((move) => move.nodeId),
+    sourceNotes: [
+      "move_nodes preserves node IDs while changing hierarchy or sibling order.",
+      "The public live runtime requires every before, after, or parentId destination to be separately typed and fingerprinted in the approved brief.",
+      "The provider's ambiguous parentId='root' alias and unverified cross-page roots are not authorized by the public live gate."
+    ],
+    riskNotes: [
+      'A live move requires an explicit fileId, dry-run review, confirm=true, and sourceAcknowledgement="move-source" for existing nodes.'
+    ],
+    nextActions: payload.status === "dry-run" ? ["Canary one cross-page move before a large batch and retain the exact destination root ID."] : payload.status === "applied" ? ["Use affectedParents from the provider result to refresh the moved hierarchy without guessing."] : [
+      "Inspect the file before retrying because sequential move batches may have partially applied upstream."
+    ],
+    payload
+  });
+}
+var paperTokenTypeSchema = Type.Union([
+  Type.Literal("breakpoint"),
+  Type.Literal("color"),
+  Type.Literal("container"),
+  Type.Literal("fontFamily"),
+  Type.Literal("fontSize"),
+  Type.Literal("fontWeight"),
+  Type.Literal("letterSpacing"),
+  Type.Literal("lineHeight"),
+  Type.Literal("radius"),
+  Type.Literal("spacing")
+]);
+var paperMcpTools = [
+  // ── Read tools ──────────────────────────────────────────────────────────
+  createPaperTool({
+    name: "paper_get_basic_info",
+    label: "Paper: Get Basic Info",
+    description: "Get file name, page name, node count, and list of artboards with dimensions from the currently open Paper file.",
+    parameters: Type.Object({ fileId: optionalFileIdSchema })
+  }),
+  createPaperTool({
+    name: "paper_get_selection",
+    label: "Paper: Get Selection",
+    description: "Get details about the currently selected nodes in Paper Desktop (IDs, names, types, size, artboard). Use this to see what the user is pointing at.",
+    parameters: Type.Object({ fileId: optionalFileIdSchema })
+  }),
+  createPaperTool({
+    name: "paper_get_node_info",
+    label: "Paper: Get Node Info",
+    description: "Get details for a specific node by ID: size, visibility, lock state, parent, children, text content.",
+    parameters: Type.Object({
+      fileId: optionalFileIdSchema,
+      id: Type.String({ description: "Node ID to inspect" })
+    }),
+    mapArgs: (a) => ({ nodeId: a.id })
+  }),
+  createPaperTool({
+    name: "paper_get_children",
+    label: "Paper: Get Children",
+    description: "Get direct children of a node: IDs, names, types, and child counts.",
+    parameters: Type.Object({
+      fileId: optionalFileIdSchema,
+      id: Type.String({ description: "Parent node ID" })
+    }),
+    mapArgs: (a) => ({ nodeId: a.id })
+  }),
+  createPaperTool({
+    name: "paper_get_tree_summary",
+    label: "Paper: Get Tree Summary",
+    description: "Get a bounded summary of one targeted subtree. Depth defaults to 4 and must be 1 through 8; start from an artboard or smaller subtree instead of a Snapshot-scale document root.",
+    parameters: Type.Object({
+      fileId: optionalFileIdSchema,
+      id: Type.String({ description: "Root node ID" }),
+      depth: Type.Optional(
+        Type.Integer({
+          minimum: PAPER_TREE_MIN_DEPTH,
+          maximum: PAPER_TREE_MAX_DEPTH,
+          default: PAPER_TREE_DEFAULT_DEPTH,
+          description: "Max depth to traverse (default 4; minimum 1; maximum 8)"
+        })
+      )
+    }),
+    mapArgs: (a) => ({ nodeId: a.id, depth: boundedTreeSummaryDepth(a.depth) }),
+    responseBudget: highVolumeReadBudget(
+      "Retry with a smaller subtree ID or a shallower depth before continuing the tree walk."
+    )
+  }),
+  createPaperTool({
+    name: "paper_get_screenshot",
+    label: "Paper: Get Screenshot",
+    description: "Screenshot one targeted artboard or node. Start with scale 1; use scale 2 only for a specific detail after the scale-1 read is insufficient.",
+    parameters: Type.Object({
+      fileId: optionalFileIdSchema,
+      id: Type.String({ description: "Node ID to screenshot" }),
+      scale: Type.Optional(
+        Type.Integer({
+          minimum: 1,
+          maximum: 2,
+          default: 1,
+          description: "Scale 1 (default) or 2; start with scale 1"
+        })
+      )
+    }),
+    mapArgs: (a) => ({ nodeId: a.id, ...a.scale !== void 0 ? { scale: a.scale } : {} }),
+    responseBudget: highVolumeReadBudget(
+      "Retry on a smaller artboard or node at scale 1; use scale 2 only for a narrowly targeted detail."
+    )
+  }),
+  createPaperTool({
+    name: "paper_get_jsx",
+    label: "Paper: Get JSX",
+    description: "Get JSX for one targeted node and its descendants. Request an artboard section or smaller subtree rather than a full Snapshot page; choose 'tailwind' or 'inline' styles.",
+    parameters: Type.Object({
+      fileId: optionalFileIdSchema,
+      id: Type.String({ description: "Node ID" }),
+      styleFormat: Type.Optional(Type.String({ description: "'tailwind' or 'inline' (default: tailwind)" }))
+    }),
+    mapArgs: (a) => ({ nodeId: a.id, ...a.styleFormat !== void 0 ? { format: a.styleFormat } : {} }),
+    responseBudget: highVolumeReadBudget(
+      "Retry with a smaller subtree ID, then summarize that section before reading the next one."
+    )
+  }),
+  createPaperTool({
+    name: "paper_get_computed_styles",
+    label: "Paper: Get Computed Styles",
+    description: "Get exact computed CSS values for 1 through 50 targeted nodes. Read only the subtree nodes needed for the current implementation decision.",
+    parameters: Type.Object({
+      fileId: optionalFileIdSchema,
+      ids: Type.Array(Type.String({ minLength: 1 }), {
+        minItems: 1,
+        maxItems: PAPER_COMPUTED_STYLES_MAX_NODE_IDS,
+        description: "Array of 1 through 50 targeted node IDs"
+      })
+    }),
+    mapArgs: (a) => ({ nodeIds: boundedComputedStyleNodeIds(a.ids) }),
+    responseBudget: highVolumeReadBudget(
+      "Retry with fewer node IDs from a smaller subtree, then summarize the relevant style decisions."
+    )
+  }),
+  createPaperTool({
+    name: "paper_get_fill_image",
+    label: "Paper: Get Fill Image",
+    description: "Get image data from one exact node already confirmed to have an image fill. Avoid broad reference roots; the result is base64 JPEG data.",
+    parameters: Type.Object({
+      fileId: optionalFileIdSchema,
+      id: Type.String({ description: "Node ID with image fill" })
+    }),
+    mapArgs: (a) => ({ nodeId: a.id }),
+    responseBudget: highVolumeReadBudget(
+      "Retry with the exact smaller image-fill node; use a targeted scale 1 screenshot when the full fill asset is unnecessary."
+    )
+  }),
+  {
+    name: "paper_find_nodes",
+    label: "Paper: Find Nodes Safely",
+    description: "Find Paper nodes by computed-style filters and/or text in an explicitly targeted file. scopeId must be an exact node ID; the belt preflights it and rejects names or stale IDs instead of returning a misleading empty result.",
+    parameters: Type.Object({
+      fileId: optionalFileIdSchema,
+      scopeId: Type.Optional(
+        Type.String({ description: "Exact Paper node ID whose descendants should be searched; not a node name" })
+      ),
+      textValue: Type.Optional(Type.String({ description: "Case-insensitive text match with * wildcards" })),
+      filters: Type.Optional(
+        Type.Array(
+          Type.Object({
+            styleName: Type.Optional(Type.String({ description: "CSS property name or wildcard" })),
+            styleValue: Type.Optional(Type.String({ description: "Literal, token reference, or wildcard" }))
+          }),
+          { minItems: 1 }
+        )
+      )
+    }),
+    async execute(_toolCallId, params, signal) {
+      const args = params && typeof params === "object" ? params : {};
+      const fixture = args._fixture;
+      if (fixture !== void 0) {
+        return { content: formatMcpResult(fixture), details: { mcpTool: "find_nodes", fixture: true } };
+      }
+      let fileId;
+      let scopeId;
+      try {
+        fileId = optionalFileId(args.fileId);
+        scopeId = args.scopeId === void 0 ? void 0 : nonEmptyString(args.scopeId, "find_nodes scopeId");
+        if (args.textValue === void 0 && args.filters === void 0) {
+          throw new TypeError("paper_find_nodes requires textValue, filters, or both.");
+        }
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+          content: [{ type: "text", text: message }],
+          details: { code: "INVALID_INPUT", error: message }
+        };
+      }
+      if (scopeId) {
+        const scopeResult = await callPaperMcp(
+          "paper_get_node_info",
+          { ...fileId ? { fileId } : {}, nodeId: scopeId },
+          signal
+        );
+        if (!scopeResult.ok) {
+          const message = `Invalid find_nodes scopeId ${JSON.stringify(scopeId)}: scopeId must be an exact Paper node ID, not a layer name. Resolve the ID first with paper_get_basic_info, paper_get_tree_summary, or paper_get_node_info. Provider detail: ${scopeResult.error}`;
+          return {
+            content: [{ type: "text", text: message }],
+            details: { code: "INVALID_SCOPE_ID", error: message, fileId: fileId ?? null, scopeId }
+          };
+        }
+      }
+      const providerArgs = {
+        ...fileId ? { fileId } : {},
+        ...scopeId ? { nodeId: scopeId } : {},
+        ...typeof args.textValue === "string" ? { textValue: args.textValue } : {},
+        ...Array.isArray(args.filters) ? { filters: args.filters } : {}
+      };
+      const response = await callPaperMcp("paper_find_nodes", providerArgs, signal);
+      if (!response.ok) {
+        return { content: [{ type: "text", text: response.error }], details: { error: response.error } };
+      }
+      return {
+        content: formatMcpResult(response.result),
+        details: { mcpTool: response.desktopToolName, fileId: fileId ?? null, validatedScopeId: scopeId ?? null }
+      };
+    }
+  },
+  createPaperTool({
+    name: "paper_get_font_family_info",
+    label: "Paper: Get Font Info",
+    description: "Look up whether a font family is available on the user's machine or Google Fonts. Inspect weights and styles.",
+    parameters: Type.Object({
+      fileId: optionalFileIdSchema,
+      family: Type.String({ description: "Font family name to look up" })
+    }),
+    fileIdPassthrough: false,
+    mapArgs: (a) => ({ familyNames: [a.family] })
+  }),
+  createPaperTool({
+    name: "paper_get_guide",
+    label: "Paper: Get Guide",
+    description: "Retrieve guided workflow documentation for a topic (e.g., 'figma-import' for Figma import steps).",
+    parameters: Type.Object({
+      fileId: optionalFileIdSchema,
+      topic: Type.String({ description: "Guide topic name" })
+    }),
+    fileIdPassthrough: false
+  }),
+  createPaperTool({
+    name: "paper_find_placement",
+    label: "Paper: Find Placement",
+    description: "Get suggested x/y coordinates on the canvas to place a new artboard without overlapping existing ones.",
+    parameters: Type.Object({
+      fileId: optionalFileIdSchema,
+      width: Type.Optional(Type.Number({ description: "Artboard width" })),
+      height: Type.Optional(Type.Number({ description: "Artboard height" }))
+    })
+  }),
+  createPaperTool({
+    name: "paper_get_tokens",
+    label: "Paper: Get Tokens",
+    description: "List the explicit file's flat design-token namespace in JSON, CSS, or Tailwind format. Paper currently supports breakpoint, color, container, fontFamily, fontSize, fontWeight, letterSpacing, lineHeight, radius, and spacing only; it has no shadow/duration/easing types or theme dimension.",
+    parameters: Type.Object({
+      fileId: optionalFileIdSchema,
+      types: Type.Optional(Type.Array(paperTokenTypeSchema)),
+      namePattern: Type.Optional(Type.String({ description: "Case-insensitive glob matched against token names" })),
+      format: Type.Optional(Type.Union([Type.Literal("json"), Type.Literal("css"), Type.Literal("tailwind")]))
+    })
+  }),
+  // ── Write tools ─────────────────────────────────────────────────────────
+  createPaperTool({
+    name: "paper_create_artboard",
+    label: "Paper: Create Artboard",
+    description: "Create a new artboard in the Paper file. Optionally specify name, width, height, and other styles.",
+    supportsDryRun: true,
+    parameters: Type.Object({
+      fileId: requiredFileIdSchema,
+      name: Type.Optional(Type.String({ description: "Artboard name" })),
+      styles: Type.Optional(
+        Type.Record(Type.String(), Type.Unknown(), { description: "CSS styles (width, height, etc.)" })
+      ),
+      dryRun: dryRunSchema
+    })
+  }),
+  createPaperTool({
+    name: "paper_write_html",
+    label: "Paper: Write HTML",
+    description: "Parse HTML and add or replace nodes in the Paper file. Use mode 'insert-children' to add inside a node, or 'replace' to replace a node's content.",
+    supportsDryRun: true,
+    parameters: Type.Object({
+      fileId: requiredFileIdSchema,
+      id: Type.String({ description: "Target node ID" }),
+      html: Type.String({ description: "HTML string to write" }),
+      mode: Type.Optional(Type.String({ description: "'insert-children' or 'replace'" })),
+      dryRun: dryRunSchema
+    }),
+    mapArgs: (a) => ({ targetNodeId: a.id, html: a.html, ...a.mode !== void 0 ? { mode: a.mode } : {} })
+  }),
+  createPaperTool({
+    name: "paper_set_text_content",
+    label: "Paper: Set Text",
+    description: "Set the text content of one or more Text nodes (batch operation).",
+    supportsDryRun: true,
+    parameters: Type.Object({
+      fileId: requiredFileIdSchema,
+      updates: Type.Array(
+        Type.Object({
+          id: Type.String({ description: "Text node ID" }),
+          text: Type.String({ description: "New text content" })
+        }),
+        { description: "Array of { id, text } updates" }
+      ),
+      dryRun: dryRunSchema
+    }),
+    mapArgs: (a) => ({
+      updates: a.updates.map((u) => ({
+        nodeId: u.id,
+        textContent: u.text
+      }))
+    })
+  }),
+  createPaperTool({
+    name: "paper_rename_nodes",
+    label: "Paper: Rename Nodes",
+    description: "Rename one or more layers in the Paper file (batch operation).",
+    supportsDryRun: true,
+    parameters: Type.Object({
+      fileId: requiredFileIdSchema,
+      updates: Type.Array(
+        Type.Object({
+          id: Type.String({ description: "Node ID" }),
+          name: Type.String({ description: "New layer name" })
+        }),
+        { description: "Array of { id, name } updates" }
+      ),
+      dryRun: dryRunSchema
+    }),
+    mapArgs: (a) => ({
+      updates: a.updates.map((u) => ({
+        nodeId: u.id,
+        name: u.name
+      }))
+    })
+  }),
+  createPaperTool({
+    name: "paper_duplicate_nodes",
+    label: "Paper: Duplicate Nodes",
+    description: "Deep-clone one or more nodes. Returns new IDs and a descendant ID mapping.",
+    supportsDryRun: true,
+    parameters: Type.Object({
+      fileId: requiredFileIdSchema,
+      ids: Type.Array(Type.String(), { description: "Array of node IDs to duplicate" }),
+      dryRun: dryRunSchema
+    }),
+    mapArgs: (a) => ({
+      nodes: a.ids.map((id) => ({ id }))
+    })
+  }),
+  createPaperTool({
+    name: "paper_update_styles",
+    label: "Paper: Update Styles",
+    description: "Update CSS styles on one or more nodes in the Paper file.",
+    supportsDryRun: true,
+    parameters: Type.Object({
+      fileId: requiredFileIdSchema,
+      updates: Type.Array(
+        Type.Object({
+          id: Type.String({ description: "Node ID" }),
+          styles: Type.Record(Type.String(), Type.Unknown(), { description: "CSS styles to apply" })
+        }),
+        { description: "Array of { id, styles } updates" }
+      ),
+      dryRun: dryRunSchema
+    }),
+    mapArgs: (a) => ({
+      updates: a.updates.map((u) => ({
+        nodeIds: [u.id],
+        styles: u.styles
+      }))
+    })
+  }),
+  createPaperTool({
+    name: "paper_delete_nodes",
+    label: "Paper: Delete Nodes",
+    description: "Delete one or more nodes and all their descendants from the Paper file.",
+    supportsDryRun: true,
+    parameters: Type.Object({
+      fileId: requiredFileIdSchema,
+      ids: Type.Array(Type.String(), { description: "Array of node IDs to delete" }),
+      dryRun: dryRunSchema
+    }),
+    mapArgs: (a) => ({ nodeIds: a.ids })
+  }),
+  createPaperTool({
+    name: "paper_finish_working_on_nodes",
+    label: "Paper: Finish Working",
+    description: "Clear the working indicator from artboards. Call this after you're done modifying artboards.",
+    supportsDryRun: true,
+    parameters: Type.Object({
+      fileId: requiredFileIdSchema,
+      ids: Type.Array(Type.String(), { description: "Array of artboard IDs to unmark" }),
+      dryRun: dryRunSchema
+    }),
+    mapArgs: (a) => a.ids ? { nodeIds: a.ids } : {}
+  }),
+  // ── Turf-wrapped tools ───────────────────────────────────────────────────
+  {
+    name: "paper_mcp_reachability_check",
+    label: "Paper: MCP Reachability Check",
+    description: "Check whether Paper Desktop's MCP server is reachable on http://127.0.0.1:29979/mcp. Use before other Paper tools to decide whether to use live Paper state or a fixture.",
+    parameters: Type.Object({ fileId: optionalFileIdSchema }),
+    async execute(_toolCallId, params, _signal) {
+      const args = params && typeof params === "object" ? params : {};
+      let fileId;
+      try {
+        fileId = optionalFileId(args.fileId);
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return { content: [{ type: "text", text: message }], details: { error: message } };
+      }
+      const reachable = await isPaperRunning(fileId);
+      const text = reachable ? fileId ? `Paper Desktop MCP server is reachable and file ${fileId} can be targeted.` : "Paper Desktop MCP server is reachable." : "Paper Desktop is not running. Open a file in Paper Desktop to start the MCP server (http://127.0.0.1:29979/mcp).";
+      return {
+        content: [{ type: "text", text }],
+        details: { reachable, fileId: fileId ?? null }
+      };
+    }
+  },
+  {
+    name: "paper_capture_provenance",
+    label: "Paper: Prepare Capture Provenance",
+    description: "Prepare a deterministic Paper capture/import name and provenance record before capture. The generated <=50-character artboardName carries route, viewport, theme, and UTC date; the receipt retains the full source URL for a sidecar manifest.",
+    parameters: Type.Object({
+      fileId: requiredFileIdSchema,
+      sourceUrl: Type.String({ minLength: 1, description: "Full URL of the captured source" }),
+      route: Type.Optional(
+        Type.String({ minLength: 1, description: "Canonical route; defaults to the URL pathname" })
+      ),
+      viewport: Type.Object({
+        width: Type.Integer({ minimum: 1, maximum: 1e4 }),
+        height: Type.Integer({ minimum: 1, maximum: 1e4 })
+      }),
+      theme: Type.String({ minLength: 1, description: "Theme label such as light, dark, system, or high-contrast" }),
+      capturedAt: Type.Optional(
+        Type.String({ description: "ISO-8601 capture timestamp; defaults to the current time" })
+      )
+    }),
+    async execute(_toolCallId, params) {
+      const args = params && typeof params === "object" ? params : {};
+      try {
+        const fileId = normalizeRequiredPageValue(args.fileId, "file ID");
+        const sourceUrl = nonEmptyString(args.sourceUrl, "Capture sourceUrl");
+        const parsedUrl = new URL(sourceUrl);
+        const viewport = args.viewport && typeof args.viewport === "object" && !Array.isArray(args.viewport) ? args.viewport : {};
+        const width = viewport.width;
+        const height = viewport.height;
+        if (typeof width !== "number" || !Number.isInteger(width) || width < 1 || width > 1e4 || typeof height !== "number" || !Number.isInteger(height) || height < 1 || height > 1e4) {
+          throw new TypeError("Capture viewport width and height must be integers from 1 to 10000.");
+        }
+        const route = args.route === void 0 ? `${parsedUrl.pathname || "/"}${parsedUrl.search}` : nonEmptyString(args.route, "Capture route");
+        const theme = nonEmptyString(args.theme, "Capture theme");
+        const capturedAt = args.capturedAt === void 0 ? (/* @__PURE__ */ new Date()).toISOString() : nonEmptyString(args.capturedAt, "capturedAt");
+        const parsedCapturedAt = new Date(capturedAt);
+        if (Number.isNaN(parsedCapturedAt.valueOf()))
+          throw new TypeError("capturedAt must be a valid ISO-8601 timestamp.");
+        const normalizedCapturedAt = parsedCapturedAt.toISOString();
+        const date = normalizedCapturedAt.slice(0, 10);
+        const artboardName = buildCaptureArtboardName({ route, width, height, theme, date });
+        const provenance = {
+          schemaVersion: "paper-capture-provenance.v1",
+          fileId,
+          sourceUrl: parsedUrl.toString(),
+          route,
+          viewport: { width, height },
+          theme,
+          capturedAt: normalizedCapturedAt,
+          artboardName,
+          namingConvention: "{routeSlug}__{width}x{height}__{theme}__{YYYY-MM-DD}"
+        };
+        return {
+          content: [{ type: "text", text: JSON.stringify(provenance, null, 2) }],
+          details: { provenance }
+        };
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+          content: [{ type: "text", text: message }],
+          details: { code: "INVALID_INPUT", error: message }
+        };
+      }
+    }
+  },
+  {
+    name: "paper_style_tokens_extract",
+    label: "Paper: Extract Style Tokens",
+    description: "Extract design tokens (colors, typography, spacing, fonts) from one or more Paper nodes by reading computed styles and font metadata, then emit a JSON token file. Useful for grounding code implementation in actual Paper styles.",
+    parameters: Type.Object({
+      fileId: requiredFileIdSchema,
+      ids: Type.Array(Type.String(), { description: "Array of Paper node IDs to extract tokens from" }),
+      outputPath: Type.Optional(
+        Type.String({
+          description: "Absolute path for the token JSON file. Live extraction rejects relative or omitted paths so session cwd and process cwd cannot diverge."
+        })
+      ),
+      dryRun: dryRunSchema
+    }),
+    async execute(_toolCallId, params, signal) {
+      const args = params && typeof params === "object" ? params : {};
+      let fileId;
+      try {
+        fileId = normalizeRequiredPageValue(args.fileId, "file ID");
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return { content: [{ type: "text", text: message }], details: { error: message } };
+      }
+      const ids = Array.isArray(args.ids) ? args.ids : [];
+      if (ids.length === 0) {
+        return {
+          content: [{ type: "text", text: "No node IDs provided." }],
+          details: { error: "Missing ids" }
+        };
+      }
+      const outputPath = typeof args.outputPath === "string" ? args.outputPath.trim() : "";
+      if (args.dryRun === true) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Dry run: would extract style tokens from ${ids.length} node(s) and write to ${outputPath || "an explicit absolute output path"}`
+            },
+            {
+              type: "text",
+              text: JSON.stringify({ meta: { nodeIds: ids, dryRun: true }, tokens: {} }, null, 2)
+            }
+          ],
+          details: { dryRun: true, outputPath, tokenCount: 0 }
+        };
+      }
+      if (!outputPath || !isAbsolute2(outputPath)) {
+        const error = "Live style-token extraction requires an absolute outputPath bound to the approved project scope.";
+        return {
+          content: [{ type: "text", text: error }],
+          details: { code: "ABSOLUTE_OUTPUT_PATH_REQUIRED", error }
+        };
+      }
+      const stylesResult = await callPaperMcp("paper_get_computed_styles", { fileId, nodeIds: ids }, signal);
+      if (!stylesResult.ok) {
+        return {
+          content: [{ type: "text", text: `Failed to read computed styles: ${stylesResult.error}` }],
+          details: { error: stylesResult.error }
+        };
+      }
+      const styles = parseMcpTextContent(stylesResult.result);
+      let parsedStyles = {};
+      try {
+        parsedStyles = styles ? JSON.parse(styles) : {};
+      } catch {
+        parsedStyles = {};
+      }
+      const families = /* @__PURE__ */ new Set();
+      for (const nodeStyles of Object.values(parsedStyles)) {
+        if (typeof nodeStyles !== "object" || nodeStyles === null) continue;
+        const ns = nodeStyles;
+        if (typeof ns.fontFamily === "string") {
+          for (const family of ns.fontFamily.split(",")) {
+            families.add(family.trim());
+          }
+        }
+      }
+      const fontInfo = {};
+      for (const family of families) {
+        const fontResult = await callPaperMcp("paper_get_font_family_info", { familyNames: [family] }, signal);
+        if (fontResult.ok) {
+          fontInfo[family] = parseMcpTextContent(fontResult.result) ?? {};
+        }
+      }
+      const tokens = {
+        meta: {
+          generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+          nodeIds: ids,
+          source: "paper_desktop_computed_styles"
+        },
+        colors: extractColorTokens(parsedStyles),
+        typography: {
+          fontFamilies: fontInfo,
+          fontSizes: collectUniqueValues(parsedStyles, "fontSize"),
+          fontWeights: collectUniqueValues(parsedStyles, "fontWeight"),
+          lineHeights: collectUniqueValues(parsedStyles, "lineHeight"),
+          letterSpacings: collectUniqueValues(parsedStyles, "letterSpacing")
+        },
+        spacing: {
+          margins: collectUniqueValues(parsedStyles, "margin"),
+          paddings: collectUniqueValues(parsedStyles, "padding"),
+          gaps: collectUniqueValues(parsedStyles, "gap")
+        },
+        raw: parsedStyles
+      };
+      const dir = dirname2(outputPath);
+      if (!existsSync2(dir)) {
+        mkdirSync(dir, { recursive: true });
+      }
+      writeFileSync(outputPath, JSON.stringify(tokens, null, 2), "utf-8");
+      return {
+        content: [
+          { type: "text", text: `Extracted style tokens to ${outputPath}` },
+          { type: "text", text: JSON.stringify(tokens, null, 2) }
+        ],
+        details: { outputPath, tokenCount: Object.keys(parsedStyles).length }
+      };
+    }
+  },
+  {
+    name: "paper_materialize_system_direction",
+    label: "Paper: Materialize System Direction",
+    description: "Create a new, non-destructive system-direction artboard from literal inline HTML, place it without overlap, screenshot the result, and return an execution receipt. Always dry-run first.",
+    parameters: Type.Object({
+      fileId: requiredFileIdSchema,
+      name: Type.String({ description: "Name for the new system-direction artboard" }),
+      width: Type.Number({ description: "Artboard width in pixels" }),
+      height: Type.Number({ description: "Artboard height in pixels" }),
+      html: Type.String({ description: "Literal inline-CSS HTML prepared by materializeSystemDirection" }),
+      confirm: Type.Optional(
+        Type.Boolean({ description: "Must be true for a live write after the dry-run receipt is approved" })
+      ),
+      dryRun: dryRunSchema
+    }),
+    async execute(_toolCallId, params, signal) {
+      const args = params && typeof params === "object" ? params : {};
+      try {
+        const fileId = normalizeRequiredPageValue(args.fileId, "file ID");
+        if (args.confirm === true && args.dryRun !== true) {
+          await beginMaterializationScope(fileId, signal);
+        }
+        const result = await materializeDirection(
+          {
+            name: typeof args.name === "string" ? args.name : "",
+            width: typeof args.width === "number" ? args.width : 0,
+            height: typeof args.height === "number" ? args.height : 0,
+            html: typeof args.html === "string" ? args.html : "",
+            confirm: args.confirm === true,
+            dryRun: args.dryRun === true
+          },
+          {
+            callTool: async (toolName, toolArgs = {}) => {
+              const response = await callPaperMcp(toolName, { ...toolArgs, fileId }, signal);
+              if (!response.ok) throw new Error(response.error);
+              return response.result;
+            }
+          }
+        );
+        if (result.receipt.payload.status === "materialized" && result.receipt.payload.artboardId) {
+          sessionCreatedNodeIds.add(result.receipt.payload.artboardId);
+        }
+        return {
+          content: [
+            {
+              type: "text",
+              text: `${result.receipt.summary}
+${JSON.stringify(result.receipt, null, 2)}`
+            },
+            ...result.screenshot.map((image) => ({ type: "image", ...image }))
+          ],
+          details: { receipt: result.receipt }
+        };
+      } catch (error) {
+        const detail = error instanceof Error ? error.message : String(error);
+        if (error instanceof PaperMaterializationError && error.artboardId) {
+          sessionCreatedNodeIds.add(error.artboardId);
+        }
+        return {
+          content: [{ type: "text", text: detail }],
+          details: {
+            error: detail,
+            ...error instanceof PaperMaterializationError ? { stage: error.stage, ...error.artboardId ? { artboardId: error.artboardId } : {} } : {}
+          }
+        };
+      }
+    }
+  }
+];
+var paperOperatorTools = [
+  {
+    name: "paper_create_page",
+    label: "Paper: Create Page",
+    description: "Create one explicitly named page in an explicit Paper file and return its page ID. This does not open, rename, overwrite, or delete any page.",
+    parameters: Type.Object({
+      fileId: Type.String({ minLength: 1, description: "Explicit Paper file ID" }),
+      name: Type.String({ minLength: 1, description: "Non-empty display name for the new page" })
+    }),
+    async execute(_toolCallId, params, signal) {
+      const args = params && typeof params === "object" ? params : {};
+      try {
+        return pageOperationToolResult(
+          await createPaperPage(
+            {
+              fileId: typeof args.fileId === "string" ? args.fileId : "",
+              name: typeof args.name === "string" ? args.name : ""
+            },
+            signal
+          )
+        );
+      } catch (error) {
+        return pageOperationToolError(error);
+      }
+    }
+  },
+  {
+    name: "paper_open_page",
+    label: "Paper: Open Page",
+    description: "Open an explicit Paper file and page, then return a receipt only when Paper reports that exact target as active. This cannot infer a target or alter page contents.",
+    parameters: Type.Object({
+      fileId: Type.String({ minLength: 1, description: "Explicit Paper file ID" }),
+      pageId: Type.String({ minLength: 1, description: "Explicit Paper page ID to make active" })
+    }),
+    async execute(_toolCallId, params, signal) {
+      const args = params && typeof params === "object" ? params : {};
+      try {
+        return pageOperationToolResult(
+          await openPaperPage(
+            {
+              fileId: typeof args.fileId === "string" ? args.fileId : "",
+              pageId: typeof args.pageId === "string" ? args.pageId : ""
+            },
+            signal
+          )
+        );
+      } catch (error) {
+        return pageOperationToolError(error);
+      }
+    }
+  },
+  {
+    name: "paper_create_tokens",
+    label: "Paper: Create Tokens Safely",
+    description: "Create file-scoped Paper design tokens through dry-run, explicit confirmation, and a per-entry receipt. The belt rejects unsupported types and known provider-invalid color-mix()/size-alias expressions before transport.",
+    parameters: Type.Object({
+      fileId: requiredFileIdSchema,
+      tokens: Type.Array(
+        Type.Object({
+          type: paperTokenTypeSchema,
+          name: Type.String({ pattern: "^--[a-zA-Z0-9_-]+$" }),
+          value: Type.Union([Type.String(), Type.Number()]),
+          description: Type.Optional(Type.String({ maxLength: 1024 }))
+        }),
+        { minItems: 1, maxItems: 500 }
+      ),
+      confirm: Type.Optional(Type.Boolean({ description: "Must be true for a live create after dry-run review" })),
+      dryRun: dryRunSchema
+    }),
+    async execute(_toolCallId, params, signal) {
+      const args = params && typeof params === "object" ? params : {};
+      let fileId = "";
+      let tokens = [];
+      try {
+        fileId = normalizeRequiredPageValue(args.fileId, "file ID");
+        tokens = normalizeCreateTokens(args.tokens);
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        const receipt = createTokenMutationReceipt(`Token creation validation failed: ${message}`, {
+          fileId,
+          status: "failed",
+          operation: "create",
+          requestedNames: [],
+          providerResults: [],
+          error: { code: "INVALID_INPUT", message }
+        });
+        return operatorReceiptError(receipt, "INVALID_INPUT", message);
+      }
+      const basePayload = {
+        fileId,
+        operation: "create",
+        requestedNames: tokens.map((token) => token.name),
+        providerResults: []
+      };
+      if (args.dryRun === true) {
+        return operatorReceiptResult(
+          createTokenMutationReceipt(`Dry run: previewed creation of ${tokens.length} Paper token(s).`, {
+            status: "dry-run",
+            ...basePayload
+          })
+        );
+      }
+      if (args.confirm !== true) {
+        const message = "Token creation refused: confirm=true is required after reviewing a dry run.";
+        const receipt = createTokenMutationReceipt(message, {
+          status: "refused",
+          ...basePayload,
+          error: { code: "CONFIRMATION_REQUIRED", message }
+        });
+        return operatorReceiptError(receipt, "CONFIRMATION_REQUIRED", message);
+      }
+      try {
+        await verifyPaperFileTarget(fileId, signal);
+        const providerResult = await callRequiredPaperMcp("paper_create_tokens", { fileId, tokens }, signal);
+        const providerResults = providerMutationEntries(providerResult);
+        if (providerResults.length === 0) {
+          throw new Error(
+            "Paper create_tokens returned no per-entry results; the provider response shape cannot be receipted."
+          );
+        }
+        const failures = providerResults.filter(mutationEntryFailed).length;
+        const status = failures === 0 ? "applied" : failures === providerResults.length ? "failed" : "partial";
+        const summary = failures === 0 ? `Created ${providerResults.length} Paper token(s).` : `Paper create_tokens returned ${failures} error result(s) across ${providerResults.length} entries.`;
+        const receipt = createTokenMutationReceipt(summary, {
+          status,
+          ...basePayload,
+          providerResults,
+          ...failures > 0 ? { error: { code: "PAPER_TOKEN_ENTRY_ERRORS", message: summary } } : {}
+        });
+        return failures > 0 ? operatorReceiptError(receipt, "PAPER_TOKEN_ENTRY_ERRORS", summary) : operatorReceiptResult(receipt);
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        const receipt = createTokenMutationReceipt(`Token creation failed: ${message}`, {
+          status: "failed",
+          ...basePayload,
+          error: { code: "PAPER_TOKEN_CREATE_FAILED", message }
+        });
+        return operatorReceiptError(receipt, "PAPER_TOKEN_CREATE_FAILED", message);
+      }
+    }
+  },
+  {
+    name: "paper_set_tokens",
+    label: "Paper: Set Tokens Safely",
+    description: "Rename, update, describe, or delete existing file-scoped Paper tokens through dry-run, explicit confirmation, source-token acknowledgement, and preserved per-entry results.",
+    parameters: Type.Object({
+      fileId: requiredFileIdSchema,
+      tokens: Type.Array(
+        Type.Object({
+          name: Type.String({ pattern: "^--[a-zA-Z0-9_-]+$" }),
+          newName: Type.Optional(Type.String({ pattern: "^--[a-zA-Z0-9_-]+$" })),
+          value: Type.Optional(Type.Union([Type.String(), Type.Number()])),
+          description: Type.Optional(Type.String({ maxLength: 1024 })),
+          delete: Type.Optional(Type.Boolean())
+        }),
+        { minItems: 1, maxItems: 500 }
+      ),
+      confirm: Type.Optional(Type.Boolean({ description: "Must be true for a live update after dry-run review" })),
+      sourceAcknowledgement: Type.Optional(
+        Type.Literal(SOURCE_ACKNOWLEDGEMENTS.setTokens, {
+          description: "Required because set_tokens changes or deletes existing source tokens"
+        })
+      ),
+      dryRun: dryRunSchema
+    }),
+    async execute(_toolCallId, params, signal) {
+      const args = params && typeof params === "object" ? params : {};
+      let fileId = "";
+      let tokens = [];
+      try {
+        fileId = normalizeRequiredPageValue(args.fileId, "file ID");
+        tokens = normalizeSetTokens(args.tokens);
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        const receipt = createTokenMutationReceipt(`Token update validation failed: ${message}`, {
+          fileId,
+          status: "failed",
+          operation: "set",
+          requestedNames: [],
+          providerResults: [],
+          error: { code: "INVALID_INPUT", message }
+        });
+        return operatorReceiptError(receipt, "INVALID_INPUT", message);
+      }
+      const basePayload = {
+        fileId,
+        operation: "set",
+        requestedNames: tokens.map((token) => token.name),
+        providerResults: []
+      };
+      if (args.dryRun === true) {
+        return operatorReceiptResult(
+          createTokenMutationReceipt(`Dry run: previewed ${tokens.length} Paper token update(s).`, {
+            status: "dry-run",
+            ...basePayload
+          })
+        );
+      }
+      if (args.confirm !== true) {
+        const message = "Token update refused: confirm=true is required after reviewing a dry run.";
+        const receipt = createTokenMutationReceipt(message, {
+          status: "refused",
+          ...basePayload,
+          error: { code: "CONFIRMATION_REQUIRED", message }
+        });
+        return operatorReceiptError(receipt, "CONFIRMATION_REQUIRED", message);
+      }
+      if (args.sourceAcknowledgement !== SOURCE_ACKNOWLEDGEMENTS.setTokens) {
+        const message = `Token update refused: sourceAcknowledgement="${SOURCE_ACKNOWLEDGEMENTS.setTokens}" is required.`;
+        const receipt = createTokenMutationReceipt(message, {
+          status: "refused",
+          ...basePayload,
+          error: { code: "SOURCE_ACKNOWLEDGEMENT_REQUIRED", message }
+        });
+        return operatorReceiptError(receipt, "SOURCE_ACKNOWLEDGEMENT_REQUIRED", message);
+      }
+      try {
+        await verifyPaperFileTarget(fileId, signal);
+        const providerResult = await callRequiredPaperMcp("paper_set_tokens", { fileId, tokens }, signal);
+        const providerResults = providerMutationEntries(providerResult);
+        if (providerResults.length === 0) {
+          throw new Error(
+            "Paper set_tokens returned no per-entry results; the provider response shape cannot be receipted."
+          );
+        }
+        const failures = providerResults.filter(mutationEntryFailed).length;
+        const status = failures === 0 ? "applied" : failures === providerResults.length ? "failed" : "partial";
+        const summary = failures === 0 ? `Updated ${providerResults.length} Paper token(s).` : `Paper set_tokens returned ${failures} error result(s) across ${providerResults.length} entries.`;
+        const receipt = createTokenMutationReceipt(summary, {
+          status,
+          ...basePayload,
+          providerResults,
+          ...failures > 0 ? { error: { code: "PAPER_TOKEN_ENTRY_ERRORS", message: summary } } : {}
+        });
+        return failures > 0 ? operatorReceiptError(receipt, "PAPER_TOKEN_ENTRY_ERRORS", summary) : operatorReceiptResult(receipt);
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        const receipt = createTokenMutationReceipt(`Token update failed: ${message}`, {
+          status: "failed",
+          ...basePayload,
+          error: { code: "PAPER_TOKEN_SET_FAILED", message }
+        });
+        return operatorReceiptError(receipt, "PAPER_TOKEN_SET_FAILED", message);
+      }
+    }
+  },
+  {
+    name: "paper_write_html",
+    label: "Paper: Write HTML Safely",
+    description: "Insert one incremental inline-HTML item under an exact target after dry-run and confirmation. The receipt always surfaces the provider response as payload.createdNodes (for example {createdNodes:[{id,name}]}); replacement is intentionally handled by paper_revise_artboard.",
+    parameters: Type.Object({
+      fileId: requiredFileIdSchema,
+      id: Type.String({ minLength: 1, description: "Exact target parent node ID" }),
+      html: Type.String({ minLength: 1, description: "One incremental HTML item with literal inline styles" }),
+      mode: Type.Optional(
+        Type.Literal("insert-children", { description: "Guarded writes support insert-children only" })
+      ),
+      confirm: Type.Optional(Type.Boolean({ description: "Must be true for a live write after dry-run review" })),
+      sourceAcknowledgement: Type.Optional(
+        Type.Literal(SOURCE_ACKNOWLEDGEMENTS.write, {
+          description: "Required when inserting into a target not created in this process session and file"
+        })
+      ),
+      dryRun: dryRunSchema
+    }),
+    async execute(_toolCallId, params, signal) {
+      const args = params && typeof params === "object" ? params : {};
+      let fileId = "";
+      let targetId = "";
+      let html = "";
+      try {
+        fileId = normalizeRequiredPageValue(args.fileId, "file ID");
+        targetId = nonEmptyString(args.id, "paper_write_html target id");
+        html = normalizeIncrementalHtml(args.html);
+        if (args.mode !== void 0 && args.mode !== "insert-children") {
+          throw new TypeError(
+            "paper_write_html supports insert-children only; use paper_revise_artboard for replacement."
+          );
+        }
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        const receipt = createWriteHtmlReceipt(`Write validation failed: ${message}`, {
+          fileId,
+          status: "failed",
+          targetId,
+          mode: "insert-children",
+          htmlBytes: typeof args.html === "string" ? Buffer.byteLength(args.html) : 0,
+          createdNodes: [],
+          sessionCreatedTargetIds: [],
+          sourceTargetIds: targetId ? [targetId] : [],
+          verifiedBy: null,
+          error: { code: "INVALID_INPUT", message }
+        });
+        return operatorReceiptError(receipt, "INVALID_INPUT", message);
+      }
+      let classification = classifyTargets([targetId]);
+      const basePayload = {
+        fileId,
+        targetId,
+        mode: "insert-children",
+        htmlBytes: Buffer.byteLength(html),
+        createdNodes: [],
+        ...classification,
+        verifiedBy: null
+      };
+      if (args.dryRun === true) {
+        return operatorReceiptResult(
+          createWriteHtmlReceipt(`Dry run: previewed one HTML insertion under ${targetId}; no mutation ran.`, {
+            status: "dry-run",
+            ...basePayload
+          })
+        );
+      }
+      if (args.confirm !== true) {
+        const message = "Write refused: confirm=true is required after reviewing a dry run.";
+        const receipt = createWriteHtmlReceipt(message, {
+          status: "refused",
+          ...basePayload,
+          error: { code: "CONFIRMATION_REQUIRED", message }
+        });
+        return operatorReceiptError(receipt, "CONFIRMATION_REQUIRED", message);
+      }
+      try {
+        await reconcileSessionFileScope(fileId, signal);
+        classification = classifyTargets([targetId]);
+        if (classification.sourceTargetIds.length > 0 && args.sourceAcknowledgement !== SOURCE_ACKNOWLEDGEMENTS.write) {
+          const message = `Write refused: source targets require sourceAcknowledgement="${SOURCE_ACKNOWLEDGEMENTS.write}".`;
+          const receipt = createWriteHtmlReceipt(message, {
+            status: "refused",
+            ...basePayload,
+            ...classification,
+            error: { code: "SOURCE_ACKNOWLEDGEMENT_REQUIRED", message }
+          });
+          return operatorReceiptError(receipt, "SOURCE_ACKNOWLEDGEMENT_REQUIRED", message);
+        }
+        await readNodeSnapshot(targetId, fileId, signal);
+        const providerResult = await callRequiredPaperMcp(
+          "paper_write_html",
+          { fileId, targetNodeId: targetId, html, mode: "insert-children" },
+          signal
+        );
+        const createdNodes = extractCreatedNodes(providerResult);
+        if (createdNodes.length === 0) {
+          throw new Error(
+            "Paper write_html reported success but returned no usable createdNodes. Stop and inspect the target before retrying; the belt will not invent IDs."
+          );
+        }
+        for (const node of createdNodes) sessionCreatedNodeIds.add(node.id);
+        return operatorReceiptResult(
+          createWriteHtmlReceipt(`Created and receipted ${createdNodes.length} Paper node(s) under ${targetId}.`, {
+            status: "applied",
+            ...basePayload,
+            ...classification,
+            createdNodes,
+            verifiedBy: "write_html.createdNodes"
+          })
+        );
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        const receipt = createWriteHtmlReceipt(`Write was not fully receipted: ${message}`, {
+          status: "failed",
+          ...basePayload,
+          ...classification,
+          error: { code: "PAPER_WRITE_FAILED", message }
+        });
+        return operatorReceiptError(receipt, "PAPER_WRITE_FAILED", message);
+      }
+    }
+  },
+  {
+    name: "paper_move_nodes",
+    label: "Paper: Move Nodes Safely",
+    description: "Move exact node IDs through dry-run, confirmation, and a receipt while preserving identity. Every live destination must be separately typed and fingerprinted in the approved brief; the root alias and unverified cross-page roots are rejected by the public runtime. The receipt surfaces resolved moves and affectedParents.",
+    parameters: Type.Object({
+      fileId: requiredFileIdSchema,
+      moves: Type.Array(
+        Type.Union([
+          Type.Object({
+            nodeId: Type.String({ minLength: 1 }),
+            before: Type.String({ minLength: 1, description: "Destination sibling ID" })
+          }),
+          Type.Object({
+            nodeId: Type.String({ minLength: 1 }),
+            after: Type.String({ minLength: 1, description: "Destination sibling ID" })
+          }),
+          Type.Object({
+            nodeId: Type.String({ minLength: 1 }),
+            parentId: Type.String({
+              minLength: 1,
+              description: "Exact destination parent ID. Live use requires the same ID as a typed approved move destination; the root alias is not authorized."
+            }),
+            index: Type.Optional(Type.Integer({ minimum: 0 }))
+          })
+        ]),
+        { minItems: 1, maxItems: 50 }
+      ),
+      confirm: Type.Optional(Type.Boolean({ description: "Must be true for a live move after dry-run review" })),
+      sourceAcknowledgement: Type.Optional(
+        Type.Literal(SOURCE_ACKNOWLEDGEMENTS.move, {
+          description: "Required for moved nodes not created in this process session and file"
+        })
+      ),
+      dryRun: dryRunSchema
+    }),
+    async execute(_toolCallId, params, signal) {
+      const args = params && typeof params === "object" ? params : {};
+      let fileId = "";
+      let moves = [];
+      try {
+        fileId = normalizeRequiredPageValue(args.fileId, "file ID");
+        moves = normalizeMoves(args.moves);
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        const receipt = createMoveNodesReceipt(`Move validation failed: ${message}`, {
+          fileId,
+          status: "failed",
+          moves: [],
+          sessionCreatedTargetIds: [],
+          sourceTargetIds: [],
+          providerResult: null,
+          verifiedBy: null,
+          error: { code: "INVALID_INPUT", message }
+        });
+        return operatorReceiptError(receipt, "INVALID_INPUT", message);
+      }
+      const targetIds = moves.map((move) => move.nodeId);
+      let classification = classifyTargets(targetIds);
+      const basePayload = {
+        fileId,
+        moves,
+        ...classification,
+        providerResult: null,
+        verifiedBy: null
+      };
+      if (args.dryRun === true) {
+        return operatorReceiptResult(
+          createMoveNodesReceipt(`Dry run: previewed ${moves.length} identity-preserving Paper move(s).`, {
+            status: "dry-run",
+            ...basePayload
+          })
+        );
+      }
+      if (args.confirm !== true) {
+        const message = "Move refused: confirm=true is required after reviewing a dry run.";
+        const receipt = createMoveNodesReceipt(message, {
+          status: "refused",
+          ...basePayload,
+          error: { code: "CONFIRMATION_REQUIRED", message }
+        });
+        return operatorReceiptError(receipt, "CONFIRMATION_REQUIRED", message);
+      }
+      try {
+        await reconcileSessionFileScope(fileId, signal);
+        classification = classifyTargets(targetIds);
+        if (classification.sourceTargetIds.length > 0 && args.sourceAcknowledgement !== SOURCE_ACKNOWLEDGEMENTS.move) {
+          const message = `Move refused: source targets require sourceAcknowledgement="${SOURCE_ACKNOWLEDGEMENTS.move}".`;
+          const receipt = createMoveNodesReceipt(message, {
+            status: "refused",
+            ...basePayload,
+            ...classification,
+            error: { code: "SOURCE_ACKNOWLEDGEMENT_REQUIRED", message }
+          });
+          return operatorReceiptError(receipt, "SOURCE_ACKNOWLEDGEMENT_REQUIRED", message);
+        }
+        const snapshots = await Promise.all(targetIds.map((id) => readNodeSnapshot(id, fileId, signal)));
+        const protectedNodes = snapshots.filter((snapshot) => !snapshot.parentId);
+        if (protectedNodes.length > 0) {
+          throw new Error(
+            `Root or page nodes cannot be moved: ${protectedNodes.map((node) => node.id).join(", ")}.`
+          );
+        }
+        const rawProviderResult = await callRequiredPaperMcp("paper_move_nodes", { fileId, moves }, signal);
+        const providerResult = parseMcpJsonValue(rawProviderResult);
+        const providerRecord = providerResult && typeof providerResult === "object" && !Array.isArray(providerResult) ? providerResult : void 0;
+        if (!Array.isArray(providerRecord?.affectedParents)) {
+          throw new Error(
+            "Paper move_nodes returned no affectedParents receipt. Stop before assuming the hierarchy is clean."
+          );
+        }
+        return operatorReceiptResult(
+          createMoveNodesReceipt(`Moved and receipted ${moves.length} Paper node(s) without changing IDs.`, {
+            status: "applied",
+            ...basePayload,
+            ...classification,
+            providerResult,
+            verifiedBy: "move_nodes.affectedParents"
+          })
+        );
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        const receipt = createMoveNodesReceipt(`Move was not fully receipted: ${message}`, {
+          status: "failed",
+          ...basePayload,
+          ...classification,
+          error: { code: "PAPER_MOVE_FAILED", message }
+        });
+        return operatorReceiptError(receipt, "PAPER_MOVE_FAILED", message);
+      }
+    }
+  },
+  {
+    name: "paper_rename_nodes",
+    label: "Paper: Rename Nodes Safely",
+    description: "Rename exactly the listed Paper nodes through a dry-run and explicit-confirmation receipt. This cannot edit styles, content, hierarchy, or delete nodes. Targets not created in this process session and active file require sourceAcknowledgement='rename-source'.",
+    parameters: Type.Object({
+      fileId: requiredFileIdSchema,
+      updates: Type.Array(
+        Type.Object({
+          id: Type.String({ description: "Paper node ID to rename" }),
+          name: Type.String({ description: "New non-empty node name" })
+        }),
+        { description: "Exact node IDs and replacement names" }
+      ),
+      confirm: Type.Optional(Type.Boolean({ description: "Must be true for a live rename after dry-run review" })),
+      sourceAcknowledgement: Type.Optional(
+        Type.Literal(SOURCE_ACKNOWLEDGEMENTS.rename, {
+          description: "Required with confirm for targets not created in this process session and active file"
+        })
+      ),
+      dryRun: dryRunSchema
+    }),
+    async execute(_toolCallId, params, signal) {
+      const args = params && typeof params === "object" ? params : {};
+      let fileId = "";
+      let updates = [];
+      try {
+        fileId = normalizeRequiredPageValue(args.fileId, "file ID");
+        updates = normalizeRenameUpdates(args.updates);
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        const receipt = createRenameReceipt(`Rename validation failed: ${message}`, {
+          fileId,
+          status: "failed",
+          updates: [],
+          sessionCreatedTargetIds: [],
+          sourceTargetIds: [],
+          verifiedBy: null,
+          error: { code: "INVALID_INPUT", message }
+        });
+        return operatorReceiptError(receipt, "INVALID_INPUT", message);
+      }
+      const targetIds = updates.map((update) => update.id);
+      let classification = classifyTargets(targetIds);
+      const previewUpdates = updates.map((update) => ({ id: update.id, from: null, to: update.name }));
+      if (args.dryRun === true) {
+        return operatorReceiptResult(
+          createRenameReceipt(`Dry run: previewed ${updates.length} Paper node rename(s); no mutation ran.`, {
+            fileId,
+            status: "dry-run",
+            updates: previewUpdates,
+            ...classification,
+            verifiedBy: null
+          })
+        );
+      }
+      if (args.confirm !== true) {
+        const message = "Rename refused: confirm=true is required after reviewing a dry run.";
+        const receipt = createRenameReceipt(message, {
+          fileId,
+          status: "refused",
+          updates: previewUpdates,
+          ...classification,
+          verifiedBy: null,
+          error: { code: "CONFIRMATION_REQUIRED", message }
+        });
+        return operatorReceiptError(receipt, "CONFIRMATION_REQUIRED", message);
+      }
+      try {
+        await reconcileSessionFileScope(fileId, signal);
+        classification = classifyTargets(targetIds);
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        const receipt = createRenameReceipt(
+          `Rename refused because file provenance could not be verified: ${message}`,
+          {
+            fileId,
+            status: "failed",
+            updates: previewUpdates,
+            ...classification,
+            verifiedBy: null,
+            error: { code: "FILE_PROVENANCE_FAILED", message }
+          }
+        );
+        return operatorReceiptError(receipt, "FILE_PROVENANCE_FAILED", message);
+      }
+      if (classification.sourceTargetIds.length > 0 && args.sourceAcknowledgement !== SOURCE_ACKNOWLEDGEMENTS.rename) {
+        const message = `Rename refused: source targets require sourceAcknowledgement="${SOURCE_ACKNOWLEDGEMENTS.rename}".`;
+        const receipt = createRenameReceipt(message, {
+          fileId,
+          status: "refused",
+          updates: previewUpdates,
+          ...classification,
+          verifiedBy: null,
+          error: { code: "SOURCE_ACKNOWLEDGEMENT_REQUIRED", message }
+        });
+        return operatorReceiptError(receipt, "SOURCE_ACKNOWLEDGEMENT_REQUIRED", message);
+      }
+      let before = [];
+      try {
+        before = await Promise.all(targetIds.map((id) => readNodeSnapshot(id, fileId, signal)));
+        const protectedNodes = before.filter((snapshot) => !snapshot.parentId);
+        if (protectedNodes.length > 0) {
+          throw new Error(
+            `Root or page nodes cannot be renamed: ${protectedNodes.map((node) => node.id).join(", ")}.`
+          );
+        }
+        await callRequiredPaperMcp(
+          "paper_rename_nodes",
+          { fileId, updates: updates.map((update) => ({ nodeId: update.id, name: update.name })) },
+          signal
+        );
+        const after = await Promise.all(targetIds.map((id) => readNodeSnapshot(id, fileId, signal)));
+        const expectedNames = new Map(updates.map((update) => [update.id, update.name]));
+        const mismatches = after.filter((snapshot) => expectedNames.get(snapshot.id) !== snapshot.name);
+        if (mismatches.length > 0) {
+          throw new Error(
+            `Paper did not verify the requested name for: ${mismatches.map((node) => node.id).join(", ")}.`
+          );
+        }
+        const previousNames = new Map(before.map((snapshot) => [snapshot.id, snapshot.name]));
+        const verifiedUpdates = updates.map((update) => ({
+          id: update.id,
+          from: previousNames.get(update.id) ?? null,
+          to: update.name
+        }));
+        return operatorReceiptResult(
+          createRenameReceipt(`Renamed and verified ${updates.length} Paper node(s).`, {
+            fileId,
+            status: "applied",
+            updates: verifiedUpdates,
+            ...classification,
+            verifiedBy: "paper_get_node_info"
+          })
+        );
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        const previousNames = new Map(before.map((snapshot) => [snapshot.id, snapshot.name]));
+        const receipt = createRenameReceipt(`Rename was not fully verified: ${message}`, {
+          fileId,
+          status: "failed",
+          updates: updates.map((update) => ({
+            id: update.id,
+            from: previousNames.get(update.id) ?? null,
+            to: update.name
+          })),
+          ...classification,
+          verifiedBy: null,
+          error: { code: "PAPER_RENAME_FAILED", message }
+        });
+        return operatorReceiptError(receipt, "PAPER_RENAME_FAILED", message);
+      }
+    }
+  },
+  {
+    name: "paper_revise_artboard",
+    label: "Paper: Revise Artboard Safely",
+    description: "Replace only the children of one existing Paper artboard from validated literal inline-CSS HTML, then screenshot the result. This cannot replace the artboard root or touch siblings. Artboards not created in this process session and active file require sourceAcknowledgement='revise-source'.",
+    parameters: Type.Object({
+      fileId: requiredFileIdSchema,
+      id: Type.String({ description: "Existing Paper artboard ID whose children will be replaced" }),
+      html: Type.String({ description: "Literal inline-CSS HTML with concrete layout and typography values" }),
+      confirm: Type.Optional(Type.Boolean({ description: "Must be true for a live revision after dry-run review" })),
+      sourceAcknowledgement: Type.Optional(
+        Type.Literal(SOURCE_ACKNOWLEDGEMENTS.revise, {
+          description: "Required with confirm for an artboard not created in this process session and active file"
+        })
+      ),
+      dryRun: dryRunSchema
+    }),
+    async execute(_toolCallId, params, signal) {
+      const args = params && typeof params === "object" ? params : {};
+      let fileId = "";
+      const id = typeof args.id === "string" ? args.id.trim() : "";
+      let html = "";
+      try {
+        fileId = normalizeRequiredPageValue(args.fileId, "file ID");
+        if (!id) throw new TypeError("Revision requires one existing Paper artboard ID.");
+        html = normalizeLiteralHtml(args.html);
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        const receipt = createReviseReceipt(`Revision validation failed: ${message}`, {
+          fileId,
+          status: "failed",
+          artboardId: id,
+          artboardName: null,
+          htmlBytes: typeof args.html === "string" ? Buffer.byteLength(args.html) : 0,
+          mode: "replace",
+          sessionCreatedTargetIds: [],
+          sourceTargetIds: id ? [id] : [],
+          verifiedBy: null,
+          error: { code: "INVALID_INPUT", message }
+        });
+        return operatorReceiptError(receipt, "INVALID_INPUT", message);
+      }
+      let classification = classifyTargets([id]);
+      let basePayload = {
+        fileId,
+        artboardId: id,
+        artboardName: null,
+        htmlBytes: Buffer.byteLength(html),
+        mode: "replace",
+        ...classification,
+        verifiedBy: null
+      };
+      if (args.dryRun === true) {
+        return operatorReceiptResult(
+          createReviseReceipt(`Dry run: previewed replacement of artboard ${id} children; no mutation ran.`, {
+            status: "dry-run",
+            ...basePayload
+          })
+        );
+      }
+      if (args.confirm !== true) {
+        const message = "Revision refused: confirm=true is required after reviewing a dry run.";
+        const receipt = createReviseReceipt(message, {
+          status: "refused",
+          ...basePayload,
+          error: { code: "CONFIRMATION_REQUIRED", message }
+        });
+        return operatorReceiptError(receipt, "CONFIRMATION_REQUIRED", message);
+      }
+      try {
+        await reconcileSessionFileScope(fileId, signal);
+        classification = classifyTargets([id]);
+        basePayload = {
+          ...basePayload,
+          ...classification
+        };
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        const receipt = createReviseReceipt(
+          `Revision refused because file provenance could not be verified: ${message}`,
+          {
+            status: "failed",
+            ...basePayload,
+            error: { code: "FILE_PROVENANCE_FAILED", message }
+          }
+        );
+        return operatorReceiptError(receipt, "FILE_PROVENANCE_FAILED", message);
+      }
+      if (classification.sourceTargetIds.length > 0 && args.sourceAcknowledgement !== SOURCE_ACKNOWLEDGEMENTS.revise) {
+        const message = `Revision refused: source artboards require sourceAcknowledgement="${SOURCE_ACKNOWLEDGEMENTS.revise}".`;
+        const receipt = createReviseReceipt(message, {
+          status: "refused",
+          ...basePayload,
+          error: { code: "SOURCE_ACKNOWLEDGEMENT_REQUIRED", message }
+        });
+        return operatorReceiptError(receipt, "SOURCE_ACKNOWLEDGEMENT_REQUIRED", message);
+      }
+      let artboardName = null;
+      try {
+        const snapshot = await readNodeSnapshot(id, fileId, signal);
+        artboardName = snapshot.name;
+        if (!snapshot.parentId?.startsWith("root_node_")) {
+          throw new Error(`${id} is not a top-level Paper artboard; revise-artboard cannot touch it.`);
+        }
+        await callRequiredPaperMcp("paper_write_html", { fileId, targetNodeId: id, html, mode: "replace" }, signal);
+        const screenshotResponse = await callPaperScreenshotWithReadiness({ fileId, nodeId: id, scale: 1 }, signal);
+        if (!screenshotResponse.ok) throw new Error(screenshotResponse.error);
+        const screenshotResult = screenshotResponse.result;
+        const images = formatMcpResult(screenshotResult).filter((part) => part.type === "image").map(({ data, mimeType }) => ({ data, mimeType }));
+        if (images.length === 0) throw new Error(`Paper returned no screenshot for revised artboard ${id}.`);
+        await callRequiredPaperMcp("paper_finish_working_on_nodes", { fileId, nodeIds: [id] }, signal);
+        return operatorReceiptResult(
+          createReviseReceipt(`Replaced and screenshot-verified the children of \u201C${artboardName}\u201D (${id}).`, {
+            status: "applied",
+            ...basePayload,
+            artboardName,
+            verifiedBy: "paper_get_screenshot"
+          }),
+          images
+        );
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        const receipt = createReviseReceipt(`Revision was not fully verified: ${message}`, {
+          status: "failed",
+          ...basePayload,
+          artboardName,
+          error: { code: "PAPER_REVISION_FAILED", message }
+        });
+        return operatorReceiptError(receipt, "PAPER_REVISION_FAILED", message);
+      }
+    }
+  },
+  {
+    name: "paper_delete_nodes",
+    label: "Paper: Delete Nodes Safely",
+    description: "Delete exactly the listed Paper nodes and descendants after a dry run, explicit confirmation, named-node preflight, and absence verification. This cannot delete root or page nodes. Targets not created in this process session and active file require sourceAcknowledgement='delete-source'.",
+    parameters: Type.Object({
+      fileId: requiredFileIdSchema,
+      ids: Type.Array(Type.String(), { description: "Exact Paper node IDs to delete" }),
+      confirm: Type.Optional(Type.Boolean({ description: "Must be true for a live deletion after dry-run review" })),
+      sourceAcknowledgement: Type.Optional(
+        Type.Literal(SOURCE_ACKNOWLEDGEMENTS.delete, {
+          description: "Required with confirm for nodes not created in this process session and active file"
+        })
+      ),
+      dryRun: dryRunSchema
+    }),
+    async execute(_toolCallId, params, signal) {
+      const args = params && typeof params === "object" ? params : {};
+      let fileId = "";
+      let ids = [];
+      try {
+        fileId = normalizeRequiredPageValue(args.fileId, "file ID");
+        ids = normalizeNodeIds(args.ids);
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        const receipt = createDeleteReceipt(`Delete validation failed: ${message}`, {
+          fileId,
+          status: "failed",
+          requestedIds: [],
+          removed: [],
+          sessionCreatedTargetIds: [],
+          sourceTargetIds: [],
+          verifiedBy: null,
+          error: { code: "INVALID_INPUT", message }
+        });
+        return operatorReceiptError(receipt, "INVALID_INPUT", message);
+      }
+      let classification = classifyTargets(ids);
+      const previewRemoved = ids.map((id) => ({ id, name: null }));
+      if (args.dryRun === true) {
+        return operatorReceiptResult(
+          createDeleteReceipt(`Dry run: previewed deletion of ${ids.length} Paper node(s); no mutation ran.`, {
+            fileId,
+            status: "dry-run",
+            requestedIds: ids,
+            removed: previewRemoved,
+            ...classification,
+            verifiedBy: null
+          })
+        );
+      }
+      if (args.confirm !== true) {
+        const message = "Delete refused: confirm=true is required after reviewing a dry run.";
+        const receipt = createDeleteReceipt(message, {
+          fileId,
+          status: "refused",
+          requestedIds: ids,
+          removed: previewRemoved,
+          ...classification,
+          verifiedBy: null,
+          error: { code: "CONFIRMATION_REQUIRED", message }
+        });
+        return operatorReceiptError(receipt, "CONFIRMATION_REQUIRED", message);
+      }
+      try {
+        await reconcileSessionFileScope(fileId, signal);
+        classification = classifyTargets(ids);
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        const receipt = createDeleteReceipt(
+          `Delete refused because file provenance could not be verified: ${message}`,
+          {
+            fileId,
+            status: "failed",
+            requestedIds: ids,
+            removed: previewRemoved,
+            ...classification,
+            verifiedBy: null,
+            error: { code: "FILE_PROVENANCE_FAILED", message }
+          }
+        );
+        return operatorReceiptError(receipt, "FILE_PROVENANCE_FAILED", message);
+      }
+      if (classification.sourceTargetIds.length > 0 && args.sourceAcknowledgement !== SOURCE_ACKNOWLEDGEMENTS.delete) {
+        const message = `Delete refused: source nodes require sourceAcknowledgement="${SOURCE_ACKNOWLEDGEMENTS.delete}".`;
+        const receipt = createDeleteReceipt(message, {
+          fileId,
+          status: "refused",
+          requestedIds: ids,
+          removed: previewRemoved,
+          ...classification,
+          verifiedBy: null,
+          error: { code: "SOURCE_ACKNOWLEDGEMENT_REQUIRED", message }
+        });
+        return operatorReceiptError(receipt, "SOURCE_ACKNOWLEDGEMENT_REQUIRED", message);
+      }
+      let snapshots = [];
+      try {
+        snapshots = await Promise.all(ids.map((id) => readNodeSnapshot(id, fileId, signal)));
+        const protectedNodes = snapshots.filter((snapshot) => !snapshot.parentId);
+        if (protectedNodes.length > 0) {
+          throw new Error(
+            `Root or page nodes cannot be deleted: ${protectedNodes.map((node) => node.id).join(", ")}.`
+          );
+        }
+        await callRequiredPaperMcp("paper_delete_nodes", { fileId, nodeIds: ids }, signal);
+        for (const id of ids) sessionCreatedNodeIds.delete(id);
+        await Promise.all(ids.map((id) => verifyNodeAbsent(id, fileId, signal)));
+        const removed = snapshots.map((snapshot) => ({ id: snapshot.id, name: snapshot.name }));
+        return operatorReceiptResult(
+          createDeleteReceipt(
+            `Deleted and absence-verified ${removed.map((node) => `\u201C${node.name}\u201D (${node.id})`).join(", ")}.`,
+            {
+              fileId,
+              status: "applied",
+              requestedIds: ids,
+              removed,
+              ...classification,
+              verifiedBy: "paper_get_node_info:not-found"
+            }
+          )
+        );
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        const receipt = createDeleteReceipt(`Delete was not fully verified: ${message}`, {
+          fileId,
+          status: "failed",
+          requestedIds: ids,
+          removed: snapshots.length > 0 ? snapshots.map((snapshot) => ({ id: snapshot.id, name: snapshot.name })) : previewRemoved,
+          ...classification,
+          verifiedBy: null,
+          error: { code: "PAPER_DELETE_FAILED", message }
+        });
+        return operatorReceiptError(receipt, "PAPER_DELETE_FAILED", message);
+      }
+    }
+  }
+];
+var RAW_PROVIDER_MUTATION_TOOLS = /* @__PURE__ */ new Set([
+  "paper_create_artboard",
+  "paper_write_html",
+  "paper_set_text_content",
+  "paper_rename_nodes",
+  "paper_duplicate_nodes",
+  "paper_update_styles",
+  "paper_delete_nodes",
+  "paper_finish_working_on_nodes"
+]);
+var paperTools = [
+  ...paperMcpTools.filter((tool) => !RAW_PROVIDER_MUTATION_TOOLS.has(tool.name)),
+  ...paperOperatorTools
+];
+var paperToolNames = new Set(paperTools.map((t) => t.name));
+async function isPaperRunning(fileId) {
+  const result = await callPaperMcp("paper_get_basic_info", fileId ? { fileId } : {}, void 0, 3e3);
+  return result.ok;
+}
+
+// src/tool-contract.ts
+var CONTRACT_PATH = join2(getPackageDir(), "tools.contract.json");
+var paperLoadedToolContract = loadMonoToolContract(CONTRACT_PATH);
+assertPaperContractIdentity(paperLoadedToolContract.contract);
+var paperToolContract = paperLoadedToolContract.contract;
+var PAPER_TOOL_CONTRACT_PATH = paperLoadedToolContract.contractPath;
+var PAPER_TOOL_CONTRACT_HASH = paperLoadedToolContract.hash;
+var PAPER_DOMAIN_TOOL_NAMES = paperToolContract.tools.map((tool) => tool.id);
+function stableJsonValue(value) {
+  if (Array.isArray(value)) return value.map(stableJsonValue);
+  if (value && typeof value === "object") {
+    const record = value;
+    return Object.fromEntries(
+      Object.keys(record).sort().map((key) => [key, stableJsonValue(record[key])])
+    );
+  }
+  return value;
+}
+var PAPER_TOOL_SCHEMA_HASHES = Object.fromEntries(
+  paperTools.map((tool) => [
+    tool.name,
+    `sha256:${createHash2("sha256").update(JSON.stringify(stableJsonValue(tool.parameters))).digest("hex")}`
+  ])
+);
+function resolvePaperAgentHome(requested) {
+  const configured = resolve2(getAgentDir());
+  if (!requested || resolve2(requested) === configured) return configured;
+  return resolveMonoAgentHome(paperToolContract, requested);
+}
+function renderPaperToolInventoryXml() {
+  return renderMonoToolPromptInventory(paperToolContract);
+}
+function extractPaperPromptToolIds(prompt) {
+  return extractMonoPromptToolIds(prompt);
+}
+function paperDomainToolIdsFromActive(toolIds) {
+  return toolIds.filter((id) => id.startsWith("paper_"));
+}
+function assertPaperToolContractHandshake(input) {
+  const agentHome = resolvePaperAgentHome(input.agentHome);
+  const handshake = assertMonoToolContractHandshake({
+    contract: paperToolContract,
+    contractHash: PAPER_TOOL_CONTRACT_HASH,
+    registeredToolIds: input.registeredToolIds,
+    customDefinitionToolIds: input.registeredToolIds,
+    prompt: input.prompt,
+    activeToolIds: input.activeToolIds ? paperDomainToolIdsFromActive(input.activeToolIds) : void 0
+  });
+  return { ...handshake, agentHome };
+}
+function resolvePaperContractRef(reference) {
+  return resolveMonoContractRef(PAPER_TOOL_CONTRACT_PATH, reference);
+}
+function assertPaperContractFixturesExist() {
+  assertMonoContractFixturesExist(paperLoadedToolContract);
+}
+function assertPaperContractIdentity(contract) {
+  if (contract.specialist !== "paper" || contract.ownerCommand !== "paper mono" || contract.agentHome !== "~/.paper/agent") {
+    throw new Error("Paper tools.contract.json identity does not match the owner runtime.");
+  }
+}
+
+export {
+  assertMonoToolContractHandshake,
+  resolveMonoAgentHome,
+  resolveMonoContractRef,
+  callPaperMcp,
+  paperTools,
+  paperLoadedToolContract,
+  paperToolContract,
+  PAPER_TOOL_CONTRACT_PATH,
+  PAPER_TOOL_CONTRACT_HASH,
+  PAPER_DOMAIN_TOOL_NAMES,
+  PAPER_TOOL_SCHEMA_HASHES,
+  resolvePaperAgentHome,
+  renderPaperToolInventoryXml,
+  extractPaperPromptToolIds,
+  paperDomainToolIdsFromActive,
+  assertPaperToolContractHandshake,
+  resolvePaperContractRef,
+  assertPaperContractFixturesExist
+};