@lovision/plugin-dev 1.0.0

package/dist/templates/export-selection/src/main.ts.template

@@ -0,0 +1,386 @@
+import { definePlugin, type PluginContext } from "@lovision/plugin-sdk";
+
+type SceneSnapshot = Awaited<ReturnType<PluginContext["document"]["snapshot"]>>;
+type SceneNodeSnapshot = SceneSnapshot["root"];
+type ExportSelectionFormat = "json" | "png" | "svg";
+
+type DownloadArtifact =
+  | {
+      kind: "bytes";
+      bytes: number[];
+      fileName: string;
+      mimeType: string;
+    }
+  | {
+      kind: "text";
+      fileName: string;
+      mimeType: string;
+      text: string;
+    };
+
+type ExportSelectionMessage =
+  | {
+      type: "error";
+      payload: {
+        message: string;
+      };
+    }
+  | {
+      type: "exported";
+      payload: {
+        download: DownloadArtifact;
+        preview: string;
+        status: string;
+      };
+    }
+  | {
+      type: "ready";
+      payload: {
+        message: string;
+      };
+    };
+
+definePlugin({
+  apiVersion: "1.0",
+  version: "0.1.0",
+  command: async (ctx) => {
+    const session = await ctx.ui.show({
+      entry: "./ui.html",
+      title: "Export Selection",
+      width: 680,
+      height: 560,
+    });
+
+    let closed = false;
+    const postToUi = async (
+      message: ExportSelectionMessage,
+    ): Promise<void> => {
+      if (closed) return;
+      await session.postMessage(message);
+    };
+    const modalClosed = new Promise<void>((resolve) => {
+      session.on("close", () => {
+        closed = true;
+        void ctx.notify.send("Export Selection closed.", { kind: "info" });
+        resolve();
+      });
+    });
+
+    session.on("export-selection", async (payload) => {
+      await handleUiAction(postToUi, async () => {
+        const format = readExportFormat(payload);
+        const artifact =
+          format === "png"
+            ? await exportSelectionWithCurrentOrFirstNode(ctx, {
+                format,
+                fileName: "selection.png",
+                scale: 1,
+                background: "current",
+              })
+            : await exportSelectionWithCurrentOrFirstNode(ctx, {
+                format,
+                fileName: `selection.${format}`,
+              });
+
+        if (artifact.delivery === "inline") {
+          const summary = summarizeInlineArtifact(artifact.format, artifact.text);
+          await postToUi({
+            type: "exported",
+            payload: {
+              status: summary.status,
+              preview: summary.preview,
+              download: {
+                kind: "text",
+                fileName:
+                  artifact.fileName ?? defaultFileNameForFormat(format),
+                mimeType: artifact.mimeType,
+                text: artifact.text,
+              },
+            },
+          });
+          await ctx.notify.send(
+            `Export Selection exported ${artifact.format} (${artifact.byteLength} bytes).`,
+            { kind: "success" },
+          );
+          return;
+        }
+
+        const bytes = await ctx.binary.read(artifact.resource);
+        await postToUi({
+          type: "exported",
+          payload: {
+            status: `Exported PNG selection raster (${bytes.byteLength} bytes).`,
+            preview: JSON.stringify(
+              {
+                mode: "selection-raster",
+                delivery: artifact.delivery,
+                format: artifact.format,
+                mimeType: artifact.mimeType,
+                byteLength: bytes.byteLength,
+                resource: {
+                  id: artifact.resource.id,
+                  byteLength: artifact.resource.byteLength,
+                },
+              },
+              null,
+              2,
+            ),
+            download: binaryDownload({
+              bytes,
+              fileName:
+                artifact.fileName ??
+                artifact.resource.name ??
+                defaultFileNameForFormat(format),
+              mimeType: artifact.mimeType,
+            }),
+          },
+        });
+        await ctx.notify.send(
+          `Export Selection exported ${artifact.format} (${bytes.byteLength} bytes).`,
+          { kind: "success" },
+        );
+      });
+    });
+
+    session.on("capture-screenshot", async () => {
+      await handleUiAction(postToUi, async () => {
+        const resource = await captureScreenshotWithCurrentOrFirstNode(ctx);
+        const bytes = await ctx.binary.read(resource);
+        await postToUi({
+          type: "exported",
+          payload: {
+            status: `Captured Screen Preview ${resource.mimeType} (${bytes.byteLength} bytes).`,
+            preview: JSON.stringify(
+              {
+                mode: "screen-preview",
+                format: "png",
+                mimeType: resource.mimeType,
+                byteLength: bytes.byteLength,
+                resource: {
+                  id: resource.id,
+                  byteLength: resource.byteLength,
+                },
+              },
+              null,
+              2,
+            ),
+            download: binaryDownload({
+              bytes,
+              fileName: resource.name ?? "screenshot.png",
+              mimeType: resource.mimeType,
+            }),
+          },
+        });
+        await ctx.notify.send(
+          `Export Selection captured screenshot (${bytes.byteLength} bytes).`,
+          { kind: "success" },
+        );
+      });
+    });
+
+    await postToUi({
+      type: "ready",
+      payload: {
+        message:
+          "Ready. Export JSON snapshots, SVG paths, PNG selection rasters, or screen previews.",
+      },
+    });
+
+    await modalClosed;
+    return { closed: true, ok: true };
+  },
+});
+
+async function handleUiAction(
+  postToUi: (message: ExportSelectionMessage) => Promise<void>,
+  action: () => Promise<unknown>,
+): Promise<void> {
+  try {
+    await action();
+  } catch (error) {
+    if (isUnsupportedSelectionRasterError(error)) {
+      await postToUi({
+        type: "error",
+        payload: {
+          message:
+            "PNG selection export is unsupported until the host provides clean selection-bounds raster capture. Use Capture Screen Preview for a screen-pixel screenshot.",
+        },
+      });
+      return;
+    }
+    const message = error instanceof Error ? error.message : String(error);
+    await postToUi({ type: "error", payload: { message } });
+  }
+}
+
+async function exportSelectionWithCurrentOrFirstNode(
+  ctx: PluginContext,
+  params: Parameters<PluginContext["export"]["selection"]>[0],
+): ReturnType<PluginContext["export"]["selection"]> {
+  try {
+    return await ctx.export.selection(params);
+  } catch (error) {
+    if (!isEmptySelectionError(error)) {
+      throw error;
+    }
+  }
+  return ctx.export.selection({
+    ...params,
+    nodeIds: await resolveFallbackExportNodeIds(ctx),
+  });
+}
+
+async function captureScreenshotWithCurrentOrFirstNode(ctx: PluginContext) {
+  const params = {
+    format: "png" as const,
+    fileName: "screenshot.png",
+    scale: 1,
+    background: "current" as const,
+  };
+  try {
+    return await ctx.export.screenshot(params);
+  } catch (error) {
+    if (!isEmptySelectionError(error)) {
+      throw error;
+    }
+  }
+  return ctx.export.screenshot({
+    ...params,
+    nodeIds: await resolveFallbackExportNodeIds(ctx),
+  });
+}
+
+async function resolveFallbackExportNodeIds(ctx: PluginContext): Promise<string[]> {
+  const snapshot = await ctx.document.snapshot();
+  const candidates = collectNodes(snapshot.root).filter(
+    (node) => node.id !== snapshot.root.id,
+  );
+  const first = candidates[0];
+  if (!first) {
+    throw new Error("Export Selection needs at least one canvas node.");
+  }
+  return [first.id];
+}
+
+function collectNodes(node: SceneNodeSnapshot): SceneNodeSnapshot[] {
+  return [node, ...node.children.flatMap((child) => collectNodes(child))];
+}
+
+function binaryDownload(input: {
+  bytes: ArrayBuffer;
+  fileName: string;
+  mimeType: string;
+}): DownloadArtifact {
+  return {
+    kind: "bytes",
+    bytes: Array.from(new Uint8Array(input.bytes)),
+    fileName: input.fileName,
+    mimeType: input.mimeType,
+  };
+}
+
+function defaultFileNameForFormat(format: ExportSelectionFormat): string {
+  return `selection.${format}`;
+}
+
+function summarizeInlineArtifact(
+  format: "json" | "svg",
+  text: string,
+): { status: string; preview: string } {
+  if (format === "json") {
+    return summarizeJsonArtifact(text);
+  }
+  return summarizeSvgArtifact(text);
+}
+
+function summarizeJsonArtifact(text: string): { status: string; preview: string } {
+  try {
+    const parsed = JSON.parse(text);
+    const nodes = Array.isArray(parsed.nodes) ? parsed.nodes : [];
+    const vectorCommandCount = nodes.reduce((sum: number, node: unknown) => {
+      if (!isRecord(node) || !isRecord(node.vector)) {
+        return sum;
+      }
+      const commands = node.vector.commands;
+      return sum + (Array.isArray(commands) ? commands.length : 0);
+    }, 0);
+    const summary = {
+      mode: "selection-json",
+      kind: parsed.kind,
+      bounds: parsed.bounds,
+      nodeCount: nodes.length,
+      vectorCommandCount,
+    };
+    return {
+      status: `Exported JSON snapshot: kind=${String(parsed.kind)} nodes=${nodes.length} vectorCommands=${vectorCommandCount}.`,
+      preview: `${JSON.stringify(summary, null, 2)}\n\n${text.slice(0, 1200)}`,
+    };
+  } catch {
+    return {
+      status: "Exported JSON snapshot.",
+      preview: text.slice(0, 1600),
+    };
+  }
+}
+
+function summarizeSvgArtifact(text: string): { status: string; preview: string } {
+  const pathCount = countMatches(text, /<path(?:\s|>)/g);
+  const fallbackCount = countMatches(text, /data-export-fallback=/g);
+  const summary = {
+    mode: "selection-svg",
+    pathCount,
+    fallbackCount,
+  };
+  return {
+    status: `Exported SVG paths: paths=${pathCount} fallbacks=${fallbackCount}.`,
+    preview: `${JSON.stringify(summary, null, 2)}\n\n${text.slice(0, 1400)}`,
+  };
+}
+
+function countMatches(text: string, pattern: RegExp): number {
+  return Array.from(text.matchAll(pattern)).length;
+}
+
+function isEmptySelectionError(error: unknown): boolean {
+  const data = readErrorData(error);
+  return (
+    readErrorCode(error) === "INVALID_PARAMS" &&
+    isRecord(data) &&
+    data.reason === "EMPTY_SELECTION"
+  );
+}
+
+function isUnsupportedSelectionRasterError(error: unknown): boolean {
+  const data = readErrorData(error);
+  return (
+    readErrorCode(error) === "INVALID_PARAMS" &&
+    isRecord(data) &&
+    data.reason === "UNSUPPORTED_EXPORT_SEMANTICS"
+  );
+}
+
+function readErrorCode(error: unknown): unknown {
+  return isRecord(error) ? error.code : undefined;
+}
+
+function readErrorData(error: unknown): unknown {
+  return isRecord(error) ? error.data : undefined;
+}
+
+function readExportFormat(payload: unknown): ExportSelectionFormat {
+  if (!isRecord(payload) || typeof payload.format !== "string") {
+    throw new Error("Export Selection requires a format.");
+  }
+  if (
+    payload.format === "json" ||
+    payload.format === "png" ||
+    payload.format === "svg"
+  ) {
+    return payload.format;
+  }
+  throw new Error(`Unsupported export format: ${payload.format}`);
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}

package/dist/templates/export-selection/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "lib": ["ESNext", "WebWorker"],
+    "module": "Preserve",
+    "moduleResolution": "bundler",
+    "target": "ESNext",
+    "strict": true,
+    "skipLibCheck": true,
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "noEmit": true
+  },
+  "include": ["src/**/*"]
+}

package/dist/templates/export-selection/ui.html.template

@@ -0,0 +1,163 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>Export Selection</title>
+    <style>
+      :root {
+        color-scheme: light dark;
+      }
+
+      body {
+        margin: 0;
+        color: CanvasText;
+        background: Canvas;
+      }
+
+      main {
+        display: grid;
+        gap: 1rem;
+        padding: 1rem;
+      }
+
+      .actions {
+        display: flex;
+        flex-wrap: wrap;
+        gap: 0.5rem;
+      }
+
+      .status {
+        min-height: 1.5rem;
+      }
+
+      pre {
+        max-height: 16rem;
+        overflow: auto;
+        padding: 0.75rem;
+        color: CanvasText;
+        background: Canvas;
+        border: 1px solid ButtonBorder;
+        white-space: pre-wrap;
+      }
+    </style>
+  </head>
+  <body>
+    <main>
+      <header>
+        <h1>Export Selection</h1>
+        <p>
+          Export the current object selection, or the first canvas node when
+          nothing is selected.
+        </p>
+      </header>
+
+      <div class="actions">
+        <button id="export-json-button" type="button">Export JSON Snapshot</button>
+        <button id="export-svg-button" type="button">Export SVG Paths</button>
+        <button id="export-png-button" type="button">Export PNG Selection</button>
+        <button id="capture-button" type="button">Capture Screen Preview</button>
+      </div>
+
+      <p id="status" class="status" role="status">Waiting for host...</p>
+      <a id="download-link" hidden>Download last export</a>
+      <pre id="preview" aria-label="Export preview"></pre>
+    </main>
+
+    <script>
+      const uiId = globalThis.__LOVISION_PLUGIN_UI_ID__;
+      const status = document.getElementById("status");
+      const preview = document.getElementById("preview");
+      const downloadLink = document.getElementById("download-link");
+      let currentDownload = null;
+
+      function post(type, payload) {
+        parent.postMessage(
+          {
+            type: "plugin-ui-message",
+            direction: "ui-to-main",
+            uiId,
+            message: { type, payload },
+          },
+          "*",
+        );
+      }
+
+      function setRunning(label) {
+        status.textContent = label;
+        preview.textContent = "";
+        setDownload(null);
+      }
+
+      function setDownload(download) {
+        currentDownload = download;
+        downloadLink.hidden = !download;
+        downloadLink.href = "#";
+        if (!download) {
+          return;
+        }
+        downloadLink.textContent = `Download ${download.fileName}`;
+      }
+
+      downloadLink.addEventListener("click", (event) => {
+        event.preventDefault();
+        if (!currentDownload) {
+          return;
+        }
+        parent.postMessage(
+          {
+            type: "plugin-ui-download",
+            uiId,
+            ...currentDownload,
+          },
+          "*",
+        );
+      });
+
+      document.getElementById("export-json-button").addEventListener("click", () => {
+        setRunning("Exporting JSON snapshot...");
+        post("export-selection", { format: "json" });
+      });
+
+      document.getElementById("export-svg-button").addEventListener("click", () => {
+        setRunning("Exporting SVG paths...");
+        post("export-selection", { format: "svg" });
+      });
+
+      document.getElementById("export-png-button").addEventListener("click", () => {
+        setRunning("Exporting PNG selection...");
+        post("export-selection", { format: "png" });
+      });
+
+      document.getElementById("capture-button").addEventListener("click", () => {
+        setRunning("Capturing screen preview...");
+        post("capture-screenshot", {});
+      });
+
+      window.addEventListener("message", (event) => {
+        const envelope = event.data;
+        if (
+          !envelope ||
+          envelope.type !== "plugin-ui-message" ||
+          envelope.direction !== "main-to-ui" ||
+          envelope.uiId !== uiId
+        ) {
+          return;
+        }
+
+        const message = envelope.message;
+        if (message.type === "ready") {
+          status.textContent = message.payload.message;
+        } else if (message.type === "exported") {
+          status.textContent = message.payload.status;
+          preview.textContent = message.payload.preview;
+          setDownload(message.payload.download);
+        } else if (message.type === "error") {
+          status.textContent = message.payload.message;
+          preview.textContent = "";
+          setDownload(null);
+        }
+      });
+    </script>
+  </body>
+</html>

package/dist/templates/review-submitter/README.md.template

@@ -0,0 +1,24 @@
+# Review Submitter
+
+This acceptance template captures the current editor context, selection metadata, and a screen preview, then submits a design review payload through `ctx.workflow.submit`. It proves the plugin can read host-owned context with `ctx.context.current`, preserve a binary screenshot artifact ref, and hand the result to a host workflow target without direct network or token access.
+
+## Development
+
+```bash
+npm install
+npm run dev
+```
+
+Copy the printed `manifestUrl=...`, open the editor shell, then use Dev Panel -> Development -> Add by URL.
+
+## Use
+
+Run **Open Review Submitter**, then click **Capture review snapshot**. The UI shows the user/workspace context, selection count, node count, and screenshot resource metadata. Click **Submit review** to call `ctx.workflow.submit` with target `review.submit`.
+
+## Formal install
+
+```bash
+npm run build
+```
+
+Upload the generated `dist/*.bundle.json` through Dev Panel -> Formal install, confirm the install dialog, then run the command from MainMenu.

package/dist/templates/review-submitter/eslint.config.mjs

@@ -0,0 +1,19 @@
+import pluginSdkConfig from "@lovision/plugin-sdk/eslint-config";
+import tsParser from "@typescript-eslint/parser";
+
+const pluginFiles = ["src/**/*.ts"];
+
+export default [
+  {
+    files: pluginFiles,
+    languageOptions: {
+      parser: tsParser,
+      ecmaVersion: "latest",
+      sourceType: "module",
+    },
+  },
+  ...pluginSdkConfig.map((entry) => ({
+    ...entry,
+    files: pluginFiles,
+  })),
+];

package/dist/templates/review-submitter/manifest.json.template

@@ -0,0 +1,35 @@
+{
+  "id": "__PLUGIN_ID__",
+  "name": {
+    "en": "Review Submitter",
+    "zh-CN": "Review Submitter"
+  },
+  "version": "0.1.0",
+  "apiVersion": "1.0",
+  "editorType": ["design"],
+  "main": "./dist/main.js",
+  "ui": "./ui.html",
+  "documentAccess": "current-page",
+  "permissions": [
+    "context:read.user",
+    "context:read.workspace",
+    "document:read",
+    "export:screenshot",
+    "notify",
+    "selection:read",
+    "ui:modal",
+    "workflow:submit"
+  ],
+  "workflowAccess": {
+    "allowedTargets": ["review.submit"]
+  },
+  "commands": [
+    {
+      "id": "run",
+      "name": {
+        "en": "__COMMAND_NAME_EN__",
+        "zh-CN": "__COMMAND_NAME_ZH__"
+      }
+    }
+  ]
+}

package/dist/templates/review-submitter/package.json.template

@@ -0,0 +1,18 @@
+{
+  "name": "__PACKAGE_NAME__",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "plugin-dev dev",
+    "build": "plugin-dev build",
+    "validate": "plugin-dev validate",
+    "lint": "eslint src --max-warnings=0"
+  },
+  "devDependencies": {
+    "@lovision/plugin-dev": "__PLUGIN_DEV_SPEC__",
+    "@lovision/plugin-sdk": "__PLUGIN_SDK_SPEC__"__LOCAL_SUPPORT_DEPS__,
+    "@typescript-eslint/parser": "^8.30.0",
+    "eslint": "^9.25.1",
+    "typescript": "^5.8.3"
+  }__LOCAL_OVERRIDES__
+}