@syntrologie/adapt-chatbot 2.26.0 → 2.28.0

package/dist/elements/ActionHandler.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Action element handler — dispatches an ActionStep through
+ * `ActionEngine.applyBatch`.
+ *
+ * The `content` field of an action `MountedElement` carries the action's
+ * params; the executor `kind` comes from the template (which the SDK
+ * doesn't have locally yet — for v1 the template's `kind` is encoded
+ * into `content.__kind`, set by the backend tool). When proper
+ * template loading lands on the SDK side, this handler resolves the
+ * kind from the loaded template instead.
+ *
+ * **Imperative actions never re-fire on boot.** The `lifecycle` field
+ * here is `imperative` — `ElementInstanceStore` skips boot rehydrate
+ * for imperative instances with `state === 'applied'`. The backend
+ * record exists for audit; replaying a scroll/navigate on every page
+ * load would be visibly wrong.
+ *
+ * Stateful actions (e.g. `content:insertHtml`, `content:setText`,
+ * `content:addClass` once Phase 7's renderer lands) ARE re-applied on
+ * boot. v1 supports the imperative shape; stateful action handling
+ * waits on the Portable Text renderer.
+ */
+import type { ElementHandlerContext, ElementTypeHandler, ValidateResult } from './ElementTypeHandler';
+import type { MountedElement } from './types';
+export declare class ActionHandler implements ElementTypeHandler {
+    readonly typeName: "action";
+    readonly lifecycle: "imperative";
+    validate(instance: MountedElement, _ctx: ElementHandlerContext): ValidateResult;
+    mount(instance: MountedElement, ctx: ElementHandlerContext): Promise<void>;
+    patch(instance: MountedElement, ctx: ElementHandlerContext): Promise<void>;
+    unmount(_instance: MountedElement, _ctx: ElementHandlerContext): Promise<void>;
+    private _actionFromInstance;
+}
+//# sourceMappingURL=ActionHandler.d.ts.map

package/dist/elements/ActionHandler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ActionHandler.d.ts","sourceRoot":"","sources":["../../src/elements/ActionHandler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAGH,OAAO,KAAK,EACV,qBAAqB,EACrB,kBAAkB,EAClB,cAAc,EACf,MAAM,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAE9C,qBAAa,aAAc,YAAW,kBAAkB;IACtD,QAAQ,CAAC,QAAQ,EAAG,QAAQ,CAAU;IAGtC,QAAQ,CAAC,SAAS,EAAG,YAAY,CAAU;IAE3C,QAAQ,CAAC,QAAQ,EAAE,cAAc,EAAE,IAAI,EAAE,qBAAqB,GAAG,cAAc;IAWzE,KAAK,CAAC,QAAQ,EAAE,cAAc,EAAE,GAAG,EAAE,qBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC;IAK1E,KAAK,CAAC,QAAQ,EAAE,cAAc,EAAE,GAAG,EAAE,qBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC;IAQ1E,OAAO,CAAC,SAAS,EAAE,cAAc,EAAE,IAAI,EAAE,qBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC;IAMpF,OAAO,CAAC,mBAAmB;CAiC5B"}

package/dist/elements/ElementInstanceStore.d.ts

@@ -0,0 +1,155 @@
+/**
+ * Type-neutral store for LLM-authored UI element instances — Phase 6.
+ *
+ * On SDK boot:
+ *   1. Caller fetches `/api/adaptive/mounted_elements` (see `fetcher.ts`).
+ *   2. Calls `store.hydrate(response.mounted_elements)`.
+ *   3. The store iterates each instance, looks up its handler, and
+ *      either mounts (stateful) or skips (imperative already-applied).
+ *
+ * During chat turns:
+ *   - AGUI `syntro.element.mutation` envelopes arrive via
+ *     `AgUiTransport.onA2UIEvent`. The transport caller decodes the
+ *     envelope and invokes `store.apply(envelope.mutations)`.
+ *
+ * Concurrency / dedup:
+ *   - Per-instance `version` is the dedup key. A mutation whose version
+ *     is `<= currentVersion` is treated as already-applied and silently
+ *     dropped — handles the SSE-during-boot-fetch race per the design
+ *     doc (the live mutation might arrive before the boot snapshot does,
+ *     and the snapshot is then a no-op).
+ *   - The store is single-threaded by Node/browser convention; no
+ *     cross-tab sync in v1.
+ *
+ * The store delegates all DOM work to per-type handlers
+ * (`ElementTypeHandler`). It owns the registry, the in-memory state,
+ * and the dispatch logic.
+ */
+import type { ActionEngine } from '../types';
+import type { ElementTypeHandler } from './ElementTypeHandler';
+import type { ElementMutation, MountedElement } from './types';
+export interface ElementInstanceStoreOptions {
+    actions: ActionEngine;
+    /** Runtime's event bus. ItemHandler publishes
+     *  `element.compositional_append` events here so container widgets
+     *  (chips strip, FAQ accordion, nav tips) can subscribe and inject
+     *  LLM-authored items into their compositional-actions lists.
+     *
+     *  When `subscribe` is also provided, the store listens for
+     *  `element.compositional_replay_request` events. A container widget
+     *  publishes this event with its `tile_id` whenever it subscribes
+     *  (e.g. on first mount AND on SPA-navigation remount); the store
+     *  responds by re-publishing `element.compositional_append` for every
+     *  matching item still in its in-memory map. This is what makes
+     *  LLM-authored items persist across navigations within the page
+     *  session — the store survives chat-bar unmount/remount, container
+     *  widgets re-pull on each fresh mount.
+     */
+    events?: {
+        publish: (name: string, props?: Record<string, unknown>) => void;
+        /**
+         * Overloaded to match the runtime SDK's `EventBus.subscribe`:
+         * pass `{names:[...]}` to filter, or a callback to receive every
+         * event. The store uses the filtered form so it doesn't fan
+         * unrelated traffic (PostHog autocapture, every action lifecycle
+         * event) into a string-compare on each delivery.
+         */
+        subscribe?: {
+            (filter: {
+                names?: string[];
+            }, handler: (event: {
+                name: string;
+                props?: Record<string, unknown>;
+            }) => void): () => void;
+            (handler: (event: {
+                name: string;
+                props?: Record<string, unknown>;
+            }) => void): () => void;
+        };
+    };
+    handlers?: ElementTypeHandler[];
+    /** Override the logger — used by tests to capture log output. */
+    logger?: Pick<Console, 'info' | 'warn' | 'error'>;
+    /**
+     * Optional template→widget resolver used by the rehydrate replay.
+     * Without this, replayed tile mounts emit ``widget: template_id``,
+     * which only works when the admin's template ids match the widget
+     * registry (e.g. ``adaptive-faq:accordion``). When an admin uses a
+     * friendly id like ``product-card`` mapping to widget
+     * ``adaptive-product:card``, the rehydrate path needs the resolver
+     * to match the live mount path.
+     *
+     * Same shape as ``TileHandler``'s resolver — pass the same function
+     * to both so live mounts and replays agree on the widget id.
+     */
+    resolveTileWidget?: (templateId: string) => string | undefined;
+}
+export declare class ElementInstanceStore {
+    private readonly _actions;
+    private readonly _events;
+    private readonly _handlers;
+    private readonly _instances;
+    private readonly _logger;
+    private readonly _resolveTileWidget?;
+    /** Active TTL timeout — replaced on each call to `scheduleClientTtl`. */
+    private _ttlTimer;
+    constructor(options: ElementInstanceStoreOptions);
+    /**
+     * Listen for `element.compositional_replay_request` from container
+     * widgets and re-publish `element.compositional_append` for every
+     * matching item still tracked in `_instances`. This keeps LLM-authored
+     * items visible across SPA navigations: the store is a module-level
+     * singleton that survives chat-bar unmount/remount, so when a fresh
+     * chips-strip mounts and subscribes, asking for a replay re-populates
+     * its chip array.
+     */
+    private _subscribeReplayRequests;
+    private _replayItems;
+    private _replayTiles;
+    registerHandler(handler: ElementTypeHandler): void;
+    /**
+     * Apply the server-provided boot snapshot. For each instance:
+     *   - stateful: validated + mounted via the type handler;
+     *   - imperative + already-applied: recorded only (no DOM action);
+     *   - any: tracked in the in-memory map for future patches.
+     *
+     * Safe to call once on SDK init. Calling again would re-mount
+     * stateful instances; callers should not.
+     */
+    hydrate(snapshot: MountedElement[]): Promise<void>;
+    /**
+     * Re-publish `element.tile_mounted` / `element.compositional_append`
+     * for every active LLM-authored instance in the store. Idempotent —
+     * receivers key by `instance_id` (tiles) or by widget identity
+     * (items via tile_id filter).
+     */
+    private _broadcastActive;
+    /**
+     * Apply a batch of mutations, atomically per-batch. Each mutation is
+     * version-checked (mount: must not conflict with existing instance;
+     * patch: resulting_version must be > current; unmount: idempotent).
+     */
+    apply(mutations: ElementMutation[]): Promise<void>;
+    /** Read-only snapshot of currently-known instances. */
+    getInstances(): MountedElement[];
+    getInstance(instance_id: string): MountedElement | undefined;
+    /**
+     * Schedule a client-side TTL that unmounts every active stateful
+     * instance when the server-side session expires. Replaces any
+     * previously-scheduled TTL.
+     *
+     * Avoids the orphan-window where session-expired tiles linger on the
+     * page until manual refresh — the server forgets at the 4h mark and
+     * the SDK tears down concurrently. Re-schedule on each boot fetch /
+     * mutation event that carries a refreshed `session_expires_at`.
+     *
+     * Pass `null` to clear the existing timer without scheduling a new one.
+     * Pass a past timestamp to trigger cleanup immediately.
+     */
+    scheduleClientTtl(session_expires_at: string | null): void;
+    private _handleSessionExpiry;
+    private _applyOne;
+    private _mount;
+    private _ctx;
+}
+//# sourceMappingURL=ElementInstanceStore.d.ts.map

package/dist/elements/ElementInstanceStore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ElementInstanceStore.d.ts","sourceRoot":"","sources":["../../src/elements/ElementInstanceStore.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAQH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAC7C,OAAO,KAAK,EAAyB,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AACtF,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAK/D,MAAM,WAAW,2BAA2B;IAC1C,OAAO,EAAE,YAAY,CAAC;IACtB;;;;;;;;;;;;;;OAcG;IACH,MAAM,CAAC,EAAE;QACP,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAC;QACjE;;;;;;WAMG;QACH,SAAS,CAAC,EAAE;YACV,CACE,MAAM,EAAE;gBAAE,KAAK,CAAC,EAAE,MAAM,EAAE,CAAA;aAAE,EAC5B,OAAO,EAAE,CAAC,KAAK,EAAE;gBAAE,IAAI,EAAE,MAAM,CAAC;gBAAC,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;aAAE,KAAK,IAAI,GAC1E,MAAM,IAAI,CAAC;YACd,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE;gBAAE,IAAI,EAAE,MAAM,CAAC;gBAAC,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;aAAE,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;SAC3F,CAAC;KACH,CAAC;IACF,QAAQ,CAAC,EAAE,kBAAkB,EAAE,CAAC;IAChC,iEAAiE;IACjE,MAAM,CAAC,EAAE,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,CAAC;IAClD;;;;;;;;;;;OAWG;IACH,iBAAiB,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,CAAC;CAChE;AAED,qBAAa,oBAAoB;IAC/B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAe;IACxC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAwC;IAChE,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAkC;IAC5D,OAAO,CAAC,QAAQ,CAAC,UAAU,CAA0C;IACrE,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA2C;IACnE,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAC,CAA6C;IACjF,yEAAyE;IACzE,OAAO,CAAC,SAAS,CAA8C;gBAEnD,OAAO,EAAE,2BAA2B;IAYhD;;;;;;;;OAQG;IACH,OAAO,CAAC,wBAAwB;IAuBhC,OAAO,CAAC,YAAY;IAkBpB,OAAO,CAAC,YAAY;IAepB,eAAe,CAAC,OAAO,EAAE,kBAAkB,GAAG,IAAI;IAIlD;;;;;;;;OAQG;IACG,OAAO,CAAC,QAAQ,EAAE,cAAc,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IA8CxD;;;;;OAKG;IACH,OAAO,CAAC,gBAAgB;IAiBxB;;;;OAIG;IACG,KAAK,CAAC,SAAS,EAAE,eAAe,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAYxD,uDAAuD;IACvD,YAAY,IAAI,cAAc,EAAE;IAIhC,WAAW,CAAC,WAAW,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS;IAI5D;;;;;;;;;;;;OAYG;IACH,iBAAiB,CAAC,kBAAkB,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI;YAuB5C,oBAAoB;YAkBpB,SAAS;YAsGT,MAAM;IAyBpB,OAAO,CAAC,IAAI;CAGb"}

package/dist/elements/ElementInstanceStore.test.d.ts

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

package/dist/elements/ElementInstanceStore.test.d.ts.map

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

package/dist/elements/ElementTypeHandler.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Per-type handler interface for `ElementInstanceStore`.
+ *
+ * Adding a future element type (overlay / tour / form) is one new
+ * `ElementTypeHandler` implementation registered in the store —
+ * `ElementInstanceStore` itself stays type-neutral.
+ *
+ * Handlers own their per-type lifecycle. They receive the current
+ * `MountedElement` snapshot and the runtime's `ActionEngine` and either
+ * call `applyBatch` to drive DOM changes or hold on to returned
+ * `ActionHandle`s for later cleanup.
+ *
+ * Design choices the handlers MUST honor:
+ *
+ * - **Imperative actions never re-fire on boot.** When the store
+ *   hydrates an element with `lifecycle === 'imperative'` and `state ===
+ *   'applied'`, the handler's `mount()` is NOT called. The backend
+ *   records the prior invocation for audit but the SDK does not replay
+ *   it (would re-scroll, re-navigate, etc.).
+ * - **Defense-in-depth content validation.** `validate()` is called
+ *   before every mount/patch. The backend already validated, but the
+ *   handler should refuse malformed content so a buggy server can't
+ *   crash the runtime.
+ */
+import type { ActionEngine } from '../types';
+import type { ElementMutation, MountedElement } from './types';
+/** Lifecycle classification used to decide whether to apply on boot rehydrate. */
+export type ElementLifecycle = 'stateful' | 'imperative' | 'ephemeral';
+export interface ElementHandlerContext {
+    /** Runtime's ActionEngine — handlers use `applyBatch` to drive DOM
+     *  changes via existing executors (`core:mountWidget`, etc.). */
+    actions: ActionEngine;
+    /** Runtime's event bus — handlers publish typed events that container
+     *  widgets subscribe to. Used by `ItemHandler` to broadcast
+     *  `element.compositional_append` so chip-strip / FAQ / nav-tips
+     *  containers can insert LLM-authored items.
+     *  Optional so test fixtures that exercise only DOM action handlers
+     *  don't need to stub the bus.
+     */
+    events?: {
+        publish: (name: string, props?: Record<string, unknown>) => void;
+    };
+}
+export type ValidateResult = {
+    accepted: true;
+} | {
+    accepted: false;
+    reason: string;
+    detail?: string;
+};
+export interface ElementTypeHandler {
+    readonly typeName: 'tile' | 'action' | 'item';
+    /** Whether the handler's elements survive a boot rehydrate. Imperative
+     *  handlers (action handler in v1) DO NOT replay applied instances. */
+    readonly lifecycle: ElementLifecycle;
+    /** Defense-in-depth — refuse malformed content/placement before the
+     *  handler touches the DOM. The store calls this before `mount` and
+     *  `patch`; a rejection is logged but does not throw — the store
+     *  records the rejection on the instance and skips the apply. */
+    validate(instance: MountedElement, ctx: ElementHandlerContext): ValidateResult;
+    /** Apply a new mount to the DOM. Called once per mount; the store
+     *  passes the instance object so the handler can read `placement`,
+     *  `content`, `template_id`, etc. */
+    mount(instance: MountedElement, ctx: ElementHandlerContext): Promise<void>;
+    /** Apply a patch — typically by re-mounting the widget with merged
+     *  content. v1 has no fine-grained reactivity; full re-mount is
+     *  expected. */
+    patch(instance: MountedElement, ctx: ElementHandlerContext): Promise<void>;
+    /** Remove the element from the DOM. Idempotent — called for both
+     *  user-initiated unmounts and TTL-triggered cleanup. */
+    unmount(instance: MountedElement, ctx: ElementHandlerContext): Promise<void>;
+}
+export interface ElementMutationContext extends ElementHandlerContext {
+    /** Op being processed — handler-side telemetry / debug surface. */
+    mutation: ElementMutation;
+}
+//# sourceMappingURL=ElementTypeHandler.d.ts.map

package/dist/elements/ElementTypeHandler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ElementTypeHandler.d.ts","sourceRoot":"","sources":["../../src/elements/ElementTypeHandler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAC7C,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAE/D,kFAAkF;AAClF,MAAM,MAAM,gBAAgB,GAAG,UAAU,GAAG,YAAY,GAAG,WAAW,CAAC;AAEvE,MAAM,WAAW,qBAAqB;IACpC;qEACiE;IACjE,OAAO,EAAE,YAAY,CAAC;IACtB;;;;;;OAMG;IACH,MAAM,CAAC,EAAE;QACP,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAC;KAClE,CAAC;CACH;AAED,MAAM,MAAM,cAAc,GACtB;IAAE,QAAQ,EAAE,IAAI,CAAA;CAAE,GAClB;IAAE,QAAQ,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAEzD,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,QAAQ,GAAG,MAAM,CAAC;IAE9C;2EACuE;IACvE,QAAQ,CAAC,SAAS,EAAE,gBAAgB,CAAC;IAErC;;;qEAGiE;IACjE,QAAQ,CAAC,QAAQ,EAAE,cAAc,EAAE,GAAG,EAAE,qBAAqB,GAAG,cAAc,CAAC;IAE/E;;yCAEqC;IACrC,KAAK,CAAC,QAAQ,EAAE,cAAc,EAAE,GAAG,EAAE,qBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE3E;;oBAEgB;IAChB,KAAK,CAAC,QAAQ,EAAE,cAAc,EAAE,GAAG,EAAE,qBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE3E;6DACyD;IACzD,OAAO,CAAC,QAAQ,EAAE,cAAc,EAAE,GAAG,EAAE,qBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9E;AAED,MAAM,WAAW,sBAAuB,SAAQ,qBAAqB;IACnE,mEAAmE;IACnE,QAAQ,EAAE,eAAe,CAAC;CAC3B"}

package/dist/elements/ItemHandler.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Item element handler — translates `parent_tile`-placed mount/patch/
+ * unmount mutations into pub/sub events that container widgets subscribe
+ * to.
+ *
+ * Container widgets (chips strip, FAQ accordion, nav tips) declare
+ * themselves participants by implementing the `CompositionalContainer`
+ * contract and subscribing to `runtime.events` with
+ * `element.compositional_append` / `element.compositional_patch` /
+ * `element.compositional_remove`. Each container filters by
+ * `props.tile_id === this.tileId`.
+ *
+ * Why pub/sub rather than DOM lookup? The runtime's event bus is
+ * domain-agnostic and already exists. Container widgets that aren't
+ * mounted yet (slow inline-slot wrapper hydration) miss the event,
+ * but the next subscribe-then-replay pass at container mount time picks
+ * up the durable session state from the LLM's `mounted_elements`. No
+ * DOM crawling, no MutationObserver wiring, no ordering assumption.
+ *
+ * The handler is dumb: it forwards the wire `content` as the `item`
+ * payload. The backend wrote that content as a fully-formed
+ * compositional-item envelope (`{kind, config: {id, title, payload}}`)
+ * so the receiving container can append it verbatim.
+ */
+import type { ElementHandlerContext, ElementTypeHandler, ValidateResult } from './ElementTypeHandler';
+import type { MountedElement } from './types';
+/** Event names. Kept as module constants so subscribers can import them
+ *  instead of memorizing strings. */
+export declare const COMPOSITIONAL_APPEND_EVENT = "element.compositional_append";
+export declare const COMPOSITIONAL_PATCH_EVENT = "element.compositional_patch";
+export declare const COMPOSITIONAL_REMOVE_EVENT = "element.compositional_remove";
+export interface CompositionalAppendEvent {
+    /** Parent tile id from the mount's placement. Receivers filter on this. */
+    tile_id: string;
+    /** Unique id of the mounted item — the receiving container should also
+     *  set this on the item's DOM as `data-syntro-element-id`. */
+    instance_id: string;
+    /** Wire shape constructed by the backend — `{kind, config: {…}}`. */
+    item: Record<string, unknown>;
+    /** Insertion position — receivers honor this when appending. */
+    position: 'append' | 'prepend';
+}
+export interface CompositionalPatchEvent {
+    tile_id: string;
+    instance_id: string;
+    item: Record<string, unknown>;
+}
+export interface CompositionalRemoveEvent {
+    tile_id: string;
+    instance_id: string;
+}
+export declare class ItemHandler implements ElementTypeHandler {
+    readonly typeName: "item";
+    readonly lifecycle: "stateful";
+    validate(instance: MountedElement, _ctx: ElementHandlerContext): ValidateResult;
+    mount(instance: MountedElement, ctx: ElementHandlerContext): Promise<void>;
+    patch(instance: MountedElement, ctx: ElementHandlerContext): Promise<void>;
+    unmount(instance: MountedElement, ctx: ElementHandlerContext): Promise<void>;
+}
+//# sourceMappingURL=ItemHandler.d.ts.map

package/dist/elements/ItemHandler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ItemHandler.d.ts","sourceRoot":"","sources":["../../src/elements/ItemHandler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,KAAK,EACV,qBAAqB,EACrB,kBAAkB,EAClB,cAAc,EACf,MAAM,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EAAE,cAAc,EAAuB,MAAM,SAAS,CAAC;AAEnE;qCACqC;AACrC,eAAO,MAAM,0BAA0B,iCAAiC,CAAC;AACzE,eAAO,MAAM,yBAAyB,gCAAgC,CAAC;AACvE,eAAO,MAAM,0BAA0B,iCAAiC,CAAC;AAEzE,MAAM,WAAW,wBAAwB;IACvC,2EAA2E;IAC3E,OAAO,EAAE,MAAM,CAAC;IAChB;kEAC8D;IAC9D,WAAW,EAAE,MAAM,CAAC;IACpB,qEAAqE;IACrE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9B,gEAAgE;IAChE,QAAQ,EAAE,QAAQ,GAAG,SAAS,CAAC;CAChC;AAED,MAAM,WAAW,uBAAuB;IACtC,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC/B;AAED,MAAM,WAAW,wBAAwB;IACvC,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,qBAAa,WAAY,YAAW,kBAAkB;IACpD,QAAQ,CAAC,QAAQ,EAAG,MAAM,CAAU;IACpC,QAAQ,CAAC,SAAS,EAAG,UAAU,CAAU;IAEzC,QAAQ,CAAC,QAAQ,EAAE,cAAc,EAAE,IAAI,EAAE,qBAAqB,GAAG,cAAc;IAqBzE,KAAK,CAAC,QAAQ,EAAE,cAAc,EAAE,GAAG,EAAE,qBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC;IAW1E,KAAK,CAAC,QAAQ,EAAE,cAAc,EAAE,GAAG,EAAE,qBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC;IAU1E,OAAO,CAAC,QAAQ,EAAE,cAAc,EAAE,GAAG,EAAE,qBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC;CAQnF"}

package/dist/elements/ItemHandler.test.d.ts

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

package/dist/elements/ItemHandler.test.d.ts.map

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

package/dist/elements/TileHandler.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Tile element handler — translates `slot`-placed mount/patch/unmount
+ * mutations into pub/sub events that the runtime SDK subscribes to.
+ *
+ * The runtime SDK's `SmartCanvasElementLit` already routes config-driven
+ * tiles to inline slots via `tile.slot === slotName`. LLM-authored tiles
+ * use the same path: we publish a TileConfig-shaped envelope and the
+ * runtime merges it into its tile array, then existing routing renders
+ * it inside the slot's `<syntro-tile-stack>` alongside any config tiles.
+ *
+ * Why pub/sub instead of `core:mountWidget` via ActionEngine?
+ *
+ *   - `Surfaces.mount` is exclusive per slot — a second LLM tile to the
+ *     same slot would displace the first.
+ *   - `Surfaces` only knows built-in slot names; inline slots resolve
+ *     anchors via SyntroInlineSlot, not via Surfaces.
+ *   - Tiles need the SyntroTileCard chrome (chromeless handling, theme
+ *     overrides, dismiss control) that `core:mountWidget` skips.
+ *
+ * Container widgets stay dumb: the runtime owns one tile array per slot
+ * and renders it the same way regardless of provenance. Subscribers
+ * filter on `slot === this.name`.
+ *
+ * Event names + payload types live in `@syntrologie/sdk-contracts` so
+ * both packages share the contract. Renaming a field there is a TS
+ * error here and in the runtime subscriber — no silent drift.
+ */
+import type { ElementHandlerContext, ElementTypeHandler, ValidateResult } from './ElementTypeHandler';
+import type { MountedElement } from './types';
+export { TILE_MOUNTED_EVENT, TILE_PATCHED_EVENT, TILE_UNMOUNTED_EVENT, } from '@syntrologie/sdk-contracts';
+/**
+ * Optional template→widget resolver. ``uiTemplates`` declares both
+ * the LLM-facing ``id`` (e.g. ``"product-card"``) and the runtime
+ * widget the chrome should render (e.g. ``"adaptive-product:card"``).
+ * Without this resolver, the handler falls back to ``template_id`` as
+ * the widget id — which only works when the admin chose ids matching
+ * the widget registry, and silently mounts to "Widget not available"
+ * when they don't.
+ */
+export type TileTemplateWidgetResolver = (templateId: string) => string | undefined;
+export declare class TileHandler implements ElementTypeHandler {
+    private readonly resolveWidget?;
+    readonly typeName: "tile";
+    readonly lifecycle: "stateful";
+    constructor(resolveWidget?: TileTemplateWidgetResolver | undefined);
+    private _widgetFor;
+    validate(instance: MountedElement, _ctx: ElementHandlerContext): ValidateResult;
+    mount(instance: MountedElement, ctx: ElementHandlerContext): Promise<void>;
+    patch(instance: MountedElement, ctx: ElementHandlerContext): Promise<void>;
+    unmount(instance: MountedElement, ctx: ElementHandlerContext): Promise<void>;
+}
+//# sourceMappingURL=TileHandler.d.ts.map

package/dist/elements/TileHandler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TileHandler.d.ts","sourceRoot":"","sources":["../../src/elements/TileHandler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAUH,OAAO,KAAK,EACV,qBAAqB,EACrB,kBAAkB,EAClB,cAAc,EACf,MAAM,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EAAE,cAAc,EAAiB,MAAM,SAAS,CAAC;AAE7D,OAAO,EACL,kBAAkB,EAClB,kBAAkB,EAClB,oBAAoB,GACrB,MAAM,4BAA4B,CAAC;AAEpC;;;;;;;;GAQG;AACH,MAAM,MAAM,0BAA0B,GAAG,CAAC,UAAU,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,CAAC;AAEpF,qBAAa,WAAY,YAAW,kBAAkB;IAIxC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAC;IAH3C,QAAQ,CAAC,QAAQ,EAAG,MAAM,CAAU;IACpC,QAAQ,CAAC,SAAS,EAAG,UAAU,CAAU;gBAEZ,aAAa,CAAC,EAAE,0BAA0B,YAAA;IAEvE,OAAO,CAAC,UAAU;IAIlB,QAAQ,CAAC,QAAQ,EAAE,cAAc,EAAE,IAAI,EAAE,qBAAqB,GAAG,cAAc;IAiBzE,KAAK,CAAC,QAAQ,EAAE,cAAc,EAAE,GAAG,EAAE,qBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC;IAY1E,KAAK,CAAC,QAAQ,EAAE,cAAc,EAAE,GAAG,EAAE,qBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC;IAY1E,OAAO,CAAC,QAAQ,EAAE,cAAc,EAAE,GAAG,EAAE,qBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC;CASnF"}

package/dist/elements/blockRenderer.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Portable Text block renderer — Phase 7 of the LLM-authored UI element
+ * instantiation work.
+ *
+ * `renderBlocks(blocks)` walks a Portable Text tree and produces a
+ * `DocumentFragment` of known-safe DOM. Calling code attaches the
+ * fragment via `target.appendChild(fragment)` /
+ * `target.insertAdjacentElement(...)` — **never** via `innerHTML`.
+ *
+ * The safety story:
+ *
+ * 1. **No `innerHTML` from agent data, ever.** Every text reaches the
+ *    DOM through `document.createTextNode` or `element.textContent`.
+ *    Even if an agent slips a `<script>` tag into a span's text, it's
+ *    rendered as the literal characters `<script>` inside a text node,
+ *    never parsed as HTML.
+ * 2. **Closed mark vocabulary.** Only `bold` / `italic` / `code` / `link`
+ *    are honored. Unknown marks are dropped at render time.
+ * 3. **Closed block vocabulary.** Only `paragraph` / `heading` / `list` /
+ *    `list_item` / `code` are honored. Unknown block types are dropped.
+ * 4. **Link href validation.** Backend already rejects `javascript:` /
+ *    `data:` / `vbscript:` etc., but the renderer re-checks for defense
+ *    in depth. Rejected links render as plain text spans.
+ * 5. **No inline styles, no event handlers, no custom attributes.**
+ *    Every attribute set on the output DOM is hard-coded in this file.
+ *
+ * Forward-compat: unknown block / mark types drop silently rather than
+ * throw — a future schema bump can add types without breaking today's
+ * renderer.
+ */
+import type { BlockNode } from './blocks';
+export interface RenderOptions {
+    /** Override the document used for `createElement` / `createTextNode`.
+     *  Tests inject jsdom's document; SSR contexts can pass a custom impl
+     *  if needed. Defaults to `globalThis.document`. */
+    doc?: Document;
+}
+/**
+ * Render an array of blocks into a `DocumentFragment` of safe DOM.
+ *
+ * Unknown / malformed entries are silently dropped — the caller has
+ * already validated server-side; the renderer is the last line of
+ * defense and stays fault-tolerant.
+ */
+export declare function renderBlocks(blocks: BlockNode[], options?: RenderOptions): DocumentFragment;
+//# sourceMappingURL=blockRenderer.d.ts.map

package/dist/elements/blockRenderer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"blockRenderer.d.ts","sourceRoot":"","sources":["../../src/elements/blockRenderer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,OAAO,KAAK,EACV,SAAS,EAQV,MAAM,UAAU,CAAC;AAQlB,MAAM,WAAW,aAAa;IAC5B;;wDAEoD;IACpD,GAAG,CAAC,EAAE,QAAQ,CAAC;CAChB;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,SAAS,EAAE,EAAE,OAAO,GAAE,aAAkB,GAAG,gBAAgB,CAiB/F"}

package/dist/elements/blockRenderer.test.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Tests for the Portable Text block renderer — Phase 7.
+ *
+ * The bulk of this file is a hostile-input corpus. The point of the
+ * renderer is that **agent-authored text cannot produce script execution
+ * or unsafe DOM**, by construction, regardless of what the agent
+ * sends. Each test below pumps a different attack shape through
+ * `renderBlocks` and asserts that the resulting DOM contains no
+ * dangerous nodes, no live script content, and no `javascript:` /
+ * `data:` URIs on anchor tags.
+ */
+export {};
+//# sourceMappingURL=blockRenderer.test.d.ts.map

package/dist/elements/blockRenderer.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"blockRenderer.test.d.ts","sourceRoot":"","sources":["../../src/elements/blockRenderer.test.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG"}

package/dist/elements/blocks.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Portable Text block + mark types — Phase 7 of the LLM-authored UI
+ * element instantiation work.
+ *
+ * Mirror of `platform/common/syntrologie_common/sdk/blocks.py`. Closed
+ * vocabulary (block types + mark types) the LLM may author in
+ * `rich_text_blocks` fields. The renderer walks this tree and produces
+ * DOM via `document.createElement` + `textContent` — **agent never
+ * writes HTML strings**. XSS-class attacks have no surface because
+ * there's no HTML on the wire.
+ *
+ * Forward-compat: unknown block types and unknown marks are dropped at
+ * render time (not thrown). A future protocol bump can add new types
+ * without breaking today's renderer.
+ */
+/**
+ * The closed inline-mark vocabulary. Adding a mark is a deliberate
+ * code change with review, never an allowlist tweak.
+ */
+export type MarkType = 'bold' | 'italic' | 'code' | 'link';
+export type HeadingLevel = 1 | 2 | 3 | 4 | 5 | 6;
+export type ListStyle = 'bullet' | 'numbered';
+export interface LinkMark {
+    /** Validated server-side; renderer revalidates for defense in depth. */
+    href: string;
+}
+export interface TextSpan {
+    text: string;
+    marks?: MarkType[];
+    link?: LinkMark;
+}
+export interface ParagraphBlock {
+    type: 'paragraph';
+    spans: TextSpan[];
+}
+export interface HeadingBlock {
+    type: 'heading';
+    level: HeadingLevel;
+    spans: TextSpan[];
+}
+export interface ListItemBlock {
+    type: 'list_item';
+    spans: TextSpan[];
+}
+export interface ListBlock {
+    type: 'list';
+    style: ListStyle;
+    items: ListItemBlock[];
+}
+export interface CodeBlock {
+    type: 'code';
+    /** Raw code text. Rendered inside `<pre><code>` via `textContent` —
+     *  no HTML interpretation, no syntax-highlight injection. */
+    text: string;
+    language?: string;
+}
+export type BlockNode = ParagraphBlock | HeadingBlock | ListBlock | CodeBlock;
+//# sourceMappingURL=blocks.d.ts.map

package/dist/elements/blocks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"blocks.d.ts","sourceRoot":"","sources":["../../src/elements/blocks.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH;;;GAGG;AACH,MAAM,MAAM,QAAQ,GAAG,MAAM,GAAG,QAAQ,GAAG,MAAM,GAAG,MAAM,CAAC;AAE3D,MAAM,MAAM,YAAY,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;AAEjD,MAAM,MAAM,SAAS,GAAG,QAAQ,GAAG,UAAU,CAAC;AAE9C,MAAM,WAAW,QAAQ;IACvB,wEAAwE;IACxE,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,QAAQ,EAAE,CAAC;IACnB,IAAI,CAAC,EAAE,QAAQ,CAAC;CACjB;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,WAAW,CAAC;IAClB,KAAK,EAAE,QAAQ,EAAE,CAAC;CACnB;AAED,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,SAAS,CAAC;IAChB,KAAK,EAAE,YAAY,CAAC;IACpB,KAAK,EAAE,QAAQ,EAAE,CAAC;CACnB;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,WAAW,CAAC;IAClB,KAAK,EAAE,QAAQ,EAAE,CAAC;CACnB;AAED,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,SAAS,CAAC;IACjB,KAAK,EAAE,aAAa,EAAE,CAAC;CACxB;AAED,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb;iEAC6D;IAC7D,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,MAAM,SAAS,GAAG,cAAc,GAAG,YAAY,GAAG,SAAS,GAAG,SAAS,CAAC"}

package/dist/elements/envelope.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Helpers for decoding AG-UI custom event payloads — Phase 6b.
+ *
+ * `AgUiTransport.onA2UIEvent` historically forwarded the raw `event.value`
+ * payload as an `ActionStep` directly to `runtime.actions.applyBatch`.
+ * Phase 5's backend now also emits `syntro.element.mutation` envelopes
+ * (mounts/patches/unmounts authored by the LLM via `mount_element` &c.),
+ * which the SDK routes to `ElementInstanceStore.apply` instead.
+ *
+ * Discrimination is by the envelope's `type` field. Non-element payloads
+ * (raw ActionStep, A2UI `createSurface` / `updateDataModel` envelopes
+ * from any A2UI integration) fall through to the legacy path.
+ */
+import type { ElementMutation } from './types';
+/**
+ * Returns the mutations array if `payload` is a well-formed
+ * `syntro.element.mutation` envelope, otherwise `null`.
+ *
+ * Validates only the discriminator + the structural shape needed to
+ * route to the store. Per-mutation validation lives in the store / its
+ * type handlers (defense in depth), so this stays small.
+ */
+export declare function decodeMutationEnvelope(payload: unknown): ElementMutation[] | null;
+//# sourceMappingURL=envelope.d.ts.map

package/dist/elements/envelope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"envelope.d.ts","sourceRoot":"","sources":["../../src/elements/envelope.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAoB,MAAM,SAAS,CAAC;AAEjE;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,OAAO,GAAG,eAAe,EAAE,GAAG,IAAI,CAOjF"}

package/dist/elements/fetcher.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Boot-time fetcher for `GET /api/adaptive/mounted_elements`.
+ *
+ * Follows the SDK's vanilla-fetch convention (see
+ * `packages/runtime-sdk/src/overlays/fetcher.ts` for the sibling pattern
+ * — no shared HTTP client, no axios, no fetch wrapper).
+ *
+ * Auth: forwards the SDK token from `window.__SYNTRO_CONFIG__.token`
+ * as a Bearer header. Cookies (`syntro_chat_session`) are sent via
+ * `credentials: 'include'` so the backend can scope to the same Redis
+ * session the chat uses.
+ *
+ * 404 contract: the backend returns 404 only when the workspace's SDK
+ * token doesn't resolve to a workspace. The SDK treats 404 as
+ * "feature unavailable" — no error UI, no retries — per the design doc.
+ * Network errors are logged + swallowed so the SDK boot path stays
+ * resilient to backend hiccups.
+ */
+import type { MountedElementsResponse } from './types';
+export interface FetchMountedElementsOptions {
+    /** Override the endpoint URL (defaults to same-origin
+     *  `/api/adaptive/mounted_elements`). Tests + multi-environment
+     *  deploys use this. */
+    endpoint?: string;
+    /** SDK token. Defaults to `window.__SYNTRO_CONFIG__.token`. */
+    token?: string;
+    /** Custom fetch implementation — used by tests to mock the network. */
+    fetchImpl?: typeof fetch;
+    /** Logger — used by tests to capture log output. */
+    logger?: Pick<Console, 'warn'>;
+}
+/**
+ * Fetch the visitor's currently-mounted elements + session expiry.
+ *
+ * Returns `null` on any failure (404, network error, malformed JSON,
+ * etc.). The caller treats `null` as "feature unavailable, no
+ * rehydrate" — boot continues normally with an empty element store.
+ */
+export declare function fetchMountedElements(options?: FetchMountedElementsOptions): Promise<MountedElementsResponse | null>;
+//# sourceMappingURL=fetcher.d.ts.map

package/dist/elements/fetcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fetcher.d.ts","sourceRoot":"","sources":["../../src/elements/fetcher.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,SAAS,CAAC;AAIvD,MAAM,WAAW,2BAA2B;IAC1C;;4BAEwB;IACxB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,+DAA+D;IAC/D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,uEAAuE;IACvE,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;IACzB,oDAAoD;IACpD,MAAM,CAAC,EAAE,IAAI,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;CAChC;AAED;;;;;;GAMG;AACH,wBAAsB,oBAAoB,CACxC,OAAO,GAAE,2BAAgC,GACxC,OAAO,CAAC,uBAAuB,GAAG,IAAI,CAAC,CA+CzC"}