@zhama/a2ui-core 0.3.0 → 0.5.0

package/README.md

@@ -1,13 +1,17 @@
 # @zhama/a2ui-core
 
-A2UI Protocol Core Library - Framework-agnostic TypeScript types and builders for A2UI protocol.
+A2UI Protocol Core Library - Framework-agnostic TypeScript types and builders for A2UI v0.9 protocol.
+
+> **Note**: This library uses A2UI v0.9 format exclusively. While v0.9 is still in draft status
+> according to [a2ui.org](https://a2ui.org/), it offers a cleaner and more modern API.
 
 ## Overview
 
 A2UI (Agent to UI) is a JSON-based streaming UI protocol for dynamically rendering user interfaces. This library provides:
 
-- **Types**: Complete TypeScript type definitions for A2UI v0.8 and v0.9
+- **Types**: Complete TypeScript type definitions for A2UI v0.9
 - **Builders**: Convenient functions to build messages and components
+- **Surface**: Surface ID constants and creation utilities
 - **Validators**: Message validation utilities
 - **Utils**: Utility functions for path bindings and data manipulation
 
@@ -24,10 +28,13 @@ pnpm add @zhama/a2ui-core
 ```typescript
 import {
   // Builders
-  text, column, button, card,
+  text, column, button, h1,
   createSurface, updateComponents, updateDataModel,
   createV09Messages,
   
+  // Surface
+  SURFACE_IDS, createA2UISurface,
+  
   // Validators
   validateMessage,
   
@@ -36,17 +43,17 @@ import {
   
   // Types
   type ComponentInstance,
-  type ServerToClientMessage,
+  type ServerToClientMessageV09,
 } from '@zhama/a2ui-core';
 
 // Create components
-const title = text('Hello World', { id: 'title', usageHint: 'h1' });
+const title = h1('Hello World', { id: 'title' });
 const greeting = text({ path: '/user/name' }, { id: 'greeting' });
 const root = column(['title', 'greeting'], { id: 'root' });
 
 // Create messages
 const messages = createV09Messages({
-  surfaceId: 'my-surface',
+  surfaceId: SURFACE_IDS.CHAT,
   components: [title, greeting, root],
   dataModel: { user: { name: 'John' } },
 });
@@ -62,7 +69,7 @@ You can import specific modules for tree-shaking:
 
 ```typescript
 // Types only
-import type { ComponentInstance, ServerToClientMessage } from '@zhama/a2ui-core/types';
+import type { ComponentInstance, ServerToClientMessageV09 } from '@zhama/a2ui-core/types';
 
 // Builders only
 import { text, column, createV09Messages } from '@zhama/a2ui-core/builders';
@@ -72,35 +79,15 @@ import { validateMessage, validateMessages } from '@zhama/a2ui-core/validators';
 
 // Utils only
 import { path, uuid, deepMerge } from '@zhama/a2ui-core/utils';
+
+// Surface utilities
+import { SURFACE_IDS, createA2UISurface, createChatSurface } from '@zhama/a2ui-core/surface';
 ```
 
 ## API Reference
 
-### Types
-
-#### Primitives
-- `StringOrPath` - String literal or data path binding
-- `NumberOrPath` - Number literal or data path binding
-- `BooleanOrPath` - Boolean literal or data path binding
-- `StringArrayOrPath` - String array literal or data path binding
-
-#### Components (18 standard components)
-**Content**: `TextComponent`, `ImageComponent`, `IconComponent`, `VideoComponent`, `AudioPlayerComponent`
-**Layout**: `RowComponent`, `ColumnComponent`, `ListComponent`, `CardComponent`, `TabsComponent`, `DividerComponent`, `ModalComponent`
-**Interactive**: `ButtonComponent`, `CheckBoxComponent`, `TextFieldComponent`, `DateTimeInputComponent`, `ChoicePickerComponent`, `SliderComponent`
+### Component Builders
 
-#### Messages
-- **v0.9**: `CreateSurfaceMessage`, `UpdateComponentsMessage`, `UpdateDataModelMessage`, `DeleteSurfaceMessage`
-- **v0.8**: `BeginRenderingMessage`, `SurfaceUpdateMessage`, `DataModelUpdateMessage`
-
-#### Other Types
-- `Theme` - UI theme configuration
-- `Action` - User action definition
-- `ComponentInstance` - Component instance with ID
-
-### Builders
-
-#### Component Builders
 ```typescript
 // Content components
 text(content: StringOrPath, options?: TextOptions): ComponentInstance
@@ -137,36 +124,53 @@ caption(content: StringOrPath, options?: TextOptions): ComponentInstance
 body(content: StringOrPath, options?: TextOptions): ComponentInstance
 ```
 
-#### Message Builders
+### Message Builders
+
 ```typescript
-// v0.9
 createSurface(surfaceId: string, catalogId?: string): CreateSurfaceMessage
 updateComponents(surfaceId: string, components: ComponentInstance[]): UpdateComponentsMessage
 updateDataModel(surfaceId: string, value: unknown, path?: string, op?: 'add' | 'replace' | 'remove'): UpdateDataModelMessage
 deleteSurface(surfaceId: string): DeleteSurfaceMessage
 createV09Messages(options): ServerToClientMessageV09[]
 
-// v0.8
-beginRendering(rootId: string, surfaceId?: string, styles?: Theme): BeginRenderingMessage
-surfaceUpdate(components: ComponentInstanceV08[], surfaceId?: string): SurfaceUpdateMessage
-dataModelUpdate(contents: ValueMap[], surfaceId?: string, path?: string): DataModelUpdateMessage
-dataModelInit(data: DataObject, surfaceId?: string): DataModelUpdateMessage
-pathUpdate(path: string, value: DataValue, surfaceId?: string): DataModelUpdateMessage
-createV08Messages(options): ServerToClientMessageV08[]
-
 // Utilities
-messagesToJsonl(messages: ServerToClientMessage[]): string
-jsonlToMessages(jsonl: string): ServerToClientMessage[]
+messagesToJsonl(messages: ServerToClientMessageV09[]): string
+jsonlToMessages(jsonl: string): ServerToClientMessageV09[]
 ```
 
-#### Data Model Builders
+### Surface Module
+
+```typescript
+// Surface ID constants
+SURFACE_IDS.CHAT           // '@chat' - Chat content area
+SURFACE_IDS.RECOMMENDATION // '@recommendation' - Agent recommendations
+SURFACE_IDS.INPUT_FORM     // '@input-form' - Input collection forms
+SURFACE_IDS.ORCHESTRATION  // '@orchestration' - Multi-agent orchestration
+SURFACE_IDS.STATUS         // '@status' - Status messages
+SURFACE_IDS.RESULT         // '@result' - Agent results
+SURFACE_IDS.CONFIRM        // '@confirm' - Confirmation dialogs
+SURFACE_IDS.NOTIFICATION   // '@notification' - Notifications
+
+// Surface creation functions
+createA2UISurface(rootId: string, components: ComponentInstance[], surfaceId?: string): SurfaceResult
+createA2UISurfaceWithData(rootId: string, components: ComponentInstance[], dataModel: DataObject, surfaceId?: string): SurfaceResult
+createDeleteSurfaceMessage(surfaceId: string): ServerToClientMessageV09
+
+// Convenience functions
+createChatSurface(rootId: string, components: ComponentInstance[]): SurfaceResult
+createRecommendationSurface(rootId: string, components: ComponentInstance[]): SurfaceResult
+createInputFormSurface(rootId: string, components: ComponentInstance[]): SurfaceResult
+createOrchestrationSurface(rootId: string, components: ComponentInstance[]): SurfaceResult
+createStatusSurface(rootId: string, components: ComponentInstance[]): SurfaceResult
+```
+
+### Data Model
+
 ```typescript
 objectToValueMap(obj: DataObject, prefix?: string): ValueMap[]
 valueToValueMap(key: string, value: DataValue): ValueMap
 valueMapToObject(valueMaps: ValueMap[]): DataObject
 normalizePath(path: string, pathMappings?: PathMappings): string
-updatesToValueMap(updates: UpdateDataItem[], basePath?: string): ValueMap[]
-flattenObjectToValueMap(obj: DataObject, basePath: string): ValueMap[]
 ```
 
 ### Validators
@@ -175,7 +179,6 @@ flattenObjectToValueMap(obj: DataObject, basePath: string): ValueMap[]
 validateMessage(message: ServerToClientMessage, options?: ValidationOptions): ValidationResult
 validateMessages(messages: ServerToClientMessage[], options?: ValidationOptions): ValidationResult
 validateV09Message(message: ServerToClientMessageV09, options?: ValidationOptions): ValidationResult
-validateV08Message(message: ServerToClientMessageV08, options?: ValidationOptions): ValidationResult
 ```
 
 ### Utils
@@ -183,10 +186,10 @@ validateV08Message(message: ServerToClientMessageV08, options?: ValidationOption
 ```typescript
 path(dataPath: string): { path: string }           // Create data binding
 isPathBinding(value): boolean                       // Check if value is a path binding
-getLiteralValue<T>(value): T | undefined           // Get literal value from StringOrPath/NumberOrPath/BooleanOrPath
+getLiteralValue<T>(value): T | undefined           // Get literal value
 getPathValue(value): string | undefined            // Get path from binding
 generateId(prefix?: string): string                // Generate unique component ID
-resetIdCounter(): void                             // Reset ID counter (for new scenes)
+resetIdCounter(): void                             // Reset ID counter
 uuid(): string                                     // Generate UUID v4
 deepMerge<T>(target: T, source: Partial<T>): T    // Deep merge objects
 ```
@@ -196,39 +199,24 @@ deepMerge<T>(target: T, source: Partial<T>): T    // Deep merge objects
 ```typescript
 STANDARD_CATALOG_ID  // Standard A2UI catalog URL
 A2UI_EXTENSION_URI   // A2UI v0.9 extension URI
-A2UI_EXTENSION_URI_V08  // A2UI v0.8 extension URI
 A2UI_MIME_TYPE       // A2UI MIME type (application/json+a2ui)
 ```
 
-## Protocol Versions
+## v0.9 Message Format
 
-### v0.9 (Prompt-first)
-Optimized for prompt-first embedding, more concise format:
-- `createSurface` - Create a new surface with catalog ID
-- `updateComponents` - Update components with flat component list
-- `updateDataModel` - Update data model with JSON Patch-like operations
-- `deleteSurface` - Delete surface
-
-### v0.8 (Structured output)
-Optimized for LLM structured output:
-- `beginRendering` - Signal to begin rendering with root component
-- `surfaceUpdate` - Update components
-- `dataModelUpdate` - Update data model using ValueMap format
-- `deleteSurface` - Delete surface
-
-## Type Guards
+A2UI v0.9 uses a cleaner, flatter format:
 
 ```typescript
-import { isV08Message, isV09Message } from '@zhama/a2ui-core';
-
-if (isV09Message(message)) {
-  // Handle v0.9 message
-} else if (isV08Message(message)) {
-  // Handle v0.8 message
-}
+// Component format
+{ id: 'title', component: 'Text', text: 'Hello World', usageHint: 'h1' }
+
+// Messages
+{ createSurface: { surfaceId: '@chat', catalogId: '...' } }
+{ updateComponents: { surfaceId: '@chat', components: [...] } }
+{ updateDataModel: { surfaceId: '@chat', op: 'replace', value: { ... } } }
+{ deleteSurface: { surfaceId: '@chat' } }
 ```
 
 ## License
 
 MIT
-

package/dist/builders/index.cjs

@@ -1,3 +1,3 @@
-'use strict';var g=0;function i(t="comp"){return `${t}_${Date.now()}_${g++}`}function V(){g=0;}function D(){return g}function p(t,e={}){let{id:n=i("text"),weight:o,usageHint:a}=e;return {id:n,component:"Text",text:t,...o!==void 0&&{weight:o},...a&&{usageHint:a}}}function v(t,e={}){let{id:n=i("image"),weight:o,fit:a,usageHint:r}=e;return {id:n,component:"Image",url:t,...o!==void 0&&{weight:o},...a&&{fit:a},...r&&{usageHint:r}}}function P(t,e={}){let{id:n=i("icon"),weight:o}=e;return {id:n,component:"Icon",name:t,...o!==void 0&&{weight:o}}}function A(t,e={}){let{id:n=i("video"),weight:o}=e;return {id:n,component:"Video",url:t,...o!==void 0&&{weight:o}}}function U(t,e={}){let{id:n=i("audio"),weight:o,description:a}=e;return {id:n,component:"AudioPlayer",url:t,...o!==void 0&&{weight:o},...a&&{description:a}}}function w(t,e={}){let{id:n=i("row"),weight:o,alignment:a,distribution:r}=e;return {id:n,component:"Row",children:t,...o!==void 0&&{weight:o},...a&&{alignment:a},...r&&{distribution:r}}}function j(t,e={}){let{id:n=i("column"),weight:o,alignment:a,distribution:r}=e;return {id:n,component:"Column",children:t,...o!==void 0&&{weight:o},...a&&{alignment:a},...r&&{distribution:r}}}function R(t,e={}){let{id:n=i("list"),weight:o,direction:a,alignment:r}=e;return {id:n,component:"List",children:t,...o!==void 0&&{weight:o},...a&&{direction:a},...r&&{alignment:r}}}function _(t,e={}){let{id:n=i("card"),weight:o}=e;return {id:n,component:"Card",child:t,...o!==void 0&&{weight:o}}}function k(t,e={}){let{id:n=i("tabs"),weight:o}=e;return {id:n,component:"Tabs",tabItems:t.map(a=>({title:a.title,child:a.childId})),...o!==void 0&&{weight:o}}}function B(t={}){let{id:e=i("divider"),weight:n,axis:o}=t;return {id:e,component:"Divider",...n!==void 0&&{weight:n},...o&&{axis:o}}}function H(t,e,n={}){let{id:o=i("modal"),weight:a}=n;return {id:o,component:"Modal",entryPointChild:t,contentChild:e,...a!==void 0&&{weight:a}}}function f(t,e,n={}){let{id:o=i("button"),weight:a,primary:r}=n;return {id:o,component:"Button",child:t,action:e,...a!==void 0&&{weight:a},...r!==void 0&&{primary:r}}}function N(t,e,n={}){let{id:o=i("checkbox"),weight:a}=n;return {id:o,component:"CheckBox",label:t,value:e,...a!==void 0&&{weight:a}}}function E(t,e,n={}){let{id:o=i("textfield"),weight:a,usageHint:r,validationRegexp:s}=n;return {id:o,component:"TextField",label:t,...e!==void 0&&{text:e},...a!==void 0&&{weight:a},...r&&{usageHint:r},...s&&{validationRegexp:s}}}function L(t,e={}){let{id:n=i("datetime"),weight:o,enableDate:a,enableTime:r,outputFormat:s,label:c}=e;return {id:n,component:"DateTimeInput",value:t,...o!==void 0&&{weight:o},...a!==void 0&&{enableDate:a},...r!==void 0&&{enableTime:r},...s&&{outputFormat:s},...c&&{label:c}}}function $(t,e,n,o={}){let{id:a=i("choice"),weight:r,label:s}=o;return {id:a,component:"ChoicePicker",options:t,value:e,usageHint:n,...r!==void 0&&{weight:r},...s&&{label:s}}}function F(t,e={}){let{id:n=i("slider"),weight:o,label:a,min:r,max:s}=e;return {id:n,component:"Slider",value:t,...o!==void 0&&{weight:o},...a&&{label:a},...r!==void 0&&{min:r},...s!==void 0&&{max:s}}}function G(t,e,n={}){let o=n.textId??i("btn_text"),a=p(t,{id:o}),r=f(o,e,n);return [a,r]}function z(t,e={}){return p(t,{...e,usageHint:"h1"})}function J(t,e={}){return p(t,{...e,usageHint:"h2"})}function X(t,e={}){return p(t,{...e,usageHint:"h3"})}function W(t,e={}){return p(t,{...e,usageHint:"h4"})}function Y(t,e={}){return p(t,{...e,usageHint:"h5"})}function K(t,e={}){return p(t,{...e,usageHint:"caption"})}function q(t,e={}){return p(t,{...e,usageHint:"body"})}var d="https://a2ui.dev/specification/0.9/standard_catalog_definition.json";var C={};function l(t,e=""){let n=[];for(let[o,a]of Object.entries(t)){let r=e?`${e}/${o}`:`/${o}`;n.push(u(r,a));}return n}function u(t,e){if(e==null)return {key:t,valueString:""};if(typeof e=="string")return {key:t,valueString:e};if(typeof e=="number")return {key:t,valueNumber:e};if(typeof e=="boolean")return {key:t,valueBoolean:e};if(Array.isArray(e))return {key:t,valueMap:e.map((n,o)=>u(String(o),n))};if(typeof e=="object"){let n=[];for(let[o,a]of Object.entries(e))n.push(u(o,a));return {key:t,valueMap:n}}return {key:t,valueString:String(e)}}function x(t,e={}){let n=t.replace(/\./g,"/");n.startsWith("/")||(n=`/${n}`);for(let[o,a]of Object.entries(e)){let r=new RegExp(`^/${o}(/|$)`);r.test(n)&&(n=n.replace(r,`/${a}$1`));}return n}function Q(t,e="",n=C){let o=[];for(let a of t){let r=a.path.startsWith("/")?a.path:`${e}/${a.path}`,s=x(r,n);if(a.value!==null&&typeof a.value=="object"&&!Array.isArray(a.value)){let c=m(a.value,s);o.push(...c);}else o.push(u(s,a.value));}return o}function m(t,e){let n=[];for(let[o,a]of Object.entries(t)){let r=`${e}/${o}`;if(a!==null&&typeof a=="object"&&!Array.isArray(a)){let s=m(a,r);n.push(...s);}else n.push(u(r,a));}return n}function M(t){let e={};for(let n of t){let o=n.key.startsWith("/")?n.key.slice(1):n.key;n.valueString!==void 0?e[o]=n.valueString:n.valueNumber!==void 0?e[o]=n.valueNumber:n.valueBoolean!==void 0?e[o]=n.valueBoolean:n.valueMap!==void 0&&(e[o]=M(n.valueMap));}return e}function O(t,e=d){return {createSurface:{surfaceId:t,catalogId:e}}}function h(t,e){return {updateComponents:{surfaceId:t,components:e}}}function I(t,e,n,o="replace"){return {updateDataModel:{surfaceId:t,...n&&{path:n},op:o,...o!=="remove"&&{value:e}}}}function Z(t){return {deleteSurface:{surfaceId:t}}}function ee(t){let{surfaceId:e,catalogId:n=d,components:o,dataModel:a}=t,r=[O(e,n),h(e,o)];return a&&r.push(I(e,a)),r}function S(t,e="@default",n){return {beginRendering:{surfaceId:e,root:t,...n&&{styles:n}}}}function T(t,e="@default"){return {surfaceUpdate:{surfaceId:e,components:t}}}function y(t,e="@default",n){return {dataModelUpdate:{surfaceId:e,contents:t,...n&&{path:n}}}}function b(t,e="@default"){return y(l(t),e)}function te(t,e,n="@default"){return {dataModelUpdate:{surfaceId:n,path:t,contents:[u("",e)]}}}function ne(t){return {deleteSurface:{surfaceId:t}}}function oe(t){let{rootId:e,components:n,dataModel:o,surfaceId:a="@default",styles:r}=t,s=[T(n,a)];return o&&s.push(b(o,a)),s.push(S(e,a,r)),s}function ae(t){return t.map(e=>JSON.stringify(e)).join(`
-`)}function re(t){return t.split(`
-`).filter(e=>e.trim()).map(e=>JSON.parse(e))}exports.DEFAULT_PATH_MAPPINGS=C;exports.audioPlayer=U;exports.beginRendering=S;exports.body=q;exports.button=f;exports.caption=K;exports.card=_;exports.checkbox=N;exports.choicePicker=$;exports.column=j;exports.createSurface=O;exports.createV08Messages=oe;exports.createV09Messages=ee;exports.dataModelInit=b;exports.dataModelUpdate=y;exports.dateTimeInput=L;exports.deleteSurface=Z;exports.deleteSurfaceV08=ne;exports.divider=B;exports.flattenObjectToValueMap=m;exports.generateId=i;exports.getIdCounter=D;exports.h1=z;exports.h2=J;exports.h3=X;exports.h4=W;exports.h5=Y;exports.icon=P;exports.image=v;exports.jsonlToMessages=re;exports.list=R;exports.messagesToJsonl=ae;exports.modal=H;exports.normalizePath=x;exports.objectToValueMap=l;exports.pathUpdate=te;exports.resetIdCounter=V;exports.row=w;exports.slider=F;exports.surfaceUpdate=T;exports.tabs=k;exports.text=p;exports.textButton=G;exports.textField=E;exports.updateComponents=h;exports.updateDataModel=I;exports.updatesToValueMap=Q;exports.valueMapToObject=M;exports.valueToValueMap=u;exports.video=A;
+'use strict';var m=0;function i(t="comp"){return `${t}_${Date.now()}_${m++}`}function I(){m=0;}function y(){return m}function p(t,e={}){let{id:n=i("text"),weight:o,usageHint:r}=e;return {id:n,component:"Text",text:t,...o!==void 0&&{weight:o},...r&&{usageHint:r}}}function S(t,e={}){let{id:n=i("image"),weight:o,fit:r,usageHint:a}=e;return {id:n,component:"Image",url:t,...o!==void 0&&{weight:o},...r&&{fit:r},...a&&{usageHint:a}}}function b(t,e={}){let{id:n=i("icon"),weight:o}=e;return {id:n,component:"Icon",name:t,...o!==void 0&&{weight:o}}}function T(t,e={}){let{id:n=i("video"),weight:o}=e;return {id:n,component:"Video",url:t,...o!==void 0&&{weight:o}}}function v(t,e={}){let{id:n=i("audio"),weight:o,description:r}=e;return {id:n,component:"AudioPlayer",url:t,...o!==void 0&&{weight:o},...r&&{description:r}}}function D(t,e={}){let{id:n=i("row"),weight:o,alignment:r,distribution:a}=e;return {id:n,component:"Row",children:t,...o!==void 0&&{weight:o},...r&&{alignment:r},...a&&{distribution:a}}}function P(t,e={}){let{id:n=i("column"),weight:o,alignment:r,distribution:a}=e;return {id:n,component:"Column",children:t,...o!==void 0&&{weight:o},...r&&{alignment:r},...a&&{distribution:a}}}function V(t,e={}){let{id:n=i("list"),weight:o,direction:r,alignment:a}=e;return {id:n,component:"List",children:t,...o!==void 0&&{weight:o},...r&&{direction:r},...a&&{alignment:a}}}function A(t,e={}){let{id:n=i("card"),weight:o}=e;return {id:n,component:"Card",child:t,...o!==void 0&&{weight:o}}}function w(t,e={}){let{id:n=i("tabs"),weight:o}=e;return {id:n,component:"Tabs",tabItems:t.map(r=>({title:r.title,child:r.childId})),...o!==void 0&&{weight:o}}}function U(t={}){let{id:e=i("divider"),weight:n,axis:o}=t;return {id:e,component:"Divider",...n!==void 0&&{weight:n},...o&&{axis:o}}}function E(t,e,n={}){let{id:o=i("modal"),weight:r}=n;return {id:o,component:"Modal",entryPointChild:t,contentChild:e,...r!==void 0&&{weight:r}}}function l(t,e,n={}){let{id:o=i("button"),weight:r,primary:a}=n;return {id:o,component:"Button",child:t,action:e,...r!==void 0&&{weight:r},...a!==void 0&&{primary:a}}}function j(t,e,n={}){let{id:o=i("checkbox"),weight:r}=n;return {id:o,component:"CheckBox",label:t,value:e,...r!==void 0&&{weight:r}}}function k(t,e,n={}){let{id:o=i("textfield"),weight:r,usageHint:a,validationRegexp:s}=n;return {id:o,component:"TextField",label:t,...e!==void 0&&{text:e},...r!==void 0&&{weight:r},...a&&{usageHint:a},...s&&{validationRegexp:s}}}function _(t,e={}){let{id:n=i("datetime"),weight:o,enableDate:r,enableTime:a,outputFormat:s,label:u}=e;return {id:n,component:"DateTimeInput",value:t,...o!==void 0&&{weight:o},...r!==void 0&&{enableDate:r},...a!==void 0&&{enableTime:a},...s&&{outputFormat:s},...u&&{label:u}}}function H(t,e,n,o={}){let{id:r=i("choice"),weight:a,label:s}=o;return {id:r,component:"ChoicePicker",options:t,value:e,usageHint:n,...a!==void 0&&{weight:a},...s&&{label:s}}}function B(t,e={}){let{id:n=i("slider"),weight:o,label:r,min:a,max:s}=e;return {id:n,component:"Slider",value:t,...o!==void 0&&{weight:o},...r&&{label:r},...a!==void 0&&{min:a},...s!==void 0&&{max:s}}}function N(t,e,n={}){let o=n.textId??i("btn_text"),r=p(t,{id:o}),a=l(o,e,n);return [r,a]}function R(t,e={}){return p(t,{...e,usageHint:"h1"})}function L(t,e={}){return p(t,{...e,usageHint:"h2"})}function F(t,e={}){return p(t,{...e,usageHint:"h3"})}function $(t,e={}){return p(t,{...e,usageHint:"h4"})}function G(t,e={}){return p(t,{...e,usageHint:"h5"})}function z(t,e={}){return p(t,{...e,usageHint:"caption"})}function J(t,e={}){return p(t,{...e,usageHint:"body"})}var d="https://a2ui.dev/specification/0.9/standard_catalog_definition.json";function f(t,e=d){return {createSurface:{surfaceId:t,catalogId:e}}}function C(t,e){return {updateComponents:{surfaceId:t,components:e}}}function x(t,e,n,o="replace"){return {updateDataModel:{surfaceId:t,...n&&{path:n},op:o,...o!=="remove"&&{value:e}}}}function W(t){return {deleteSurface:{surfaceId:t}}}function X(t){let{surfaceId:e,catalogId:n=d,components:o,dataModel:r}=t,a=[f(e,n),C(e,o)];return r&&a.push(x(e,r)),a}function Y(t){return t.map(e=>JSON.stringify(e)).join(`
+`)}function K(t){return t.split(`
+`).filter(e=>e.trim()).map(e=>JSON.parse(e))}var O={};function q(t,e=""){let n=[];for(let[o,r]of Object.entries(t)){let a=e?`${e}/${o}`:`/${o}`;n.push(c(a,r));}return n}function c(t,e){if(e==null)return {key:t,valueString:""};if(typeof e=="string")return {key:t,valueString:e};if(typeof e=="number")return {key:t,valueNumber:e};if(typeof e=="boolean")return {key:t,valueBoolean:e};if(Array.isArray(e))return {key:t,valueMap:e.map((n,o)=>c(String(o),n))};if(typeof e=="object"){let n=[];for(let[o,r]of Object.entries(e))n.push(c(o,r));return {key:t,valueMap:n}}return {key:t,valueString:String(e)}}function h(t,e={}){let n=t.replace(/\./g,"/");n.startsWith("/")||(n=`/${n}`);for(let[o,r]of Object.entries(e)){let a=new RegExp(`^/${o}(/|$)`);a.test(n)&&(n=n.replace(a,`/${r}$1`));}return n}function Q(t,e="",n=O){let o=[];for(let r of t){let a=r.path.startsWith("/")?r.path:`${e}/${r.path}`,s=h(a,n);if(r.value!==null&&typeof r.value=="object"&&!Array.isArray(r.value)){let u=g(r.value,s);o.push(...u);}else o.push(c(s,r.value));}return o}function g(t,e){let n=[];for(let[o,r]of Object.entries(t)){let a=`${e}/${o}`;if(r!==null&&typeof r=="object"&&!Array.isArray(r)){let s=g(r,a);n.push(...s);}else n.push(c(a,r));}return n}function M(t){let e={};for(let n of t){let o=n.key.startsWith("/")?n.key.slice(1):n.key;n.valueString!==void 0?e[o]=n.valueString:n.valueNumber!==void 0?e[o]=n.valueNumber:n.valueBoolean!==void 0?e[o]=n.valueBoolean:n.valueMap!==void 0&&(e[o]=M(n.valueMap));}return e}exports.DEFAULT_PATH_MAPPINGS=O;exports.audioPlayer=v;exports.body=J;exports.button=l;exports.caption=z;exports.card=A;exports.checkbox=j;exports.choicePicker=H;exports.column=P;exports.createSurface=f;exports.createV09Messages=X;exports.dateTimeInput=_;exports.deleteSurface=W;exports.divider=U;exports.flattenObjectToValueMap=g;exports.generateId=i;exports.getIdCounter=y;exports.h1=R;exports.h2=L;exports.h3=F;exports.h4=$;exports.h5=G;exports.icon=b;exports.image=S;exports.jsonlToMessages=K;exports.list=V;exports.messagesToJsonl=Y;exports.modal=E;exports.normalizePath=h;exports.objectToValueMap=q;exports.resetIdCounter=I;exports.row=D;exports.slider=B;exports.tabs=w;exports.text=p;exports.textButton=N;exports.textField=k;exports.updateComponents=C;exports.updateDataModel=x;exports.updatesToValueMap=Q;exports.valueMapToObject=M;exports.valueToValueMap=c;exports.video=T;

package/dist/builders/index.d.cts

@@ -1,5 +1,5 @@
-import { S as StringOrPath, B as BooleanOrPath, a as StringArrayOrPath, N as NumberOrPath } from '../primitives-nmkVz-tB.cjs';
-import { TextComponent, ImageComponent, RowComponent, ListComponent, DividerComponent, TextFieldComponent, ComponentInstance, ChildrenProperty, Action, ChoicePickerComponent, CreateSurfaceMessage, UpdateComponentsMessage, UpdateDataModelMessage, DeleteSurfaceMessage, DataObject, ServerToClientMessageV09, BeginRenderingMessage, ComponentInstanceV08, SurfaceUpdateMessage, ValueMap, DataModelUpdateMessage, DataValue, ServerToClientMessageV08 } from '../types/index.cjs';
+import { S as StringOrPath, B as BooleanOrPath, a as StringArrayOrPath, N as NumberOrPath } from '../primitives-DLbBDhLq.cjs';
+import { TextComponent, ImageComponent, RowComponent, ListComponent, DividerComponent, TextFieldComponent, ComponentInstance, ChildrenProperty, Action, ChoicePickerComponent, CreateSurfaceMessage, UpdateComponentsMessage, UpdateDataModelMessage, DeleteSurfaceMessage, DataObject, ServerToClientMessageV09, DataValue } from '../types/index.cjs';
 
 /**
  * ID Generator
@@ -322,35 +322,66 @@ declare function body(content: StringOrPath, options?: Omit<TextOptions, 'usageH
 /**
  * Message Builder
  *
- * 提供 A2UI 协议消息的构建工具函数
- * 支持 v0.8 和 v0.9 两种消息格式
+ * 提供 A2UI v0.9 协议消息的构建工具函数
+ *
+ * v0.9 消息类型：
+ * - createSurface: 创建新的 UI Surface
+ * - updateComponents: 更新组件
+ * - updateDataModel: 更新数据模型 (JSON Patch 风格)
+ * - deleteSurface: 删除 Surface
+ *
+ * 参考: https://a2ui.org/
  */
 
 /**
- * 创建 CreateSurface 消息 (v0.9)
+ * 创建 CreateSurface 消息
  *
  * @param surfaceId - Surface ID
  * @param catalogId - Catalog ID（默认为标准目录）
+ *
+ * @example
+ * ```typescript
+ * const msg = createSurface('my-surface');
+ * // { createSurface: { surfaceId: 'my-surface', catalogId: '...' } }
+ * ```
  */
 declare function createSurface(surfaceId: string, catalogId?: string): CreateSurfaceMessage;
 /**
- * 创建 UpdateComponents 消息 (v0.9)
+ * 创建 UpdateComponents 消息
  *
  * @param surfaceId - Surface ID
  * @param components - 组件列表
+ *
+ * @example
+ * ```typescript
+ * const title = text('Hello', { id: 'title' });
+ * const msg = updateComponents('my-surface', [title]);
+ * ```
  */
 declare function updateComponents(surfaceId: string, components: ComponentInstance[]): UpdateComponentsMessage;
 /**
- * 创建 UpdateDataModel 消息 (v0.9)
+ * 创建 UpdateDataModel 消息
  *
  * @param surfaceId - Surface ID
  * @param value - 数据值
- * @param path - 数据路径（可选）
+ * @param path - 数据路径（可选，默认为根路径）
  * @param op - 操作类型（默认为 replace）
+ *
+ * @example
+ * ```typescript
+ * // 替换整个数据模型
+ * updateDataModel('my-surface', { user: { name: 'John' } });
+ *
+ * // 更新特定路径
+ * updateDataModel('my-surface', 'Jane', '/user/name', 'replace');
+ *
+ * // 添加数据
+ * updateDataModel('my-surface', 'new-item', '/items/-', 'add');
+ * ```
  */
 declare function updateDataModel(surfaceId: string, value: unknown, path?: string, op?: 'add' | 'replace' | 'remove'): UpdateDataModelMessage;
 /**
- * 创建 DeleteSurface 消息 (v0.9)
+ * 创建 DeleteSurface 消息
  *
  * @param surfaceId - 要删除的 Surface ID
  */
@@ -360,6 +391,21 @@ declare function deleteSurface(surfaceId: string): DeleteSurfaceMessage;
  *
  * @param options - 选项
  * @returns 消息数组（可直接作为 JSONL 流发送）
+ *
+ * @example
+ * ```typescript
+ * const title = h1('Welcome', { id: 'title' });
+ * const root = column(['title'], { id: 'root' });
+ *
+ * const messages = createV09Messages({
+ *   surfaceId: '@chat',
+ *   components: [title, root],
+ *   dataModel: { user: { name: 'John' } }
+ * });
+ *
+ * // 发送为 JSONL 流
+ * const jsonl = messagesToJsonl(messages);
+ * ```
  */
 declare function createV09Messages(options: {
     surfaceId: string;
@@ -367,89 +413,45 @@ declare function createV09Messages(options: {
     components: ComponentInstance[];
     dataModel?: DataObject;
 }): ServerToClientMessageV09[];
-/**
- * 创建 BeginRendering 消息 (v0.8)
- *
- * @param rootId - 根组件 ID
- * @param surfaceId - Surface ID
- * @param styles - 样式配置
- */
-declare function beginRendering(rootId: string, surfaceId?: string, styles?: Record<string, string>): BeginRenderingMessage;
-/**
- * 创建 SurfaceUpdate 消息 (v0.8)
- *
- * @param components - 组件定义数组
- * @param surfaceId - Surface ID
- */
-declare function surfaceUpdate(components: ComponentInstanceV08[], surfaceId?: string): SurfaceUpdateMessage;
-/**
- * 创建 DataModelUpdate 消息 (v0.8)
- *
- * @param contents - ValueMap 数组
- * @param surfaceId - Surface ID
- * @param path - 数据路径（可选）
- */
-declare function dataModelUpdate(contents: ValueMap[], surfaceId?: string, path?: string): DataModelUpdateMessage;
-/**
- * 创建 DataModel 初始化消息 (v0.8)
- *
- * @param data - 初始数据对象
- * @param surfaceId - Surface ID
- */
-declare function dataModelInit(data: DataObject, surfaceId?: string): DataModelUpdateMessage;
-/**
- * 创建路径更新消息 (v0.8)
- *
- * @param path - 数据路径
- * @param value - 新值
- * @param surfaceId - Surface ID
- */
-declare function pathUpdate(path: string, value: DataValue, surfaceId?: string): DataModelUpdateMessage;
-/**
- * 创建 DeleteSurface 消息 (v0.8)
- *
- * @param surfaceId - 要删除的 Surface ID
- */
-declare function deleteSurfaceV08(surfaceId: string): {
-    deleteSurface: {
-        surfaceId: string;
-    };
-};
-/**
- * 创建完整的 v0.8 消息数组
- *
- * @param options - 选项
- * @returns 消息数组
- */
-declare function createV08Messages(options: {
-    rootId: string;
-    components: ComponentInstanceV08[];
-    dataModel?: DataObject;
-    surfaceId?: string;
-    styles?: Record<string, string>;
-}): ServerToClientMessageV08[];
 /**
  * 将消息数组转换为 JSONL 格式字符串
  *
  * @param messages - 消息数组
  * @returns JSONL 格式字符串
+ *
+ * @example
+ * ```typescript
+ * const jsonl = messagesToJsonl(messages);
+ * // 每行一个 JSON 对象
+ * ```
  */
-declare function messagesToJsonl(messages: Array<ServerToClientMessageV08 | ServerToClientMessageV09>): string;
+declare function messagesToJsonl(messages: ServerToClientMessageV09[]): string;
 /**
  * 从 JSONL 格式字符串解析消息数组
  *
  * @param jsonl - JSONL 格式字符串
  * @returns 消息数组
  */
-declare function jsonlToMessages(jsonl: string): Array<ServerToClientMessageV08 | ServerToClientMessageV09>;
+declare function jsonlToMessages(jsonl: string): ServerToClientMessageV09[];
 
 /**
  * Data Model Builder
  *
  * 提供 DataModel 相关的构建工具函数
- * 符合 A2UI 协议的 ValueMap 格式
+ * 包括 v0.9 JSON 对象格式和 v0.8 ValueMap 格式转换
  */
 
+/**
+ * ValueMap 格式 - 用于 v0.8 兼容和内部数据转换
+ * @internal
+ */
+interface ValueMap {
+    key: string;
+    valueString?: string;
+    valueNumber?: number;
+    valueBoolean?: boolean;
+    valueMap?: ValueMap[];
+}
 /**
  * 路径映射表类型
  */
@@ -530,4 +532,4 @@ declare function flattenObjectToValueMap(obj: DataObject, basePath: string): Val
  */
 declare function valueMapToObject(valueMaps: ValueMap[]): DataObject;
 
-export { type AudioPlayerOptions, type ButtonOptions, type CardOptions, type CheckBoxOptions, type ChoicePickerOptions, type ComponentOptions, DEFAULT_PATH_MAPPINGS, type DateTimeInputOptions, type DividerOptions, type IconOptions, type ImageOptions, type LayoutOptions, type ListOptions, type ModalOptions, type PathMappings, type SliderOptions, type TabItem, type TabsOptions, type TextFieldOptions, type TextOptions, type UpdateDataItem, type VideoOptions, audioPlayer, beginRendering, body, button, caption, card, checkbox, choicePicker, column, createSurface, createV08Messages, createV09Messages, dataModelInit, dataModelUpdate, dateTimeInput, deleteSurface, deleteSurfaceV08, divider, flattenObjectToValueMap, generateId, getIdCounter, h1, h2, h3, h4, h5, icon, image, jsonlToMessages, list, messagesToJsonl, modal, normalizePath, objectToValueMap, pathUpdate, resetIdCounter, row, slider, surfaceUpdate, tabs, text, textButton, textField, updateComponents, updateDataModel, updatesToValueMap, valueMapToObject, valueToValueMap, video };
+export { type AudioPlayerOptions, type ButtonOptions, type CardOptions, type CheckBoxOptions, type ChoicePickerOptions, type ComponentOptions, DEFAULT_PATH_MAPPINGS, type DateTimeInputOptions, type DividerOptions, type IconOptions, type ImageOptions, type LayoutOptions, type ListOptions, type ModalOptions, type PathMappings, type SliderOptions, type TabItem, type TabsOptions, type TextFieldOptions, type TextOptions, type UpdateDataItem, type VideoOptions, audioPlayer, body, button, caption, card, checkbox, choicePicker, column, createSurface, createV09Messages, dateTimeInput, deleteSurface, divider, flattenObjectToValueMap, generateId, getIdCounter, h1, h2, h3, h4, h5, icon, image, jsonlToMessages, list, messagesToJsonl, modal, normalizePath, objectToValueMap, resetIdCounter, row, slider, tabs, text, textButton, textField, updateComponents, updateDataModel, updatesToValueMap, valueMapToObject, valueToValueMap, video };