@longzai-intelligence-agent-ui-render/render 0.0.0-stage → 0.0.1

package/README.md

@@ -1,3 +1,11 @@
-# Temporary Holding Version
+# @longzai-intelligence-agent-ui-render/render
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+渲染端口包。承载 `RendererPort` 与流编译器端口、`SpecStreamCompiler` 与表达式与可见性与 watch 三类求值器、json-render 适配器与注册表构建器、`createRendererPort` 与 `createRendererCapability` 装配工厂，保留 headless 与带注册表两形态。
+
+## 导出面
+
+- 端口：`RendererPort`、`SpecStreamCompilerPort` 及注入令牌
+- 纯逻辑件：`SpecStreamCompiler`、`ExpressionEvaluator`、`VisibilityEvaluator`、`WatchEvaluator`
+- 基础设施件：`createJsonRenderAdapter`、`RegistryBuilder`、`Registry`
+- 装配工厂：`createRendererPort`、`createRendererCapability`
+- 错误面：`RendererError`、`SpecValidationError`、`UnknownComponentError`

package/dist/index.d.ts

@@ -0,0 +1,608 @@
+import { DomainError } from "@longzai-intelligence-error/core";
+import { Catalog, Spec, SpecStreamPatch } from "@longzai-intelligence-agent-ui-render/core";
+import { ComponentType } from "react";
+/**
+ * The result of a render operation.
+ *
+ * Either carries the serialized HTML output of the rendered Spec tree,
+ * or an error message describing why rendering failed.
+ */
+type RenderResult = {
+  /**
+   * The serialized HTML output of the rendered tree (present on success).
+   */
+  html?: string;
+  /**
+   * The error message (present on failure).
+   */
+  error?: string;
+};
+/**
+ * Options for a single-shot render operation.
+ *
+ * The renderer takes a fully-assembled Spec plus optional initial state
+ * and an optional Catalog snapshot, and produces a RenderResult.
+ */
+type RenderOptions = {
+  /**
+   * The fully-assembled Spec tree to render.
+   */
+  spec: Spec;
+  /**
+   * Optional initial state values merged on top of the Spec's state.
+   */
+  state?: Record<string, unknown>;
+  /**
+   * Optional Catalog snapshot used for component whitelist resolution.
+   */
+  catalog?: Catalog;
+};
+/**
+ * Options for a streaming render operation.
+ *
+ * The renderer consumes a sequence of SpecStreamPatch values, progressively
+ * building the Spec tree, and yields the intermediate Spec after each patch
+ * is applied. This enables progressive rendering of AI-generated UIs.
+ */
+type StreamRenderOptions = {
+  /**
+   * The sequence of SpecStreamPatch values to apply.
+   */
+  patches: SpecStreamPatch[];
+  /**
+   * Optional initial state values merged into the initial Spec state.
+   */
+  initialState?: Record<string, unknown>;
+};
+/**
+ * Renderer domain service interface (Port).
+ *
+ * Defines the standard operations for the rendering runtime:
+ * single-shot rendering of a fully-assembled Spec, and progressive
+ * streaming render of SpecStream patches.
+ *
+ * **Architecture**:
+ *
+ * - Defined in the Contract package, consumed by Implementation and external packages.
+ * - The Implementation package provides the SpecStreamCompiler and expression evaluators.
+ * - The Infrastructure package provides the concrete json-render adapter implementation.
+ */
+type RendererPort = {
+  /**
+   * Render a fully-assembled Spec tree.
+   *
+   * @param options - Render options (spec + optional state and catalog)
+   * @returns The render result (HTML output or error message)
+   */
+  render(options: RenderOptions): Promise<RenderResult>;
+  /**
+   * Progressively render a stream of SpecStream patches.
+   *
+   * Yields the intermediate Spec after each patch is applied,
+   * enabling progressive rendering of AI-generated UIs.
+   *
+   * @param options - Stream render options (patches + optional initial state)
+   * @returns An async generator yielding the intermediate Spec after each patch
+   */
+  renderStream(options: StreamRenderOptions): AsyncGenerator<Spec, void, unknown>;
+};
+/**
+ * RendererPort dependency injection token.
+ */
+declare const RENDERER_PORT_TOKEN: unique symbol;
+/**
+ * 流编译器端口
+ *
+ * @remarks
+ *   以无状态方式把补丁序列应用到初始 Spec，返回渐进装配后的 Spec 树
+ */
+type SpecStreamCompilerPort = {
+  /**
+   * 编译一段补丁序列为 Spec 树
+   *
+   * @param patches - 待应用的 SpecStream 补丁序列
+   * @param initialSpec - 可选的初始 Spec，缺省为空 Spec
+   * @returns 装配完成的 Spec 树
+   */
+  compile(patches: SpecStreamPatch[], initialSpec?: Spec): Spec;
+};
+/**
+ * 流编译器端口依赖注入令牌
+ */
+declare const SPEC_STREAM_COMPILER_TOKEN: unique symbol;
+/**
+ * Generic renderer error.
+ *
+ * Thrown when a rendering operation fails for a reason not covered by
+ * the more specific error subclasses (e.g. an unexpected exception
+ * during expression evaluation or component rendering).
+ */
+declare class RendererError extends DomainError {
+  /**
+   * Create a RendererError instance.
+   *
+   * @param message - The error message describing the failure
+   */
+  constructor(message: string);
+}
+/**
+ * Spec validation error.
+ *
+ * Thrown when a Spec or SpecStreamPatch fails schema validation
+ * (e.g. missing root element, unknown patch operation, malformed
+ * element definition).
+ */
+declare class SpecValidationError extends DomainError {
+  /**
+   * The validation error messages.
+   */
+  readonly errors: string[];
+  /**
+   * Create a SpecValidationError instance.
+   *
+   * @param errors - The validation error messages
+   */
+  constructor(errors: string[]);
+}
+/**
+ * Unknown component error.
+ *
+ * Thrown when a Spec element references a component type that is not
+ * present in the Catalog or Registry (i.e. no React implementation is
+ * registered for the component name).
+ */
+declare class UnknownComponentError extends DomainError {
+  /**
+   * The unknown component type name.
+   */
+  readonly componentType: string;
+  /**
+   * Create an UnknownComponentError instance.
+   *
+   * @param componentType - The unknown component type name
+   */
+  constructor(componentType: string);
+}
+/**
+ * SpecStream compiler.
+ *
+ * Applies a sequence of SpecStreamPatch values onto an initial Spec,
+ * producing the progressively-built Spec tree. The compiler is
+ * stateless: each `compile` call returns a fresh result derived from
+ * the supplied initial Spec (or an empty Spec when omitted).
+ */
+declare class SpecStreamCompiler {
+  /**
+   * Compile a sequence of SpecStreamPatch values into a Spec.
+   *
+   * @param patches - The sequence of SpecStreamPatch values to apply
+   * @param initialSpec - Optional initial Spec to apply patches onto
+   * @returns The fully-assembled Spec tree
+   */
+  compile(patches: SpecStreamPatch[], initialSpec?: Spec): Spec;
+  /**
+   * Apply a single SpecStreamPatch onto the working Spec.
+   *
+   * @param spec - The working Spec (mutated in place)
+   * @param patch - The patch to apply
+   * @throws {@link SpecValidationError} The patch operation is unknown
+   */
+  private applyPatch;
+  /**
+   * Parse a JSON-pointer-like path into decoded segments.
+   *
+   * @param path - The JSON-pointer-like path (e.g. "/elements/btn1/props/label")
+   * @returns The decoded path segments (e.g. ["elements", "btn1", "props", "label"])
+   * @throws {@link SpecValidationError} A path segment is malformed
+   */
+  private parsePath;
+  /**
+   * Apply an `add` patch.
+   *
+   * Creates a new element or nested field. When targeting `/elements/<id>`,
+   * the value is treated as a full SpecElement. When targeting `/root`,
+   * the value is the root element id string. When targeting `/state`,
+   * the value is the initial state object.
+   *
+   * @param spec - The working Spec (mutated in place)
+   * @param segments - The decoded path segments
+   * @param value - The patch payload value
+   * @throws {@link SpecValidationError} The add target is invalid
+   */
+  private applyAdd;
+  /**
+   * Add an element or a nested field on an existing element.
+   *
+   * @param spec - The working Spec (mutated in place)
+   * @param rest - The path segments after "/elements"
+   * @param value - The patch payload value
+   * @throws {@link SpecValidationError} The element target or value is invalid
+   */
+  private addElement;
+  /**
+   * Add a state field (or nested state path).
+   *
+   * @param spec - The working Spec (mutated in place)
+   * @param rest - The path segments after "/state"
+   * @param value - The patch payload value
+   * @throws {@link SpecValidationError} The state value is not an object
+   */
+  private addStateField;
+  /**
+   * Apply an `update` patch.
+   *
+   * Replaces a field value in place. Behaves like `replace` but is
+   * conventionally used for partial field updates.
+   *
+   * @param spec - The working Spec (mutated in place)
+   * @param segments - The decoded path segments
+   * @param value - The patch payload value
+   * @throws {@link SpecValidationError} Delegated to applyReplace when the target is invalid
+   */
+  private applyUpdate;
+  /**
+   * Apply a `remove` patch.
+   *
+   * Deletes an element or nested field.
+   *
+   * @param spec - The working Spec (mutated in place)
+   * @param segments - The decoded path segments
+   * @throws {@link SpecValidationError} The remove target is invalid
+   */
+  private applyRemove;
+  /**
+   * Apply a `replace` patch.
+   *
+   * Wholesale replaces an element or subtree.
+   *
+   * @param spec - The working Spec (mutated in place)
+   * @param segments - The decoded path segments
+   * @param value - The patch payload value
+   * @throws {@link SpecValidationError} The replace target or value is invalid
+   */
+  private applyReplace;
+  /**
+   * Set a nested field on a SpecElement (e.g. props.label, children).
+   *
+   * @param element - The element to mutate
+   * @param segments - The path segments relative to the element
+   * @param value - The value to set
+   * @throws {@link SpecValidationError} The field path is invalid
+   */
+  private setNestedField;
+  /**
+   * Remove a nested field on a SpecElement.
+   *
+   * @param element - The element to mutate
+   * @param segments - The path segments relative to the element
+   * @throws {@link SpecValidationError} The field path is invalid
+   */
+  private removeNestedField;
+  /**
+   * Set a nested field on a plain record, creating intermediate objects
+   * as needed.
+   *
+   * @param record - The record to mutate
+   * @param segments - The path segments
+   * @param value - The value to set
+   */
+  private setNestedRecord;
+  /**
+   * Remove a nested field from a plain record.
+   *
+   * @param record - The record to mutate
+   * @param segments - The path segments
+   */
+  private removeNestedRecord;
+  /**
+   * Determine whether a value is a valid SpecElement.
+   *
+   * @param value - The value to test
+   * @returns True if the value narrows to SpecElement
+   */
+  private isSpecElement;
+}
+/**
+ * Expression evaluator.
+ *
+ * Evaluates the json-render expression DSL against a state snapshot.
+ * The supported expression directives are:
+ *
+ * - `$state` — read a value from state by dot path
+ * - `$cond` — conditional (if / then / else)
+ * - `$template` — string interpolation with `{{path}}` placeholders
+ * - `$computed` — call a registered function with arguments
+ * - `$bindState` — two-way binding path (returns the binding path string)
+ */
+/**
+ * A registered computed function. Receives the resolved arguments and
+ * the current state, and returns a value of any type.
+ */
+type ComputedFunction = (args: unknown[], state: Record<string, unknown>) => unknown;
+/**
+ * Expression evaluator.
+ *
+ * Recursively walks an expression tree, resolving json-render
+ * directives against the supplied state. Plain objects without a
+ * recognized directive key are walked deeply, so nested expressions
+ * inside props are resolved.
+ */
+declare class ExpressionEvaluator {
+  /**
+   * The registered computed functions, keyed by function name.
+   */
+  private readonly computed;
+  /**
+   * Create an ExpressionEvaluator instance.
+   *
+   * @param computed - Optional map of registered computed functions
+   */
+  constructor(computed?: Map<string, ComputedFunction>);
+  /**
+   * Evaluate an expression against a state snapshot.
+   *
+   * @param expr - The expression value (any type)
+   * @param state - The current state snapshot
+   * @returns The resolved value
+   */
+  evaluateExpression(expr: unknown, state: Record<string, unknown>): unknown;
+  /**
+   * Evaluate a `$state` directive.
+   *
+   * Reads a value from state by dot path. A non-string operand is
+   * returned as-is.
+   *
+   * @param operand - The directive operand (a dot path string)
+   * @param state - The current state snapshot
+   * @returns The state value at the path, or undefined if not found
+   */
+  private evaluateState;
+  /**
+   * Evaluate a `$cond` directive.
+   *
+   * Expects an operand with `if`, `then`, and optional `else` fields.
+   * The `if` condition is evaluated as a boolean; truthy yields `then`,
+   * otherwise `else` (or undefined when `else` is omitted).
+   *
+   * @param operand - The directive operand
+   * @param state - The current state snapshot
+   * @returns The resolved branch value
+   */
+  private evaluateCond;
+  /**
+   * Evaluate a `$template` directive.
+   *
+   * Interpolates `{{path}}` placeholders in a string with state values
+   * read by dot path.
+   *
+   * @param operand - The template string
+   * @param state - The current state snapshot
+   * @returns The interpolated string
+   */
+  private evaluateTemplate;
+  /**
+   * Evaluate a `$computed` directive.
+   *
+   * Expects an operand with `fn` (the function name) and optional
+   * `args` (an array of expressions to evaluate before calling).
+   *
+   * @param operand - The directive operand
+   * @param state - The current state snapshot
+   * @returns The computed function's return value
+   */
+  private evaluateComputed;
+  /**
+   * Evaluate a `$bindState` directive.
+   *
+   * Returns the binding path string as-is, enabling the renderer to
+   * wire two-way bindings between a component prop and a state path.
+   *
+   * @param operand - The binding path string
+   * @returns The binding path string
+   */
+  private evaluateBindState;
+  /**
+   * Read a value from a record by dot path.
+   *
+   * @param record - The record to read from
+   * @param path - The dot path (e.g. "user.profile.name")
+   * @returns The value at the path, or undefined if not found
+   */
+  private readPath;
+  /**
+   * Determine whether a value is truthy for $cond evaluation.
+   *
+   * @param value - The value to test
+   * @returns True if the value is truthy
+   */
+  private isTruthy;
+}
+/**
+ * Visibility evaluator.
+ *
+ * Delegates expression resolution to the {@link ExpressionEvaluator}
+ * and coerces the result to a boolean. A missing `visible` field
+ * means the element is visible.
+ */
+declare class VisibilityEvaluator {
+  /**
+   * The expression evaluator used to resolve expression-typed visible
+   * values.
+   */
+  private readonly expressionEvaluator;
+  /**
+   * Create a VisibilityEvaluator instance.
+   *
+   * @param expressionEvaluator - The expression evaluator to delegate to
+   */
+  constructor(expressionEvaluator: ExpressionEvaluator);
+  /**
+   * Evaluate a `visible` value against a state snapshot.
+   *
+   * @param visible - The visible value (boolean, expression, or undefined)
+   * @param state - The current state snapshot
+   * @returns True if the element should be rendered
+   */
+  evaluate(visible: unknown, state: Record<string, unknown>): boolean;
+  /**
+   * Coerce a resolved value to a boolean for visibility decisions.
+   *
+   * @param value - The resolved value
+   * @returns The boolean coercion
+   */
+  private coerceBoolean;
+}
+/**
+ * Watch evaluator.
+ *
+ * Evaluates the `watch` field of a SpecElement against a state
+ * transition. Each watch entry is keyed by a state path; when the
+ * value at that path changes between the previous and current state
+ * snapshots, the entry's action is emitted.
+ */
+/**
+ * A triggered watch action. Emitted when a watched state path changes
+ * between two state snapshots.
+ */
+type WatchAction = {
+  /**
+   * The action name to invoke.
+   */
+  action: string;
+  /**
+   * The action parameters (carried verbatim from the watch entry).
+   */
+  params: unknown;
+};
+/**
+ * Watch evaluator.
+ *
+ * Iterates over a SpecElement's `watch` map, comparing the previous
+ * and current state values at each watched path. When a change is
+ * detected, the entry's action is added to the emitted list.
+ */
+declare class WatchEvaluator {
+  /**
+   * Evaluate the watch map of a SpecElement.
+   *
+   * @param watch - The watch map (keyed by state path)
+   * @param state - The current state snapshot
+   * @param prevState - The previous state snapshot
+   * @returns The list of triggered actions
+   */
+  evaluateWatches(watch: Record<string, unknown>, state: Record<string, unknown>, prevState: Record<string, unknown>): WatchAction[];
+  /**
+   * Extract an action from a watch entry.
+   *
+   * Accepts either a plain action string, or an object with `action`
+   * and optional `params` fields.
+   *
+   * @param entry - The watch entry value
+   * @returns The extracted action, or null if no action is present
+   */
+  private extractAction;
+  /**
+   * Read a value from a record by dot path.
+   *
+   * @param record - The record to read from
+   * @param path - The dot path (e.g. "form.username")
+   * @returns The value at the path, or undefined if not found
+   */
+  private readPath;
+  /**
+   * Determine whether two values are equal for watch change detection.
+   *
+   * Uses reference equality for objects and arrays, and value equality
+   * for primitives.
+   *
+   * @param a - The previous value
+   * @param b - The current value
+   * @returns True if the values are considered equal
+   */
+  private isEqual;
+}
+/**
+ * A runtime component registry mapping component names to their React
+ * implementations.
+ */
+type Registry = Map<string, ComponentType>;
+/**
+ * Registry builder.
+ *
+ * Walks the Catalog's component map and pairs each entry with the
+ * corresponding React component from the supplied components map.
+ * Components not present in the components map are silently skipped,
+ * enabling partial registration during incremental adoption.
+ */
+declare class RegistryBuilder {
+  /**
+   * Build a Registry from a Catalog and a components map.
+   *
+   * @param catalog - The Catalog whitelist defining component names
+   * @param components - A record of component name → React implementation
+   * @returns The populated Registry
+   */
+  build(catalog: Catalog, components: Record<string, ComponentType>): Registry;
+}
+/**
+ * Options for the json-render adapter factory.
+ */
+type JsonRenderAdapterOptions = {
+  /**
+   * The stream compiler used to progressively build Spec trees from
+   * SpecStreamPatch sequences. Injected via the contract port so the
+   * infrastructure package does not depend on the implementation
+   * package.
+   */
+  compiler: SpecStreamCompilerPort;
+  /**
+   * Optional pre-built component registry. When omitted, the adapter
+   * operates in a headless mode (stream compilation only) and
+   * single-shot render returns a serialized spec representation.
+   */
+  registry?: Registry;
+  /**
+   * Optional components map used for single-shot rendering when no
+   * pre-built registry is supplied.
+   */
+  components?: Record<string, ComponentType>;
+};
+/**
+ * Create a json-render-based RendererPort implementation.
+ *
+ * The adapter wraps @json-render/react's Renderer and Registry. For
+ * single-shot rendering, it validates the Spec, resolves the component
+ * registry, and renders the tree. For streaming rendering, it uses
+ * the injected SpecStreamCompilerPort to progressively build the Spec
+ * and yields each intermediate state.
+ *
+ * @param options - Adapter configuration (compiler + optional registry / components)
+ * @returns A RendererPort implementation
+ */
+declare function createJsonRenderAdapter(options: JsonRenderAdapterOptions): RendererPort;
+/**
+ * renderer 域端口装配配置
+ *
+ * @remarks
+ *   即基础设施适配器配置去掉编译器项，编译器由本工厂注入
+ */
+type RendererPortFactoryOptions = Omit<JsonRenderAdapterOptions, 'compiler'>;
+/**
+ * 创建 renderer 域端口
+ *
+ * @remarks
+ *   以自有 `SpecStreamCompiler` 满足流编译器端口，组件注册面经可选项透传
+ * @param options - 端口装配配置，缺省为无注册表的 headless 形态
+ * @returns renderer 域端口
+ */
+declare function createRendererPort(options?: RendererPortFactoryOptions): RendererPort;
+/**
+ * 创建渲染开箱即用能力
+ *
+ * @remarks
+ *   零配置即得 headless 渲染端口，携组件注册表形态请经 `createRendererPort` 传入注册面配置
+ * @param options - 端口装配配置
+ * @returns 渲染端口
+ */
+declare function createRendererCapability(options?: RendererPortFactoryOptions): RendererPort;
+export { type ComputedFunction, ExpressionEvaluator, type JsonRenderAdapterOptions, RENDERER_PORT_TOKEN, type Registry, RegistryBuilder, type RenderOptions, type RenderResult, RendererError, type RendererPort, type RendererPortFactoryOptions, SPEC_STREAM_COMPILER_TOKEN, SpecStreamCompiler, type SpecStreamCompilerPort, SpecValidationError, type StreamRenderOptions, UnknownComponentError, VisibilityEvaluator, type WatchAction, WatchEvaluator, createJsonRenderAdapter, createRendererCapability, createRendererPort };

package/dist/index.js

@@ -0,0 +1 @@
+import{DomainError as e}from"@longzai-intelligence-error/core";import{SpecSchema as t}from"@longzai-intelligence-agent-ui-render/core";import{ensureError as n}from"@longzai-intelligence-error/utils";const r=Symbol(`RendererPort`),i=Symbol(`SpecStreamCompilerPort`);var a=class extends e{constructor(e){super(e,`RENDERER_ERROR`,{message:e}),this.name=`RendererError`}},o=class extends e{errors;constructor(e){super(`Spec validation failed: ${e.join(`, `)}`,`SPEC_VALIDATION_ERROR`,{errors:e}),this.name=`SpecValidationError`,this.errors=e}},s=class extends e{componentType;constructor(e){super(`Unknown component type: ${e}`,`UNKNOWN_COMPONENT`,{componentType:e}),this.name=`UnknownComponentError`,this.componentType=e}};function c(e){return typeof e==`object`&&!!e&&!Array.isArray(e)}function l(e){return typeof e==`object`&&!!e}const u={root:``,elements:{}};var d=class{compile(e,t){let n={root:t?.root??u.root,elements:{...t?.elements??u.elements},...t?.state===void 0?{}:{state:{...t.state}}};for(let t of e)this.applyPatch(n,t);return n}applyPatch(e,t){let n=this.parsePath(t.path);switch(t.op){case`add`:this.applyAdd(e,n,t.value);break;case`update`:this.applyUpdate(e,n,t.value);break;case`remove`:this.applyRemove(e,n);break;case`replace`:this.applyReplace(e,n,t.value);break;default:throw new o([`Unknown patch operation: ${t.op}`])}}parsePath(e){return e.length===0||e===`/`?[]:(e.startsWith(`/`)?e.slice(1):e).split(`/`).map(e=>e.replace(/~1/g,`/`).replace(/~0/g,`~`))}applyAdd(e,t,n){if(t.length===0)throw new o([`Cannot 'add' the Spec root itself`]);let[r,...i]=t;if(r===`elements`)this.addElement(e,i,n);else if(r===`root`){if(i.length>0)throw new o([`Cannot 'add' nested fields under /root`]);if(typeof n!=`string`)throw new o([`/root value must be a string element id`]);e.root=n}else if(r===`state`)this.addStateField(e,i,n);else throw new o([`Unknown top-level field: ${r}`])}addElement(e,t,n){if(t.length===0)throw new o([`Cannot 'add' to /elements without an element id`]);let[r,...i]=t;if(r===void 0)throw new o([`Cannot 'add' to /elements without an element id`]);if(i.length===0){if(!this.isSpecElement(n))throw new o([`Invalid element value for /elements/${r}`]);e.elements[r]={...n};return}let a=e.elements[r];if(!a)throw new o([`Element not found: ${r}`]);this.setNestedField(a,i,n)}addStateField(e,t,n){if(e.state||={},t.length===0){if(!c(n))throw new o([`/state value must be an object`]);e.state={...n}}else this.setNestedRecord(e.state,t,n)}applyUpdate(e,t,n){this.applyReplace(e,t,n)}applyRemove(e,t){if(t.length===0)throw new o([`Cannot 'remove' the Spec root itself`]);let[n,...r]=t;if(n===`elements`){if(r.length===0)throw new o([`Cannot 'remove' all elements`]);let[t,...n]=r;if(t===void 0)throw new o([`Cannot 'remove' /elements without an element id`]);if(n.length===0){delete e.elements[t],e.root===t&&(e.root=``);return}let i=e.elements[t];if(!i)throw new o([`Element not found: ${t}`]);this.removeNestedField(i,n)}else if(n===`root`)e.root=``;else if(n===`state`){if(!e.state)return;if(r.length===0){delete e.state;return}this.removeNestedRecord(e.state,r)}else throw new o([`Unknown top-level field: ${n}`])}applyReplace(e,t,n){if(t.length===0)throw new o([`Cannot 'replace' the Spec root itself`]);let[r,...i]=t;if(r===`elements`){if(i.length===0)throw new o([`Cannot 'replace' all elements`]);let[t,...r]=i;if(t===void 0)throw new o([`Cannot 'replace' /elements without an element id`]);if(r.length===0){if(!this.isSpecElement(n))throw new o([`Invalid element value for /elements/${t}`]);e.elements[t]={...n};return}let a=e.elements[t];if(!a)throw new o([`Element not found: ${t}`]);this.setNestedField(a,r,n)}else if(r===`root`){if(i.length>0)throw new o([`Cannot 'replace' nested fields under /root`]);if(typeof n!=`string`)throw new o([`/root value must be a string element id`]);e.root=n}else if(r===`state`){if(i.length===0){if(!c(n))throw new o([`/state value must be an object`]);e.state={...n};return}e.state||={},this.setNestedRecord(e.state,i,n)}else throw new o([`Unknown top-level field: ${r}`])}setNestedField(e,t,n){let[r,...i]=t;if(r===`props`){if(e.props||={},i.length===0){if(!c(n))throw new o([`/props value must be an object`]);e.props={...n};return}this.setNestedRecord(e.props,i,n)}else if(r===`children`){if(i.length>0)throw new o([`Cannot set nested fields under /children`]);if(!Array.isArray(n))throw new o([`/children value must be an array`]);e.children=[...n]}else if(r===`visible`){if(i.length>0)throw new o([`Cannot set nested fields under /visible`]);e.visible=n}else if(r===`watch`){if(e.watch||={},i.length===0){if(!c(n))throw new o([`/watch value must be an object`]);e.watch={...n};return}this.setNestedRecord(e.watch,i,n)}else if(r===`type`){if(i.length>0)throw new o([`Cannot set nested fields under /type`]);if(typeof n!=`string`)throw new o([`/type value must be a string`]);e.type=n}else if(r===`id`){if(i.length>0)throw new o([`Cannot set nested fields under /id`]);if(typeof n!=`string`)throw new o([`/id value must be a string`]);e.id=n}else throw new o([`Unknown element field: ${r}`])}removeNestedField(e,t){let[n,...r]=t;if(n===`props`){if(!e.props)return;if(r.length===0){delete e.props;return}this.removeNestedRecord(e.props,r)}else if(n===`children`)delete e.children;else if(n===`visible`)delete e.visible;else if(n===`watch`){if(!e.watch)return;if(r.length===0){delete e.watch;return}this.removeNestedRecord(e.watch,r)}else throw n===`type`||n===`id`?new o([`Cannot remove required field: ${n}`]):new o([`Unknown element field: ${n}`])}setNestedRecord(e,t,n){let r=t.at(-1);if(r===void 0)return;let i=e;for(let e of t.slice(0,-1)){let t=i[e];if(l(t))i=t;else{let t={};i[e]=t,i=t}}i[r]=n}removeNestedRecord(e,t){let n=t.at(-1);if(n===void 0)return;let r=e;for(let e of t.slice(0,-1)){let t=r[e];if(!l(t))return;r=t}delete r[n]}isSpecElement(e){return c(e)?typeof e.id==`string`&&typeof e.type==`string`:!1}};function f(e){return typeof e==`object`&&!!e&&!Array.isArray(e)}function p(e){return typeof e==`object`&&!!e}var m=class{computed;constructor(e=/* @__PURE__ */ new Map){this.computed=e}evaluateExpression(e,t){if(typeof e!=`object`||!e)return e;if(Array.isArray(e))return e.map(e=>this.evaluateExpression(e,t));if(!f(e))return e;let n=e;if(`$state`in n)return this.evaluateState(n.$state,t);if(`$cond`in n)return this.evaluateCond(n.$cond,t);if(`$template`in n)return this.evaluateTemplate(n.$template,t);if(`$computed`in n)return this.evaluateComputed(n.$computed,t);if(`$bindState`in n)return this.evaluateBindState(n.$bindState);let r={};for(let[e,i]of Object.entries(n))r[e]=this.evaluateExpression(i,t);return r}evaluateState(e,t){return typeof e==`string`?this.readPath(t,e):e}evaluateCond(e,t){if(!f(e))return;let n=e,r=this.evaluateExpression(n.if,t);if(this.isTruthy(r))return this.evaluateExpression(n.then,t);if(`else`in n)return this.evaluateExpression(n.else,t)}evaluateTemplate(e,t){return typeof e==`string`?e.replace(/\{\{([^}]+)\}\}/g,(e,n)=>{let r=String(n).trim();if(r.length===0)return e;let i=this.readPath(t,r);return i==null?``:typeof i==`string`?i:String(i)}):e}evaluateComputed(e,t){if(!f(e))return;let n=e,r=n.fn;if(typeof r!=`string`)return;let i=this.computed.get(r);if(i)return i((Array.isArray(n.args)?n.args:[]).map(e=>this.evaluateExpression(e,t)),t)}evaluateBindState(e){return e}readPath(e,t){let n=t.split(`.`),r=e;for(let e of n){if(!p(r))return;r=r[e]}return r}isTruthy(e){return e==null?!1:typeof e==`boolean`?e:typeof e==`number`?e!==0&&!Number.isNaN(e):typeof e==`string`||Array.isArray(e)?e.length>0:typeof e==`object`&&e?Object.keys(e).length>0:!!e}},h=class{expressionEvaluator;constructor(e){this.expressionEvaluator=e}evaluate(e,t){if(e==null)return!0;if(typeof e==`boolean`)return e;let n=this.expressionEvaluator.evaluateExpression(e,t);return this.coerceBoolean(n)}coerceBoolean(e){return typeof e==`boolean`?e:e==null?!1:typeof e==`number`?e!==0&&!Number.isNaN(e):typeof e==`string`||Array.isArray(e)?e.length>0:typeof e==`object`&&e?Object.keys(e).length>0:!!e}};function g(e){return typeof e==`object`&&!!e&&!Array.isArray(e)}function _(e){return typeof e==`object`&&!!e}var v=class{evaluateWatches(e,t,n){let r=[];for(let[i,a]of Object.entries(e)){let e=this.readPath(n,i),o=this.readPath(t,i);if(!this.isEqual(e,o)){let e=this.extractAction(a);e!==null&&r.push(e)}}return r}extractAction(e){return typeof e==`string`?{action:e,params:void 0}:g(e)&&typeof e.action==`string`?{action:e.action,params:e.params}:null}readPath(e,t){let n=t.split(`.`),r=e;for(let e of n){if(!_(r))return;r=r[e]}return r}isEqual(e,t){return e===t||(e===null||t===null||typeof e==typeof t&&typeof e!=`object`)&&e===t}};function y(e){return typeof e==`object`&&!!e&&!Array.isArray(e)}function b(e){return typeof e==`function`}function x(e){let r=e.compiler;return{async render(r){try{let n=t.safeParse(r.spec);if(!n.success)return{error:`Spec validation failed: ${n.error.message}`};let i=n.data;return{html:await C(i,{...i.state,...r.state},e)}}catch(e){return{error:n(e).message}}},async*renderStream(e){let t={root:``,elements:{},...e.initialState?{state:{...e.initialState}}:{}};for(let n of e.patches)t=S(r,t,n),yield t}}}function S(e,t,n){return e.compile([n],t)}async function C(e,t,n){let r=n.registry,i=n.components;if(!r&&!i)return E(e,t);let a=await w();if(!a)return E(e,t);let{Renderer:o}=await import(`@json-render/react`);return a({type:o,props:{spec:e,state:t,registry:r??T(i??{})}})}async function w(){try{let e=await import(`react-dom/server`);if(y(e)){let t=e.renderToString;if(b(t))return t}return null}catch{return null}}function T(e){let t=/* @__PURE__ */ new Map;for(let[n,r]of Object.entries(e))t.set(n,r);return t}function E(e,t){return`<div data-renderer="headless" data-root="${e.root||`(empty)`}" data-elements="${Object.keys(e.elements).length}" data-state="${JSON.stringify(t)}"></div>`}var D=class{build(e,t){let n=/* @__PURE__ */ new Map;for(let r of Object.keys(e.components)){let e=t[r];e&&n.set(r,e)}return n}};function O(e={}){return x({compiler:new d,...e})}function k(e={}){return O(e)}export{m as ExpressionEvaluator,r as RENDERER_PORT_TOKEN,D as RegistryBuilder,a as RendererError,i as SPEC_STREAM_COMPILER_TOKEN,d as SpecStreamCompiler,o as SpecValidationError,s as UnknownComponentError,h as VisibilityEvaluator,v as WatchEvaluator,x as createJsonRenderAdapter,k as createRendererCapability,O as createRendererPort};

package/package.json

@@ -1,6 +1,58 @@
 {
   "name": "@longzai-intelligence-agent-ui-render/render",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.0.1",
+  "description": "Longzai Intelligence Agent UI 渲染端口与 json-render 适配器包",
+  "keywords": [
+    "adapter",
+    "agent-ui",
+    "longzai-intelligence",
+    "renderer",
+    "spec-stream"
+  ],
+  "license": "UNLICENSED",
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "lzi-builder",
+    "build:prod": "NODE_ENV=production bun run build",
+    "prepublishOnly": "bun run build:prod",
+    "dev": "lzi-builder --watch",
+    "clean": "lzi-dev-tools clean",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "lint": "lzi-lint lint",
+    "lint:fix": "lzi-lint fix",
+    "typecheck": "bun run typecheck:app && bun run typecheck:node && bun run typecheck:test",
+    "typecheck:app": "lzi-tsgo typecheck tsconfig/app.json",
+    "typecheck:node": "lzi-tsgo typecheck tsconfig/node.json",
+    "typecheck:test": "lzi-tsgo typecheck tsconfig/test.json"
+  },
+  "dependencies": {
+    "@json-render/core": "^0.1.0",
+    "@json-render/react": "^0.1.0",
+    "@longzai-intelligence-agent-ui-render/core": "0.0.1",
+    "@longzai-intelligence-error/core": "^0.2.0",
+    "@longzai-intelligence-error/utils": "^0.2.0",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@longzai-intelligence-testing/utils": "^0.0.3",
+    "@longzai-intelligence-vitest/config": "^0.0.12",
+    "@types/react": "^19.2.17",
+    "react": "^19.2.7",
+    "vitest": "^4.1.4"
+  },
+  "peerDependencies": {
+    "react": ">=18.0.0"
+  },
+  "packageManager": "bun@1.4.3"
+}