@trohde/excal-cli 1.0.0

package/dist/cli/index.js

@@ -0,0 +1,1245 @@
+#!/usr/bin/env node
+
+// src/cli/index.ts
+import { Command, CommanderError } from "commander";
+
+// src/core/envelope.ts
+function buildEnvelope(opts) {
+  return {
+    schema_version: "1.0",
+    request_id: opts.request_id,
+    ok: opts.ok,
+    command: opts.command,
+    target: opts.target ?? null,
+    result: opts.result,
+    warnings: opts.warnings ?? [],
+    errors: opts.errors ?? [],
+    metrics: { duration_ms: opts.duration_ms }
+  };
+}
+
+// src/core/errors.ts
+var CliError = class extends Error {
+  constructor(structured) {
+    super(structured.message);
+    this.structured = structured;
+    this.name = "CliError";
+  }
+};
+function validationError(code, message, details) {
+  return new CliError({
+    code: `ERR_VALIDATION_${code}`,
+    message,
+    retryable: false,
+    suggested_action: "fix_input",
+    details
+  });
+}
+function renderError(code, message, details) {
+  return new CliError({
+    code: `ERR_RENDER_${code}`,
+    message,
+    retryable: false,
+    suggested_action: "escalate",
+    details
+  });
+}
+function ioError(code, message, details) {
+  return new CliError({
+    code: `ERR_IO_${code}`,
+    message,
+    retryable: true,
+    suggested_action: "retry",
+    details
+  });
+}
+function internalError(message, details) {
+  return new CliError({
+    code: "ERR_INTERNAL_UNEXPECTED",
+    message,
+    retryable: false,
+    suggested_action: "escalate",
+    details
+  });
+}
+function errorMessage(err) {
+  return err instanceof Error ? err.message : String(err);
+}
+
+// src/core/exit-codes.ts
+var ExitCode = {
+  OK: 0,
+  VALIDATION: 10,
+  RENDER: 20,
+  IO: 50,
+  INTERNAL: 90
+};
+function exitCodeForError(code) {
+  if (code.startsWith("ERR_VALIDATION")) return ExitCode.VALIDATION;
+  if (code.startsWith("ERR_RENDER")) return ExitCode.RENDER;
+  if (code.startsWith("ERR_IO")) return ExitCode.IO;
+  return ExitCode.INTERNAL;
+}
+
+// src/core/request-id.ts
+import { randomBytes } from "crypto";
+function generateRequestId() {
+  const now = /* @__PURE__ */ new Date();
+  const pad = (n, len = 2) => String(n).padStart(len, "0");
+  const date = `${now.getFullYear()}${pad(now.getMonth() + 1)}${pad(now.getDate())}`;
+  const time = `${pad(now.getHours())}${pad(now.getMinutes())}${pad(now.getSeconds())}`;
+  const rand = randomBytes(2).toString("hex");
+  return `req_${date}_${time}_${rand}`;
+}
+
+// src/core/timer.ts
+var Timer = class {
+  start;
+  constructor() {
+    this.start = process.hrtime.bigint();
+  }
+  elapsed() {
+    const diff = process.hrtime.bigint() - this.start;
+    return Number(diff / 1000000n);
+  }
+};
+
+// src/core/command-wrapper.ts
+function wrapCommand(command, handler) {
+  return async (...args) => {
+    const timer = new Timer();
+    const requestId = generateRequestId();
+    const warnings = [];
+    const ctx = {
+      requestId,
+      timer,
+      warnings,
+      warn(w) {
+        warnings.push(w);
+      }
+    };
+    let envelope;
+    try {
+      const { result, target } = await handler(ctx, ...args);
+      envelope = buildEnvelope({
+        request_id: requestId,
+        command,
+        target,
+        result,
+        ok: true,
+        warnings,
+        duration_ms: timer.elapsed()
+      });
+    } catch (err) {
+      const structured = err instanceof CliError ? err.structured : internalError(errorMessage(err)).structured;
+      envelope = buildEnvelope({
+        request_id: requestId,
+        command,
+        result: null,
+        ok: false,
+        warnings,
+        errors: [structured],
+        duration_ms: timer.elapsed()
+      });
+      process.exitCode = exitCodeForError(structured.code);
+    }
+    const json = JSON.stringify(envelope, null, 2) + "\n";
+    await new Promise((resolve2) => {
+      process.stdout.write(json, () => resolve2());
+    });
+  };
+}
+
+// src/scene/schema.ts
+import { z } from "zod";
+var ExcalidrawElementSchema = z.object({
+  id: z.string(),
+  type: z.string(),
+  x: z.number(),
+  y: z.number(),
+  width: z.number(),
+  height: z.number(),
+  isDeleted: z.boolean().optional().default(false),
+  opacity: z.number().optional().default(100),
+  groupIds: z.array(z.string()).optional().default([]),
+  frameId: z.string().nullable().optional().default(null),
+  boundElements: z.array(
+    z.object({
+      id: z.string(),
+      type: z.string()
+    })
+  ).nullable().optional().default(null),
+  // Text-specific
+  text: z.string().optional(),
+  fontSize: z.number().optional(),
+  fontFamily: z.number().optional(),
+  containerId: z.string().nullable().optional().default(null),
+  // Arrow-specific
+  startBinding: z.object({
+    elementId: z.string(),
+    focus: z.number(),
+    gap: z.number()
+  }).nullable().optional().default(null),
+  endBinding: z.object({
+    elementId: z.string(),
+    focus: z.number(),
+    gap: z.number()
+  }).nullable().optional().default(null),
+  // Image-specific
+  fileId: z.string().nullable().optional().default(null),
+  // Frame-specific
+  name: z.string().nullable().optional().default(null)
+}).passthrough();
+var ExcalidrawSceneSchema = z.object({
+  type: z.string().optional().default("excalidraw"),
+  version: z.number().optional().default(2),
+  source: z.string().optional(),
+  elements: z.array(ExcalidrawElementSchema),
+  appState: z.record(z.unknown()).optional().default({}),
+  files: z.record(z.unknown()).optional().default({})
+});
+
+// src/core/io.ts
+import { readFile, writeFile, rename, mkdir } from "fs/promises";
+import { dirname, join } from "path";
+import { randomBytes as randomBytes2 } from "crypto";
+async function readInput(fileOrDash) {
+  if (fileOrDash === "-") {
+    return readStdin();
+  }
+  try {
+    const content = await readFile(fileOrDash, "utf-8");
+    return { content, source: fileOrDash };
+  } catch (err) {
+    const msg = errorMessage(err);
+    throw ioError("READ_FAILED", `Failed to read file: ${fileOrDash}: ${msg}`, {
+      path: fileOrDash
+    });
+  }
+}
+async function readStdin() {
+  return new Promise((resolve2, reject) => {
+    const chunks = [];
+    process.stdin.on("data", (chunk) => chunks.push(chunk));
+    process.stdin.on("end", () => {
+      resolve2({
+        content: Buffer.concat(chunks).toString("utf-8"),
+        source: "stdin"
+      });
+    });
+    process.stdin.on("error", (err) => {
+      reject(ioError("STDIN_FAILED", `Failed to read stdin: ${err.message}`));
+    });
+  });
+}
+async function ensureDir(dir) {
+  await mkdir(dir, { recursive: true });
+}
+async function writeOutput(path, data) {
+  try {
+    await ensureDir(dirname(path));
+    const tmpPath = join(dirname(path), `.tmp_${randomBytes2(4).toString("hex")}`);
+    await writeFile(tmpPath, data);
+    await rename(tmpPath, path);
+  } catch (err) {
+    const msg = errorMessage(err);
+    throw ioError("WRITE_FAILED", `Failed to write file: ${path}: ${msg}`, {
+      path
+    });
+  }
+}
+
+// src/core/fingerprint.ts
+import { createHash } from "crypto";
+function sha256(data) {
+  return createHash("sha256").update(data).digest("hex");
+}
+
+// src/scene/load-scene.ts
+async function loadScene(fileOrDash) {
+  const { content, source } = await readInput(fileOrDash);
+  const fingerprint = sha256(content);
+  let json;
+  try {
+    json = JSON.parse(content);
+  } catch {
+    throw validationError("INVALID_JSON", "Input is not valid JSON", { source });
+  }
+  const parsed = detectAndParse(json, source);
+  return { parsed, source, fingerprint };
+}
+function detectAndParse(json, source) {
+  if (isObject(json) && json.type === "excalidraw/clipboard" && "elements" in json) {
+    const sceneData = { ...json, type: "excalidraw" };
+    const result = ExcalidrawSceneSchema.safeParse(sceneData);
+    if (result.success) return result.data;
+    throw validationError(
+      "INVALID_CLIPBOARD",
+      `Clipboard data validation failed: ${result.error.message}`,
+      { source }
+    );
+  }
+  if (isObject(json) && "elements" in json && Array.isArray(json.elements)) {
+    const result = ExcalidrawSceneSchema.safeParse(json);
+    if (result.success) return result.data;
+    throw validationError("INVALID_SCENE", `Scene validation failed: ${result.error.message}`, {
+      source,
+      issues: result.error.issues
+    });
+  }
+  if (Array.isArray(json)) {
+    const wrapped = { type: "excalidraw", version: 2, elements: json };
+    const result = ExcalidrawSceneSchema.safeParse(wrapped);
+    if (result.success) return result.data;
+    throw validationError(
+      "INVALID_ELEMENTS",
+      `Elements array validation failed: ${result.error.message}`,
+      { source, issues: result.error.issues }
+    );
+  }
+  throw validationError("UNKNOWN_FORMAT", "Input is not a recognized Excalidraw format", {
+    source
+  });
+}
+function isObject(v) {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+// src/scene/inspect-scene.ts
+function inspectScene(scene) {
+  const countsByType = {};
+  const deletedCountsByType = {};
+  const frameElements = [];
+  const images = [];
+  const frameChildCounts = /* @__PURE__ */ new Map();
+  let deletedCount = 0;
+  let textCount = 0;
+  let boundTextCount = 0;
+  let minX = Infinity;
+  let minY = Infinity;
+  let maxX = -Infinity;
+  let maxY = -Infinity;
+  let liveCount = 0;
+  for (const el of scene.elements) {
+    if (el.isDeleted) {
+      deletedCount++;
+      deletedCountsByType[el.type] = (deletedCountsByType[el.type] ?? 0) + 1;
+      continue;
+    }
+    liveCount++;
+    countsByType[el.type] = (countsByType[el.type] ?? 0) + 1;
+    minX = Math.min(minX, el.x);
+    minY = Math.min(minY, el.y);
+    maxX = Math.max(maxX, el.x + el.width);
+    maxY = Math.max(maxY, el.y + el.height);
+    if (el.frameId) {
+      frameChildCounts.set(el.frameId, (frameChildCounts.get(el.frameId) ?? 0) + 1);
+    }
+    if (el.type === "frame") {
+      frameElements.push(el);
+    }
+    if (el.type === "image") {
+      images.push({ id: el.id, fileId: el.fileId, width: el.width, height: el.height });
+    }
+    if (el.type === "text") {
+      textCount++;
+      if (el.containerId) boundTextCount++;
+    }
+  }
+  const frames = frameElements.map((f) => ({
+    id: f.id,
+    name: f.name,
+    child_count: frameChildCounts.get(f.id) ?? 0
+  }));
+  const bounding_box = liveCount === 0 ? null : { minX, minY, maxX, maxY, width: maxX - minX, height: maxY - minY };
+  const binaryFiles = [];
+  if (scene.files && typeof scene.files === "object") {
+    for (const [id, file] of Object.entries(scene.files)) {
+      if (isFileEntry(file)) {
+        const size = typeof file.dataURL === "string" ? Math.round(file.dataURL.length * 3 / 4) : 0;
+        binaryFiles.push({ id, mimeType: file.mimeType ?? "unknown", size });
+      }
+    }
+  }
+  return {
+    element_count: liveCount,
+    deleted_count: deletedCount,
+    counts_by_type: countsByType,
+    deleted_counts_by_type: deletedCountsByType,
+    frames,
+    images,
+    text_stats: {
+      count: textCount,
+      bound_count: boundTextCount,
+      unbound_count: textCount - boundTextCount
+    },
+    bounding_box,
+    binary_files: binaryFiles
+  };
+}
+function isFileEntry(v) {
+  return typeof v === "object" && v !== null;
+}
+
+// src/scene/filters.ts
+function applyFilters(scene, opts) {
+  let elements = scene.elements;
+  const warnings = [];
+  if (!opts.includeDeleted) {
+    elements = elements.filter((e) => !e.isDeleted);
+  }
+  if (opts.frameId) {
+    const hasById = elements.some((e) => e.id === opts.frameId || e.frameId === opts.frameId);
+    if (hasById) {
+      elements = filterByFrame(elements, opts.frameId);
+    } else {
+      const frame = elements.find(
+        (e) => e.type === "frame" && e.name === opts.frameId
+      );
+      if (frame) {
+        elements = filterByFrame(elements, frame.id);
+      } else {
+        warnings.push({
+          code: "ERR_VALIDATION_FRAME_NOT_FOUND",
+          message: `Frame not found: "${opts.frameId}" does not match any frame ID or name`,
+          retryable: false,
+          suggested_action: "fix_input"
+        });
+      }
+    }
+  } else if (opts.frameName) {
+    const frame = elements.find(
+      (e) => e.type === "frame" && e.name === opts.frameName
+    );
+    if (frame) {
+      elements = filterByFrame(elements, frame.id);
+    } else {
+      warnings.push({
+        code: "ERR_VALIDATION_FRAME_NOT_FOUND",
+        message: `Frame not found: no frame with name "${opts.frameName}"`,
+        retryable: false,
+        suggested_action: "fix_input"
+      });
+    }
+  }
+  if (opts.elementIds && opts.elementIds.length > 0) {
+    const idSet = new Set(opts.elementIds);
+    const before = elements.length;
+    elements = elements.filter((e) => idSet.has(e.id));
+    const missing = [...idSet].filter((id) => !elements.some((e) => e.id === id));
+    if (missing.length > 0) {
+      warnings.push({
+        code: "ERR_VALIDATION_ELEMENT_NOT_FOUND",
+        message: `Element IDs not found: ${missing.join(", ")}`,
+        retryable: false,
+        suggested_action: "fix_input",
+        details: { missing_ids: missing }
+      });
+    }
+  }
+  return { scene: { ...scene, elements }, warnings };
+}
+function filterByFrame(elements, frameId) {
+  return elements.filter((e) => e.id === frameId || e.frameId === frameId);
+}
+
+// src/cli/commands/inspect.ts
+function registerInspect(program2) {
+  program2.command("inspect <file>").description("Inspect an Excalidraw scene and return metadata").option("--include-deleted", "Include deleted elements in inspection").option("--frame <id-or-name>", "Filter to a specific frame").action(
+    wrapCommand("scene.inspect", async (ctx, file, opts) => {
+      const options = opts;
+      const fileStr = file;
+      const loaded = await loadScene(fileStr);
+      const { scene: filtered, warnings: filterWarnings } = applyFilters(loaded.parsed, {
+        includeDeleted: options.includeDeleted,
+        frameId: options.frame
+      });
+      for (const w of filterWarnings) ctx.warn(w);
+      const inspection = inspectScene(filtered);
+      return {
+        target: { file: loaded.source, fingerprint: loaded.fingerprint },
+        result: inspection
+      };
+    })
+  );
+}
+
+// src/scene/validate-scene.ts
+function validateScene(scene, opts = {}) {
+  const checks = [];
+  const warnings = [];
+  const elementMap = new Map(scene.elements.map((e) => [e.id, e]));
+  const liveElements = scene.elements.filter((e) => !e.isDeleted);
+  {
+    const orphans = [];
+    for (const el of liveElements) {
+      if (el.frameId && !elementMap.has(el.frameId)) {
+        orphans.push(el.id);
+      }
+    }
+    checks.push({
+      name: "frame_references",
+      passed: orphans.length === 0,
+      message: orphans.length > 0 ? `${orphans.length} element(s) reference non-existent frames` : void 0
+    });
+    if (orphans.length > 0) {
+      warnings.push({
+        code: "ERR_VALIDATION_FRAME_ORPHAN",
+        message: `Elements reference non-existent frames: ${orphans.join(", ")}`,
+        retryable: false,
+        suggested_action: "fix_input",
+        details: { element_ids: orphans }
+      });
+    }
+  }
+  {
+    const broken = [];
+    for (const el of liveElements) {
+      if (el.type === "text" && el.containerId) {
+        const container = elementMap.get(el.containerId);
+        if (!container) {
+          broken.push(el.id);
+        } else if (container.boundElements) {
+          const hasRef = container.boundElements.some(
+            (b) => b.id === el.id && b.type === "text"
+          );
+          if (!hasRef) broken.push(el.id);
+        }
+      }
+    }
+    checks.push({
+      name: "bound_text",
+      passed: broken.length === 0,
+      message: broken.length > 0 ? `${broken.length} bound text element(s) have broken references` : void 0
+    });
+    if (broken.length > 0) {
+      warnings.push({
+        code: "ERR_VALIDATION_BOUND_TEXT",
+        message: `Bound text elements with broken references: ${broken.join(", ")}`,
+        retryable: false,
+        suggested_action: "fix_input",
+        details: { element_ids: broken }
+      });
+    }
+  }
+  {
+    const broken = [];
+    for (const el of liveElements) {
+      if (el.type === "arrow") {
+        if (el.startBinding && !elementMap.has(el.startBinding.elementId)) {
+          broken.push(`${el.id}:start`);
+        }
+        if (el.endBinding && !elementMap.has(el.endBinding.elementId)) {
+          broken.push(`${el.id}:end`);
+        }
+      }
+    }
+    checks.push({
+      name: "arrow_bindings",
+      passed: broken.length === 0,
+      message: broken.length > 0 ? `${broken.length} arrow binding(s) reference non-existent elements` : void 0
+    });
+    if (broken.length > 0) {
+      warnings.push({
+        code: "ERR_VALIDATION_ARROW_BINDING",
+        message: `Broken arrow bindings: ${broken.join(", ")}`,
+        retryable: false,
+        suggested_action: "fix_input",
+        details: { bindings: broken }
+      });
+    }
+  }
+  if (opts.checkAssets) {
+    const missing = [];
+    for (const el of liveElements) {
+      if (el.type === "image" && el.fileId) {
+        if (!scene.files || !(el.fileId in scene.files)) {
+          missing.push(el.id);
+        }
+      }
+    }
+    checks.push({
+      name: "image_assets",
+      passed: missing.length === 0,
+      message: missing.length > 0 ? `${missing.length} image(s) reference missing binary files` : void 0
+    });
+    if (missing.length > 0) {
+      warnings.push({
+        code: "ERR_VALIDATION_MISSING_ASSET",
+        message: `Images with missing file data: ${missing.join(", ")}`,
+        retryable: false,
+        suggested_action: "fix_input",
+        details: { element_ids: missing }
+      });
+    }
+  }
+  {
+    const knownTypes = /* @__PURE__ */ new Set([
+      "rectangle",
+      "diamond",
+      "ellipse",
+      "arrow",
+      "line",
+      "freedraw",
+      "text",
+      "image",
+      "frame",
+      "group",
+      "embeddable",
+      "iframe",
+      "magicframe"
+    ]);
+    const unknownTypes = /* @__PURE__ */ new Set();
+    for (const el of liveElements) {
+      if (!knownTypes.has(el.type)) unknownTypes.add(el.type);
+    }
+    if (unknownTypes.size > 0) {
+      warnings.push({
+        code: "ERR_VALIDATION_UNKNOWN_TYPE",
+        message: `Unknown element types: ${[...unknownTypes].join(", ")}`,
+        retryable: false,
+        suggested_action: "fix_input",
+        details: { types: [...unknownTypes] }
+      });
+    }
+  }
+  const valid = checks.every((c) => c.passed);
+  return { result: { valid, checks }, warnings };
+}
+
+// src/cli/commands/validate.ts
+function registerValidate(program2) {
+  program2.command("validate <file>").description("Validate an Excalidraw scene for structural consistency").option("--check-assets", "Verify image file references exist").action(
+    wrapCommand("scene.validate", async (ctx, file, opts) => {
+      const options = opts;
+      const fileStr = file;
+      const loaded = await loadScene(fileStr);
+      const { result, warnings } = validateScene(loaded.parsed, {
+        checkAssets: options.checkAssets
+      });
+      for (const w of warnings) ctx.warn(w);
+      return {
+        target: { file: loaded.source, fingerprint: loaded.fingerprint },
+        result
+      };
+    })
+  );
+}
+
+// src/cli/commands/render.ts
+import { basename, extname } from "path";
+
+// src/scene/normalize-scene.ts
+function deterministicSeed(id) {
+  let hash = 0;
+  for (let i = 0; i < id.length; i++) {
+    hash = (hash << 5) - hash + id.charCodeAt(i) | 0;
+  }
+  return Math.abs(hash);
+}
+function normalizeScene(scene) {
+  const elements = scene.elements.map(normalizeElement);
+  elements.sort((a, b) => {
+    if (a.type !== b.type) return a.type.localeCompare(b.type);
+    if (a.y !== b.y) return a.y - b.y;
+    if (a.x !== b.x) return a.x - b.x;
+    return a.id.localeCompare(b.id);
+  });
+  return { ...scene, elements };
+}
+function normalizeElement(el) {
+  const raw = el;
+  const result = {
+    ...el,
+    isDeleted: el.isDeleted ?? false,
+    opacity: el.opacity ?? 100,
+    groupIds: el.groupIds ?? [],
+    frameId: el.frameId ?? null,
+    boundElements: el.boundElements ?? null,
+    containerId: el.containerId ?? null,
+    startBinding: el.startBinding ?? null,
+    endBinding: el.endBinding ?? null,
+    fileId: el.fileId ?? null,
+    name: el.name ?? null,
+    // Properties required by @excalidraw/utils for rendering
+    angle: raw.angle ?? 0,
+    strokeColor: raw.strokeColor ?? "#1e1e1e",
+    backgroundColor: raw.backgroundColor ?? "transparent",
+    fillStyle: raw.fillStyle ?? "solid",
+    strokeWidth: raw.strokeWidth ?? 2,
+    strokeStyle: raw.strokeStyle ?? "solid",
+    roughness: raw.roughness ?? 1,
+    roundness: raw.roundness ?? null,
+    seed: raw.seed ?? deterministicSeed(el.id),
+    version: raw.version ?? 1,
+    versionNonce: raw.versionNonce ?? 1,
+    updated: raw.updated ?? Date.now(),
+    link: raw.link ?? null,
+    locked: raw.locked ?? false
+  };
+  if ((el.type === "arrow" || el.type === "line" || el.type === "freedraw") && !raw.points) {
+    result.points = [[0, 0], [el.width, el.height]];
+  }
+  if (el.type === "text") {
+    result.fontSize = raw.fontSize ?? 20;
+    result.fontFamily = raw.fontFamily ?? 1;
+    result.textAlign = raw.textAlign ?? "left";
+    result.verticalAlign = raw.verticalAlign ?? "top";
+    result.lineHeight = raw.lineHeight ?? 1.25;
+    result.originalText = raw.originalText ?? raw.text ?? "";
+    result.baseline = raw.baseline ?? 0;
+  }
+  return result;
+}
+
+// src/render/bridge-page.ts
+import { readFile as readFile2 } from "fs/promises";
+import { resolve, dirname as dirname2 } from "path";
+import { fileURLToPath } from "url";
+async function generateBridgeHtml() {
+  const thisDir = dirname2(fileURLToPath(import.meta.url));
+  const bridgePath = resolve(thisDir, "..", "render", "bridge.global.js");
+  let bridgeScript;
+  try {
+    bridgeScript = await readFile2(bridgePath, "utf-8");
+  } catch {
+    const fallbackPath = resolve(process.cwd(), "dist", "render", "bridge.global.js");
+    bridgeScript = await readFile2(fallbackPath, "utf-8");
+  }
+  return `<!DOCTYPE html>
+<html>
+<head><meta charset="utf-8"></head>
+<body>
+<script>${bridgeScript}</script>
+<script>
+  window.__bridgeReady = typeof window.__excalidrawExport !== 'undefined' && window.__excalidrawExport.ready;
+</script>
+</body>
+</html>`;
+}
+
+// src/render/render-bridge.ts
+var RenderBridge = class {
+  browser = null;
+  page = null;
+  bridgeHtml = null;
+  async initialize() {
+    let pw;
+    try {
+      pw = await import("playwright");
+    } catch {
+      throw renderError(
+        "BROWSER_UNAVAILABLE",
+        "Playwright is not installed. Install it with: npm install playwright"
+      );
+    }
+    this.browser = await pw.chromium.launch({ headless: true });
+    const context = await this.browser.newContext();
+    this.page = await context.newPage();
+    try {
+      await import("@excalidraw/excalidraw");
+      const { resolve: resolve2, dirname: dirname3 } = await import("path");
+      const { readFile: readFile3 } = await import("fs/promises");
+      const { createRequire } = await import("module");
+      const require2 = createRequire(import.meta.url);
+      const excalidrawDir = dirname3(require2.resolve("@excalidraw/excalidraw/package.json"));
+      await this.page.route("**/*.woff2", async (route) => {
+        try {
+          const url = new URL(route.request().url());
+          const fontName = url.pathname.split("/").pop();
+          if (fontName) {
+            const fontPath = resolve2(excalidrawDir, "dist", "excalidraw-assets", fontName);
+            const body = await readFile3(fontPath);
+            await route.fulfill({ body, contentType: "font/woff2" });
+            return;
+          }
+        } catch {
+        }
+        await route.abort();
+      });
+    } catch {
+    }
+    this.bridgeHtml = await generateBridgeHtml();
+    await this.page.setContent(this.bridgeHtml);
+    await this.page.waitForFunction("window.__bridgeReady === true", {
+      timeout: 1e4
+    });
+  }
+  async exportSvg(sceneData) {
+    if (!this.page) throw renderError("EXPORT_FAILED", "Bridge not initialized");
+    try {
+      const svgString = await this.page.evaluate(
+        async (data) => {
+          return window.__excalidrawExport.exportToSvg(data);
+        },
+        sceneData
+      );
+      return svgString;
+    } catch (err) {
+      throw renderError("EXPORT_FAILED", `SVG export failed: ${errorMessage(err)}`);
+    }
+  }
+  async exportPng(sceneData, scale = 2) {
+    if (!this.page) throw renderError("EXPORT_FAILED", "Bridge not initialized");
+    try {
+      const base64 = await this.page.evaluate(
+        async (data) => {
+          const appState = { ...data.scene.appState, exportScale: data.scale };
+          return window.__excalidrawExport.exportToBlob({
+            ...data.scene,
+            appState
+          });
+        },
+        { scene: sceneData, scale }
+      );
+      return Buffer.from(base64, "base64");
+    } catch (err) {
+      throw renderError("EXPORT_FAILED", `PNG export failed: ${errorMessage(err)}`);
+    }
+  }
+  async exportPdf(sceneData) {
+    if (!this.page) throw renderError("EXPORT_FAILED", "Bridge not initialized");
+    try {
+      const svgString = await this.exportSvg(sceneData);
+      await this.page.setContent(`<!DOCTYPE html>
+<html>
+<head>
+<meta charset="utf-8">
+<style>
+  body { margin: 0; display: flex; justify-content: center; align-items: center; }
+  svg { max-width: 100%; height: auto; }
+</style>
+</head>
+<body>${svgString}</body>
+</html>`);
+      const pdf = await this.page.pdf({
+        preferCSSPageSize: true,
+        printBackground: true
+      });
+      if (this.bridgeHtml) {
+        await this.page.setContent(this.bridgeHtml);
+        await this.page.waitForFunction("window.__bridgeReady === true", {
+          timeout: 1e4
+        });
+      }
+      return Buffer.from(pdf);
+    } catch (err) {
+      if (err instanceof Error && err.message.includes("ERR_RENDER")) throw err;
+      throw renderError("EXPORT_FAILED", `PDF export failed: ${errorMessage(err)}`);
+    }
+  }
+  async dispose() {
+    if (this.browser) {
+      await this.browser.close();
+      this.browser = null;
+      this.page = null;
+      this.bridgeHtml = null;
+    }
+  }
+};
+
+// src/render/export-common.ts
+import { join as join2 } from "path";
+async function exportFormat(opts) {
+  const sceneData = {
+    elements: opts.scene.elements,
+    appState: opts.scene.appState,
+    files: opts.scene.files,
+    exportPadding: opts.exportPadding
+  };
+  const { data, bytes } = await opts.render(opts.bridge, sceneData);
+  const path = join2(opts.outDir, `${opts.baseName}.${opts.ext}`).replace(/\\/g, "/");
+  if (!opts.dryRun) {
+    await writeOutput(path, data);
+  }
+  return { type: opts.ext, path, bytes };
+}
+
+// src/render/export-svg.ts
+async function exportSvg(opts) {
+  return exportFormat({
+    ...opts,
+    ext: "svg",
+    render: async (bridge, sceneData) => {
+      const svg = await bridge.exportSvg(sceneData);
+      return { data: svg, bytes: Buffer.byteLength(svg, "utf-8") };
+    }
+  });
+}
+
+// src/render/export-png.ts
+async function exportPng(opts) {
+  return exportFormat({
+    ...opts,
+    ext: "png",
+    render: async (bridge, sceneData) => {
+      const buf = await bridge.exportPng(sceneData, opts.scale);
+      return { data: buf, bytes: buf.length };
+    }
+  });
+}
+
+// src/render/export-pdf.ts
+async function exportPdf(opts) {
+  return exportFormat({
+    ...opts,
+    ext: "pdf",
+    render: async (bridge, sceneData) => {
+      const buf = await bridge.exportPdf(sceneData);
+      return { data: buf, bytes: buf.length };
+    }
+  });
+}
+
+// src/cli/commands/render.ts
+function registerRender(program2) {
+  program2.command("render <file>").description("Render an Excalidraw scene to SVG, PNG, or PDF").option("--outDir <dir>", "Output directory", ".").option("--svg", "Export SVG").option("--png", "Export PNG (requires Playwright)").option("--pdf", "Export PDF (requires Playwright)").option("--dark-mode", "Use dark theme").option("--no-background", "Transparent background").option("--scale <n>", "Scale factor for PNG output only", "2").option("--padding <n>", "Padding in pixels", "20").option("--frame <id-or-name>", "Export specific frame only").option("--element <id>", "Export specific element only").option("--dry-run", "Run pipeline but write no files").action(
+    wrapCommand("scene.render", async (ctx, file, opts) => {
+      const options = opts;
+      const fileStr = file;
+      const loaded = await loadScene(fileStr);
+      const normalized = normalizeScene(loaded.parsed);
+      const { scene: filtered, warnings: filterWarnings } = applyFilters(normalized, {
+        frameId: options.frame,
+        frameName: options.frame,
+        elementIds: options.element ? [options.element] : void 0
+      });
+      for (const w of filterWarnings) ctx.warn(w);
+      const inspection = inspectScene(filtered);
+      const formats = {
+        svg: options.svg || !options.png && !options.pdf,
+        png: options.png || false,
+        pdf: options.pdf || false
+      };
+      const scale = parseFloat(options.scale);
+      if (scale !== 2 && formats.svg && !formats.png && !formats.pdf) {
+        ctx.warn({
+          code: "ERR_VALIDATION_SCALE_IGNORED",
+          message: "--scale has no effect on SVG output; it only applies to PNG",
+          retryable: false,
+          suggested_action: "fix_input"
+        });
+      }
+      const appState = { ...filtered.appState };
+      if (options.darkMode) appState.exportWithDarkMode = true;
+      if (!options.background) appState.exportBackground = false;
+      const sceneForExport = { ...filtered, appState };
+      const baseName = loaded.source === "stdin" ? "scene" : basename(loaded.source, extname(loaded.source));
+      const shared = {
+        bridge: void 0,
+        scene: sceneForExport,
+        outDir: options.outDir,
+        baseName,
+        dryRun: options.dryRun,
+        exportPadding: parseInt(options.padding, 10)
+      };
+      const bridge = new RenderBridge();
+      shared.bridge = bridge;
+      try {
+        await bridge.initialize();
+        const artefacts = [];
+        if (formats.svg) {
+          artefacts.push(await exportSvg(shared));
+        }
+        if (formats.png) {
+          artefacts.push(
+            await exportPng({ ...shared, scale })
+          );
+        }
+        if (formats.pdf) {
+          artefacts.push(await exportPdf(shared));
+        }
+        return {
+          target: { file: loaded.source, fingerprint: loaded.fingerprint },
+          result: {
+            artefacts,
+            scene_summary: {
+              element_count: inspection.element_count,
+              bounding_box: inspection.bounding_box,
+              fingerprint: loaded.fingerprint
+            },
+            dry_run: options.dryRun || false
+          }
+        };
+      } finally {
+        await bridge.dispose();
+      }
+    })
+  );
+}
+
+// src/guide/guide-schema.ts
+function getGuideContent() {
+  return `# excal \u2014 CLI Guide
+
+Agent-first CLI for Excalidraw scene inspection, validation, and rendering.
+
+## Commands
+
+### excal inspect <file|->
+
+Inspect an Excalidraw scene and return element counts, bounds, and metadata.
+
+| Flag | Description |
+|------|-------------|
+| \`--include-deleted\` | Include deleted elements |
+| \`--frame <id\\|name>\` | Filter to a specific frame |
+
+\`\`\`bash
+excal inspect diagram.excalidraw
+cat scene.json | excal inspect -
+\`\`\`
+
+### excal validate <file|->
+
+Validate scene structure: frame refs, bound text, arrow bindings, assets.
+
+| Flag | Description |
+|------|-------------|
+| \`--check-assets\` | Verify image file references exist in scene |
+
+\`\`\`bash
+excal validate diagram.excalidraw
+excal validate diagram.excalidraw --check-assets
+\`\`\`
+
+### excal render <file|->
+
+Render scene to SVG, PNG, or PDF. PNG/PDF require Playwright.
+
+| Flag | Description |
+|------|-------------|
+| \`--outDir <dir>\` | Output directory (default: .) |
+| \`--svg\` | Export SVG (default if no format specified) |
+| \`--png\` | Export PNG (requires Playwright) |
+| \`--pdf\` | Export PDF (requires Playwright) |
+| \`--dark-mode\` | Use dark theme |
+| \`--no-background\` | Transparent background |
+| \`--scale <n>\` | Scale factor for PNG output only (default: 2) |
+| \`--padding <n>\` | Padding in pixels (default: 20) |
+| \`--frame <id\\|name>\` | Export specific frame only |
+| \`--element <id>\` | Export specific element only |
+| \`--dry-run\` | Run pipeline but write no files |
+
+\`\`\`bash
+excal render diagram.excalidraw --outDir ./out
+excal render diagram.excalidraw --outDir ./out --png --pdf
+excal render - --outDir ./out < scene.json
+\`\`\`
+
+### excal guide
+
+Output this CLI guide as Markdown.
+
+### excal skill
+
+Return Excalidraw domain knowledge for AI agents.
+
+## Error Codes
+
+| Code | Exit | Description |
+|------|------|-------------|
+| \`ERR_VALIDATION_INVALID_JSON\` | 10 | Input is not valid JSON |
+| \`ERR_VALIDATION_INVALID_SCENE\` | 10 | Scene structure validation failed |
+| \`ERR_VALIDATION_UNKNOWN_FORMAT\` | 10 | Input is not a recognized format |
+| \`ERR_RENDER_BROWSER_UNAVAILABLE\` | 20 | Playwright not installed |
+| \`ERR_RENDER_EXPORT_FAILED\` | 20 | Export failed in browser bridge |
+| \`ERR_IO_READ_FAILED\` | 50 | Failed to read input file |
+| \`ERR_IO_WRITE_FAILED\` | 50 | Failed to write output file |
+| \`ERR_INTERNAL_UNEXPECTED\` | 90 | Unexpected internal error |
+
+## Response Envelope
+
+Every command returns a JSON envelope on stdout:
+
+\`\`\`jsonc
+{
+  "schema_version": "1.0",
+  "request_id": "req_20260302_143000_7f3a",
+  "ok": true,              // always present
+  "command": "scene.inspect",
+  "target": { ... },       // what was acted on (null for global commands)
+  "result": { ... },       // command payload (null on failure)
+  "warnings": [],          // always an array
+  "errors": [],            // always an array
+  "metrics": { "duration_ms": 42 }
+}
+\`\`\`
+
+- \`errors\` and \`warnings\` are always arrays (possibly empty), never omitted.
+- \`result\` is always present; on failure it is \`null\`.
+- Each error carries \`code\`, \`message\`, \`retryable\`, and \`suggested_action\`.
+- **Note on \`validate\`**: \`ok: true\` means the command executed successfully, not that the scene is valid. Check \`result.valid\` (boolean) for scene validity, and \`result.issues\` / \`warnings\` for details.
+
+## Concurrency
+
+- **Reads** (inspect, validate): safe to run concurrently.
+- **Renders**: each invocation launches its own browser; safe to parallelize.
+`;
+}
+
+// src/cli/commands/guide.ts
+function registerGuide(program2) {
+  program2.command("guide").description("Return CLI guide as Markdown for agent bootstrapping").action(
+    wrapCommand("cli.guide", async () => {
+      return { result: { content: getGuideContent(), format: "markdown" } };
+    })
+  );
+}
+
+// src/guide/skill-content.ts
+function getSkillContent() {
+  return `# Excalidraw Scene Structure \u2014 Agent Guide
+
+## File Format
+
+Excalidraw scenes are JSON files (typically \`.excalidraw\`) with this structure:
+
+\`\`\`json
+{
+  "type": "excalidraw",
+  "version": 2,
+  "source": "https://excalidraw.com",
+  "elements": [ ... ],
+  "appState": { ... },
+  "files": { ... }
+}
+\`\`\`
+
+## Element Types
+
+| Type | Description |
+|------|-------------|
+| rectangle | Box shape |
+| diamond | Diamond/rhombus shape |
+| ellipse | Circle/ellipse shape |
+| arrow | Arrow connector |
+| line | Line/polyline |
+| freedraw | Freehand drawing |
+| text | Text label |
+| image | Embedded image |
+| frame | Grouping frame |
+
+## Key Element Properties
+
+Every element has: \`id\`, \`type\`, \`x\`, \`y\`, \`width\`, \`height\`, \`isDeleted\`, \`opacity\`, \`groupIds\`, \`frameId\`.
+
+## Frames
+
+Frames group elements visually. Elements inside a frame have \`frameId\` set to the frame's \`id\`. Frames themselves have \`type: "frame"\` and an optional \`name\`.
+
+To export a single frame: use \`--frame <id|name>\`.
+
+## Bound Text
+
+Text can be bound to a container (rectangle, diamond, ellipse). The text element has \`containerId\` pointing to the container, and the container has a \`boundElements\` entry with \`{ id, type: "text" }\`.
+
+## Arrows & Bindings
+
+Arrows connect elements via \`startBinding\` and \`endBinding\`:
+\`\`\`json
+{
+  "startBinding": { "elementId": "target-id", "focus": 0, "gap": 1 },
+  "endBinding": { "elementId": "target-id", "focus": 0, "gap": 1 }
+}
+\`\`\`
+
+## Images & Binary Files
+
+Image elements have \`fileId\` referencing an entry in \`files\`. The files object maps IDs to \`{ mimeType, dataURL }\` where dataURL is base64-encoded.
+
+## Export Tips
+
+- SVG export inlines fonts; no external dependencies
+- PNG/PDF require Playwright for headless browser rendering
+- Use \`--scale 2\` (default) for crisp PNG exports
+- Use \`--dark-mode\` for dark theme exports
+- Use \`--no-background\` for transparent backgrounds
+- \`--dry-run\` validates the full pipeline without writing files
+
+## Common Patterns
+
+1. **Inspect before modifying**: Always run \`excal inspect\` to understand scene structure
+2. **Validate after changes**: Run \`excal validate --check-assets\` to catch broken references
+3. **Frame-based export**: Use frames to organize sections, export individually with \`--frame\`
+4. **Deterministic output**: Same input + same options = same output (for CI/CD)
+`;
+}
+
+// src/cli/commands/skill.ts
+function registerSkill(program2) {
+  program2.command("skill").description("Return Excalidraw domain knowledge for AI agents").action(
+    wrapCommand("cli.skill", async () => {
+      return { result: { content: getSkillContent(), format: "markdown" } };
+    })
+  );
+}
+
+// src/cli/index.ts
+var program = new Command();
+program.name("excal").description("Agent-first CLI for Excalidraw scene inspection, validation, and rendering").version("1.0.0");
+program.action(() => {
+  const envelope = buildEnvelope({
+    request_id: generateRequestId(),
+    command: "",
+    result: null,
+    ok: false,
+    errors: [
+      {
+        code: "ERR_VALIDATION_NO_COMMAND",
+        message: "No command specified. Run `excal --help` for usage.",
+        retryable: false,
+        suggested_action: "fix_input"
+      }
+    ],
+    duration_ms: 0
+  });
+  process.exitCode = 10;
+  process.stdout.write(JSON.stringify(envelope, null, 2) + "\n");
+});
+program.exitOverride();
+program.configureOutput({
+  writeOut: () => {
+  },
+  writeErr: () => {
+  }
+});
+registerInspect(program);
+registerValidate(program);
+registerRender(program);
+registerGuide(program);
+registerSkill(program);
+try {
+  program.parse();
+} catch (err) {
+  if (err instanceof CommanderError) {
+    if (err.code === "commander.helpDisplayed") {
+      process.stdout.write(program.helpInformation());
+      process.exit(0);
+    }
+    if (err.code === "commander.version") {
+      process.stdout.write(program.version() + "\n");
+      process.exit(0);
+    }
+    const envelope = buildEnvelope({
+      request_id: generateRequestId(),
+      command: "",
+      result: null,
+      ok: false,
+      errors: [
+        {
+          code: "ERR_VALIDATION_INVALID_ARGS",
+          message: err.message,
+          retryable: false,
+          suggested_action: "fix_input"
+        }
+      ],
+      duration_ms: 0
+    });
+    process.exitCode = 10;
+    process.stdout.write(JSON.stringify(envelope, null, 2) + "\n");
+  } else {
+    throw err;
+  }
+}
+//# sourceMappingURL=index.js.map