@ycodium-ai/plugin-visualize 0.0.0-stage → 0.2.2944

package/dist/index.js

@@ -0,0 +1,505 @@
+// src/index.ts
+import { definePlugin } from "@ycodium-ai/plugin-api";
+
+// src/paths.ts
+var VIZ_FILE = /^viz\/[a-z0-9][a-z0-9-]{0,80}-[0-9a-f]{8}\.html$/u;
+function slugOf(title) {
+  const slug = title.toLowerCase().replaceAll(/[^a-z0-9]+/gu, "-").replaceAll(/^-+|-+$/gu, "").slice(0, 48);
+  return slug.length > 0 ? slug : "visualization";
+}
+function contentHash(text) {
+  let hash = 2166136261;
+  for (let i = 0; i < text.length; i++) {
+    hash ^= text.charCodeAt(i);
+    hash = Math.imul(hash, 16777619);
+  }
+  return (hash >>> 0).toString(16).padStart(8, "0");
+}
+function vizPathFor(title, fragment) {
+  return `viz/${slugOf(title)}-${contentHash(fragment)}.html`;
+}
+function acceptVizPath(path) {
+  const normalized = path.trim().replaceAll("\\", "/").replace(/^\.\//u, "");
+  if (normalized.includes("..") || normalized.startsWith("/") || normalized.includes("//")) {
+    return null;
+  }
+  return VIZ_FILE.test(normalized) ? normalized : null;
+}
+
+// src/presentation.ts
+function cardIndex(card) {
+  return {
+    invocationId: card.invocationId,
+    title: card.title,
+    mode: card.mode,
+    path: card.path,
+    sizeBytes: card.sizeBytes,
+    action: card.action
+  };
+}
+
+// src/ledger.ts
+var MAX_CARDS_PER_THREAD = 32;
+var CARDS_PROJECTION = "cards";
+function createLedger(input) {
+  const live = /* @__PURE__ */ new Map();
+  const indexes = /* @__PURE__ */ new Map();
+  const listeners = /* @__PURE__ */ new Map();
+  const notify = (threadId) => {
+    for (const listener of listeners.get(threadId) ?? []) listener();
+  };
+  return {
+    async remember(threadId, card) {
+      const prior = await readIndex(input.cache, indexes, threadId);
+      const nextIndex = [...prior, cardIndex(card)].slice(-MAX_CARDS_PER_THREAD);
+      const kept = new Set(nextIndex.map((entry) => entry.invocationId));
+      const bodies = [...live.get(threadId) ?? [], card].filter(
+        (entry) => kept.has(entry.invocationId)
+      );
+      live.set(threadId, bodies);
+      indexes.set(threadId, nextIndex);
+      await input.cache.setJson(indexKey(threadId), nextIndex);
+      await input.cache.setJson(cardKey(threadId, card.invocationId), card);
+      try {
+        await input.projections.set({
+          name: CARDS_PROJECTION,
+          threadId,
+          value: { cards: nextIndex }
+        });
+      } catch (error) {
+        input.log.warn("visualize projection was not stored", {
+          threadId,
+          detail: error instanceof Error ? error.message : String(error)
+        });
+      }
+      notify(threadId);
+    },
+    async get(threadId, invocationId) {
+      return readCard(input.cache, live, threadId, invocationId);
+    },
+    async findByPath(threadId, path) {
+      const index = await readIndex(input.cache, indexes, threadId);
+      for (let i = index.length - 1; i >= 0; i -= 1) {
+        const entry = index[i];
+        if (entry === void 0 || entry.path !== path) continue;
+        const card = await readCard(input.cache, live, threadId, entry.invocationId);
+        if (card !== null) return card;
+      }
+      const remembered = live.get(threadId);
+      if (remembered === void 0) return null;
+      for (let i = remembered.length - 1; i >= 0; i -= 1) {
+        const card = remembered[i];
+        if (card !== void 0 && card.path === path) return card;
+      }
+      return null;
+    },
+    indexOf(threadId) {
+      return readIndex(input.cache, indexes, threadId);
+    },
+    subscribe(threadId, listener, signal) {
+      const bucket = listeners.get(threadId) ?? /* @__PURE__ */ new Set();
+      bucket.add(listener);
+      listeners.set(threadId, bucket);
+      return new Promise((resolve) => {
+        const finish = () => {
+          bucket.delete(listener);
+          resolve();
+        };
+        if (signal.aborted) {
+          finish();
+          return;
+        }
+        signal.addEventListener("abort", finish, { once: true });
+      });
+    }
+  };
+}
+async function readIndex(cache, indexes, threadId) {
+  const memory = indexes.get(threadId);
+  if (memory !== void 0) return memory;
+  const stored = await cache.getJson(indexKey(threadId));
+  const parsed = stored === null ? [] : parseIndex(stored.value);
+  indexes.set(threadId, parsed);
+  return parsed;
+}
+function parseIndex(value) {
+  if (!Array.isArray(value)) return [];
+  const out = [];
+  for (const entry of value) {
+    if (!isIndexEntry(entry)) continue;
+    out.push(entry);
+  }
+  return out;
+}
+function isIndexEntry(value) {
+  if (typeof value !== "object" || value === null) return false;
+  const record = value;
+  return typeof record["invocationId"] === "string" && typeof record["title"] === "string" && (record["mode"] === "inline" || record["mode"] === "wide") && typeof record["path"] === "string" && typeof record["sizeBytes"] === "number" && (record["action"] === "create" || record["action"] === "update");
+}
+function isCard(value) {
+  if (!isIndexEntry(value)) return false;
+  const record = value;
+  return record["kind"] === "visualize" && typeof record["fragment"] === "string";
+}
+async function readCard(cache, live, threadId, invocationId) {
+  const found = live.get(threadId)?.find((card) => card.invocationId === invocationId);
+  if (found !== void 0) return found;
+  const stored = await cache.getJson(cardKey(threadId, invocationId));
+  if (stored === null || !isCard(stored.value)) return null;
+  return stored.value;
+}
+function indexKey(threadId) {
+  return `index:${threadId}`;
+}
+function cardKey(threadId, invocationId) {
+  return `card:${threadId}:${invocationId}`;
+}
+
+// src/limits.ts
+var DEFAULT_MAX_FRAGMENT_BYTES = 1e6;
+function maxFragmentBytesOf(value) {
+  const parsed = typeof value === "number" ? value : typeof value === "string" && value.trim() !== "" ? Number(value) : DEFAULT_MAX_FRAGMENT_BYTES;
+  if (!Number.isFinite(parsed)) return DEFAULT_MAX_FRAGMENT_BYTES;
+  const whole = Math.floor(parsed);
+  if (whole < 1) return DEFAULT_MAX_FRAGMENT_BYTES;
+  return Math.min(whole, DEFAULT_MAX_FRAGMENT_BYTES);
+}
+
+// src/tool.ts
+import {
+  MAX_PLUGIN_TOOL_PRESENTATION_BYTES,
+  pluginJsonByteLength
+} from "@ycodium-ai/plugin-api";
+
+// src/confirm.ts
+var LIVE_TOOL_OUTPUT_LINE = 84;
+function confirmationLine(input) {
+  const line = input.action === "update" ? `updated card at ${input.path}` : `workspace copy at ${input.path}`;
+  return line.length <= LIVE_TOOL_OUTPUT_LINE ? line : line.slice(0, LIVE_TOOL_OUTPUT_LINE);
+}
+
+// src/fragment.ts
+var VISUALIZE_TOOL_NAME = "visualize";
+var VISUALIZE_WIRE_NAME = "visualize_visualize";
+var SKELETON_TAG = /<!doctype\b|<\s*(?:html|head|body)\b/iu;
+function byteLength(text) {
+  return new TextEncoder().encode(text).length;
+}
+function validateFragment(fragment, maxBytes) {
+  if (fragment.trim().length === 0) {
+    throw new Error("invalid visualization: the fragment is empty");
+  }
+  const sizeBytes = byteLength(fragment);
+  if (sizeBytes > maxBytes) {
+    throw new Error(
+      `invalid visualization: fragment is ${sizeBytes} bytes, over the ${maxBytes}-byte limit \u2014 shrink the inline data first (fewer rows, coarser buckets, fewer decimals)`
+    );
+  }
+  const skeleton = SKELETON_TAG.exec(fragment);
+  if (skeleton) {
+    throw new Error(
+      `invalid visualization: fragment contains a document-skeleton tag (${JSON.stringify(skeleton[0])}) \u2014 write only the inline body; the card supplies the document`
+    );
+  }
+  const external = externalAssetUrl(fragment);
+  if (external !== null) {
+    throw new Error(
+      `invalid visualization: fragment loads an external resource (${JSON.stringify(external)}) \u2014 inline the script or stylesheet in the fragment; do not use a CDN or any network URL`
+    );
+  }
+  return sizeBytes;
+}
+function externalAssetUrl(fragment) {
+  for (const match of fragment.matchAll(/<(script|link)\b([^>]*)>/giu)) {
+    const tag = match[1]?.toLowerCase();
+    const attrs = match[2] ?? "";
+    if (tag === "script") {
+      const src = attr(attrs, "src");
+      if (src !== null && src.length > 0 && !inlineAssetUrl(src)) return src;
+    } else if (attr(attrs, "rel")?.toLowerCase() === "stylesheet") {
+      const href = attr(attrs, "href");
+      if (href !== null && href.length > 0 && !inlineAssetUrl(href)) return href;
+    }
+  }
+  const imported = /@import\s+(?:url\(\s*)?['"]?(https?:\/\/[^'")\s]+)/iu.exec(fragment);
+  return imported?.[1] ?? null;
+}
+function inlineAssetUrl(value) {
+  const trimmed = value.trim().toLowerCase();
+  return trimmed.startsWith("data:") || trimmed.startsWith("blob:");
+}
+function attr(attrs, name) {
+  const match = new RegExp(`\\b${name}\\s*=\\s*(?:"([^"]*)"|'([^']*)'|([^\\s"'=<>]+))`, "iu").exec(
+    attrs
+  );
+  return (match?.[1] ?? match?.[2] ?? match?.[3] ?? "").trim() || null;
+}
+var PATCH_CONTEXT_CHARS = 160;
+var MIN_ANCHOR_CHARS = 12;
+function applyFragmentPatch(base, oldStr, newStr) {
+  if (oldStr.length === 0) {
+    throw new Error(
+      "invalid visualization patch: old_str is empty \u2014 pass the exact card text to replace"
+    );
+  }
+  const first = base.indexOf(oldStr);
+  if (first === -1) {
+    throw new Error(
+      `invalid visualization patch: old_str does not appear in the card. ${nearestAnchor(base, oldStr)}`
+    );
+  }
+  if (base.indexOf(oldStr, first + oldStr.length) !== -1) {
+    throw new Error(
+      `invalid visualization patch: old_str appears ${countOccurrences(base, oldStr)} times in the card \u2014 extend it with neighbouring lines until exactly one site matches`
+    );
+  }
+  return base.slice(0, first) + newStr + base.slice(first + oldStr.length);
+}
+function nearestAnchor(base, oldStr) {
+  let matched = 0;
+  let beyond = oldStr.length;
+  while (matched < beyond) {
+    const mid = Math.ceil((matched + beyond) / 2);
+    if (base.includes(oldStr.slice(0, mid))) matched = mid;
+    else beyond = mid - 1;
+  }
+  if (matched < MIN_ANCHOR_CHARS) {
+    return "None of it matched, so the card is not in the state you assumed \u2014 re-render the whole card instead.";
+  }
+  const at = base.indexOf(oldStr.slice(0, matched));
+  return `Its first ${matched} characters do match, at offset ${at}, where the card actually reads ${JSON.stringify(base.slice(at, at + PATCH_CONTEXT_CHARS))} \u2014 correct old_str against that and retry.`;
+}
+function countOccurrences(base, needle) {
+  let count = 0;
+  for (let at = base.indexOf(needle); at !== -1; at = base.indexOf(needle, at + needle.length)) {
+    count += 1;
+  }
+  return count;
+}
+
+// src/tool.ts
+var DESCRIPTION = `Show the user an interactive HTML visualization as a live card in the conversation. Call \`${VISUALIZE_WIRE_NAME}\`. \`create\` (the default) takes the whole markup in \`fragment\`: literal inline HTML only (no <!doctype>, <html>, <head>, or <body>, and no <script src> or stylesheet URL \u2014 inline every script and style; the card supplies the document and theme). To correct a card you already rendered, call \`update\` with its \`path\` and one exact \`old_str\`/\`new_str\` replacement instead of re-sending the whole fragment. The card appears while you generate; a copy of the finished fragment is saved under viz/ in the session workspace. Load the visualize skill before the first call. The user sees the card; your reply must not paste the markup.`;
+function visualizeTool(input) {
+  return {
+    name: VISUALIZE_TOOL_NAME,
+    description: DESCRIPTION,
+    inputSchema: {
+      type: "object",
+      properties: {
+        action: {
+          type: "string",
+          enum: ["create", "update"],
+          description: "`create` (default) renders a new card from `fragment`. `update` patches the card at `path`, replacing `old_str` with `new_str`. Use update for a correction touching fewer than 20 lines in fewer than 5 places, and at most 4 times per reply."
+        },
+        fragment: {
+          type: "string",
+          description: "create only, required: the inline HTML fragment to render (markup, style, and script \u2014 no document skeleton)."
+        },
+        title: {
+          type: "string",
+          description: 'Concise card title. Defaults to "Visualization" on create; required on update.'
+        },
+        mode: {
+          type: "string",
+          enum: ["inline", "wide"],
+          description: "Card width: `inline` (default) or `wide` for side-by-side panel comparisons."
+        },
+        path: {
+          type: "string",
+          description: "update only, required: workspace path of the card to patch, as its own call reported it (viz/<slug>-<hash>.html)."
+        },
+        old_str: {
+          type: "string",
+          description: "update only, required: the exact card text to replace, whitespace included. It must appear exactly once."
+        },
+        new_str: {
+          type: "string",
+          description: "update only, required: the replacement text. Empty deletes the matched region."
+        }
+      }
+    },
+    handle: (args, invocation) => runVisualize(args, invocation, input)
+  };
+}
+async function runVisualize(args, invocation, input) {
+  try {
+    const action = readAction(args["action"]);
+    const mode = readMode(args["mode"]);
+    const workspace = invocation.workspace;
+    if (workspace?.writeFile === void 0 || workspace.readFile === void 0) {
+      return failure(
+        "invalid visualization: this call has no session workspace to write the card into"
+      );
+    }
+    const invocationId = invocation.id;
+    if (invocationId === void 0 || invocationId.length === 0) {
+      return failure("invalid visualization: this call has no invocation id");
+    }
+    let path;
+    let fragment;
+    if (action === "update") {
+      const reported = acceptVizPath(required(args["path"], "path", action));
+      if (reported === null) {
+        return failure(
+          "invalid visualization: `path` must be the viz/<slug>-<hash>.html path this tool reported"
+        );
+      }
+      path = reported;
+      const current = await workspace.readFile(path);
+      fragment = applyFragmentPatch(
+        new TextDecoder().decode(current.bytes),
+        required(args["old_str"], "old_str", action),
+        present(args["new_str"], "new_str", action)
+      );
+    } else {
+      fragment = required(args["fragment"], "fragment", action);
+      const titleForPath = typeof args["title"] === "string" ? args["title"] : "";
+      path = vizPathFor(titleForPath.trim() || "Visualization", fragment);
+    }
+    const sizeBytes = validateFragment(fragment, input.maxFragmentBytes());
+    const title = action === "update" ? required(args["title"], "title", action).trim() : (typeof args["title"] === "string" ? args["title"].trim() : "") || "Visualization";
+    const card = {
+      kind: "visualize",
+      invocationId,
+      fragment,
+      title,
+      mode,
+      path,
+      sizeBytes,
+      action
+    };
+    const presentationBytes = pluginJsonByteLength(card);
+    if (presentationBytes > MAX_PLUGIN_TOOL_PRESENTATION_BYTES) {
+      return failure(
+        `invalid visualization: the card payload is ${presentationBytes} bytes, over the ${MAX_PLUGIN_TOOL_PRESENTATION_BYTES}-byte presentation limit \u2014 shrink the fragment`
+      );
+    }
+    await workspace.writeFile(path, new TextEncoder().encode(fragment));
+    if (invocation.threadId !== null) {
+      await input.ledger.remember(invocation.threadId, card);
+    }
+    return {
+      text: confirmationLine({ action, title, sizeBytes, path }),
+      presentation: card
+    };
+  } catch (error) {
+    return failure(error instanceof Error ? error.message : String(error));
+  }
+}
+function readAction(value) {
+  if (value === void 0 || value === "create") return "create";
+  if (value === "update") return "update";
+  throw new Error('invalid visualization: `action` must be "create" or "update"');
+}
+function readMode(value) {
+  return value === "wide" ? "wide" : "inline";
+}
+function required(value, name, action) {
+  if (typeof value !== "string" || value.trim().length === 0) {
+    throw new Error(`invalid visualization: \`${name}\` is required when action is "${action}"`);
+  }
+  return value;
+}
+function present(value, name, action) {
+  if (typeof value !== "string") {
+    throw new Error(`invalid visualization: \`${name}\` is required when action is "${action}"`);
+  }
+  return value;
+}
+function failure(text) {
+  return { isError: true, text, errorCode: "invalid_visualization" };
+}
+
+// src/index.ts
+var visualizePlugin = definePlugin({
+  id: "visualize",
+  apiVersion: 4,
+  activate(ctx) {
+    const ledger = createLedger({
+      cache: ctx.cache,
+      projections: ctx.sessionProjections,
+      log: ctx.log
+    });
+    ctx.sessionProjections.register({ name: CARDS_PROJECTION });
+    ctx.toolkit({
+      name: "visualize",
+      tools: [
+        visualizeTool({
+          maxFragmentBytes: () => maxFragmentBytesOf(ctx.config.maxFragmentBytes),
+          ledger
+        })
+      ]
+    });
+    ctx.command({
+      name: "card",
+      description: "Read one stored visualization card for a thread.",
+      scope: "read",
+      payloadSchema: {
+        type: "object",
+        properties: {
+          threadId: { type: "string" },
+          invocationId: { type: "string" },
+          path: { type: "string" }
+        },
+        required: ["threadId", "invocationId"]
+      },
+      handle: async (payload) => {
+        const threadId = readString(payload["threadId"]);
+        const path = readString(payload["path"]);
+        if (path.length > 0) {
+          const byPath = await ledger.findByPath(threadId, path);
+          if (byPath !== null) return { card: byPath };
+        }
+        return {
+          card: await ledger.get(threadId, readString(payload["invocationId"]))
+        };
+      }
+    });
+    ctx.stream({
+      name: "cards",
+      description: "List visualization cards stored for a thread.",
+      scope: "read",
+      buffer: { latest: 1 },
+      payloadSchema: {
+        type: "object",
+        properties: {
+          threadId: { type: "string" }
+        },
+        required: ["threadId"]
+      },
+      handle: async (payload, emit, signal) => {
+        const threadId = readString(payload["threadId"]);
+        const push = async () => {
+          emit({ cards: await ledger.indexOf(threadId) });
+        };
+        await push();
+        await ledger.subscribe(
+          threadId,
+          () => {
+            void push();
+          },
+          signal
+        );
+      }
+    });
+    ctx.settingsCard({
+      titleKey: "settings.card.title",
+      descriptionKey: "settings.card.description",
+      fields: [
+        {
+          key: "maxFragmentBytes",
+          kind: "number",
+          labelKey: "settings.maxFragmentBytes.label",
+          descriptionKey: "settings.maxFragmentBytes.description"
+        }
+      ]
+    });
+  }
+});
+function readString(value) {
+  return typeof value === "string" ? value : "";
+}
+var index_default = visualizePlugin;
+export {
+  index_default as default
+};

package/locales/en.json

@@ -0,0 +1,35 @@
+{
+  "settings": {
+    "card": {
+      "title": "Visualize",
+      "description": "Agents call this to put an interactive HTML card in the conversation. The card is sandboxed. Nothing is sent from the card back into the chat."
+    },
+    "maxFragmentBytes": {
+      "label": "Maximum fragment size",
+      "description": "Largest inline HTML fragment, in bytes. The default is 1000000. Larger values are capped at 1000000 so the card still fits the presentation limit."
+    }
+  },
+  "status": {
+    "streaming": "Preview",
+    "ready": "Ready",
+    "loading": "Loading",
+    "missing": "Unavailable"
+  },
+  "card": {
+    "modeInline": "Inline",
+    "modeWide": "Wide",
+    "bytes": "{{count}} bytes",
+    "path": "Workspace copy: {{path}}",
+    "copyPath": "Copy path",
+    "copied": "Copied",
+    "frame": "Visualization: {{title}}",
+    "loading": "Loading the saved visualization.",
+    "missing": "This visualization is not on this machine anymore. The confirmation line is still in the tool result."
+  },
+  "dock": {
+    "waiting": "The visualization will appear here as it is written."
+  },
+  "tool": {
+    "title": "Visualize"
+  }
+}

package/locales/zh-CN.json

@@ -0,0 +1,35 @@
+{
+  "settings": {
+    "card": {
+      "title": "可视化",
+      "description": "智能体用它在会话里放一张可交互的 HTML 卡片。卡片在沙箱里运行。卡片里的操作不会发回对话。"
+    },
+    "maxFragmentBytes": {
+      "label": "片段大小上限",
+      "description": "一段内联 HTML 最多多少字节。默认 1000000。更大的值会被压到 1000000，好让卡片仍放得进展示体上限里。"
+    }
+  },
+  "status": {
+    "streaming": "预览",
+    "ready": "已就绪",
+    "loading": "加载中",
+    "missing": "不可用"
+  },
+  "card": {
+    "modeInline": "标准",
+    "modeWide": "加宽",
+    "bytes": "{{count}} 字节",
+    "path": "工作区副本：{{path}}",
+    "copyPath": "复制路径",
+    "copied": "已复制",
+    "frame": "可视化：{{title}}",
+    "loading": "正在加载已保存的可视化。",
+    "missing": "这台机器上已经没有这份可视化了。工具结果里的确认行还在。"
+  },
+  "dock": {
+    "waiting": "可视化会在撰写过程中出现在这里。"
+  },
+  "tool": {
+    "title": "可视化"
+  }
+}

package/package.json

@@ -1,6 +1,82 @@
 {
   "name": "@ycodium-ai/plugin-visualize",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.2944",
+  "description": "Renders an inline HTML fragment as a sandboxed card in the conversation.",
+  "keywords": [
+    "visualization",
+    "ycodium",
+    "ycodium-plugin"
+  ],
+  "license": "UNLICENSED",
+  "files": [
+    "dist",
+    "assets",
+    "skills",
+    "locales",
+    "README.md"
+  ],
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@types/react": "~19.2.14",
+    "esbuild": "0.28.1",
+    "react": "19.2.6",
+    "typescript": "~6.0.3",
+    "vite-plus": "0.2.2",
+    "@ycodium-ai/plugin-api": "0.2.2944"
+  },
+  "ycodium": {
+    "plugin": "./dist/index.js",
+    "displayName": "Visualize",
+    "description": "Renders an inline HTML fragment as a sandboxed card in the conversation.",
+    "icon": "./assets/icon.svg",
+    "permissions": [
+      {
+        "kind": "workspace.read"
+      },
+      {
+        "kind": "workspace.write"
+      },
+      {
+        "kind": "ui.seats",
+        "seats": [
+          "conversation.input.dock",
+          "conversation.chat.turnTail"
+        ]
+      },
+      {
+        "kind": "sessionProjection"
+      }
+    ],
+    "skills": [
+      {
+        "dir": "./skills/visualize",
+        "files": [
+          "references/charts.md",
+          "references/design.md",
+          "examples/comparison-chart.html",
+          "examples/interactive-simulator.html"
+        ]
+      }
+    ],
+    "ui": {
+      "assets": "./assets",
+      "entry": "ui.js",
+      "toolViews": [
+        {
+          "tool": "visualize",
+          "view": "card",
+          "placement": "deliverable",
+          "titleKey": "tool.title"
+        }
+      ]
+    }
+  },
+  "scripts": {
+    "build": "node build.mjs",
+    "typecheck": "tsgo --noEmit && tsgo --noEmit -p tsconfig.ui.json",
+    "test": "vp test run"
+  }
 }