@a2ui/web_core 0.8.0 → 0.9.0

package/src/v0_9/catalog/types.js

@@ -0,0 +1,68 @@
+/*
+ * Copyright 2025 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { z } from 'zod';
+import { A2uiExpressionError } from '../errors.js';
+/**
+ * Robust check for a Preact Signal that works across package boundaries.
+ */
+export function isSignal(val) {
+    return val && typeof val === 'object' && 'value' in val && 'peek' in val;
+}
+export function createFunctionImplementation(api, execute) {
+    return {
+        name: api.name,
+        returnType: api.returnType,
+        schema: api.schema,
+        execute: execute,
+    };
+}
+/**
+ * A collection of available components and functions.
+ */
+export class Catalog {
+    constructor(id, components, functions = [], themeSchema) {
+        this.id = id;
+        const compMap = new Map();
+        for (const comp of components) {
+            compMap.set(comp.name, comp);
+        }
+        this.components = compMap;
+        const funcMap = new Map();
+        for (const fn of functions) {
+            funcMap.set(fn.name, fn);
+        }
+        this.functions = funcMap;
+        this.themeSchema = themeSchema;
+        this.invoker = (name, rawArgs, ctx, abortSignal) => {
+            const fn = this.functions.get(name);
+            if (!fn) {
+                throw new A2uiExpressionError(`Function not found in catalog '${this.id}': ${name}`, name);
+            }
+            // Provides runtime safety: Coerces and strips invalid arguments before execute()
+            try {
+                const safeArgs = fn.schema.parse(rawArgs);
+                return fn.execute(safeArgs, ctx, abortSignal);
+            }
+            catch (e) {
+                if (e?.name === 'ZodError' || e instanceof z.ZodError) {
+                    throw new A2uiExpressionError(`Validation failed for function '${name}': ${e.message}`, name, e.errors ?? e.issues);
+                }
+                throw e;
+            }
+        };
+    }
+}
+//# sourceMappingURL=types.js.map

package/src/v0_9/catalog/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../../src/v0_9/catalog/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAC,CAAC,EAAC,MAAM,KAAK,CAAC;AAGtB,OAAO,EAAC,mBAAmB,EAAC,MAAM,cAAc,CAAC;AAEjD;;GAEG;AACH,MAAM,UAAU,QAAQ,CAAC,GAAQ;IAC/B,OAAO,GAAG,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,OAAO,IAAI,GAAG,IAAI,MAAM,IAAI,GAAG,CAAC;AAC3E,CAAC;AA6CD,MAAM,UAAU,4BAA4B,CAI1C,GAAwD,EACxD,OAIwE;IAExE,OAAO;QACL,IAAI,EAAE,GAAG,CAAC,IAAI;QACd,UAAU,EAAE,GAAG,CAAC,UAAU;QAC1B,MAAM,EAAE,GAAG,CAAC,MAAM;QAClB,OAAO,EAAE,OAIG;KACb,CAAC;AACJ,CAAC;AAkCD;;GAEG;AACH,MAAM,OAAO,OAAO;IAyBlB,YACE,EAAU,EACV,UAAe,EACf,YAAsC,EAAE,EACxC,WAA8B;QAE9B,IAAI,CAAC,EAAE,GAAG,EAAE,CAAC;QAEb,MAAM,OAAO,GAAG,IAAI,GAAG,EAAa,CAAC;QACrC,KAAK,MAAM,IAAI,IAAI,UAAU,EAAE,CAAC;YAC9B,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;QAC/B,CAAC;QACD,IAAI,CAAC,UAAU,GAAG,OAAO,CAAC;QAE1B,MAAM,OAAO,GAAG,IAAI,GAAG,EAAkC,CAAC;QAC1D,KAAK,MAAM,EAAE,IAAI,SAAS,EAAE,CAAC;YAC3B,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;QAC3B,CAAC;QACD,IAAI,CAAC,SAAS,GAAG,OAAO,CAAC;QAEzB,IAAI,CAAC,WAAW,GAAG,WAAW,CAAC;QAE/B,IAAI,CAAC,OAAO,GAAG,CAAC,IAAI,EAAE,OAAO,EAAE,GAAG,EAAE,WAAW,EAAE,EAAE;YACjD,MAAM,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;YACpC,IAAI,CAAC,EAAE,EAAE,CAAC;gBACR,MAAM,IAAI,mBAAmB,CAC3B,kCAAkC,IAAI,CAAC,EAAE,MAAM,IAAI,EAAE,EACrD,IAAI,CACL,CAAC;YACJ,CAAC;YAED,iFAAiF;YACjF,IAAI,CAAC;gBACH,MAAM,QAAQ,GAAG,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;gBAC1C,OAAO,EAAE,CAAC,OAAO,CAAC,QAAQ,EAAE,GAAG,EAAE,WAAW,CAAC,CAAC;YAChD,CAAC;YAAC,OAAO,CAAM,EAAE,CAAC;gBAChB,IAAI,CAAC,EAAE,IAAI,KAAK,UAAU,IAAI,CAAC,YAAY,CAAC,CAAC,QAAQ,EAAE,CAAC;oBACtD,MAAM,IAAI,mBAAmB,CAC3B,mCAAmC,IAAI,MAAM,CAAC,CAAC,OAAO,EAAE,EACxD,IAAI,EACJ,CAAC,CAAC,MAAM,IAAI,CAAC,CAAC,MAAM,CACrB,CAAC;gBACJ,CAAC;gBACD,MAAM,CAAC,CAAC;YACV,CAAC;QACH,CAAC,CAAC;IACJ,CAAC;CACF"}

package/src/v0_9/catalog/types.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.test.d.ts.map

package/src/v0_9/catalog/types.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.test.d.ts","sourceRoot":"","sources":["../../../../src/v0_9/catalog/types.test.ts"],"names":[],"mappings":""}

package/src/v0_9/catalog/types.test.js

@@ -0,0 +1,88 @@
+/*
+ * Copyright 2025 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import assert from 'node:assert';
+import { describe, it } from 'node:test';
+import { Catalog, createFunctionImplementation, } from './types.js';
+import { A2uiExpressionError } from '../errors.js';
+import { z } from 'zod';
+describe('Catalog Types', () => {
+    it('creates a catalog with functions', () => {
+        const mockComponent = {
+            name: 'MockComp',
+            schema: z.object({}),
+        };
+        const mockFunc = createFunctionImplementation({
+            name: 'mockFunc',
+            returnType: 'string',
+            schema: z.object({}),
+        }, () => 'result');
+        const catalog = new Catalog('test-cat', [mockComponent], [mockFunc]);
+        assert.strictEqual(catalog.id, 'test-cat');
+        assert.strictEqual(catalog.components.size, 1);
+        assert.strictEqual(catalog.components.get('MockComp'), mockComponent);
+        assert.ok(catalog.functions);
+        assert.strictEqual(catalog.functions.size, 1);
+        assert.strictEqual(catalog.functions.get('mockFunc'), mockFunc);
+    });
+    it('throws A2uiExpressionError when function is not found', () => {
+        const catalog = new Catalog('test-cat', []);
+        const ctx = {};
+        assert.throws(() => catalog.invoker('nonExistent', {}, ctx), (err) => {
+            return (err instanceof A2uiExpressionError &&
+                err.message.includes('Function not found') &&
+                err.expression === 'nonExistent');
+        });
+    });
+    it('throws A2uiExpressionError when zod validation fails', () => {
+        const mockFunc = createFunctionImplementation({
+            name: 'test',
+            returnType: 'string',
+            schema: z.object({
+                requiredField: z.string(),
+            }),
+        }, () => 'result');
+        const catalog = new Catalog('test-cat', [], [mockFunc]);
+        const ctx = {};
+        assert.throws(() => catalog.invoker('test', {}, ctx), (err) => {
+            return (err instanceof A2uiExpressionError &&
+                err.message.includes('Validation failed') &&
+                err.expression === 'test' &&
+                Array.isArray(err.details));
+        });
+    });
+});
+describe('InferredComponentApiSchemaType', () => {
+    it('infers the correct schema type from a ComponentApi', () => {
+        const mockSchema = z.object({
+            field1: z.string(),
+            field2: z.number().optional(),
+        });
+        const mockApi = {
+            name: 'MockComp',
+            schema: mockSchema,
+        };
+        assert.ok(mockApi);
+        // inferredIsAny only accepts "true" if `InferredType` is "any".
+        // This happens when `mockApi: ComponentApi`, but doesn't when
+        // `mockApi {} satisfies ComponentApi`!
+        const inferredIsAny = false;
+        assert.strictEqual(inferredIsAny, false);
+        // typesMatchExact only accepts "true" if `TypesAreEquivalent`
+        const typesMatchExact = true;
+        assert.strictEqual(typesMatchExact, true);
+    });
+});
+//# sourceMappingURL=types.test.js.map

package/src/v0_9/catalog/types.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.test.js","sourceRoot":"","sources":["../../../../src/v0_9/catalog/types.test.ts"],"names":[],"mappings":"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"}

package/src/v0_9/common/events.d.ts

@@ -0,0 +1,45 @@
+/** Standard cleanup interface returned by all subscriptions. */
+export interface Subscription {
+    /** Unsubscribes from the event source. */
+    unsubscribe(): void;
+}
+/** A function that handles emitted events. */
+export type EventListener<T> = (data: T) => void | Promise<void>;
+/**
+ * Public interface exposed by models.
+ * Allows ONLY subscribing to events.
+ */
+export interface EventSource<T> {
+    /**
+     * Subscribes to the event.
+     *
+     * @param listener The listener function to call when the event is emitted.
+     * @returns A subscription object that can be used to unsubscribe.
+     */
+    subscribe(listener: EventListener<T>): Subscription;
+}
+/**
+ * Internal implementation used by the model.
+ * Implements EventSource but also provides the 'emit' method.
+ */
+export declare class EventEmitter<T> implements EventSource<T> {
+    private listeners;
+    /**
+     * Subscribes to the event.
+     *
+     * @param listener The listener function to call when the event is emitted.
+     * @returns A subscription object that can be used to unsubscribe.
+     */
+    subscribe(listener: EventListener<T>): Subscription;
+    /**
+     * Emits an event to all subscribers.
+     *
+     * @param data The data to pass to subscribers.
+     */
+    emit(data: T): Promise<void>;
+    /**
+     * Removes all listeners.
+     */
+    dispose(): void;
+}
+//# sourceMappingURL=events.d.ts.map

package/src/v0_9/common/events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../../../../src/v0_9/common/events.ts"],"names":[],"mappings":"AAgBA,gEAAgE;AAChE,MAAM,WAAW,YAAY;IAC3B,0CAA0C;IAC1C,WAAW,IAAI,IAAI,CAAC;CACrB;AAED,8CAA8C;AAC9C,MAAM,MAAM,aAAa,CAAC,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;AAEjE;;;GAGG;AACH,MAAM,WAAW,WAAW,CAAC,CAAC;IAC5B;;;;;OAKG;IACH,SAAS,CAAC,QAAQ,EAAE,aAAa,CAAC,CAAC,CAAC,GAAG,YAAY,CAAC;CACrD;AAED;;;GAGG;AACH,qBAAa,YAAY,CAAC,CAAC,CAAE,YAAW,WAAW,CAAC,CAAC,CAAC;IACpD,OAAO,CAAC,SAAS,CAA+B;IAEhD;;;;;OAKG;IACH,SAAS,CAAC,QAAQ,EAAE,aAAa,CAAC,CAAC,CAAC,GAAG,YAAY;IAOnD;;;;OAIG;IACG,IAAI,CAAC,IAAI,EAAE,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAUlC;;OAEG;IACH,OAAO,IAAI,IAAI;CAGhB"}

package/src/v0_9/common/events.js

@@ -0,0 +1,58 @@
+/*
+ * Copyright 2025 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * Internal implementation used by the model.
+ * Implements EventSource but also provides the 'emit' method.
+ */
+export class EventEmitter {
+    constructor() {
+        this.listeners = new Set();
+    }
+    /**
+     * Subscribes to the event.
+     *
+     * @param listener The listener function to call when the event is emitted.
+     * @returns A subscription object that can be used to unsubscribe.
+     */
+    subscribe(listener) {
+        this.listeners.add(listener);
+        return {
+            unsubscribe: () => this.listeners.delete(listener),
+        };
+    }
+    /**
+     * Emits an event to all subscribers.
+     *
+     * @param data The data to pass to subscribers.
+     */
+    async emit(data) {
+        for (const listener of this.listeners) {
+            try {
+                await listener(data);
+            }
+            catch (e) {
+                console.error('EventEmitter error:', e);
+            }
+        }
+    }
+    /**
+     * Removes all listeners.
+     */
+    dispose() {
+        this.listeners.clear();
+    }
+}
+//# sourceMappingURL=events.js.map

package/src/v0_9/common/events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.js","sourceRoot":"","sources":["../../../../src/v0_9/common/events.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAyBH;;;GAGG;AACH,MAAM,OAAO,YAAY;IAAzB;QACU,cAAS,GAAG,IAAI,GAAG,EAAoB,CAAC;IAoClD,CAAC;IAlCC;;;;;OAKG;IACH,SAAS,CAAC,QAA0B;QAClC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QAC7B,OAAO;YACL,WAAW,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,QAAQ,CAAC;SACnD,CAAC;IACJ,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,IAAI,CAAC,IAAO;QAChB,KAAK,MAAM,QAAQ,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;YACtC,IAAI,CAAC;gBACH,MAAM,QAAQ,CAAC,IAAI,CAAC,CAAC;YACvB,CAAC;YAAC,OAAO,CAAC,EAAE,CAAC;gBACX,OAAO,CAAC,KAAK,CAAC,qBAAqB,EAAE,CAAC,CAAC,CAAC;YAC1C,CAAC;QACH,CAAC;IACH,CAAC;IAED;;OAEG;IACH,OAAO;QACL,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,CAAC;IACzB,CAAC;CACF"}

package/src/v0_9/common/events.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=events.test.d.ts.map

package/src/v0_9/common/events.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.test.d.ts","sourceRoot":"","sources":["../../../../src/v0_9/common/events.test.ts"],"names":[],"mappings":""}

package/src/v0_9/common/events.test.js

@@ -0,0 +1,58 @@
+/*
+ * Copyright 2025 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import assert from 'node:assert';
+import { describe, it } from 'node:test';
+import { EventEmitter } from './events.js';
+describe('Events', () => {
+    it('handles subscriptions and unsubscriptions correctly', async () => {
+        const emitter = new EventEmitter();
+        let callCount = 0;
+        let lastValue = '';
+        const listener = (val) => {
+            callCount++;
+            lastValue = val;
+        };
+        const sub = emitter.subscribe(listener);
+        await emitter.emit('hello');
+        assert.strictEqual(callCount, 1);
+        assert.strictEqual(lastValue, 'hello');
+        sub.unsubscribe();
+        await emitter.emit('world');
+        assert.strictEqual(callCount, 1); // Should not increase
+        assert.strictEqual(lastValue, 'hello'); // Should not change
+    });
+    it('handles errors thrown by listeners', async () => {
+        const emitter = new EventEmitter();
+        const originalConsoleError = console.error;
+        let errorLogged = false;
+        console.error = (msg, e) => {
+            if (msg === 'EventEmitter error:' && e.message === 'Test Error') {
+                errorLogged = true;
+            }
+        };
+        try {
+            emitter.subscribe(() => {
+                throw new Error('Test Error');
+            });
+            await emitter.emit('trigger');
+            assert.strictEqual(errorLogged, true);
+        }
+        finally {
+            console.error = originalConsoleError;
+        }
+    });
+});
+//# sourceMappingURL=events.test.js.map

package/src/v0_9/common/events.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.test.js","sourceRoot":"","sources":["../../../../src/v0_9/common/events.test.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,MAAM,MAAM,aAAa,CAAC;AACjC,OAAO,EAAC,QAAQ,EAAE,EAAE,EAAC,MAAM,WAAW,CAAC;AACvC,OAAO,EAAC,YAAY,EAAC,MAAM,aAAa,CAAC;AAEzC,QAAQ,CAAC,QAAQ,EAAE,GAAG,EAAE;IACtB,EAAE,CAAC,qDAAqD,EAAE,KAAK,IAAI,EAAE;QACnE,MAAM,OAAO,GAAG,IAAI,YAAY,EAAU,CAAC;QAC3C,IAAI,SAAS,GAAG,CAAC,CAAC;QAClB,IAAI,SAAS,GAAG,EAAE,CAAC;QAEnB,MAAM,QAAQ,GAAG,CAAC,GAAW,EAAE,EAAE;YAC/B,SAAS,EAAE,CAAC;YACZ,SAAS,GAAG,GAAG,CAAC;QAClB,CAAC,CAAC;QAEF,MAAM,GAAG,GAAG,OAAO,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC;QAExC,MAAM,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QAC5B,MAAM,CAAC,WAAW,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC;QACjC,MAAM,CAAC,WAAW,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;QAEvC,GAAG,CAAC,WAAW,EAAE,CAAC;QAElB,MAAM,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QAC5B,MAAM,CAAC,WAAW,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,CAAC,sBAAsB;QACxD,MAAM,CAAC,WAAW,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC,CAAC,oBAAoB;IAC9D,CAAC,CAAC,CAAC;IACH,EAAE,CAAC,oCAAoC,EAAE,KAAK,IAAI,EAAE;QAClD,MAAM,OAAO,GAAG,IAAI,YAAY,EAAU,CAAC;QAC3C,MAAM,oBAAoB,GAAG,OAAO,CAAC,KAAK,CAAC;QAC3C,IAAI,WAAW,GAAG,KAAK,CAAC;QAExB,OAAO,CAAC,KAAK,GAAG,CAAC,GAAW,EAAE,CAAM,EAAE,EAAE;YACtC,IAAI,GAAG,KAAK,qBAAqB,IAAI,CAAC,CAAC,OAAO,KAAK,YAAY,EAAE,CAAC;gBAChE,WAAW,GAAG,IAAI,CAAC;YACrB,CAAC;QACH,CAAC,CAAC;QAEF,IAAI,CAAC;YACH,OAAO,CAAC,SAAS,CAAC,GAAG,EAAE;gBACrB,MAAM,IAAI,KAAK,CAAC,YAAY,CAAC,CAAC;YAChC,CAAC,CAAC,CAAC;YACH,MAAM,OAAO,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;YAC9B,MAAM,CAAC,WAAW,CAAC,WAAW,EAAE,IAAI,CAAC,CAAC;QACxC,CAAC;gBAAS,CAAC;YACT,OAAO,CAAC,KAAK,GAAG,oBAAoB,CAAC;QACvC,CAAC;IACH,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/src/v0_9/errors.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Base class for all A2UI specific errors.
+ *
+ * Includes a machine-readable `code` for categorical handling and ensures
+ * proper stack trace capturing.
+ */
+export declare class A2uiError extends Error {
+    /** A machine-readable string identifying the error category. */
+    readonly code: string;
+    constructor(message: string, code?: string);
+}
+/**
+ * Thrown when JSON validation fails or schemas are mismatched.
+ */
+export declare class A2uiValidationError extends A2uiError {
+    readonly details?: any | undefined;
+    constructor(message: string, details?: any | undefined);
+}
+/**
+ * Thrown during DataModel mutations (invalid paths, type mismatches).
+ */
+export declare class A2uiDataError extends A2uiError {
+    readonly path?: string | undefined;
+    constructor(message: string, path?: string | undefined);
+}
+/**
+ * Thrown during string interpolation and function evaluation.
+ */
+export declare class A2uiExpressionError extends A2uiError {
+    readonly expression?: string | undefined;
+    readonly details?: any | undefined;
+    constructor(message: string, expression?: string | undefined, details?: any | undefined);
+}
+/**
+ * Thrown for structural issues in the UI tree (missing surfaces, duplicate components).
+ */
+export declare class A2uiStateError extends A2uiError {
+    constructor(message: string);
+}
+//# sourceMappingURL=errors.d.ts.map

package/src/v0_9/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../../src/v0_9/errors.ts"],"names":[],"mappings":"AAwBA;;;;;GAKG;AACH,qBAAa,SAAU,SAAQ,KAAK;IAClC,gEAAgE;IAChE,SAAgB,IAAI,EAAE,MAAM,CAAC;gBAEjB,OAAO,EAAE,MAAM,EAAE,IAAI,GAAE,MAAwB;CAU5D;AAED;;GAEG;AACH,qBAAa,mBAAoB,SAAQ,SAAS;aAG9B,OAAO,CAAC,EAAE,GAAG;gBAD7B,OAAO,EAAE,MAAM,EACC,OAAO,CAAC,EAAE,GAAG,YAAA;CAIhC;AAED;;GAEG;AACH,qBAAa,aAAc,SAAQ,SAAS;aAGxB,IAAI,CAAC,EAAE,MAAM;gBAD7B,OAAO,EAAE,MAAM,EACC,IAAI,CAAC,EAAE,MAAM,YAAA;CAIhC;AAED;;GAEG;AACH,qBAAa,mBAAoB,SAAQ,SAAS;aAG9B,UAAU,CAAC,EAAE,MAAM;aACnB,OAAO,CAAC,EAAE,GAAG;gBAF7B,OAAO,EAAE,MAAM,EACC,UAAU,CAAC,EAAE,MAAM,YAAA,EACnB,OAAO,CAAC,EAAE,GAAG,YAAA;CAIhC;AAED;;GAEG;AACH,qBAAa,cAAe,SAAQ,SAAS;gBAC/B,OAAO,EAAE,MAAM;CAG5B"}

package/src/v0_9/errors.js

@@ -0,0 +1,69 @@
+/*
+ * Copyright 2025 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * Base class for all A2UI specific errors.
+ *
+ * Includes a machine-readable `code` for categorical handling and ensures
+ * proper stack trace capturing.
+ */
+export class A2uiError extends Error {
+    constructor(message, code = 'UNKNOWN_ERROR') {
+        super(message);
+        this.name = this.constructor.name;
+        this.code = code;
+        // Maintains proper stack trace for where our error was thrown (only available on V8)
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, this.constructor);
+        }
+    }
+}
+/**
+ * Thrown when JSON validation fails or schemas are mismatched.
+ */
+export class A2uiValidationError extends A2uiError {
+    constructor(message, details) {
+        super(message, 'VALIDATION_ERROR');
+        this.details = details;
+    }
+}
+/**
+ * Thrown during DataModel mutations (invalid paths, type mismatches).
+ */
+export class A2uiDataError extends A2uiError {
+    constructor(message, path) {
+        super(message, 'DATA_ERROR');
+        this.path = path;
+    }
+}
+/**
+ * Thrown during string interpolation and function evaluation.
+ */
+export class A2uiExpressionError extends A2uiError {
+    constructor(message, expression, details) {
+        super(message, 'EXPRESSION_ERROR');
+        this.expression = expression;
+        this.details = details;
+    }
+}
+/**
+ * Thrown for structural issues in the UI tree (missing surfaces, duplicate components).
+ */
+export class A2uiStateError extends A2uiError {
+    constructor(message) {
+        super(message, 'STATE_ERROR');
+    }
+}
+//# sourceMappingURL=errors.js.map

package/src/v0_9/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../../src/v0_9/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAUH;;;;;GAKG;AACH,MAAM,OAAO,SAAU,SAAQ,KAAK;IAIlC,YAAY,OAAe,EAAE,OAAe,eAAe;QACzD,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC;QAClC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QAEjB,qFAAqF;QACrF,IAAK,KAA4B,CAAC,iBAAiB,EAAE,CAAC;YACnD,KAA4B,CAAC,iBAAiB,CAAC,IAAI,EAAE,IAAI,CAAC,WAAW,CAAC,CAAC;QAC1E,CAAC;IACH,CAAC;CACF;AAED;;GAEG;AACH,MAAM,OAAO,mBAAoB,SAAQ,SAAS;IAChD,YACE,OAAe,EACC,OAAa;QAE7B,KAAK,CAAC,OAAO,EAAE,kBAAkB,CAAC,CAAC;QAFnB,YAAO,GAAP,OAAO,CAAM;IAG/B,CAAC;CACF;AAED;;GAEG;AACH,MAAM,OAAO,aAAc,SAAQ,SAAS;IAC1C,YACE,OAAe,EACC,IAAa;QAE7B,KAAK,CAAC,OAAO,EAAE,YAAY,CAAC,CAAC;QAFb,SAAI,GAAJ,IAAI,CAAS;IAG/B,CAAC;CACF;AAED;;GAEG;AACH,MAAM,OAAO,mBAAoB,SAAQ,SAAS;IAChD,YACE,OAAe,EACC,UAAmB,EACnB,OAAa;QAE7B,KAAK,CAAC,OAAO,EAAE,kBAAkB,CAAC,CAAC;QAHnB,eAAU,GAAV,UAAU,CAAS;QACnB,YAAO,GAAP,OAAO,CAAM;IAG/B,CAAC;CACF;AAED;;GAEG;AACH,MAAM,OAAO,cAAe,SAAQ,SAAS;IAC3C,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,EAAE,aAAa,CAAC,CAAC;IAChC,CAAC;CACF"}

package/src/v0_9/index.d.ts

@@ -0,0 +1,152 @@
+/**
+ * Core rendering and state management logic for A2UI v0.9.
+ *
+ * This module exports the fundamental building blocks for building web-based A2UI renderers,
+ * including the data model, component model, and expression parsing logic.
+ */
+export * from './catalog/function_invoker.js';
+export * from './catalog/types.js';
+export * from './common/events.js';
+export * from './processing/message-processor.js';
+export * from './rendering/component-context.js';
+export * from './rendering/data-context.js';
+export * from './rendering/generic-binder.js';
+export * from './schema/index.js';
+export * from './state/component-model.js';
+export * from './state/data-model.js';
+export * from './state/surface-components-model.js';
+export * from './state/surface-group-model.js';
+export * from './state/surface-model.js';
+export * from './errors.js';
+export { effect, Signal, signal } from '@preact/signals-core';
+export declare const Schemas: {
+    A2uiMessageSchemaRaw: {
+        $schema: string;
+        $id: string;
+        title: string;
+        description: string;
+        type: string;
+        oneOf: {
+            $ref: string;
+        }[];
+        $defs: {
+            CreateSurfaceMessage: {
+                type: string;
+                properties: {
+                    version: {
+                        const: string;
+                    };
+                    createSurface: {
+                        type: string;
+                        description: string;
+                        properties: {
+                            surfaceId: {
+                                type: string;
+                                description: string;
+                            };
+                            catalogId: {
+                                description: string;
+                                type: string;
+                            };
+                            theme: {
+                                $ref: string;
+                                description: string;
+                            };
+                            sendDataModel: {
+                                type: string;
+                                description: string;
+                            };
+                        };
+                        required: string[];
+                        additionalProperties: boolean;
+                    };
+                };
+                required: string[];
+                additionalProperties: boolean;
+            };
+            UpdateComponentsMessage: {
+                type: string;
+                properties: {
+                    version: {
+                        const: string;
+                    };
+                    updateComponents: {
+                        type: string;
+                        description: string;
+                        properties: {
+                            surfaceId: {
+                                type: string;
+                                description: string;
+                            };
+                            components: {
+                                type: string;
+                                description: string;
+                                minItems: number;
+                                items: {
+                                    $ref: string;
+                                };
+                            };
+                        };
+                        required: string[];
+                        additionalProperties: boolean;
+                    };
+                };
+                required: string[];
+                additionalProperties: boolean;
+            };
+            UpdateDataModelMessage: {
+                type: string;
+                properties: {
+                    version: {
+                        const: string;
+                    };
+                    updateDataModel: {
+                        type: string;
+                        description: string;
+                        properties: {
+                            surfaceId: {
+                                type: string;
+                                description: string;
+                            };
+                            path: {
+                                type: string;
+                                description: string;
+                            };
+                            value: {
+                                description: string;
+                                additionalProperties: boolean;
+                            };
+                        };
+                        required: string[];
+                        additionalProperties: boolean;
+                    };
+                };
+                required: string[];
+                additionalProperties: boolean;
+            };
+            DeleteSurfaceMessage: {
+                type: string;
+                properties: {
+                    version: {
+                        const: string;
+                    };
+                    deleteSurface: {
+                        type: string;
+                        description: string;
+                        properties: {
+                            surfaceId: {
+                                type: string;
+                                description: string;
+                            };
+                        };
+                        required: string[];
+                        additionalProperties: boolean;
+                    };
+                };
+                required: string[];
+                additionalProperties: boolean;
+            };
+        };
+    };
+};
+//# sourceMappingURL=index.d.ts.map

package/src/v0_9/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/v0_9/index.ts"],"names":[],"mappings":"AAgBA;;;;;GAKG;AAEH,cAAc,+BAA+B,CAAC;AAC9C,cAAc,oBAAoB,CAAC;AACnC,cAAc,oBAAoB,CAAC;AACnC,cAAc,mCAAmC,CAAC;AAClD,cAAc,kCAAkC,CAAC;AACjD,cAAc,6BAA6B,CAAC;AAC5C,cAAc,+BAA+B,CAAC;AAC9C,cAAc,mBAAmB,CAAC;AAClC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,uBAAuB,CAAC;AACtC,cAAc,qCAAqC,CAAC;AACpD,cAAc,gCAAgC,CAAC;AAC/C,cAAc,0BAA0B,CAAC;AACzC,cAAc,aAAa,CAAC;AAE5B,OAAO,EAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAC,MAAM,sBAAsB,CAAC;AAI5D,eAAO,MAAM,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAEnB,CAAC"}