@popcraft/kit 0.53.14 → 0.53.16

package/dist/chunks/chunk-2FFA6464.js

@@ -0,0 +1,941 @@
+import { createRequire as __popcraftRequire } from 'node:module';
+import { fileURLToPath as __popcraftPath } from 'node:url';
+import { dirname as __popcraftDirname } from 'node:path';
+const require = __popcraftRequire(import.meta.url);
+const __filename = __popcraftPath(import.meta.url);
+const __dirname = __popcraftDirname(__filename);
+import {
+  MIME,
+  hostEnv,
+  plain,
+  registerBuiltinCommands
+} from "./chunk-YPSNEHNF.js";
+import {
+  storeOpsSeam
+} from "./chunk-GUR467P4.js";
+import {
+  external_exports
+} from "./chunk-UDDWBCFE.js";
+import {
+  defineCommand
+} from "./chunk-T2U7UWFL.js";
+import {
+  withHistoryGroup
+} from "./chunk-DUH4J3CB.js";
+import {
+  dispatchShaped
+} from "./chunk-SZHIVENR.js";
+import {
+  PluginApiError,
+  listCommandsForSurface,
+  registerCommand
+} from "./chunk-YJFJEFYZ.js";
+import {
+  addNode,
+  init_scene_graph,
+  updateNode
+} from "./chunk-XK54ZTFX.js";
+import {
+  init_dist_node,
+  v4_default
+} from "./chunk-KFAO6UMP.js";
+import {
+  createDefaultSceneNodeProps,
+  init_types
+} from "./chunk-OLOY3JN6.js";
+import {
+  init_define_POPCRAFT_COMPONENT_IDS
+} from "./chunk-63KP74KB.js";
+
+// lib/commands/plugin.ts
+init_define_POPCRAFT_COMPONENT_IDS();
+
+// lib/commands/plugin-widget.ts
+init_define_POPCRAFT_COMPONENT_IDS();
+init_scene_graph();
+
+// lib/extensions/widget/factory.ts
+init_define_POPCRAFT_COMPONENT_IDS();
+init_dist_node();
+init_types();
+
+// lib/extensions/widget/layout.ts
+init_define_POPCRAFT_COMPONENT_IDS();
+var MAX_WIDGET_ELEMENTS = 400;
+var MAX_WIDGET_DEPTH = 16;
+var MAX_WIDGET_STATE_BYTES = 64 * 1024;
+var WidgetTreeError = class extends Error {
+};
+var num = (v, min, max, fallback) => {
+  if (typeof v !== "number" || !Number.isFinite(v)) return fallback;
+  return Math.max(min, Math.min(max, v));
+};
+var HEX = /^#([0-9a-f]{3}|[0-9a-f]{6}|[0-9a-f]{8})$/i;
+var color = (v) => typeof v === "string" && HEX.test(v) ? v : void 0;
+var str = (v, max) => typeof v === "string" ? v.slice(0, max) : void 0;
+var align = (v) => v === "start" || v === "center" || v === "end" ? v : void 0;
+var size = (v) => v === "hug" ? "hug" : num(v, 0, 4e3);
+function sanitizeWidgetTree(raw) {
+  let count = 0;
+  const visit = (el, depth) => {
+    if (depth > MAX_WIDGET_DEPTH) throw new WidgetTreeError(`Widget trees may be at most ${MAX_WIDGET_DEPTH} levels deep`);
+    if (++count > MAX_WIDGET_ELEMENTS) throw new WidgetTreeError(`Widget trees may have at most ${MAX_WIDGET_ELEMENTS} elements`);
+    if (!el || typeof el !== "object") throw new WidgetTreeError("Widget elements must be objects");
+    const e = el;
+    const base = { onClick: str(e.onClick, 200), tooltip: str(e.tooltip, 200) };
+    switch (e.type) {
+      case "AutoLayout": {
+        let padding2;
+        if (typeof e.padding === "number") padding2 = num(e.padding, 0, 1e3);
+        else if (e.padding && typeof e.padding === "object") {
+          const p = e.padding;
+          padding2 = { top: num(p.top, 0, 1e3), right: num(p.right, 0, 1e3), bottom: num(p.bottom, 0, 1e3), left: num(p.left, 0, 1e3), horizontal: num(p.horizontal, 0, 1e3), vertical: num(p.vertical, 0, 1e3) };
+        }
+        const children = Array.isArray(e.children) ? e.children.filter((c) => c !== null && c !== void 0 && c !== false).map((c) => visit(c, depth + 1)) : [];
+        return strip({
+          type: "AutoLayout",
+          ...base,
+          direction: e.direction === "vertical" ? "vertical" : "horizontal",
+          spacing: num(e.spacing, 0, 1e3),
+          padding: padding2,
+          width: size(e.width),
+          height: size(e.height),
+          horizontalAlign: align(e.horizontalAlign),
+          verticalAlign: align(e.verticalAlign),
+          fill: color(e.fill),
+          stroke: color(e.stroke),
+          strokeWidth: num(e.strokeWidth, 0, 100),
+          cornerRadius: num(e.cornerRadius, 0, 2e3),
+          children
+        });
+      }
+      case "Text":
+        return strip({
+          type: "Text",
+          ...base,
+          characters: String(e.characters ?? "").slice(0, 2e3),
+          fontSize: num(e.fontSize, 1, 400),
+          fontWeight: num(e.fontWeight, 100, 900),
+          fill: color(e.fill),
+          width: num(e.width, 0, 4e3)
+        });
+      case "Rectangle":
+      case "Ellipse":
+        return strip({
+          type: e.type,
+          ...base,
+          width: num(e.width, 0, 4e3, 0),
+          height: num(e.height, 0, 4e3, 0),
+          fill: color(e.fill),
+          stroke: color(e.stroke),
+          strokeWidth: num(e.strokeWidth, 0, 100),
+          cornerRadius: num(e.cornerRadius, 0, 2e3)
+        });
+      default:
+        throw new WidgetTreeError(`Unknown widget element type ${JSON.stringify(e.type)}`);
+    }
+  };
+  return visit(raw, 0);
+}
+function strip(o) {
+  for (const k of Object.keys(o)) if (o[k] === void 0) delete o[k];
+  return o;
+}
+function parseWidgetColor(hex) {
+  if (!hex || !HEX.test(hex)) return null;
+  let h = hex.slice(1);
+  if (h.length === 3) h = h.split("").map((c) => c + c).join("");
+  const n = (i) => parseInt(h.slice(i, i + 2), 16) / 255;
+  return { r: n(0), g: n(2), b: n(4), a: h.length === 8 ? n(6) : 1 };
+}
+var DEFAULT_FONT_SIZE = 16;
+var TEXT_COLOR = { r: 0.12, g: 0.12, b: 0.14, a: 1 };
+function measureWidgetText(text, fontSize, fontWeight = 400) {
+  const lines = text.split("\n");
+  let widest = 0;
+  for (const line of lines) {
+    let w = 0;
+    for (const ch of line) {
+      const cp = ch.codePointAt(0);
+      if (cp > 8192) w += 1.15;
+      else if (/[ilIj.,:;'|!]/.test(ch)) w += 0.3;
+      else if (/[mwMW@]/.test(ch)) w += 0.85;
+      else if (ch === " ") w += 0.28;
+      else if (/[A-Z0-9]/.test(ch)) w += 0.64;
+      else w += 0.54;
+    }
+    widest = Math.max(widest, w);
+  }
+  const weight = fontWeight >= 600 ? 1.05 : 1;
+  return { w: Math.ceil(widest * fontSize * weight + fontSize * 0.2), h: Math.ceil(lines.length * fontSize * 1.25) };
+}
+var layoutCache = /* @__PURE__ */ new WeakMap();
+function layoutWidget(tree) {
+  const hit = layoutCache.get(tree);
+  if (hit) return hit;
+  const boxes = [];
+  const measure = (el) => {
+    if (el.type === "Text") {
+      const m = measureWidgetText(el.characters, el.fontSize ?? DEFAULT_FONT_SIZE, el.fontWeight);
+      return { w: el.width ?? m.w, h: m.h };
+    }
+    if (el.type !== "AutoLayout") return { w: el.width, h: el.height };
+    const pad = padding(el);
+    const kids = (el.children ?? []).map(measure);
+    const horizontal = el.direction !== "vertical";
+    const gap = (el.spacing ?? 0) * Math.max(0, kids.length - 1);
+    const main = kids.reduce((s, k) => s + (horizontal ? k.w : k.h), 0) + gap;
+    const cross = kids.reduce((m, k) => Math.max(m, horizontal ? k.h : k.w), 0);
+    const hugW = (horizontal ? main : cross) + pad.left + pad.right;
+    const hugH = (horizontal ? cross : main) + pad.top + pad.bottom;
+    return { w: typeof el.width === "number" ? el.width : hugW, h: typeof el.height === "number" ? el.height : hugH };
+  };
+  const place = (el, x, y, w, h) => {
+    const common = { x, y, w, h, onClick: el.onClick, tooltip: el.tooltip };
+    if (el.type === "Text") {
+      boxes.push({ ...common, kind: "text", fill: parseWidgetColor(el.fill) ?? TEXT_COLOR, stroke: null, strokeWidth: 0, cornerRadius: 0, text: el.characters, fontSize: el.fontSize ?? DEFAULT_FONT_SIZE, fontWeight: el.fontWeight ?? 400 });
+      return;
+    }
+    const fill = parseWidgetColor(el.fill);
+    const stroke = parseWidgetColor(el.stroke);
+    if (fill || stroke || el.onClick) {
+      boxes.push({ ...common, kind: el.type === "Ellipse" ? "ellipse" : "rect", fill, stroke, strokeWidth: stroke ? el.strokeWidth ?? 1 : 0, cornerRadius: el.cornerRadius ?? 0 });
+    }
+    if (el.type !== "AutoLayout") return;
+    const pad = padding(el);
+    const horizontal = el.direction !== "vertical";
+    const kids = (el.children ?? []).map((c) => ({ el: c, size: measure(c) }));
+    const innerW = w - pad.left - pad.right;
+    const innerH = h - pad.top - pad.bottom;
+    const gap = el.spacing ?? 0;
+    const main = kids.reduce((s, k) => s + (horizontal ? k.size.w : k.size.h), 0) + gap * Math.max(0, kids.length - 1);
+    const mainAlign = horizontal ? el.horizontalAlign : el.verticalAlign;
+    const crossAlign = horizontal ? el.verticalAlign : el.horizontalAlign;
+    const free = (horizontal ? innerW : innerH) - main;
+    let cursor = mainAlign === "center" ? free / 2 : mainAlign === "end" ? free : 0;
+    for (const k of kids) {
+      const crossFree = (horizontal ? innerH : innerW) - (horizontal ? k.size.h : k.size.w);
+      const crossOff = crossAlign === "center" ? crossFree / 2 : crossAlign === "end" ? crossFree : 0;
+      const cx = x + pad.left + (horizontal ? cursor : crossOff);
+      const cy = y + pad.top + (horizontal ? crossOff : cursor);
+      place(k.el, cx, cy, k.size.w, k.size.h);
+      cursor += (horizontal ? k.size.w : k.size.h) + gap;
+    }
+  };
+  const root = measure(tree);
+  place(tree, 0, 0, root.w, root.h);
+  const out = { width: Math.max(1, root.w), height: Math.max(1, root.h), boxes };
+  layoutCache.set(tree, out);
+  return out;
+}
+function padding(el) {
+  const p = el.padding;
+  if (typeof p === "number") return { top: p, right: p, bottom: p, left: p };
+  return {
+    top: p?.top ?? p?.vertical ?? 0,
+    bottom: p?.bottom ?? p?.vertical ?? 0,
+    left: p?.left ?? p?.horizontal ?? 0,
+    right: p?.right ?? p?.horizontal ?? 0
+  };
+}
+
+// lib/extensions/widget/factory.ts
+function createWidget(props = {}) {
+  const tree = props.widgetTree ?? null;
+  const size2 = tree ? layoutWidget(tree) : { width: 120, height: 52 };
+  return {
+    id: v4_default(),
+    name: props.pluginName ?? "Widget",
+    type: "WIDGET",
+    x: 0,
+    y: 0,
+    rotation: 0,
+    opacity: 1,
+    visible: true,
+    locked: false,
+    parentId: null,
+    childIds: [],
+    ...createDefaultSceneNodeProps(),
+    fills: [],
+    strokes: [],
+    ...props,
+    width: props.width ?? size2.width,
+    height: props.height ?? size2.height,
+    pluginId: props.pluginId ?? "",
+    pluginName: props.pluginName ?? "Widget",
+    widgetTree: tree,
+    widgetState: props.widgetState ?? {}
+  };
+}
+
+// lib/commands/plugin-widget.ts
+var widgetTree = external_exports.unknown().transform((raw, ctx) => {
+  try {
+    return sanitizeWidgetTree(raw);
+  } catch (e) {
+    ctx.addIssue({ code: "custom", message: e instanceof WidgetTreeError ? e.message : "Invalid widget tree" });
+    return external_exports.NEVER;
+  }
+});
+var widgetState = external_exports.unknown().transform((raw, ctx) => {
+  if (raw === void 0 || raw === null) return {};
+  if (typeof raw !== "object" || Array.isArray(raw)) {
+    ctx.addIssue({ code: "custom", message: "Widget state must be an object" });
+    return external_exports.NEVER;
+  }
+  const json = JSON.stringify(raw);
+  if (json.length > MAX_WIDGET_STATE_BYTES) {
+    ctx.addIssue({ code: "custom", message: "Widget state is limited to 64 KB" });
+    return external_exports.NEVER;
+  }
+  return JSON.parse(json);
+});
+function ownWidget(ctx, id) {
+  const node = ctx.doc().nodes[id];
+  if (!node) throw new PluginApiError(`No node with id ${id}`, "not_found");
+  if (node.type !== "WIDGET" || node.pluginId !== ctx.actor.id) {
+    throw new PluginApiError(`${id} is not one of this plugin's widgets`, "denied");
+  }
+  return node;
+}
+function cameraCentre(ctx) {
+  const env = ctx.actor.host;
+  const camera = env?.getState?.().camera;
+  return { x: camera?.x ?? 0, y: camera?.y ?? 0 };
+}
+function widgetCommands(id) {
+  return [
+    defineCommand({
+      id: id("widgetInsert"),
+      title: "Insert widget",
+      domain: "widget",
+      params: external_exports.object({
+        tree: widgetTree,
+        state: widgetState.optional(),
+        x: external_exports.number().optional(),
+        y: external_exports.number().optional()
+      }),
+      effect: "document",
+      permission: null,
+      undoLabel: "Insert widget",
+      expose: {
+        plugin: {
+          method: "widgetInsert",
+          // FROZEN: a bare node id string.
+          shape: (r) => r.data.id
+        }
+      },
+      run: (p, ctx) => {
+        const node = createWidget({
+          pluginId: ctx.actor.id ?? "",
+          pluginName: ctx.actor.label ?? "Widget",
+          widgetTree: p.tree,
+          widgetState: p.state ?? {}
+        });
+        const centre = cameraCentre(ctx);
+        node.x = Math.round((p.x ?? centre.x) - node.width / 2);
+        node.y = Math.round((p.y ?? centre.y) - node.height / 2);
+        ctx.commit(addNode(ctx.doc(), node, ctx.pageId()), `Insert ${ctx.actor.label ?? "widget"}`);
+        ctx.setSelection([node.id]);
+        return { summary: `Inserted ${ctx.actor.label ?? "widget"}`, data: { id: node.id } };
+      }
+    }),
+    defineCommand({
+      id: id("widgetUpdate"),
+      title: "Update widget",
+      domain: "widget",
+      params: external_exports.object({ id: external_exports.string(), tree: widgetTree, state: widgetState.optional() }),
+      effect: "document",
+      permission: null,
+      undoLabel: "Update widget",
+      expose: { plugin: { method: "widgetUpdate" } },
+      run: (p, ctx) => {
+        const node = ownWidget(ctx, p.id);
+        const tree = p.tree;
+        const next = p.state ?? {};
+        if (JSON.stringify(tree) === JSON.stringify(node.widgetTree) && JSON.stringify(next) === JSON.stringify(node.widgetState)) {
+          return { summary: "Widget unchanged" };
+        }
+        const before = layoutWidget(node.widgetTree ?? tree);
+        const after = layoutWidget(tree);
+        const sx = node.widgetTree ? node.width / before.width : 1;
+        const sy = node.widgetTree ? node.height / before.height : 1;
+        const patch = { widgetTree: tree, widgetState: next, width: after.width * sx, height: after.height * sy };
+        ctx.commit(updateNode(ctx.doc(), node.id, patch), ctx.actor.label ?? "Update widget");
+        return { summary: "Widget updated" };
+      }
+    }),
+    defineCommand({
+      id: id("widgetGet"),
+      title: "Read widget state",
+      domain: "widget",
+      params: external_exports.object({ id: external_exports.string() }),
+      effect: "none",
+      permission: null,
+      expose: { plugin: { method: "widgetGet" } },
+      run: (p, ctx) => ({ summary: "Widget state", data: JSON.parse(JSON.stringify(ownWidget(ctx, p.id).widgetState ?? {})) })
+    })
+  ];
+}
+
+// lib/commands/plugin.ts
+var PLUGIN_CAPABILITIES = ["render", "storage", "panel"];
+var pluginCommandId = (method) => `plugin.${method}`;
+var empty = external_exports.object({});
+function isOpenableUrl(v) {
+  try {
+    const u = new URL(v);
+    if (u.protocol === "https:") return true;
+    return u.protocol === "http:" && (u.hostname === "localhost" || u.hostname === "127.0.0.1");
+  } catch {
+    return false;
+  }
+}
+var MAX_UPLOAD_BYTES = 500 * 1024 * 1024;
+var MAX_UPLOAD_REPLY_CHARS = 1024 * 1024;
+function pluginOf(ctx) {
+  if (ctx.actor.kind !== "plugin" || !ctx.actor.id) throw new PluginApiError("Only a plugin keeps file data");
+  return ctx.actor.id;
+}
+var commands = [
+  defineCommand({
+    id: pluginCommandId("getVariables"),
+    title: "Get variables",
+    domain: "variable",
+    params: empty,
+    effect: "none",
+    permission: "read",
+    expose: { plugin: { method: "getVariables" } },
+    run: (_p, ctx) => {
+      const doc = ctx.doc();
+      return {
+        summary: "Variables",
+        data: plain({
+          collections: Object.values(doc.variableCollections ?? {}),
+          variables: Object.values(doc.variables ?? {})
+        })
+      };
+    }
+  }),
+  defineCommand({
+    id: pluginCommandId("exportNode"),
+    title: "Export node",
+    domain: "export",
+    params: external_exports.object({
+      /**
+       * One node, or several as ONE PDF.
+       *
+       * A plugin that wanted the whole book had to export a page at a time and stitch them back
+       * together — which puts a second imposition implementation in whatever received them. The
+       * array goes through the exporter Print uses, so what comes back is the file the printer
+       * would get. Same method name, so the shipped SDK passes it through unchanged.
+       */
+      id: external_exports.union([external_exports.string(), external_exports.array(external_exports.string()).min(1)]),
+      options: external_exports.object({
+        format: external_exports.unknown().transform((v) => String(v ?? "PNG").toUpperCase()).refine((f) => f in MIME, { error: (iss) => `Unsupported format ${String(iss.input)}` }).optional(),
+        // Clamped, not rejected: the legacy switch clamped, and a plugin asking for scale 20 should get
+        // an 8× image rather than an exception it never handled.
+        scale: external_exports.unknown().transform((v) => Math.max(0.1, Math.min(8, Number(v) || 1))).optional(),
+        // PDF only. true: 0.125 in of bleed outside the trim, what a commercial printer needs. false: the
+        // page is the trim. Left out, it follows the person's Print setting.
+        bleed: external_exports.boolean().optional()
+      }).optional()
+    }),
+    effect: "none",
+    permission: "export",
+    expose: { plugin: { method: "exportNode" } },
+    // NOT merged with `export.nodes` / `export.svg`, and not on the `rasterise` capability either: the
+    // frozen return here is raw bytes (or SVG text) from the HOST's own exporter, which is a different
+    // implementation from the canvas renderer the export domain drives. See lib/commands/export.ts.
+    run: async (p, ctx) => {
+      const env = hostEnv(ctx);
+      const doc = ctx.doc();
+      const format = p.options?.format ?? "PNG";
+      const ids = Array.isArray(p.id) ? p.id : [p.id];
+      const nodes = ids.map((id) => {
+        const node = doc.nodes[id];
+        if (!node || node.type === "PAGE") throw new PluginApiError(`No node with id ${id}`, "not_found");
+        return node;
+      });
+      if (nodes.length > 1 && format !== "PDF") {
+        throw new PluginApiError("Several nodes can only be exported as one PDF", "invalid_params");
+      }
+      const data = await env.effects.exportNode(nodes, format, p.options?.scale ?? 1, p.options?.bleed);
+      return { summary: nodes.length > 1 ? `Exported ${nodes.length} pages` : `Exported ${nodes[0].name ?? nodes[0].id}`, data };
+    }
+  }),
+  defineCommand({
+    id: pluginCommandId("openExternal"),
+    title: "Open a link",
+    domain: "ui",
+    params: external_exports.object({
+      url: external_exports.string().refine(isOpenableUrl, { error: "url must be https, or http on localhost" })
+    }),
+    effect: "none",
+    permission: "network",
+    expose: { plugin: { method: "openExternal" } },
+    run: (p, ctx) => {
+      hostEnv(ctx).effects.openExternal(p.url);
+      return { summary: "Opened link" };
+    }
+  }),
+  defineCommand({
+    id: pluginCommandId("upload"),
+    title: "Upload a file",
+    domain: "ui",
+    // The sandbox's own fetch is fine for small requests; a book-sized export goes through here so it can be
+    // PUT straight onto a presigned storage URL rather than through a server that caps its request body.
+    params: external_exports.object({
+      url: external_exports.string().refine(isOpenableUrl, { error: "url must be https, or http on localhost" }),
+      body: external_exports.union([external_exports.instanceof(Uint8Array), external_exports.string()]),
+      method: external_exports.enum(["PUT", "POST"]).optional(),
+      contentType: external_exports.string().max(200).optional(),
+      headers: external_exports.record(external_exports.string(), external_exports.string()).optional()
+    }),
+    effect: "none",
+    permission: "network",
+    expose: { plugin: { method: "upload", shape: (r) => r.data } },
+    run: async (p) => {
+      const size2 = typeof p.body === "string" ? p.body.length : p.body.byteLength;
+      if (size2 > MAX_UPLOAD_BYTES) throw new PluginApiError(`upload is limited to ${MAX_UPLOAD_BYTES / 1024 / 1024} MB`, "invalid_params");
+      if (typeof location !== "undefined" && new URL(p.url).origin === location.origin) {
+        throw new PluginApiError("upload cannot send to PopCraft itself", "invalid_params");
+      }
+      const headers = new Headers(p.headers ?? {});
+      if (p.contentType) headers.set("content-type", p.contentType);
+      let res;
+      try {
+        res = await fetch(p.url, { method: p.method ?? "PUT", body: p.body, headers, credentials: "omit", mode: "cors" });
+      } catch (err) {
+        throw new PluginApiError(`Could not reach ${new URL(p.url).origin}: ${err instanceof Error ? err.message : String(err)}`, "unsupported");
+      }
+      const text = await res.text();
+      const data = {
+        ok: res.ok,
+        status: res.status,
+        headers: Object.fromEntries(res.headers.entries()),
+        body: text.length > MAX_UPLOAD_REPLY_CHARS ? text.slice(0, MAX_UPLOAD_REPLY_CHARS) : text
+      };
+      return { summary: `Uploaded ${size2} bytes (${res.status})`, data };
+    }
+  }),
+  defineCommand({
+    id: pluginCommandId("showUI"),
+    title: "Show plugin UI",
+    domain: "ui",
+    params: external_exports.object({
+      width: external_exports.number().optional(),
+      height: external_exports.number().optional(),
+      title: external_exports.string().optional(),
+      visible: external_exports.boolean().optional()
+    }),
+    effect: "none",
+    permission: null,
+    needs: ["panel"],
+    expose: { plugin: { method: "showUI" } },
+    run: (p, ctx) => {
+      if (!hostEnv(ctx).manifest.ui) throw new PluginApiError('This plugin has no "ui" file in its manifest');
+      ctx.use("panel").showUI(p);
+      return { summary: "UI shown" };
+    }
+  }),
+  defineCommand({
+    id: pluginCommandId("hideUI"),
+    title: "Hide plugin UI",
+    domain: "ui",
+    params: empty,
+    effect: "none",
+    permission: null,
+    needs: ["panel"],
+    expose: { plugin: { method: "hideUI" } },
+    run: (_p, ctx) => {
+      ctx.use("panel").hideUI();
+      return { summary: "UI hidden" };
+    }
+  }),
+  defineCommand({
+    id: pluginCommandId("closePlugin"),
+    title: "Close plugin",
+    domain: "ui",
+    params: external_exports.object({ message: external_exports.string().optional() }),
+    effect: "none",
+    permission: null,
+    needs: ["panel"],
+    expose: { plugin: { method: "closePlugin" } },
+    run: (p, ctx) => {
+      ctx.use("panel").close(p.message);
+      return { summary: "Closed" };
+    }
+  }),
+  defineCommand({
+    id: pluginCommandId("getImportMode"),
+    title: "Get import mode",
+    domain: "ui",
+    params: empty,
+    effect: "none",
+    permission: null,
+    expose: { plugin: { method: "getImportMode", shape: (r) => r.data } },
+    run: (_p, ctx) => ({ summary: "Import mode", data: hostEnv(ctx).importMode ?? null })
+  }),
+  defineCommand({
+    id: pluginCommandId("getImportFile"),
+    title: "Get import file",
+    domain: "ui",
+    params: empty,
+    effect: "none",
+    permission: null,
+    expose: { plugin: { method: "getImportFile", shape: (r) => r.data } },
+    run: (_p, ctx) => ({ summary: "Import file", data: hostEnv(ctx).importFile ?? null })
+  }),
+  defineCommand({
+    id: pluginCommandId("getStorefront"),
+    title: "Get storefront design",
+    domain: "export",
+    params: empty,
+    effect: "none",
+    permission: "read",
+    expose: { plugin: { method: "getStorefront", shape: (r) => r.data } },
+    // A storefront design in a neutral form (lib/io/web/project/storefront.ts `storefrontDesign`): what an exporter
+    // plugin turns into its own store's templates, as PopCraft turns it into a Next.js Commerce store (the Ecommerce plugin makes a Shopify theme of it).
+    run: async (_p, ctx) => {
+      const [{ componentScreens }, { storefrontDesign }] = await Promise.all([import("./components-WHVIHV3K.js"), import("./storefront-N34CMI4B.js")]);
+      const doc = ctx.doc();
+      const design = storefrontDesign(doc, componentScreens(doc, ctx.pageId()));
+      return { summary: `Storefront: ${design.pages.length} pages`, data: design };
+    }
+  }),
+  defineCommand({
+    id: pluginCommandId("getStorefrontFiles"),
+    title: "Build a storefront target",
+    domain: "export",
+    params: external_exports.object({ target: external_exports.enum(["shopify-theme", "next-commerce", "next-commerce-store"]) }),
+    effect: "none",
+    permission: "export",
+    expose: { plugin: { method: "getStorefrontFiles", shape: (r) => r.data } },
+    // A store's project, built from the open page as Export storefront builds it, zipped: what an exporter plugin
+    // saves (the Ecommerce plugin's Shopify theme), so a target is written once, here, and never again in a plugin.
+    run: async (p, ctx) => {
+      const [{ storefrontInputs }, { STOREFRONT_TARGETS }, { bytesOf }, { zipFiles }, { EXPORT_NODE_CAP }] = await Promise.all([
+        import("./storefront-prepare-6WYLPH6E.js"),
+        import("./storefront-N34CMI4B.js"),
+        import("./project-JGVNQ5OU.js"),
+        import("./zip-export-ITATIAQ3.js"),
+        import("./tree-SQJHUZW2.js")
+      ]);
+      const doc = ctx.doc();
+      const { screens, media } = await storefrontInputs(doc, ctx.pageId(), EXPORT_NODE_CAP);
+      if (!screens.length) throw new PluginApiError("This page has no screens: a top-level frame is a page of the store.");
+      const files = STOREFRONT_TARGETS[p.target].files(doc, screens, { media });
+      const zip = zipFiles(files.map((f) => ({ name: f.path, bytes: bytesOf(f) })));
+      return { summary: `${STOREFRONT_TARGETS[p.target].label}: ${files.length} files`, data: { name: `${doc.name || "store"}-${p.target}.zip`, files: files.length, bytes: new Uint8Array(await zip.arrayBuffer()) } };
+    }
+  }),
+  defineCommand({
+    id: pluginCommandId("getExportRequest"),
+    title: "Get export request",
+    domain: "ui",
+    params: empty,
+    effect: "none",
+    permission: null,
+    expose: { plugin: { method: "getExportRequest", shape: (r) => r.data } },
+    run: (_p, ctx) => ({ summary: "Export request", data: hostEnv(ctx).exportRequest ?? null })
+  }),
+  defineCommand({
+    id: pluginCommandId("saveExport"),
+    title: "Save exported file",
+    domain: "export",
+    // The file an exporter wrote. Bytes arrive as a Uint8Array (structured clone), a number list, or a
+    // base64 data: URL — the same three shapes `createImage` takes for its input.
+    params: external_exports.object({
+      name: external_exports.string().max(200).optional(),
+      mimeType: external_exports.string().max(100).optional(),
+      bytes: external_exports.union([external_exports.instanceof(Uint8Array), external_exports.array(external_exports.number().int().min(0).max(255))]).optional(),
+      dataUrl: external_exports.string().startsWith("data:").optional()
+    }),
+    effect: "none",
+    permission: "export",
+    expose: { plugin: { method: "saveExport", shape: (r) => r.data } },
+    run: (p, ctx) => {
+      const save = hostEnv(ctx).effects.saveExport;
+      if (!save) throw new PluginApiError("saveExport is not available in this host", "unsupported");
+      let bytes = null;
+      if (p.bytes) bytes = p.bytes instanceof Uint8Array ? p.bytes : Uint8Array.from(p.bytes);
+      else if (p.dataUrl) {
+        const bin = atob(p.dataUrl.slice(p.dataUrl.indexOf(",") + 1));
+        bytes = new Uint8Array(bin.length);
+        for (let i = 0; i < bin.length; i++) bytes[i] = bin.charCodeAt(i);
+      }
+      if (!bytes || !bytes.byteLength) throw new PluginApiError("saveExport needs bytes or dataUrl", "invalid_params");
+      let data;
+      try {
+        data = save({ name: p.name, bytes, mimeType: p.mimeType });
+      } catch (err) {
+        throw new PluginApiError(err instanceof Error ? err.message : String(err), "unsupported");
+      }
+      return { summary: `Saved ${data.name}`, data };
+    }
+  }),
+  defineCommand({
+    id: pluginCommandId("createDocument"),
+    title: "Create document",
+    domain: "file",
+    params: external_exports.object({ name: external_exports.string().optional() }),
+    effect: "document",
+    permission: "write",
+    expose: { plugin: { method: "createDocument", shape: (r) => r.data } },
+    run: async (p, ctx) => {
+      const create = hostEnv(ctx).effects.createDocument;
+      if (!create) throw new PluginApiError("createDocument is not available in this host", "unsupported");
+      const data = await create({ name: p.name });
+      return { summary: `Created \u201C${data.name}\u201D`, data };
+    }
+  }),
+  defineCommand({
+    id: pluginCommandId("createImage"),
+    title: "Create image",
+    domain: "node",
+    params: external_exports.object({
+      dataUrl: external_exports.string().optional(),
+      bytes: external_exports.array(external_exports.number()).optional(),
+      mimeType: external_exports.string().optional(),
+      name: external_exports.string().optional(),
+      x: external_exports.number().optional(),
+      y: external_exports.number().optional(),
+      width: external_exports.number().optional(),
+      height: external_exports.number().optional(),
+      parentId: external_exports.string().optional()
+    }),
+    effect: "document",
+    permission: "write",
+    undoLabel: (p) => `Create ${p.name ?? "image"}`,
+    expose: { plugin: { method: "createImage", shape: (r) => r.data.id } },
+    run: async (p, ctx) => {
+      const { internDataUrl, internBytes } = await import("./media-store-MRUY25FE.js");
+      const { createImage, addNode: addNode2 } = await import("../lib/document/scene-graph.js");
+      const { applyInvariants } = await import("./invariants-CHE4TKXX.js");
+      let imageUrl;
+      if (typeof p.dataUrl === "string" && p.dataUrl.startsWith("data:")) imageUrl = internDataUrl(p.dataUrl);
+      else if (Array.isArray(p.bytes) && p.bytes.length) {
+        imageUrl = internBytes(Uint8Array.from(p.bytes), p.mimeType || "image/png");
+      } else {
+        throw new PluginApiError("createImage needs dataUrl or bytes", "invalid_params");
+      }
+      const parentId = p.parentId ?? ctx.pageId();
+      const node = createImage(imageUrl, {
+        name: p.name ?? "Image",
+        x: p.x ?? 0,
+        y: p.y ?? 0,
+        width: p.width ?? 200,
+        height: p.height ?? 200
+      });
+      ctx.commit(applyInvariants(addNode2(ctx.doc(), node, parentId), [node.id, parentId]), `Create ${node.name}`);
+      ctx.setSelection([node.id]);
+      return { summary: `Created image \u201C${node.name}\u201D`, data: { id: node.id } };
+    }
+  }),
+  defineCommand({
+    id: pluginCommandId("storageGet"),
+    title: "Read plugin storage",
+    domain: "storage",
+    params: external_exports.object({ key: external_exports.unknown().transform((v) => String(v)) }),
+    effect: "none",
+    permission: null,
+    needs: ["storage"],
+    // No `?? null` fallback: a missing key has always resolved to `undefined` for plugins.
+    expose: { plugin: { method: "storageGet", shape: (r) => r.data } },
+    run: async (p, ctx) => ({ summary: `Read ${p.key}`, data: await ctx.use("storage").get(p.key) })
+  }),
+  defineCommand({
+    id: pluginCommandId("storageSet"),
+    title: "Write plugin storage",
+    domain: "storage",
+    params: external_exports.object({ key: external_exports.unknown().transform((v) => String(v)), value: external_exports.unknown() }),
+    effect: "none",
+    permission: null,
+    needs: ["storage"],
+    expose: { plugin: { method: "storageSet" } },
+    run: async (p, ctx) => {
+      await ctx.use("storage").set(p.key, plain(p.value));
+      return { summary: `Wrote ${p.key}` };
+    }
+  }),
+  // What the plugin keeps with the open file (Document.pluginData), under its own id: its settings for this design.
+  defineCommand({
+    id: pluginCommandId("getFileData"),
+    title: "Read plugin file data",
+    domain: "storage",
+    params: external_exports.object({ key: external_exports.unknown().transform((v) => String(v)) }),
+    effect: "none",
+    permission: "read",
+    expose: { plugin: { method: "getFileData", shape: (r) => r.data } },
+    run: (p, ctx) => ({ summary: `Read ${p.key}`, data: ctx.doc().pluginData?.[pluginOf(ctx)]?.[p.key] })
+  }),
+  defineCommand({
+    id: pluginCommandId("setFileData"),
+    title: "Write plugin file data",
+    domain: "storage",
+    params: external_exports.object({ key: external_exports.unknown().transform((v) => String(v)), value: external_exports.unknown() }),
+    effect: "document",
+    permission: "write",
+    expose: { plugin: { method: "setFileData" } },
+    run: (p, ctx) => {
+      const doc = ctx.doc();
+      const id = pluginOf(ctx);
+      const mine = { ...doc.pluginData?.[id] ?? {} };
+      if (p.value === void 0 || p.value === null) delete mine[p.key];
+      else mine[p.key] = plain(p.value);
+      const { [id]: _, ...others } = doc.pluginData ?? {};
+      ctx.commit({ ...doc, pluginData: Object.keys(mine).length ? { ...others, [id]: mine } : others });
+      return { summary: `Wrote ${p.key}` };
+    }
+  }),
+  ...widgetCommands(pluginCommandId)
+];
+var pluginRun = defineCommand({
+  id: "plugin.run",
+  title: "Run a plugin",
+  domain: "plugin",
+  // Whatever the plugin does, it does through the plugin API, which commits its own steps. The honest
+  // answer is still "this changes the document", and a read-only session must not reach it.
+  effect: "document",
+  permission: null,
+  params: external_exports.object({
+    pluginId: external_exports.string().describe("The installed plugin\u2019s id."),
+    commandId: external_exports.string().describe("Which of the plugin\u2019s commands to run. Omit for its first one.").optional()
+  }),
+  confirm: {
+    level: "confirm",
+    summary: (p) => `Run the third-party plugin "${p.pluginId}"${p.commandId ? ` (command: ${p.commandId})` : ""}`,
+    detail: () => "This executes code PopCraft did not write, inside this document, with whatever permissions the plugin was granted when it was installed. It can create, change and delete layers on its own."
+  },
+  expose: {
+    agent: {
+      name: "run_plugin",
+      description: "Run an installed plugin against this document. This executes third-party code, which can change the document however it likes. The user approves every call."
+    }
+  },
+  run: async (p, ctx) => {
+    const { runPlugin } = await import("./host-YTWNKTAD.js");
+    await runPlugin(p.pluginId, p.commandId);
+    ctx.notice(`Started ${p.pluginId}.`);
+    return {
+      summary: `Ran plugin ${p.pluginId}${p.commandId ? ` \u2192 ${p.commandId}` : ""}`,
+      data: {
+        pluginId: p.pluginId,
+        commandId: p.commandId ?? null,
+        note: "The plugin runs in its own sandbox and reports through the UI. Re-read the document to see what it changed."
+      }
+    };
+  }
+});
+function pluginMethods() {
+  registerPluginCommands();
+  return listCommandsForSurface("plugin").map((c) => c.expose.plugin.method);
+}
+var registered = false;
+function registerPluginCommands() {
+  if (registered) return;
+  registered = true;
+  registerBuiltinCommands();
+  registerCommand(...commands);
+}
+function methodsByPermission() {
+  registerPluginCommands();
+  const out = {};
+  for (const c of listCommandsForSurface("plugin")) {
+    const method = c.expose.plugin?.method;
+    if (!method || !c.permission) continue;
+    (out[c.permission] ??= []).push(method);
+  }
+  for (const list of Object.values(out)) list.sort();
+  return out;
+}
+function bytesToDataUrl(bytes, format) {
+  let binary = "";
+  for (const byte of bytes) binary += String.fromCharCode(byte);
+  return `data:${MIME[format.toUpperCase()] ?? "application/octet-stream"};base64,${btoa(binary)}`;
+}
+function grouped(env, seam) {
+  const out = {};
+  for (const [k, v] of Object.entries(seam)) {
+    out[k] = typeof v === "function" ? (...args) => withHistoryGroup(env.historyGroup, () => v(...args)) : v;
+  }
+  return out;
+}
+function pluginContext(env) {
+  const have = new Set(PLUGIN_CAPABILITIES);
+  const capabilities = {
+    render: async (nodeIds, options) => {
+      const state = env.getState();
+      const out = [];
+      for (const id of nodeIds) {
+        const node = state.document.nodes[id];
+        if (!node) continue;
+        const bytes = await env.effects.exportNode(
+          [node],
+          options?.format ?? "PNG",
+          options?.scale ?? 1
+        );
+        out.push(typeof bytes === "string" ? bytes : bytesToDataUrl(bytes, options?.format ?? "PNG"));
+      }
+      return out;
+    },
+    storage: { get: env.effects.storageGet, set: env.effects.storageSet },
+    panel: { showUI: env.effects.showUI, hideUI: env.effects.hideUI, close: env.effects.close }
+  };
+  const st = () => env.getState();
+  return {
+    doc: () => st().document,
+    commit: (next, label) => {
+      withHistoryGroup(env.historyGroup, () => st().commitDocument(next, label ?? env.manifest.name));
+    },
+    pageId: () => st().currentPageId,
+    selection: () => [...st().selection],
+    setSelection: (ids) => {
+      st().setSelection(ids);
+    },
+    notice: (text, options) => {
+      env.effects.notify(text, !!options?.error);
+    },
+    actor: { kind: "plugin", id: env.manifest.id, label: env.manifest.name, host: env },
+    can: (name) => have.has(name),
+    use: (name) => capabilities[name],
+    pages: grouped(env, {
+      setCurrent: (id) => st().setCurrentPage(id),
+      create: (name) => {
+        st().addPage(name);
+        return st().currentPageId;
+      },
+      rename: (id, name) => st().renamePage(id, name)
+    }),
+    // Boolean ops, flatten, outline stroke, masks and the shape builder are store actions (they push their own undo
+    // step), grouped like `commit` while an agent tool call is running.
+    ops: grouped(env, storeOpsSeam(st))
+  };
+}
+function dispatchPluginCall(env, method, params = {}) {
+  registerPluginCommands();
+  return dispatchShaped(method, {
+    surface: "plugin",
+    params,
+    ctx: pluginContext(env),
+    granted: env.granted,
+    capabilities: PLUGIN_CAPABILITIES,
+    errorClass: PluginApiError,
+    messages: {
+      notFound: (key) => `Unknown method ${key}`,
+      denied: (key, permission) => `Permission "${permission}" is required for ${key}. Add it to manifest.permissions.`,
+      unsupported: (key, reason) => `Unknown method ${key} (${reason})`
+    }
+  });
+}
+
+export {
+  PLUGIN_CAPABILITIES,
+  pluginCommandId,
+  pluginRun,
+  pluginMethods,
+  registerPluginCommands,
+  methodsByPermission,
+  dispatchPluginCall
+};