@threadplane/a2ui 0.0.55 → 0.0.56

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@threadplane/a2ui",
-  "version": "0.0.55",
+  "version": "0.0.56",
   "license": "MIT",
   "repository": {
     "type": "git",

package/src/lib/guards.d.ts

@@ -1,12 +1,16 @@
+/** Returns true when `value` is an A2UI dynamic path reference. */
 export declare function isPathRef(value: unknown): value is {
     path: string;
 };
+/** Returns true when `value` is an A2UI string literal wrapper. */
 export declare function isLiteralString(value: unknown): value is {
     literalString: string;
 };
+/** Returns true when `value` is an A2UI number literal wrapper. */
 export declare function isLiteralNumber(value: unknown): value is {
     literalNumber: number;
 };
+/** Returns true when `value` is an A2UI boolean literal wrapper. */
 export declare function isLiteralBoolean(value: unknown): value is {
     literalBoolean: boolean;
 };

package/src/lib/guards.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"guards.d.ts","sourceRoot":"","sources":["../../../../../libs/a2ui/src/lib/guards.ts"],"names":[],"mappings":"AAEA,wBAAgB,SAAS,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,CAGnE;AAED,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI;IAAE,aAAa,EAAE,MAAM,CAAA;CAAE,CAElF;AAED,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI;IAAE,aAAa,EAAE,MAAM,CAAA;CAAE,CAElF;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI;IAAE,cAAc,EAAE,OAAO,CAAA;CAAE,CAErF"}
+{"version":3,"file":"guards.d.ts","sourceRoot":"","sources":["../../../../../libs/a2ui/src/lib/guards.ts"],"names":[],"mappings":"AAEA,mEAAmE;AACnE,wBAAgB,SAAS,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,CAGnE;AAED,mEAAmE;AACnE,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI;IAAE,aAAa,EAAE,MAAM,CAAA;CAAE,CAElF;AAED,mEAAmE;AACnE,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI;IAAE,aAAa,EAAE,MAAM,CAAA;CAAE,CAElF;AAED,oEAAoE;AACpE,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI;IAAE,cAAc,EAAE,OAAO,CAAA;CAAE,CAErF"}

package/src/lib/guards.js

@@ -1,14 +1,18 @@
 // SPDX-License-Identifier: MIT
+/** Returns true when `value` is an A2UI dynamic path reference. */
 export function isPathRef(value) {
     return typeof value === 'object' && value !== null
         && 'path' in value && typeof value.path === 'string';
 }
+/** Returns true when `value` is an A2UI string literal wrapper. */
 export function isLiteralString(value) {
     return typeof value === 'object' && value !== null && 'literalString' in value;
 }
+/** Returns true when `value` is an A2UI number literal wrapper. */
 export function isLiteralNumber(value) {
     return typeof value === 'object' && value !== null && 'literalNumber' in value;
 }
+/** Returns true when `value` is an A2UI boolean literal wrapper. */
 export function isLiteralBoolean(value) {
     return typeof value === 'object' && value !== null && 'literalBoolean' in value;
 }

package/src/lib/parser.d.ts

@@ -1,6 +1,20 @@
 import type { A2uiMessage } from './types.js';
 export interface A2uiMessageParser {
+    /** Push a JSONL stream chunk and return every complete A2UI envelope parsed from it. */
     push(chunk: string): A2uiMessage[];
 }
+/**
+ * Creates a stateful parser for newline-delimited A2UI message streams.
+ *
+ * The parser buffers incomplete lines, skips malformed JSON, and returns only
+ * recognized A2UI envelopes: `surfaceUpdate`, `dataModelUpdate`,
+ * `beginRendering`, and `deleteSurface`.
+ *
+ * @example
+ * ```ts
+ * const parser = createA2uiMessageParser();
+ * const messages = parser.push('{"beginRendering":{"surfaceId":"s1","root":"root"}}\n');
+ * ```
+ */
 export declare function createA2uiMessageParser(): A2uiMessageParser;
 //# sourceMappingURL=parser.d.ts.map

package/src/lib/parser.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"parser.d.ts","sourceRoot":"","sources":["../../../../../libs/a2ui/src/lib/parser.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAI9C,MAAM,WAAW,iBAAiB;IAChC,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,WAAW,EAAE,CAAC;CACpC;AAED,wBAAgB,uBAAuB,IAAI,iBAAiB,CAsC3D"}
+{"version":3,"file":"parser.d.ts","sourceRoot":"","sources":["../../../../../libs/a2ui/src/lib/parser.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAI9C,MAAM,WAAW,iBAAiB;IAChC,wFAAwF;IACxF,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,WAAW,EAAE,CAAC;CACpC;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,uBAAuB,IAAI,iBAAiB,CAsC3D"}

package/src/lib/parser.js

@@ -1,4 +1,17 @@
 const ENVELOPE_KEYS = ['surfaceUpdate', 'dataModelUpdate', 'beginRendering', 'deleteSurface'];
+/**
+ * Creates a stateful parser for newline-delimited A2UI message streams.
+ *
+ * The parser buffers incomplete lines, skips malformed JSON, and returns only
+ * recognized A2UI envelopes: `surfaceUpdate`, `dataModelUpdate`,
+ * `beginRendering`, and `deleteSurface`.
+ *
+ * @example
+ * ```ts
+ * const parser = createA2uiMessageParser();
+ * const messages = parser.push('{"beginRendering":{"surfaceId":"s1","root":"root"}}\n');
+ * ```
+ */
 export function createA2uiMessageParser() {
     let buffer = '';
     function parseEnvelope(json) {

package/src/lib/pointer.d.ts

@@ -1,4 +1,36 @@
+/**
+ * Reads a value from a model using the package's simple slash-separated pointer syntax.
+ *
+ * Empty string and `/` target the root. Segments are not RFC 6901-unescaped;
+ * normalize keys before using pointers that would require `~0` or `~1`.
+ *
+ * @example
+ * ```ts
+ * getByPointer({ user: { name: 'Ada' } }, '/user/name'); // 'Ada'
+ * ```
+ */
 export declare function getByPointer(model: Record<string, unknown>, pointer: string): unknown;
+/**
+ * Returns a new model with `value` written at `pointer`.
+ *
+ * The input model is not mutated. Missing intermediate objects are created.
+ *
+ * @example
+ * ```ts
+ * const next = setByPointer({}, '/user/name', 'Ada');
+ * ```
+ */
 export declare function setByPointer(model: Record<string, unknown>, pointer: string, value: unknown): Record<string, unknown>;
+/**
+ * Returns a new model with the key at `pointer` removed.
+ *
+ * Empty string and `/` clear the whole model. Missing parent paths leave the
+ * input model unchanged.
+ *
+ * @example
+ * ```ts
+ * const next = deleteByPointer({ user: { name: 'Ada' } }, '/user/name');
+ * ```
+ */
 export declare function deleteByPointer(model: Record<string, unknown>, pointer: string): Record<string, unknown>;
 //# sourceMappingURL=pointer.d.ts.map

package/src/lib/pointer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pointer.d.ts","sourceRoot":"","sources":["../../../../../libs/a2ui/src/lib/pointer.ts"],"names":[],"mappings":"AAOA,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAQrF;AAED,wBAAgB,YAAY,CAC1B,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,OAAO,GACb,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAmBzB;AAED,wBAAgB,eAAe,CAC7B,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,OAAO,EAAE,MAAM,GACd,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAkBzB"}
+{"version":3,"file":"pointer.d.ts","sourceRoot":"","sources":["../../../../../libs/a2ui/src/lib/pointer.ts"],"names":[],"mappings":"AAOA;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAQrF;AAED;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAC1B,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,OAAO,GACb,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAmBzB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAC7B,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,OAAO,EAAE,MAAM,GACd,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAkBzB"}

package/src/lib/pointer.js

@@ -4,6 +4,17 @@ function parsePointer(pointer) {
         return [];
     return pointer.split('/').filter(Boolean);
 }
+/**
+ * Reads a value from a model using the package's simple slash-separated pointer syntax.
+ *
+ * Empty string and `/` target the root. Segments are not RFC 6901-unescaped;
+ * normalize keys before using pointers that would require `~0` or `~1`.
+ *
+ * @example
+ * ```ts
+ * getByPointer({ user: { name: 'Ada' } }, '/user/name'); // 'Ada'
+ * ```
+ */
 export function getByPointer(model, pointer) {
     const segments = parsePointer(pointer);
     let current = model;
@@ -14,6 +25,16 @@ export function getByPointer(model, pointer) {
     }
     return current;
 }
+/**
+ * Returns a new model with `value` written at `pointer`.
+ *
+ * The input model is not mutated. Missing intermediate objects are created.
+ *
+ * @example
+ * ```ts
+ * const next = setByPointer({}, '/user/name', 'Ada');
+ * ```
+ */
 export function setByPointer(model, pointer, value) {
     const segments = parsePointer(pointer);
     if (segments.length === 0)
@@ -30,6 +51,17 @@ export function setByPointer(model, pointer, value) {
     }
     return clone(model, segments, value);
 }
+/**
+ * Returns a new model with the key at `pointer` removed.
+ *
+ * Empty string and `/` clear the whole model. Missing parent paths leave the
+ * input model unchanged.
+ *
+ * @example
+ * ```ts
+ * const next = deleteByPointer({ user: { name: 'Ada' } }, '/user/name');
+ * ```
+ */
 export function deleteByPointer(model, pointer) {
     const segments = parsePointer(pointer);
     if (segments.length === 0)

package/src/lib/resolve.d.ts

@@ -2,5 +2,19 @@ export interface A2uiScope {
     basePath: string;
     item: unknown;
 }
+/**
+ * Resolves an A2UI dynamic value against a client data model.
+ *
+ * Literal wrappers unwrap to their inner values, `{ path }` references read
+ * from the model by JSON-pointer path, arrays resolve recursively, and
+ * unrecognized plain values pass through unchanged.
+ *
+ * @example
+ * ```ts
+ * const model = { customer: { name: 'Ada' } };
+ * resolveDynamic({ path: '/customer/name' }, model); // 'Ada'
+ * resolveDynamic({ literalString: 'Checkout' }, model); // 'Checkout'
+ * ```
+ */
 export declare function resolveDynamic(value: unknown, model: Record<string, unknown>, scope?: A2uiScope): unknown;
 //# sourceMappingURL=resolve.d.ts.map

package/src/lib/resolve.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"resolve.d.ts","sourceRoot":"","sources":["../../../../../libs/a2ui/src/lib/resolve.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,SAAS;IACxB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,OAAO,CAAC;CACf;AA+BD,wBAAgB,cAAc,CAC5B,KAAK,EAAE,OAAO,EACd,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,KAAK,CAAC,EAAE,SAAS,GAChB,OAAO,CAeT"}
+{"version":3,"file":"resolve.d.ts","sourceRoot":"","sources":["../../../../../libs/a2ui/src/lib/resolve.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,SAAS;IACxB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,OAAO,CAAC;CACf;AA+BD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,OAAO,EACd,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,KAAK,CAAC,EAAE,SAAS,GAChB,OAAO,CAeT"}

package/src/lib/resolve.js

@@ -23,6 +23,20 @@ function resolvePathRef(ref, model, scope) {
         return getByPointer(model, `${scope.basePath}/${path}`);
     return getByPointer(model, '/' + path);
 }
+/**
+ * Resolves an A2UI dynamic value against a client data model.
+ *
+ * Literal wrappers unwrap to their inner values, `{ path }` references read
+ * from the model by JSON-pointer path, arrays resolve recursively, and
+ * unrecognized plain values pass through unchanged.
+ *
+ * @example
+ * ```ts
+ * const model = { customer: { name: 'Ada' } };
+ * resolveDynamic({ path: '/customer/name' }, model); // 'Ada'
+ * resolveDynamic({ literalString: 'Checkout' }, model); // 'Checkout'
+ * ```
+ */
 export function resolveDynamic(value, model, scope) {
     if (value == null)
         return value;