@lovision/plugin-dev 1.0.0

package/dist/templates/asset-browser/src/main.ts.template

@@ -0,0 +1,177 @@
+import { definePlugin } from "@lovision/plugin-sdk";
+
+type Vec2 = {
+  x: number;
+  y: number;
+};
+
+type Size = {
+  height: number;
+  width: number;
+};
+
+type SampleAsset = {
+  id: "badge" | "hero";
+  fileName: string;
+  insertName: string;
+  label: string;
+  position: Vec2;
+  size: Size;
+  svg: string;
+};
+
+type AssetBrowserMessage =
+  | {
+      type: "error";
+      payload: {
+        message: string;
+      };
+    }
+  | {
+      type: "inserted";
+      payload: {
+        message: string;
+        newVersion: number;
+        resourceId: string;
+      };
+    }
+  | {
+      type: "ready";
+      payload: {
+        assets: Array<{
+          id: SampleAsset["id"];
+          label: string;
+        }>;
+        message: string;
+      };
+    };
+
+const SAMPLE_ASSETS: readonly SampleAsset[] = [
+  {
+    id: "hero",
+    label: "Hero asset",
+    insertName: "Asset Browser Hero",
+    fileName: "asset-browser-hero.svg",
+    position: { x: 440, y: 120 },
+    size: { width: 240, height: 160 },
+    svg: `<svg xmlns="http://www.w3.org/2000/svg" width="240" height="160" viewBox="0 0 240 160"><rect width="240" height="160" rx="20" fill="#0f766e"/><circle cx="190" cy="44" r="28" fill="#facc15"/><path d="M28 118 82 70l42 36 28-24 60 36v20H28Z" fill="#ecfeff"/><text x="28" y="38" fill="#ecfeff" font-family="Arial, sans-serif" font-size="18" font-weight="700">Hero Asset</text></svg>`,
+  },
+  {
+    id: "badge",
+    label: "Badge asset",
+    insertName: "Asset Browser Badge",
+    fileName: "asset-browser-badge.svg",
+    position: { x: 460, y: 320 },
+    size: { width: 160, height: 160 },
+    svg: `<svg xmlns="http://www.w3.org/2000/svg" width="160" height="160" viewBox="0 0 160 160"><rect width="160" height="160" rx="80" fill="#4338ca"/><path d="m80 26 13 34 36 2-28 23 9 35-30-20-30 20 9-35-28-23 36-2Z" fill="#f8fafc"/><text x="80" y="132" text-anchor="middle" fill="#f8fafc" font-family="Arial, sans-serif" font-size="14" font-weight="700">Badge</text></svg>`,
+  },
+];
+
+definePlugin({
+  apiVersion: "1.0",
+  version: "0.1.0",
+  command: async (ctx) => {
+    const session = await ctx.ui.show({
+      mode: "panel",
+      entry: "./ui.html",
+      title: "Asset Browser",
+      width: 420,
+    });
+
+    let closed = false;
+    const postToUi = async (message: AssetBrowserMessage): Promise<void> => {
+      if (closed) return;
+      await session.postMessage(message);
+    };
+    const panelClosed = new Promise<void>((resolve) => {
+      session.on("close", () => {
+        closed = true;
+        void ctx.notify.send("Asset Browser closed.", { kind: "info" });
+        resolve();
+      });
+    });
+
+    session.on("insert-asset", async (payload) => {
+      await handleUiAction(postToUi, async () => {
+        const asset = readSampleAsset(payload);
+        const snapshot = await ctx.document.snapshot();
+        const ref = await ctx.binary.create({
+          bytes: encodeUtf8(asset.svg),
+          mimeType: "image/svg+xml",
+          name: asset.fileName,
+          kind: "generated",
+        });
+        const result = await ctx.assets.insertImage({
+          source: ref,
+          position: { ...asset.position },
+          size: { ...asset.size },
+          name: asset.insertName,
+          expectedVersion: snapshot.version,
+        });
+        await postToUi({
+          type: "inserted",
+          payload: {
+            message: `Inserted ${asset.insertName}.`,
+            newVersion: result.newVersion,
+            resourceId: ref.id,
+          },
+        });
+        await ctx.notify.send(
+          `Asset Browser inserted ${asset.insertName}.`,
+          { kind: "success" },
+        );
+      });
+    });
+
+    await postToUi({
+      type: "ready",
+      payload: {
+        message: "Ready. Choose an asset and insert it as an image node.",
+        assets: SAMPLE_ASSETS.map((asset) => ({
+          id: asset.id,
+          label: asset.label,
+        })),
+      },
+    });
+
+    await panelClosed;
+    return { closed: true, ok: true };
+  },
+});
+
+async function handleUiAction(
+  postToUi: (message: AssetBrowserMessage) => 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 } });
+  }
+}
+
+function readSampleAsset(payload: unknown): SampleAsset {
+  if (!isRecord(payload) || typeof payload.assetId !== "string") {
+    throw new Error("Asset Browser requires an assetId.");
+  }
+  const asset = SAMPLE_ASSETS.find(
+    (candidate) => candidate.id === payload.assetId,
+  );
+  if (!asset) {
+    throw new Error(`Unknown asset: ${payload.assetId}`);
+  }
+  return asset;
+}
+
+function encodeUtf8(text: string): ArrayBuffer {
+  const bytes = new TextEncoder().encode(text);
+  return bytes.buffer.slice(
+    bytes.byteOffset,
+    bytes.byteOffset + bytes.byteLength,
+  );
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}

package/dist/templates/asset-browser/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/asset-browser/ui.html.template

@@ -0,0 +1,137 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>Asset Browser</title>
+    <style>
+      :root {
+        color-scheme: light dark;
+      }
+
+      body {
+        margin: 0;
+        color: CanvasText;
+        background: Canvas;
+      }
+
+      main {
+        display: grid;
+        gap: 1rem;
+        padding: 1rem;
+      }
+
+      .assets {
+        display: grid;
+        gap: 0.75rem;
+      }
+
+      .asset {
+        display: grid;
+        gap: 0.5rem;
+        padding: 0.75rem;
+        border: 1px solid ButtonBorder;
+      }
+
+      .asset-preview {
+        width: 100%;
+        min-height: 4rem;
+        display: grid;
+        place-items: center;
+        color: CanvasText;
+        background: Canvas;
+        border: 1px solid ButtonBorder;
+      }
+
+      .status {
+        min-height: 1.5rem;
+      }
+
+      pre {
+        max-height: 8rem;
+        overflow: auto;
+        padding: 0.75rem;
+        color: CanvasText;
+        background: Canvas;
+        border: 1px solid ButtonBorder;
+      }
+    </style>
+  </head>
+  <body>
+    <main>
+      <header>
+        <h1>Asset Browser</h1>
+        <p>Insert generated image assets through the plugin main worker.</p>
+      </header>
+
+      <section class="assets" aria-label="Assets">
+        <article class="asset">
+          <div class="asset-preview">Hero Asset</div>
+          <button id="insert-hero-button" type="button">Insert hero asset</button>
+        </article>
+        <article class="asset">
+          <div class="asset-preview">Badge Asset</div>
+          <button id="insert-badge-button" type="button">Insert badge asset</button>
+        </article>
+      </section>
+
+      <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 },
+          },
+          "*",
+        );
+      }
+
+      function insertAsset(assetId) {
+        status.textContent = "Inserting...";
+        details.textContent = "";
+        post("insert-asset", { assetId });
+      }
+
+      document.getElementById("insert-hero-button").addEventListener("click", () => {
+        insertAsset("hero");
+      });
+
+      document.getElementById("insert-badge-button").addEventListener("click", () => {
+        insertAsset("badge");
+      });
+
+      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;
+          details.textContent = JSON.stringify(message.payload.assets, null, 2);
+        } else if (message.type === "inserted") {
+          status.textContent = message.payload.message;
+          details.textContent = JSON.stringify(message.payload, null, 2);
+        } else if (message.type === "error") {
+          status.textContent = message.payload.message;
+        }
+      });
+    </script>
+  </body>
+</html>

package/dist/templates/base/README.md.template

@@ -0,0 +1,34 @@
+# __PLUGIN_NAME_EN__
+
+An Instinct plugin scaffold generated by `create-instinct-plugin`.
+
+## Scripts
+
+- `dev` — start the local HTTPS sideload server and print `manifestUrl`
+- `build` — emit a formal-install bundle under `dist/`
+- `validate` — run the same manifest + bundle validation path used by the host
+- `lint` — run the default plugin ESLint setup
+
+## First Run
+
+1. Install dependencies with your preferred package manager.
+2. Run `dev`.
+3. Open the editor's plugin development surface and sideload the printed `manifestUrl`.
+4. Accept the local HTTPS certificate once if the browser asks.
+
+## Network Allowlist Example
+
+The default manifest keeps permissions minimal. When you need fetch access, declare both:
+
+- `network:fetch`
+- `domain:api.example.com`
+
+and pair them with:
+
+```json
+"networkAccess": {
+  "allowedDomains": ["api.example.com"]
+}
+```
+
+That keeps Step 13 network enforcement on the documented happy path and avoids a first-run `network denied` surprise.

package/dist/templates/base/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/base/manifest.json.template

@@ -0,0 +1,22 @@
+{
+  "id": "__PLUGIN_ID__",
+  "name": {
+    "en": "__PLUGIN_NAME_EN__",
+    "zh-CN": "__PLUGIN_NAME_ZH__"
+  },
+  "version": "0.1.0",
+  "apiVersion": "1.0",
+  "editorType": ["design"],
+  "main": "./dist/main.js",
+  "documentAccess": "current-page",
+  "permissions": ["document:read", "notify"],
+  "commands": [
+    {
+      "id": "run",
+      "name": {
+        "en": "__COMMAND_NAME_EN__",
+        "zh-CN": "__COMMAND_NAME_ZH__"
+      }
+    }
+  ]
+}

package/dist/templates/base/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__
+}

package/dist/templates/base/src/main.ts.template

@@ -0,0 +1,20 @@
+import { definePlugin } from "@lovision/plugin-sdk";
+
+definePlugin({
+  apiVersion: "1.0",
+  version: "0.1.0",
+  command: async (ctx, info) => {
+    const snapshot = await ctx.document.snapshot();
+    const childCount = snapshot.root.children.length;
+    await ctx.notify.send(
+      `Ran ${info.id} with ${childCount} top-level node(s)`,
+      { kind: "success" },
+    );
+
+    return {
+      childCount,
+      commandId: info.id,
+      ok: true,
+    };
+  },
+});

package/dist/templates/base/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/README.md.template

@@ -0,0 +1,24 @@
+# Batch Layout Organizer
+
+This Step 27 acceptance template proves the structural Host Facade through a real `plugin-dev` project. The panel asks the main worker to create demo cards when the scene is sparse, then runs `group / reparent / reorder` through `ctx.nodes`.
+
+## 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 Batch Layout Organizer**, click **Analyze canvas**, then click **Organize layout**. The command creates a `Batch Layout Group`, reparents a promoted card into it, reorders that card to the top, focuses the group, and emits a notification.
+
+## 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/batch-layout-organizer/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/batch-layout-organizer/manifest.json.template

@@ -0,0 +1,31 @@
+{
+  "id": "__PLUGIN_ID__",
+  "name": {
+    "en": "Batch Layout Organizer",
+    "zh-CN": "Batch Layout Organizer"
+  },
+  "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.reparent",
+    "notify",
+    "selection:read",
+    "ui:panel",
+    "viewport:write"
+  ],
+  "commands": [
+    {
+      "id": "run",
+      "name": {
+        "en": "__COMMAND_NAME_EN__",
+        "zh-CN": "__COMMAND_NAME_ZH__"
+      }
+    }
+  ]
+}

package/dist/templates/batch-layout-organizer/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__
+}