@ai-gui/plugin-sdk 0.4.0

package/CHANGELOG.md

@@ -0,0 +1,18 @@
+# @ai-gui/plugin-sdk
+
+## 0.4.0
+
+### Minor Changes
+
+- Add plugin authoring helpers, secure source citation blocks, revisioned artifacts, bounded declarative AI-generated UI trees, molecular structures, and interactive maps.
+
+### Patch Changes
+
+- Updated dependencies
+  - @ai-gui/core@0.4.0
+
+## 0.3.0
+
+### Minor Changes
+
+- Add minimal plugin authoring exports and pure plugin test helpers.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Liang Li
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,48 @@
+# @ai-gui/plugin-sdk
+
+Minimal authoring and test helpers for AIGUI plugins. The package has no test-runner dependency and is safe to import in Node.js.
+
+## Install
+
+```sh
+pnpm add @ai-gui/core @ai-gui/plugin-sdk
+```
+
+## Author a plugin
+
+```ts
+import { definePlugin } from "@ai-gui/plugin-sdk"
+
+export const example = definePlugin({
+  name: "example",
+  nodeRenderers: {
+    example: (node) => ({ kind: "html", html: node.content ?? "" }),
+  },
+})
+```
+
+`definePlugin` is an identity helper: it validates the plugin shape while preserving its concrete inferred type.
+
+## Test a plugin
+
+```ts
+import { createTestNode, renderPluginNode } from "@ai-gui/plugin-sdk"
+
+const output = await renderPluginNode(example, createTestNode("example", { content: "Hello" }))
+```
+
+For mount outputs, supply your own element and clean up safely:
+
+```ts
+import { mountOutputForTest } from "@ai-gui/plugin-sdk"
+
+const cleanup = mountOutputForTest(output, element, optionalMountContext)
+cleanup()
+cleanup() // harmless; an underlying disposer runs at most once
+```
+
+## Exports
+
+- Core authoring types: `AIGuiPlugin`, `ASTNode`, `CardDef`, `CollectNodeRendererOptions`, `JSONSchema`, `NodeRenderer`, `PluginCommitContext`, `RenderOutput`.
+- Core helpers: `collectNodeRenderers`, `pluginNodeTypes`.
+- SDK helpers: `definePlugin`, `createTestNode`, `getPluginRenderer`, `renderPluginNode`, `mountOutputForTest`.

package/dist/index.cjs

@@ -0,0 +1,80 @@
+"use strict";
+//#region rolldown:runtime
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+	if (from && typeof from === "object" || typeof from === "function") for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
+		key = keys[i];
+		if (!__hasOwnProp.call(to, key) && key !== except) __defProp(to, key, {
+			get: ((k) => from[k]).bind(null, key),
+			enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+		});
+	}
+	return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", {
+	value: mod,
+	enumerable: true
+}) : target, mod));
+
+//#endregion
+const __ai_gui_core = __toESM(require("@ai-gui/core"));
+
+//#region src/index.ts
+/** Define a plugin while preserving the concrete type of its configuration. */
+function definePlugin(plugin) {
+	return plugin;
+}
+/** Create a complete plugin node with deterministic defaults for tests. */
+function createTestNode(type, overrides = {}) {
+	return {
+		key: `test:${type}`,
+		type,
+		complete: true,
+		...overrides
+	};
+}
+/** Return a plugin renderer or throw when the node type is not registered. */
+function getPluginRenderer(plugin, nodeType) {
+	const renderer = plugin.nodeRenderers?.[nodeType];
+	if (!renderer) throw new Error(`Plugin "${plugin.name}" does not define a renderer for node type "${nodeType}".`);
+	return renderer;
+}
+/** Render a node through its plugin renderer and normalize sync output to a promise. */
+async function renderPluginNode(plugin, node) {
+	return getPluginRenderer(plugin, node.type)(node);
+}
+/** Mount a mount output into a supplied element and return an idempotent cleanup. */
+function mountOutputForTest(output, element, context = {}) {
+	if (output.kind !== "mount") throw new Error(`Expected a "mount" render output, received "${output.kind}".`);
+	const dispose = output.mount(element, context);
+	let cleaned = false;
+	return () => {
+		if (cleaned) return;
+		cleaned = true;
+		dispose?.();
+	};
+}
+
+//#endregion
+Object.defineProperty(exports, 'collectNodeRenderers', {
+  enumerable: true,
+  get: function () {
+    return __ai_gui_core.collectNodeRenderers;
+  }
+});
+exports.createTestNode = createTestNode
+exports.definePlugin = definePlugin
+exports.getPluginRenderer = getPluginRenderer
+exports.mountOutputForTest = mountOutputForTest
+Object.defineProperty(exports, 'pluginNodeTypes', {
+  enumerable: true,
+  get: function () {
+    return __ai_gui_core.pluginNodeTypes;
+  }
+});
+exports.renderPluginNode = renderPluginNode

package/dist/index.d.cts

@@ -0,0 +1,17 @@
+import { AIGuiPlugin, AIGuiPlugin as AIGuiPlugin$1, ASTNode, ASTNode as ASTNode$1, CardDef, CollectNodeRendererOptions, JSONSchema, MountCardSlotRequest, MountedCardSlot, NodeRenderer, NodeRenderer as NodeRenderer$1, PluginCommitContext, RenderMountContext, RenderMountContext as RenderMountContext$1, RenderOutput, RenderOutput as RenderOutput$1, collectNodeRenderers, pluginNodeTypes } from "@ai-gui/core";
+
+//#region src/index.d.ts
+/** Define a plugin while preserving the concrete type of its configuration. */
+/** Define a plugin while preserving the concrete type of its configuration. */
+declare function definePlugin<const TPlugin extends AIGuiPlugin$1>(plugin: TPlugin): TPlugin;
+/** Create a complete plugin node with deterministic defaults for tests. */
+declare function createTestNode(type: string, overrides?: Omit<Partial<ASTNode$1>, "type">): ASTNode$1;
+/** Return a plugin renderer or throw when the node type is not registered. */
+declare function getPluginRenderer(plugin: AIGuiPlugin$1, nodeType: string): NodeRenderer$1;
+/** Render a node through its plugin renderer and normalize sync output to a promise. */
+declare function renderPluginNode(plugin: AIGuiPlugin$1, node: ASTNode$1): Promise<RenderOutput$1>;
+/** Mount a mount output into a supplied element and return an idempotent cleanup. */
+declare function mountOutputForTest(output: RenderOutput$1, element: HTMLElement, context?: RenderMountContext$1): () => void;
+
+//#endregion
+export { AIGuiPlugin, ASTNode, CardDef, CollectNodeRendererOptions, JSONSchema, MountCardSlotRequest, MountedCardSlot, NodeRenderer, PluginCommitContext, RenderMountContext, RenderOutput, collectNodeRenderers, createTestNode, definePlugin, getPluginRenderer, mountOutputForTest, pluginNodeTypes, renderPluginNode };

package/dist/index.d.ts

@@ -0,0 +1,17 @@
+import { AIGuiPlugin, AIGuiPlugin as AIGuiPlugin$1, ASTNode, ASTNode as ASTNode$1, CardDef, CollectNodeRendererOptions, JSONSchema, MountCardSlotRequest, MountedCardSlot, NodeRenderer, NodeRenderer as NodeRenderer$1, PluginCommitContext, RenderMountContext, RenderMountContext as RenderMountContext$1, RenderOutput, RenderOutput as RenderOutput$1, collectNodeRenderers, pluginNodeTypes } from "@ai-gui/core";
+
+//#region src/index.d.ts
+/** Define a plugin while preserving the concrete type of its configuration. */
+/** Define a plugin while preserving the concrete type of its configuration. */
+declare function definePlugin<const TPlugin extends AIGuiPlugin$1>(plugin: TPlugin): TPlugin;
+/** Create a complete plugin node with deterministic defaults for tests. */
+declare function createTestNode(type: string, overrides?: Omit<Partial<ASTNode$1>, "type">): ASTNode$1;
+/** Return a plugin renderer or throw when the node type is not registered. */
+declare function getPluginRenderer(plugin: AIGuiPlugin$1, nodeType: string): NodeRenderer$1;
+/** Render a node through its plugin renderer and normalize sync output to a promise. */
+declare function renderPluginNode(plugin: AIGuiPlugin$1, node: ASTNode$1): Promise<RenderOutput$1>;
+/** Mount a mount output into a supplied element and return an idempotent cleanup. */
+declare function mountOutputForTest(output: RenderOutput$1, element: HTMLElement, context?: RenderMountContext$1): () => void;
+
+//#endregion
+export { AIGuiPlugin, ASTNode, CardDef, CollectNodeRendererOptions, JSONSchema, MountCardSlotRequest, MountedCardSlot, NodeRenderer, PluginCommitContext, RenderMountContext, RenderOutput, collectNodeRenderers, createTestNode, definePlugin, getPluginRenderer, mountOutputForTest, pluginNodeTypes, renderPluginNode };

package/dist/index.js

@@ -0,0 +1,40 @@
+import { collectNodeRenderers, pluginNodeTypes } from "@ai-gui/core";
+
+//#region src/index.ts
+/** Define a plugin while preserving the concrete type of its configuration. */
+function definePlugin(plugin) {
+	return plugin;
+}
+/** Create a complete plugin node with deterministic defaults for tests. */
+function createTestNode(type, overrides = {}) {
+	return {
+		key: `test:${type}`,
+		type,
+		complete: true,
+		...overrides
+	};
+}
+/** Return a plugin renderer or throw when the node type is not registered. */
+function getPluginRenderer(plugin, nodeType) {
+	const renderer = plugin.nodeRenderers?.[nodeType];
+	if (!renderer) throw new Error(`Plugin "${plugin.name}" does not define a renderer for node type "${nodeType}".`);
+	return renderer;
+}
+/** Render a node through its plugin renderer and normalize sync output to a promise. */
+async function renderPluginNode(plugin, node) {
+	return getPluginRenderer(plugin, node.type)(node);
+}
+/** Mount a mount output into a supplied element and return an idempotent cleanup. */
+function mountOutputForTest(output, element, context = {}) {
+	if (output.kind !== "mount") throw new Error(`Expected a "mount" render output, received "${output.kind}".`);
+	const dispose = output.mount(element, context);
+	let cleaned = false;
+	return () => {
+		if (cleaned) return;
+		cleaned = true;
+		dispose?.();
+	};
+}
+
+//#endregion
+export { collectNodeRenderers, createTestNode, definePlugin, getPluginRenderer, mountOutputForTest, pluginNodeTypes, renderPluginNode };

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@ai-gui/plugin-sdk",
+  "version": "0.4.0",
+  "description": "Minimal plugin authoring and testing helpers for AIGUI.",
+  "keywords": [
+    "llm",
+    "ai",
+    "streaming",
+    "plugin",
+    "testing",
+    "sdk",
+    "aigui"
+  ],
+  "license": "MIT",
+  "author": "Liang Li <ll_faw@hotmail.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/liliang-cn/aigui.git",
+    "directory": "packages/plugin-sdk"
+  },
+  "homepage": "https://github.com/liliang-cn/aigui#readme",
+  "bugs": "https://github.com/liliang-cn/aigui/issues",
+  "type": "module",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18"
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@ai-gui/core": "0.4.0"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "test": "pnpm --dir ../.. exec vitest run --project plugin-sdk",
+    "typecheck": "tsc --noEmit"
+  }
+}