@a2ui/web_core 0.8.0 → 0.9.1-alpha.0

package/src/v0_9/schemas/server_to_client.json

@@ -0,0 +1,131 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "https://a2ui.org/specification/v0_9/server_to_client.json",
+    "title": "A2UI Message Schema",
+    "description": "Describes a JSON payload for an A2UI (Agent to UI) message, which is used to dynamically construct and update user interfaces.",
+    "type": "object",
+    "oneOf": [
+        { "$ref": "#/$defs/CreateSurfaceMessage" },
+        { "$ref": "#/$defs/UpdateComponentsMessage" },
+        { "$ref": "#/$defs/UpdateDataModelMessage" },
+        { "$ref": "#/$defs/DeleteSurfaceMessage" }
+    ],
+    "$defs": {
+        "CreateSurfaceMessage": {
+            "type": "object",
+            "properties": {
+                "version": {
+                    "const": "v0.9"
+                },
+                "createSurface": {
+                    "type": "object",
+                    "description": "Signals the client to create a new surface and begin rendering it. When this message is sent, the client will expect 'updateComponents' and/or 'updateDataModel' messages for the same surfaceId that define the component tree.",
+                    "properties": {
+                        "surfaceId": {
+                            "type": "string",
+                            "description": "The unique identifier for the UI surface to be rendered."
+                        },
+                        "catalogId": {
+                            "description": "A string that uniquely identifies this catalog. It is recommended to prefix this with an internet domain that you own, to avoid conflicts e.g. mycompany.com:somecatalog'.",
+                            "type": "string"
+                        },
+                        "theme": {
+                            "$ref": "catalog.json#/$defs/theme",
+                            "description": "Theme parameters for the surface (e.g., {'primaryColor': '#FF0000'}). These must validate against the 'theme' schema defined in the catalog."
+                        },
+                        "sendDataModel": {
+                            "type": "boolean",
+                            "description": "If true, the client will send the full data model of this surface in the metadata of every A2A message sent to the server that created the surface. Defaults to false."
+                        }
+                    },
+                    "required": ["surfaceId", "catalogId"],
+                    "additionalProperties": false
+                }
+            },
+            "required": ["createSurface", "version"],
+            "additionalProperties": false
+        },
+        "UpdateComponentsMessage": {
+            "type": "object",
+            "properties": {
+                "version": {
+                    "const": "v0.9"
+                },
+                "updateComponents": {
+                    "type": "object",
+                    "description": "Updates a surface with a new set of components. This message can be sent multiple times to update the component tree of an existing surface. One of the components in one of the components lists MUST have an 'id' of 'root' to serve as the root of the component tree. The createSurface message MUST have been previously sent with the 'catalogId' that is in this message.",
+                    "properties": {
+                        "surfaceId": {
+                            "type": "string",
+                            "description": "The unique identifier for the UI surface to be updated."
+                        },
+                        "components": {
+                            "type": "array",
+                            "description": "A list containing all UI components for the surface.",
+                            "minItems": 1,
+                            "items": {
+                                "$ref": "catalog.json#/$defs/anyComponent"
+                            }
+                        }
+                    },
+                    "required": ["surfaceId", "components"],
+                    "additionalProperties": false
+                }
+            },
+            "required": ["updateComponents", "version"],
+            "additionalProperties": false
+        },
+        "UpdateDataModelMessage": {
+            "type": "object",
+            "properties": {
+                "version": {
+                    "const": "v0.9"
+                },
+                "updateDataModel": {
+                    "type": "object",
+                    "description": "Updates the data model for an existing surface. This message can be sent multiple times to update the data model. The createSurface message MUST have been previously sent with the 'catalogId' that is in this message.",
+                    "properties": {
+                        "surfaceId": {
+                            "type": "string",
+                            "description": "The unique identifier for the UI surface this data model update applies to."
+                        },
+                        "path": {
+                            "type": "string",
+                            "description": "An optional path to a location within the data model (e.g., '/user/name'). If omitted, or set to '/', refers to the entire data model."
+                        },
+                        "value": {
+                            "description": "The data to be updated in the data model. If present, the value at 'path' is replaced (or created). If omitted, the key at 'path' is removed.",
+                            "additionalProperties": true
+                        }
+                    },
+                    "required": ["surfaceId"],
+                    "additionalProperties": false
+                }
+            },
+            "required": ["updateDataModel", "version"],
+            "additionalProperties": false
+        },
+        "DeleteSurfaceMessage": {
+            "type": "object",
+            "properties": {
+                "version": {
+                    "const": "v0.9"
+                },
+                "deleteSurface": {
+                    "type": "object",
+                    "description": "Signals the client to delete the surface identified by 'surfaceId'. The createSurface message MUST have been previously sent with the 'catalogId' that is in this message.",
+                    "properties": {
+                        "surfaceId": {
+                            "type": "string",
+                            "description": "The unique identifier for the UI surface to be deleted."
+                        }
+                    },
+                    "required": ["surfaceId"],
+                    "additionalProperties": false
+                }
+            },
+            "required": ["deleteSurface", "version"],
+            "additionalProperties": false
+        }
+    }
+}

package/src/v0_9/schemas/server_to_client_list.json

@@ -0,0 +1,19 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "https://a2ui.org/specification/v0_9/server_to_client_list.json",
+    "title": "A2UI Server-to-Client Message List",
+    "description": "A list of A2UI Server-to-Client messages.",
+    "type": "object",
+    "properties": {
+        "messages": {
+            "type": "array",
+            "items": {
+                "$ref": "server_to_client.json"
+            }
+        }
+    },
+    "additionalProperties": false,
+    "required": [
+        "messages"
+    ]
+}

package/src/v0_9/state/component-model.d.ts

@@ -0,0 +1,36 @@
+import { EventSource } from '../common/events.js';
+/**
+ * Represents the state model for an individual UI component.
+ */
+export declare class ComponentModel {
+    readonly id: string;
+    readonly type: string;
+    private _properties;
+    private readonly _onUpdated;
+    /**
+     * Fires whenever the component's properties are updated.
+     */
+    readonly onUpdated: EventSource<ComponentModel>;
+    /**
+     * Creates a new component model.
+     *
+     * @param id The unique identifier for this component.
+     * @param type The component type name.
+     * @param initialProperties The initial properties for the component.
+     */
+    constructor(id: string, type: string, initialProperties: Record<string, any>);
+    /**
+     * The current properties of the component.
+     */
+    get properties(): Record<string, any>;
+    set properties(newProperties: Record<string, any>);
+    /**
+     * Disposes of the component and its resources.
+     */
+    dispose(): void;
+    /**
+     * Returns a JSON representation of the component tree.
+     */
+    get componentTree(): any;
+}
+//# sourceMappingURL=component-model.d.ts.map

package/src/v0_9/state/component-model.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"component-model.d.ts","sourceRoot":"","sources":["../../../../src/v0_9/state/component-model.ts"],"names":[],"mappings":"AAgBA,OAAO,EAAe,WAAW,EAAC,MAAM,qBAAqB,CAAC;AAE9D;;GAEG;AACH,qBAAa,cAAc;IAiBvB,QAAQ,CAAC,EAAE,EAAE,MAAM;IACnB,QAAQ,CAAC,IAAI,EAAE,MAAM;IAjBvB,OAAO,CAAC,WAAW,CAAsB;IACzC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAsC;IAEjE;;OAEG;IACH,QAAQ,CAAC,SAAS,EAAE,WAAW,CAAC,cAAc,CAAC,CAAmB;IAElE;;;;;;OAMG;gBAEQ,EAAE,EAAE,MAAM,EACV,IAAI,EAAE,MAAM,EACrB,iBAAiB,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC;IAKxC;;OAEG;IACH,IAAI,UAAU,IAAI,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAEpC;IAED,IAAI,UAAU,CAAC,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAGhD;IAED;;OAEG;IACH,OAAO,IAAI,IAAI;IAIf;;OAEG;IACH,IAAI,aAAa,IAAI,GAAG,CAMvB;CACF"}

package/src/v0_9/state/component-model.js

@@ -0,0 +1,65 @@
+/*
+ * 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 { EventEmitter } from '../common/events.js';
+/**
+ * Represents the state model for an individual UI component.
+ */
+export class ComponentModel {
+    /**
+     * Creates a new component model.
+     *
+     * @param id The unique identifier for this component.
+     * @param type The component type name.
+     * @param initialProperties The initial properties for the component.
+     */
+    constructor(id, type, initialProperties) {
+        this.id = id;
+        this.type = type;
+        this._onUpdated = new EventEmitter();
+        /**
+         * Fires whenever the component's properties are updated.
+         */
+        this.onUpdated = this._onUpdated;
+        this._properties = initialProperties;
+    }
+    /**
+     * The current properties of the component.
+     */
+    get properties() {
+        return this._properties;
+    }
+    set properties(newProperties) {
+        this._properties = newProperties;
+        this._onUpdated.emit(this);
+    }
+    /**
+     * Disposes of the component and its resources.
+     */
+    dispose() {
+        this._onUpdated.dispose();
+    }
+    /**
+     * Returns a JSON representation of the component tree.
+     */
+    get componentTree() {
+        return {
+            id: this.id,
+            type: this.type,
+            ...this._properties,
+        };
+    }
+}
+//# sourceMappingURL=component-model.js.map

package/src/v0_9/state/component-model.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"component-model.js","sourceRoot":"","sources":["../../../../src/v0_9/state/component-model.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAC,YAAY,EAAc,MAAM,qBAAqB,CAAC;AAE9D;;GAEG;AACH,MAAM,OAAO,cAAc;IASzB;;;;;;OAMG;IACH,YACW,EAAU,EACV,IAAY,EACrB,iBAAsC;QAF7B,OAAE,GAAF,EAAE,CAAQ;QACV,SAAI,GAAJ,IAAI,CAAQ;QAhBN,eAAU,GAAG,IAAI,YAAY,EAAkB,CAAC;QAEjE;;WAEG;QACM,cAAS,GAAgC,IAAI,CAAC,UAAU,CAAC;QAchE,IAAI,CAAC,WAAW,GAAG,iBAAiB,CAAC;IACvC,CAAC;IAED;;OAEG;IACH,IAAI,UAAU;QACZ,OAAO,IAAI,CAAC,WAAW,CAAC;IAC1B,CAAC;IAED,IAAI,UAAU,CAAC,aAAkC;QAC/C,IAAI,CAAC,WAAW,GAAG,aAAa,CAAC;QACjC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC7B,CAAC;IAED;;OAEG;IACH,OAAO;QACL,IAAI,CAAC,UAAU,CAAC,OAAO,EAAE,CAAC;IAC5B,CAAC;IAED;;OAEG;IACH,IAAI,aAAa;QACf,OAAO;YACL,EAAE,EAAE,IAAI,CAAC,EAAE;YACX,IAAI,EAAE,IAAI,CAAC,IAAI;YACf,GAAG,IAAI,CAAC,WAAW;SACpB,CAAC;IACJ,CAAC;CACF"}

package/{dist/src → src}/v0_9/state/component-model.test.js

@@ -1,3 +1,18 @@
+/*
+ * 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, beforeEach } from 'node:test';
 import { ComponentModel } from './component-model.js';
@@ -35,5 +50,13 @@ describe('ComponentModel', () => {
         component.properties = { label: '2' };
         assert.strictEqual(callCount, 1);
     });
+    it('returns component tree representation', () => {
+        const tree = component.componentTree;
+        assert.deepStrictEqual(tree, {
+            id: 'c1',
+            type: 'Button',
+            label: 'Click Me',
+        });
+    });
 });
 //# sourceMappingURL=component-model.test.js.map

package/src/v0_9/state/component-model.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"component-model.test.js","sourceRoot":"","sources":["../../../../src/v0_9/state/component-model.test.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,MAAM,MAAM,aAAa,CAAC;AACjC,OAAO,EAAC,QAAQ,EAAE,EAAE,EAAE,UAAU,EAAC,MAAM,WAAW,CAAC;AACnD,OAAO,EAAC,cAAc,EAAC,MAAM,sBAAsB,CAAC;AAEpD,QAAQ,CAAC,gBAAgB,EAAE,GAAG,EAAE;IAC9B,IAAI,SAAyB,CAAC;IAE9B,UAAU,CAAC,GAAG,EAAE;QACd,SAAS,GAAG,IAAI,cAAc,CAAC,IAAI,EAAE,QAAQ,EAAE,EAAC,KAAK,EAAE,UAAU,EAAC,CAAC,CAAC;IACtE,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,wBAAwB,EAAE,GAAG,EAAE;QAChC,MAAM,CAAC,WAAW,CAAC,SAAS,CAAC,EAAE,EAAE,IAAI,CAAC,CAAC;QACvC,MAAM,CAAC,WAAW,CAAC,SAAS,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;QAC7C,MAAM,CAAC,WAAW,CAAC,SAAS,CAAC,UAAU,CAAC,KAAK,EAAE,UAAU,CAAC,CAAC;IAC7D,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,oBAAoB,EAAE,GAAG,EAAE;QAC5B,SAAS,CAAC,UAAU,GAAG,EAAC,KAAK,EAAE,SAAS,EAAC,CAAC;QAC1C,MAAM,CAAC,WAAW,CAAC,SAAS,CAAC,UAAU,CAAC,KAAK,EAAE,SAAS,CAAC,CAAC;IAC5D,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,8BAA8B,EAAE,GAAG,EAAE;QACtC,IAAI,gBAA4C,CAAC;QAEjD,SAAS,CAAC,SAAS,CAAC,SAAS,CAAC,CAAC,CAAiB,EAAE,EAAE;YAClD,gBAAgB,GAAG,CAAC,CAAC;QACvB,CAAC,CAAC,CAAC;QAEH,SAAS,CAAC,UAAU,GAAG,EAAC,KAAK,EAAE,KAAK,EAAC,CAAC;QAEtC,MAAM,CAAC,WAAW,CAAC,gBAAgB,EAAE,SAAS,CAAC,CAAC;QAChD,MAAM,CAAC,WAAW,CAAC,gBAAgB,EAAE,UAAU,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;IAChE,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,wBAAwB,EAAE,GAAG,EAAE;QAChC,IAAI,SAAS,GAAG,CAAC,CAAC;QAElB,MAAM,GAAG,GAAG,SAAS,CAAC,SAAS,CAAC,SAAS,CAAC,GAAG,EAAE;YAC7C,SAAS,EAAE,CAAC;QACd,CAAC,CAAC,CAAC;QAEH,SAAS,CAAC,UAAU,GAAG,EAAC,KAAK,EAAE,GAAG,EAAC,CAAC;QACpC,MAAM,CAAC,WAAW,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC;QAEjC,GAAG,CAAC,WAAW,EAAE,CAAC;QAClB,SAAS,CAAC,UAAU,GAAG,EAAC,KAAK,EAAE,GAAG,EAAC,CAAC;QACpC,MAAM,CAAC,WAAW,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC;IACnC,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,uCAAuC,EAAE,GAAG,EAAE;QAC/C,MAAM,IAAI,GAAG,SAAS,CAAC,aAAa,CAAC;QACrC,MAAM,CAAC,eAAe,CAAC,IAAI,EAAE;YAC3B,EAAE,EAAE,IAAI;YACR,IAAI,EAAE,QAAQ;YACd,KAAK,EAAE,UAAU;SAClB,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/src/v0_9/state/data-model.d.ts

@@ -0,0 +1,75 @@
+import { Subscription as BaseSubscription } from '../common/events.js';
+import { Signal } from '@preact/signals-core';
+/**
+ * Represents a reactive connection to a specific path in the data model.
+ */
+export interface DataSubscription<T> extends BaseSubscription {
+    /**
+     * The current value at the subscribed path.
+     */
+    readonly value: T | undefined;
+}
+/**
+ * A standalone, observable data store representing the client-side state.
+ * It handles JSON Pointer path resolution and subscription management.
+ */
+export declare class DataModel {
+    private data;
+    private readonly signals;
+    private readonly subscriptions;
+    /**
+     * Creates a new data model.
+     *
+     * @param initialData The initial data for the model. Defaults to an empty object.
+     */
+    constructor(initialData?: Record<string, unknown>);
+    /**
+     * Retrieves a Preact Signal for a specific data path.
+     *
+     * This provides a reactive way to access a value. If the value at the path changes via `set()`,
+     * the signal will automatically be updated.
+     *
+     * @param path The JSON pointer path to create or retrieve a signal for.
+     * @returns A Preact Signal representing the value at the specified path.
+     */
+    getSignal<T>(path: string): Signal<T | undefined>;
+    /**
+     * Updates the model at the specific path and notifies all relevant signals.
+     * If path is '/' or empty, replaces the entire root.
+     *
+     * Note on `undefined` values:
+     * - For objects: Setting a property to `undefined` removes the key from the object.
+     * - For arrays: Setting an index to `undefined` sets that index to `undefined` but preserves the array length (sparse array).
+     */
+    set(path: string, value: any): this;
+    /**
+     * Retrieves data at a specific JSON pointer path.
+     *
+     * @param path The JSON pointer path to read from.
+     * @returns The value at the specified path, or undefined if not found.
+     */
+    get(path: string): any;
+    /**
+     * Subscribes to changes at the specified data path.
+     *
+     * This is a backwards-compatible layer using Preact Signals internally. It allows
+     * listeners to be notified whenever the value at the specified path (or any of its
+     * ancestors/descendants) changes.
+     *
+     * @param path The JSON pointer path to observe.
+     * @param onChange A callback fired whenever the value changes.
+     * @returns A `DataSubscription` containing the initial value and an `unsubscribe` method.
+     */
+    subscribe<T>(path: string, onChange: (value: T | undefined) => void): DataSubscription<T>;
+    /**
+     * Clears all internal subscriptions.
+     */
+    dispose(): void;
+    private normalizePath;
+    private parsePath;
+    private notifySignals;
+    private updateSignal;
+    private notifyAllSignals;
+    private isDescendant;
+}
+//# sourceMappingURL=data-model.d.ts.map

package/src/v0_9/state/data-model.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"data-model.d.ts","sourceRoot":"","sources":["../../../../src/v0_9/state/data-model.ts"],"names":[],"mappings":"AAgBA,OAAO,EAAC,YAAY,IAAI,gBAAgB,EAAC,MAAM,qBAAqB,CAAC;AAErE,OAAO,EAAS,MAAM,EAAgB,MAAM,sBAAsB,CAAC;AAEnE;;GAEG;AACH,MAAM,WAAW,gBAAgB,CAAC,CAAC,CAAE,SAAQ,gBAAgB;IAC3D;;OAEG;IACH,QAAQ,CAAC,KAAK,EAAE,CAAC,GAAG,SAAS,CAAC;CAC/B;AAMD;;;GAGG;AACH,qBAAa,SAAS;IACpB,OAAO,CAAC,IAAI,CAA+B;IAC3C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAuC;IAC/D,OAAO,CAAC,QAAQ,CAAC,aAAa,CAA8B;IAE5D;;;;OAIG;gBACS,WAAW,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM;IAIrD;;;;;;;;OAQG;IACH,SAAS,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC,CAAC,GAAG,SAAS,CAAC;IAQjD;;;;;;;OAOG;IACH,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,GAAG,IAAI;IAsEnC;;;;;OAKG;IACH,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,GAAG;IAmBtB;;;;;;;;;;OAUG;IACH,SAAS,CAAC,CAAC,EACT,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,CAAC,KAAK,EAAE,CAAC,GAAG,SAAS,KAAK,IAAI,GACvC,gBAAgB,CAAC,CAAC,CAAC;IA2BtB;;OAEG;IACH,OAAO,IAAI,IAAI;IAQf,OAAO,CAAC,aAAa;IAOrB,OAAO,CAAC,SAAS;IAIjB,OAAO,CAAC,aAAa;IAuBrB,OAAO,CAAC,YAAY;IAcpB,OAAO,CAAC,gBAAgB;IAQxB,OAAO,CAAC,YAAY;CAMrB"}

package/src/v0_9/state/data-model.js

@@ -0,0 +1,235 @@
+/*
+ * 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 { A2uiDataError } from '../errors.js';
+import { signal, batch, effect } from '@preact/signals-core';
+function isNumeric(value) {
+    return /^\d+$/.test(value);
+}
+/**
+ * A standalone, observable data store representing the client-side state.
+ * It handles JSON Pointer path resolution and subscription management.
+ */
+export class DataModel {
+    /**
+     * Creates a new data model.
+     *
+     * @param initialData The initial data for the model. Defaults to an empty object.
+     */
+    constructor(initialData = {}) {
+        this.data = {};
+        this.signals = new Map();
+        this.subscriptions = new Set(); // To track direct subscriptions for dispose
+        this.data = initialData;
+    }
+    /**
+     * Retrieves a Preact Signal for a specific data path.
+     *
+     * This provides a reactive way to access a value. If the value at the path changes via `set()`,
+     * the signal will automatically be updated.
+     *
+     * @param path The JSON pointer path to create or retrieve a signal for.
+     * @returns A Preact Signal representing the value at the specified path.
+     */
+    getSignal(path) {
+        const normalizedPath = this.normalizePath(path);
+        if (!this.signals.has(normalizedPath)) {
+            this.signals.set(normalizedPath, signal(this.get(normalizedPath)));
+        }
+        return this.signals.get(normalizedPath);
+    }
+    /**
+     * Updates the model at the specific path and notifies all relevant signals.
+     * If path is '/' or empty, replaces the entire root.
+     *
+     * Note on `undefined` values:
+     * - For objects: Setting a property to `undefined` removes the key from the object.
+     * - For arrays: Setting an index to `undefined` sets that index to `undefined` but preserves the array length (sparse array).
+     */
+    set(path, value) {
+        if (path === null || path === undefined) {
+            throw new A2uiDataError('Path cannot be null or undefined.');
+        }
+        if (path === '/' || path === '') {
+            this.data = value;
+            this.notifyAllSignals();
+            return this;
+        }
+        const segments = this.parsePath(path);
+        const lastSegment = segments.pop();
+        if (!this.data) {
+            this.data = {};
+        }
+        let current = this.data;
+        for (let i = 0; i < segments.length; i++) {
+            const segment = segments[i];
+            if (Array.isArray(current) && !isNumeric(segment)) {
+                throw new A2uiDataError(`Cannot use non-numeric segment '${segment}' on an array in path '${path}'.`, path);
+            }
+            // If we encounter a primitive where a container is expected, we cannot proceed.
+            // We allow undefined/null to be overwritten by a new container.
+            if (current[segment] !== undefined &&
+                current[segment] !== null &&
+                typeof current[segment] !== 'object') {
+                throw new A2uiDataError(`Cannot set path '${path}': segment '${segment}' is a primitive value.`, path);
+            }
+            if (current[segment] === undefined || current[segment] === null) {
+                const nextSegment = i < segments.length - 1 ? segments[i + 1] : lastSegment;
+                current[segment] = isNumeric(nextSegment) ? [] : {};
+            }
+            current = current[segment];
+        }
+        if (Array.isArray(current) && !isNumeric(lastSegment)) {
+            throw new A2uiDataError(`Cannot use non-numeric segment '${lastSegment}' on an array in path '${path}'.`, path);
+        }
+        if (value === undefined) {
+            if (Array.isArray(current)) {
+                current[parseInt(lastSegment, 10)] = undefined;
+            }
+            else {
+                delete current[lastSegment];
+            }
+        }
+        else {
+            current[lastSegment] = value;
+        }
+        this.notifySignals(path);
+        return this;
+    }
+    /**
+     * Retrieves data at a specific JSON pointer path.
+     *
+     * @param path The JSON pointer path to read from.
+     * @returns The value at the specified path, or undefined if not found.
+     */
+    get(path) {
+        if (path === null || path === undefined) {
+            throw new A2uiDataError('Path cannot be null or undefined.');
+        }
+        if (path === '/' || path === '') {
+            return this.data;
+        }
+        const segments = this.parsePath(path);
+        let current = this.data;
+        for (const segment of segments) {
+            if (current === undefined || current === null) {
+                return undefined;
+            }
+            current = current[segment];
+        }
+        return current;
+    }
+    /**
+     * Subscribes to changes at the specified data path.
+     *
+     * This is a backwards-compatible layer using Preact Signals internally. It allows
+     * listeners to be notified whenever the value at the specified path (or any of its
+     * ancestors/descendants) changes.
+     *
+     * @param path The JSON pointer path to observe.
+     * @param onChange A callback fired whenever the value changes.
+     * @returns A `DataSubscription` containing the initial value and an `unsubscribe` method.
+     */
+    subscribe(path, onChange) {
+        const sig = this.getSignal(path);
+        let isSync = true;
+        let currentValue = sig.peek();
+        const dispose = effect(() => {
+            const val = sig.value;
+            currentValue = val;
+            if (!isSync) {
+                onChange(val);
+            }
+        });
+        isSync = false;
+        this.subscriptions.add(dispose);
+        return {
+            get value() {
+                return currentValue;
+            },
+            unsubscribe: () => {
+                dispose();
+                this.subscriptions.delete(dispose);
+            },
+        };
+    }
+    /**
+     * Clears all internal subscriptions.
+     */
+    dispose() {
+        for (const dispose of this.subscriptions) {
+            dispose();
+        }
+        this.subscriptions.clear();
+        this.signals.clear();
+    }
+    normalizePath(path) {
+        if (path.length > 1 && path.endsWith('/')) {
+            return path.slice(0, -1);
+        }
+        return path || '/';
+    }
+    parsePath(path) {
+        return path.split('/').filter(p => p.length > 0);
+    }
+    notifySignals(path) {
+        const normalizedPath = this.normalizePath(path);
+        batch(() => {
+            this.updateSignal(normalizedPath);
+            // Notify Ancestors
+            let parentPath = normalizedPath;
+            while (parentPath !== '/' && parentPath !== '') {
+                parentPath =
+                    parentPath.substring(0, parentPath.lastIndexOf('/')) || '/';
+                this.updateSignal(parentPath);
+            }
+            // Notify Descendants
+            for (const subPath of this.signals.keys()) {
+                if (this.isDescendant(subPath, normalizedPath)) {
+                    this.updateSignal(subPath);
+                }
+            }
+        });
+    }
+    updateSignal(path) {
+        const sig = this.signals.get(path);
+        if (sig) {
+            const val = this.get(path);
+            if (Array.isArray(val)) {
+                sig.value = [...val];
+            }
+            else if (typeof val === 'object' && val !== null) {
+                sig.value = { ...val };
+            }
+            else {
+                sig.value = val;
+            }
+        }
+    }
+    notifyAllSignals() {
+        batch(() => {
+            for (const path of this.signals.keys()) {
+                this.updateSignal(path);
+            }
+        });
+    }
+    isDescendant(childPath, parentPath) {
+        if (parentPath === '/' || parentPath === '') {
+            return childPath !== '/';
+        }
+        return childPath.startsWith(parentPath + '/');
+    }
+}
+//# sourceMappingURL=data-model.js.map

package/src/v0_9/state/data-model.js.map

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