@ai-slot/registry 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 iannil
+
+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,49 @@
+# @ai-slot/registry
+
+AI output protocol for [ai-slot-component](https://github.com/iannil/ai-slot-component#readme): declare the components a model may use, validate its component trees, and derive skeleton frames.
+
+The model never writes HTML — it returns component-tree JSON whose component names must exist in your registry, validated against prop schemas, slot rules, depth and node-count limits before anything renders.
+
+## Install
+
+```bash
+npm install @ai-slot/registry
+```
+
+## Usage
+
+```ts
+import { defineRegistry, validateComponentTree, deriveSkeleton } from "@ai-slot/registry";
+
+// 1. Declare what the model is allowed to output
+const registry = defineRegistry({
+  components: {
+    Banner: {
+      description: "A hero banner",
+      props: { title: "string", emphasis: "boolean" },
+      required: ["title"],
+      slots: ["default"],
+    },
+  },
+});
+
+// 2. Validate an untrusted model response (in the proxy AND again in the client)
+const result = validateComponentTree(registry, modelOutput, { maxDepth: 8, maxNodes: 64 });
+if (!result.ok) {
+  // fall back to the original content — never render unvalidated output
+}
+
+// 3. Derive a skeleton frame from a final tree (for SSE streaming)
+const skeleton = deriveSkeleton(tree);
+```
+
+Consumed by the proxy, the client runtime and build tooling — one shared contract, validated on both ends.
+
+## Docs
+
+- [Root README](https://github.com/iannil/ai-slot-component#readme)
+- [Design spec](https://github.com/iannil/ai-slot-component/blob/master/docs/superpowers/specs/2026-09-24-ai-native-rendering-sdk-design.md)
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,91 @@
+/** AI 输出协议与组件注册表的核心类型。 */
+type PropType = "string" | "number" | "boolean" | "object" | "array";
+interface PropSchema {
+    type: PropType;
+    /** string：最大长度 */
+    maxLength?: number;
+    /** array：最大元素数 */
+    maxItems?: number;
+    enum?: readonly (string | number | boolean)[];
+    /** object：嵌套属性（允许字符串简写，defineRegistry 会规范化） */
+    props?: Record<string, PropSchemaInput>;
+    /** array：元素 Schema */
+    items?: PropSchemaInput;
+    required?: boolean;
+}
+/** 注册表输入侧的 props 写法：完整 Schema 或 "string" 之类的简写。 */
+type PropSchemaInput = PropType | PropSchema;
+interface ComponentDefInput {
+    description: string;
+    props?: Record<string, PropSchemaInput>;
+    required?: string[];
+    /** 允许的槽位名；"default" 对应组件树的 children 字段 */
+    slots?: string[];
+    dataSources?: string[];
+}
+interface ComponentDef {
+    description: string;
+    props: Record<string, PropSchema>;
+    required: string[];
+    slots: string[];
+    dataSources: string[];
+}
+interface Registry {
+    components: Record<string, ComponentDef>;
+}
+/** AI 输出的组件树节点。 */
+interface ComponentNode {
+    component: string;
+    props?: Record<string, unknown>;
+    /** 默认槽位（要求组件声明 slots 含 "default"） */
+    children?: ComponentNode[];
+    /** 命名槽位（槽位名必须在组件声明的 slots 内） */
+    slots?: Record<string, ComponentNode[]>;
+}
+/** 代理返回给客户端的响应协议。 */
+interface AiRenderResponse {
+    version: 1;
+    slot: string;
+    tree: ComponentNode;
+    meta?: Record<string, unknown>;
+}
+
+/** 开发者声明「AI 可用的积木清单」。输入允许字符串简写，输出为规范化后的注册表。 */
+declare function defineRegistry(input: {
+    components: Record<string, ComponentDefInput>;
+}): Registry;
+
+interface ValidatorOptions {
+    /** 嵌套深度上限，默认 5 */
+    maxDepth?: number;
+    /** 节点总数上限，默认 50 */
+    maxNodes?: number;
+    /** 字符串 prop 全局上限（与 schema maxLength 取较严者），默认 10_000 */
+    maxStringLength?: number;
+    /** 数组 prop 全局上限（与 schema maxItems 取较严者），默认 200 */
+    maxArrayItems?: number;
+}
+interface ValidationError {
+    path: string;
+    rule: "structure" | "unknown-component" | "props" | "slot" | "depth" | "nodes";
+    message: string;
+}
+type ValidationResult = {
+    ok: true;
+} | {
+    ok: false;
+    errors: ValidationError[];
+};
+/**
+ * OutputValidator：AI 输出永远被视为不可信输入。
+ * 纯函数，第一个错误即停（fail-fast）。
+ */
+declare function validateComponentTree(registry: Registry, tree: unknown, options?: ValidatorOptions): ValidationResult;
+
+/**
+ * 派生组件骨架：结构确定、文本占位（所有字符串置空）。
+ * 用于 SSE 流式渲染的第一帧；纯函数，不修改入参。
+ */
+declare function deriveSkeleton(node: ComponentNode): ComponentNode;
+
+export { type AiRenderResponse, type ComponentDef, type ComponentDefInput, type ComponentNode, type PropSchema, type PropSchemaInput, type PropType, type Registry, type ValidationError, type ValidationResult, type ValidatorOptions, defineRegistry, deriveSkeleton, validateComponentTree };

package/dist/index.js

@@ -0,0 +1,180 @@
+// src/define-registry.ts
+function defineRegistry(input) {
+  const components = {};
+  for (const [name, def] of Object.entries(input.components)) {
+    components[name] = {
+      description: def.description,
+      props: normalizeProps(def.props ?? {}),
+      required: def.required ?? [],
+      slots: def.slots ?? [],
+      dataSources: def.dataSources ?? []
+    };
+  }
+  return { components };
+}
+function normalizeProps(props) {
+  const out = {};
+  for (const [key, schema] of Object.entries(props)) {
+    out[key] = normalizeSchema(schema);
+  }
+  return out;
+}
+function normalizeSchema(schema) {
+  if (typeof schema === "string") return { type: schema };
+  const out = { ...schema };
+  if (schema.props) out.props = normalizeProps(schema.props);
+  if (schema.items) out.items = normalizeSchema(schema.items);
+  return out;
+}
+
+// src/validator.ts
+function validateComponentTree(registry, tree, options = {}) {
+  const maxDepth = options.maxDepth ?? 5;
+  const maxNodes = options.maxNodes ?? 50;
+  const maxStringLength = options.maxStringLength ?? 1e4;
+  const maxArrayItems = options.maxArrayItems ?? 200;
+  const errors = [];
+  let nodeCount = 0;
+  const fail = (path, rule, message) => {
+    errors.push({ path, rule, message });
+  };
+  function visit(node, path, depth) {
+    if (errors.length > 0) return;
+    if (depth > maxDepth) return fail(path, "depth", `\u5D4C\u5957\u6DF1\u5EA6\u8D85\u8FC7\u4E0A\u9650 ${maxDepth}`);
+    nodeCount += 1;
+    if (nodeCount > maxNodes) return fail(path, "nodes", `\u8282\u70B9\u603B\u6570\u8D85\u8FC7\u4E0A\u9650 ${maxNodes}`);
+    if (typeof node !== "object" || node === null || Array.isArray(node)) {
+      return fail(path, "structure", "\u8282\u70B9\u5FC5\u987B\u662F\u5BF9\u8C61");
+    }
+    const n = node;
+    if (typeof n.component !== "string") {
+      return fail(path, "structure", "\u8282\u70B9\u7F3A\u5C11 component \u5B57\u6BB5");
+    }
+    if (!Object.hasOwn(registry.components, n.component)) {
+      return fail(path, "unknown-component", `\u7EC4\u4EF6\u672A\u6CE8\u518C: ${n.component}`);
+    }
+    const def = registry.components[n.component];
+    if (n.props !== void 0) {
+      validateProps(def.props, def.required, n.props, `${path}.props`);
+      if (errors.length > 0) return;
+    }
+    if (n.children !== void 0) {
+      if (!def.slots.includes("default")) {
+        return fail(path, "slot", `\u7EC4\u4EF6 ${n.component} \u4E0D\u5141\u8BB8 children`);
+      }
+      if (!Array.isArray(n.children)) return fail(path, "structure", "children \u5FC5\u987B\u662F\u6570\u7EC4");
+      for (let i = 0; i < n.children.length; i++) visit(n.children[i], `${path}.children[${i}]`, depth + 1);
+    }
+    if (errors.length > 0) return;
+    if (n.slots !== void 0) {
+      if (typeof n.slots !== "object" || n.slots === null || Array.isArray(n.slots)) {
+        return fail(path, "structure", "slots \u5FC5\u987B\u662F\u5BF9\u8C61");
+      }
+      for (const [slotName, nodes] of Object.entries(n.slots)) {
+        if (!def.slots.includes(slotName)) {
+          return fail(path, "slot", `\u7EC4\u4EF6 ${n.component} \u4E0D\u652F\u6301\u69FD\u4F4D ${slotName}`);
+        }
+        if (!Array.isArray(nodes)) return fail(path, "structure", `\u69FD\u4F4D ${slotName} \u5FC5\u987B\u662F\u6570\u7EC4`);
+        for (let i = 0; i < nodes.length; i++) visit(nodes[i], `${path}.slots.${slotName}[${i}]`, depth + 1);
+        if (errors.length > 0) return;
+      }
+    }
+  }
+  function validateProps(schemas, required, value, path) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+      return fail(path, "props", "props \u5FC5\u987B\u662F\u5BF9\u8C61");
+    }
+    const props = value;
+    for (const key of required) {
+      if (!(key in props)) return fail(`${path}.${key}`, "props", `\u7F3A\u5C11\u5FC5\u586B prop: ${key}`);
+    }
+    for (const [key, v] of Object.entries(props)) {
+      const schema = Object.hasOwn(schemas, key) ? schemas[key] : void 0;
+      if (!schema) return fail(`${path}.${key}`, "props", `\u672A\u58F0\u660E\u7684 prop: ${key}`);
+      validateValue(schema, v, `${path}.${key}`);
+      if (errors.length > 0) return;
+    }
+  }
+  function validateValue(schema, value, path) {
+    switch (schema.type) {
+      case "string": {
+        if (typeof value !== "string") return fail(path, "props", "\u671F\u671B string");
+        const cap = Math.min(schema.maxLength ?? maxStringLength, maxStringLength);
+        if (value.length > cap) {
+          return fail(path, "props", `\u8D85\u8FC7\u957F\u5EA6\u4E0A\u9650 ${cap}`);
+        }
+        if (schema.enum && !schema.enum.includes(value)) return fail(path, "props", "\u4E0D\u5728\u679A\u4E3E\u8303\u56F4\u5185");
+        return;
+      }
+      case "number": {
+        if (typeof value !== "number" || !Number.isFinite(value)) return fail(path, "props", "\u671F\u671B number");
+        if (schema.enum && !schema.enum.includes(value)) return fail(path, "props", "\u4E0D\u5728\u679A\u4E3E\u8303\u56F4\u5185");
+        return;
+      }
+      case "boolean": {
+        if (typeof value !== "boolean") return fail(path, "props", "\u671F\u671B boolean");
+        if (schema.enum && !schema.enum.includes(value)) return fail(path, "props", "\u4E0D\u5728\u679A\u4E3E\u8303\u56F4\u5185");
+        return;
+      }
+      case "object": {
+        if (typeof value !== "object" || value === null || Array.isArray(value)) {
+          return fail(path, "props", "\u671F\u671B object");
+        }
+        if (schema.props) {
+          const nestedRequired = Object.entries(schema.props).filter(([, s]) => typeof s === "object" && s.required === true).map(([key]) => key);
+          validateProps(schema.props, nestedRequired, value, path);
+        }
+        return;
+      }
+      case "array": {
+        if (!Array.isArray(value)) return fail(path, "props", "\u671F\u671B array");
+        const cap = Math.min(schema.maxItems ?? maxArrayItems, maxArrayItems);
+        if (value.length > cap) {
+          return fail(path, "props", `\u8D85\u8FC7\u5143\u7D20\u6570\u4E0A\u9650 ${cap}`);
+        }
+        if (schema.items) {
+          for (let i = 0; i < value.length; i++) {
+            validateValue(schema.items, value[i], `${path}[${i}]`);
+            if (errors.length > 0) return;
+          }
+        }
+        return;
+      }
+      default: {
+        return fail(path, "props", "\u672A\u77E5\u7684 schema \u7C7B\u578B");
+      }
+    }
+  }
+  visit(tree, "tree", 1);
+  return errors.length === 0 ? { ok: true } : { ok: false, errors };
+}
+
+// src/skeleton.ts
+function deriveSkeleton(node) {
+  const out = { component: node.component };
+  if (node.props !== void 0) out.props = blankStrings(node.props);
+  if (node.children !== void 0) out.children = node.children.map(deriveSkeleton);
+  if (node.slots !== void 0) {
+    const slots = {};
+    for (const [name, nodes] of Object.entries(node.slots)) {
+      slots[name] = nodes.map(deriveSkeleton);
+    }
+    out.slots = slots;
+  }
+  return out;
+}
+function blankStrings(value) {
+  if (typeof value === "string") return "";
+  if (Array.isArray(value)) return value.map(blankStrings);
+  if (typeof value === "object" && value !== null) {
+    const out = {};
+    for (const [k, v] of Object.entries(value)) out[k] = blankStrings(v);
+    return out;
+  }
+  return value;
+}
+export {
+  defineRegistry,
+  deriveSkeleton,
+  validateComponentTree
+};

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@ai-slot/registry",
+  "version": "0.1.0",
+  "license": "MIT",
+  "description": "AI output protocol for ai-slot: registry definition, validated component trees, and skeleton derivation.",
+  "keywords": [
+    "ai",
+    "llm",
+    "registry",
+    "json-schema",
+    "validator",
+    "web-components"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/iannil/ai-slot-component.git",
+    "directory": "packages/registry"
+  },
+  "bugs": "https://github.com/iannil/ai-slot-component/issues",
+  "homepage": "https://github.com/iannil/ai-slot-component/tree/master/packages/registry#readme",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "sideEffects": false,
+  "devDependencies": {
+    "tsup": "^8.3.0",
+    "typescript": "^5.6.0",
+    "vitest": "^2.1.0"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  }
+}