@lovision/plugin-dev 1.0.0

package/dist/templates/batch-layout-organizer/src/main.ts.template

@@ -0,0 +1,324 @@
+import { definePlugin } from "@lovision/plugin-sdk";
+
+type Vec2 = {
+  x: number;
+  y: number;
+};
+
+type Size = {
+  height: number;
+  width: number;
+};
+
+type SceneNodeSnapshot = {
+  children: SceneNodeSnapshot[];
+  id: string;
+  name: string;
+  parentId: string | null;
+  position: Vec2;
+  size: Size;
+  type: string;
+};
+
+type SceneSnapshot = {
+  root: SceneNodeSnapshot;
+  version: number;
+};
+
+type NodeCreateSpec = {
+  name?: string;
+  parentId?: string | null;
+  position?: Vec2;
+  size?: Size;
+  type: string;
+};
+
+type MutationResult = {
+  newVersion: number;
+};
+
+type NodesApi = {
+  create(
+    specs: NodeCreateSpec[],
+    opts?: { expectedVersion?: number },
+  ): Promise<MutationResult>;
+  group(params: {
+    expectedVersion?: number;
+    name?: string;
+    nodeIds: string[];
+    parentId?: string | null;
+  }): Promise<{ groupId: string; newVersion: number }>;
+  reparent(params: {
+    expectedVersion?: number;
+    index?: number;
+    nodeIds: string[];
+    parentId: string | null;
+    preserveAbsolutePosition?: boolean;
+  }): Promise<MutationResult>;
+  reorder(params: {
+    expectedVersion?: number;
+    index: number;
+    nodeIds: string[];
+    parentId?: string | null;
+  }): Promise<MutationResult>;
+};
+
+type OrganizerContext = {
+  document: {
+    snapshot(): Promise<SceneSnapshot>;
+  };
+  nodes: NodesApi;
+  notify: {
+    send(
+      message: string,
+      options?: { kind?: "error" | "info" | "success" | "warning" },
+    ): Promise<void>;
+  };
+  selection: {
+    get(): Promise<string[]>;
+  };
+  viewport: {
+    focusNode(nodeId: string): Promise<void>;
+  };
+};
+
+type OrganizerMessage =
+  | {
+      type: "analysis";
+      payload: {
+        message: string;
+        targetNames: string[];
+        totalNodes: number;
+      };
+    }
+  | {
+      type: "error";
+      payload: {
+        message: string;
+      };
+    }
+  | {
+      type: "organized";
+      payload: {
+        childCount: number;
+        groupId: string;
+        newVersion: number;
+      };
+    }
+  | {
+      type: "ready";
+      payload: {
+        message: string;
+      };
+    };
+
+const GROUP_NAME = "Batch Layout Group";
+
+definePlugin({
+  apiVersion: "1.0",
+  version: "0.1.0",
+  command: async (ctx) => {
+    const session = await ctx.ui.show({
+      mode: "panel",
+      entry: "./ui.html",
+      title: "Batch Layout Organizer",
+      width: 420,
+    });
+
+    let closed = false;
+    const postToUi = async (message: OrganizerMessage): Promise<void> => {
+      if (closed) return;
+      await session.postMessage(message);
+    };
+    const panelClosed = new Promise<void>((resolve) => {
+      session.on("close", () => {
+        closed = true;
+        void ctx.notify.send("Batch Layout Organizer closed.", {
+          kind: "info",
+        });
+        resolve();
+      });
+    });
+
+    session.on("analyze-canvas", async () => {
+      await handleUiAction(postToUi, async () => {
+        const analysis = await analyzeScene(ctx);
+        await postToUi({
+          type: "analysis",
+          payload: analysis,
+        });
+      });
+    });
+
+    session.on("organize-layout", async () => {
+      await handleUiAction(postToUi, async () => {
+        const result = await organizeLayout(ctx);
+        await postToUi({
+          type: "organized",
+          payload: result,
+        });
+        await ctx.notify.send(
+          `Batch Layout Organizer organized ${result.childCount} node(s).`,
+          { kind: "success" },
+        );
+      });
+    });
+
+    await postToUi({
+      type: "ready",
+      payload: {
+        message:
+          "Ready. Analyze the scene, then organize a batch into a grouped hierarchy.",
+      },
+    });
+
+    await panelClosed;
+    return { closed: true, ok: true };
+  },
+});
+
+async function handleUiAction(
+  postToUi: (message: OrganizerMessage) => Promise<void>,
+  action: () => Promise<unknown>,
+): Promise<void> {
+  try {
+    await action();
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    await postToUi({ type: "error", payload: { message } });
+  }
+}
+
+async function analyzeScene(ctx: OrganizerContext): Promise<{
+  message: string;
+  targetNames: string[];
+  totalNodes: number;
+}> {
+  const snapshot = await ctx.document.snapshot();
+  const selection = await ctx.selection.get();
+  const nodes = collectNodes(snapshot.root).filter(
+    (node) => node.id !== snapshot.root.id,
+  );
+  const targetNames = resolveCandidateNodes(snapshot, selection)
+    .slice(0, 3)
+    .map((node) => node.name);
+  const message =
+    targetNames.length >= 3
+      ? "Found at least three candidate nodes."
+      : "Scene is sparse; Organize layout will create three demo cards first.";
+  return {
+    message,
+    targetNames,
+    totalNodes: nodes.length,
+  };
+}
+
+async function organizeLayout(ctx: OrganizerContext): Promise<{
+  childCount: number;
+  groupId: string;
+  newVersion: number;
+}> {
+  const prepared = await prepareTargets(ctx);
+  const firstId = prepared.targetIds[0];
+  const secondId = prepared.targetIds[1];
+  const promotedId = prepared.targetIds[2];
+  if (!firstId || !secondId || !promotedId) {
+    throw new Error("Batch Layout Organizer needs at least three nodes.");
+  }
+
+  const groupResult = await ctx.nodes.group({
+    nodeIds: [firstId, secondId],
+    name: GROUP_NAME,
+    expectedVersion: prepared.version,
+  });
+  const reparentResult = await ctx.nodes.reparent({
+    nodeIds: [promotedId],
+    parentId: groupResult.groupId,
+    index: 2,
+    preserveAbsolutePosition: true,
+    expectedVersion: groupResult.newVersion,
+  });
+  const reorderResult = await ctx.nodes.reorder({
+    nodeIds: [promotedId],
+    parentId: groupResult.groupId,
+    index: 0,
+    expectedVersion: reparentResult.newVersion,
+  });
+  await ctx.viewport.focusNode(groupResult.groupId);
+  return {
+    childCount: 3,
+    groupId: groupResult.groupId,
+    newVersion: reorderResult.newVersion,
+  };
+}
+
+async function prepareTargets(ctx: OrganizerContext): Promise<{
+  targetIds: string[];
+  version: number;
+}> {
+  const snapshot = await ctx.document.snapshot();
+  const selection = await ctx.selection.get();
+  const candidates = resolveCandidateNodes(snapshot, selection);
+  if (candidates.length >= 3) {
+    return {
+      targetIds: candidates.slice(0, 3).map((node) => node.id),
+      version: snapshot.version,
+    };
+  }
+
+  const runId = Date.now().toString(36);
+  const cardNames = [
+    `Batch Layout Card A ${runId}`,
+    `Batch Layout Card B ${runId}`,
+    `Batch Layout Card C ${runId}`,
+  ];
+  await ctx.nodes.create(
+    cardNames.map((name, index) => ({
+      type: "shape",
+      name,
+      parentId: null,
+      position: { x: 120 + index * 120, y: 360 },
+      size: { width: 96, height: 72 },
+    })),
+    { expectedVersion: snapshot.version },
+  );
+
+  const afterCreate = await ctx.document.snapshot();
+  const created = collectNodes(afterCreate.root)
+    .filter((node) => cardNames.includes(node.name))
+    .sort((left, right) => left.name.localeCompare(right.name));
+  if (created.length < 3) {
+    throw new Error("Could not find the demo cards after creation.");
+  }
+  return {
+    targetIds: created.slice(0, 3).map((node) => node.id),
+    version: afterCreate.version,
+  };
+}
+
+function resolveCandidateNodes(
+  snapshot: SceneSnapshot,
+  selection: string[],
+): SceneNodeSnapshot[] {
+  const allNodes = collectNodes(snapshot.root).filter(
+    (node) => node.id !== snapshot.root.id,
+  );
+  const selected = selection
+    .map((nodeId) => allNodes.find((node) => node.id === nodeId))
+    .filter((node): node is SceneNodeSnapshot => node !== undefined);
+  if (selected.length >= 3) {
+    return selected;
+  }
+  return snapshot.root.children.filter((node) => node.name !== GROUP_NAME);
+}
+
+function collectNodes(
+  node: SceneNodeSnapshot,
+  out: SceneNodeSnapshot[] = [],
+): SceneNodeSnapshot[] {
+  out.push(node);
+  for (const child of node.children) {
+    collectNodes(child, out);
+  }
+  return out;
+}

package/dist/templates/batch-layout-organizer/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/batch-layout-organizer/ui.html.template

@@ -0,0 +1,116 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>Batch Layout Organizer</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: 10rem;
+        overflow: auto;
+        padding: 0.75rem;
+        color: CanvasText;
+        background: Canvas;
+        border: 1px solid ButtonBorder;
+      }
+    </style>
+  </head>
+  <body>
+    <main>
+      <header>
+        <h1>Batch Layout Organizer</h1>
+        <p>
+          Analyze candidate nodes, then organize a batch into a grouped
+          hierarchy through the plugin main worker.
+        </p>
+      </header>
+
+      <div class="actions">
+        <button id="analyze-button" type="button">Analyze canvas</button>
+        <button id="organize-button" type="button">Organize layout</button>
+      </div>
+
+      <p id="status" class="status" role="status">Waiting for host...</p>
+      <pre id="details" aria-label="Details"></pre>
+    </main>
+
+    <script>
+      const uiId = globalThis.__LOVISION_PLUGIN_UI_ID__;
+      const status = document.getElementById("status");
+      const details = document.getElementById("details");
+
+      function post(type, payload) {
+        parent.postMessage(
+          {
+            type: "plugin-ui-message",
+            direction: "ui-to-main",
+            uiId,
+            message: { type, payload },
+          },
+          "*",
+        );
+      }
+
+      document.getElementById("analyze-button").addEventListener("click", () => {
+        status.textContent = "Analyzing...";
+        post("analyze-canvas", {});
+      });
+
+      document.getElementById("organize-button").addEventListener("click", () => {
+        status.textContent = "Organizing...";
+        post("organize-layout", {});
+      });
+
+      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 === "analysis") {
+          status.textContent = `${message.payload.message} Found ${message.payload.totalNodes} node(s).`;
+          details.textContent = JSON.stringify(message.payload.targetNames, null, 2);
+        } else if (message.type === "organized") {
+          status.textContent = `Organized ${message.payload.childCount} node(s).`;
+          details.textContent = JSON.stringify(message.payload, null, 2);
+        } else if (message.type === "error") {
+          status.textContent = message.payload.message;
+        }
+      });
+    </script>
+  </body>
+</html>

package/dist/templates/data-filler-full/README.md.template

@@ -0,0 +1,32 @@
+# Data Filler
+
+This Step 27 acceptance template is the full Data Filler demo. The UI sends field mapping intent to the plugin main worker; the worker reads the scene snapshot, resolves text nodes, writes content with `ctx.nodes.setText`, and updates node properties with `ctx.nodes.update`.
+
+## 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 Data Filler**, paste CSV or JSON, set the field mapping, click **Preview mapping**, then click **Apply mapping**.
+
+The default mapping is:
+
+- Text field: `title`
+- Name field: `name`
+- Opacity field: `opacity`
+
+If the current canvas has no text nodes, the plugin creates one demo text node and then writes through `ctx.nodes.setText`; it does not use node name as a substitute for text content.
+
+## 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/data-filler-full/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/data-filler-full/manifest.json.template

@@ -0,0 +1,31 @@
+{
+  "id": "__PLUGIN_ID__",
+  "name": {
+    "en": "Data Filler",
+    "zh-CN": "Data Filler"
+  },
+  "version": "0.1.0",
+  "apiVersion": "1.0",
+  "editorType": ["design"],
+  "main": "./dist/main.js",
+  "ui": "./ui.html",
+  "documentAccess": "current-page",
+  "permissions": [
+    "document:read",
+    "document:write.create",
+    "document:write.style",
+    "document:write.text",
+    "notify",
+    "selection:read",
+    "ui:modal"
+  ],
+  "commands": [
+    {
+      "id": "run",
+      "name": {
+        "en": "__COMMAND_NAME_EN__",
+        "zh-CN": "__COMMAND_NAME_ZH__"
+      }
+    }
+  ]
+}

package/dist/templates/data-filler-full/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__
+}