@mgamadeus/ddd-agents 0.0.0-stage → 0.1.0-alpha.21

package/dist/types/renderer/widget-hydration/widget-hydration.registry.d.ts

@@ -0,0 +1,7 @@
+import { RegisteredWidget, WidgetHydratorOptions } from "./widget-hydration.types";
+export declare const registerWidgetHydrator: <TPayload = unknown, TData = unknown>(type: string, options: WidgetHydratorOptions<TPayload, TData>) => void;
+export declare const getWidgetHydrator: <TPayload = unknown, TData = unknown>(type: string) => RegisteredWidget<TPayload, TData> | undefined;
+export declare const hasWidgetHydrator: (type: string) => boolean;
+/** Every registered hydrator type — the widget preview answers them from its fixture (`widget-preview-hydration.ts`). */
+export declare const listWidgetHydratorTypes: () => string[];
+export declare const unregisterWidgetHydrator: (type: string) => void;

package/dist/types/renderer/widget-hydration/widget-hydration.slice.d.ts

@@ -0,0 +1,8 @@
+import type { WidgetHydrationSliceState, WidgetMemory } from "./widget-hydration.types";
+export { WidgetHydrationReducer, WidgetHydrationSlice } from "./widget-hydration.reducer";
+/** A store state that carries the widget hydration state. */
+interface StateWithWidgetHydration {
+    AIExtensionsWidgetHydration?: WidgetHydrationSliceState;
+}
+export declare const selectWidgetMemory: (key: string) => (state: StateWithWidgetHydration) => WidgetMemory | undefined;
+export declare const useWidgetMemory: (key: string) => WidgetMemory<unknown> | undefined;

package/dist/types/renderer/widget-hydration/widget-hydration.types.d.ts

@@ -0,0 +1,27 @@
+export type WidgetHydrationStatus = "idle" | "loading" | "success" | "error";
+export interface WidgetMemory<TData = unknown> {
+    data: TData | null;
+    status: WidgetHydrationStatus;
+    error: string | null;
+    loadingInstanceId: string | null;
+    inFlight: boolean;
+    requestId: number;
+    lastLoadedAt: number | null;
+}
+export interface WidgetHydrationSliceState {
+    widgets: Record<string, WidgetMemory>;
+}
+export interface WidgetHydratorContext {
+    signal: AbortSignal;
+}
+export type WidgetHydrator<TPayload = unknown, TData = unknown> = (payload: TPayload, ctx: WidgetHydratorContext) => Promise<TData>;
+export interface WidgetHydratorOptions<TPayload = unknown, TData = unknown> {
+    hydrator: WidgetHydrator<TPayload, TData>;
+    deriveKey?: (type: string, payload: TPayload) => string;
+    isPayloadEqual?: (prev: TPayload | undefined, next: TPayload) => boolean;
+    refetchOnNewInstance?: boolean;
+    staleMs?: number;
+}
+export interface RegisteredWidget<TPayload = unknown, TData = unknown> extends Required<Omit<WidgetHydratorOptions<TPayload, TData>, "isPayloadEqual">> {
+    isPayloadEqual: (prev: TPayload | undefined, next: TPayload) => boolean;
+}

package/dist/types/renderer/widget-name-resolver.d.ts

@@ -0,0 +1,22 @@
+/**
+ * THE resolution rule (see the file header): exact canonical match, else — only for a name ending in `Directive` —
+ * strip that legacy suffix once and match again. Undefined = no such widget. Every lookup in the pipeline goes through
+ * this function (the fence plugin, the AST plugin, the drawer-reset scan, the unrendered-widget detector), so a name
+ * that renders in one place renders in all of them.
+ */
+export declare const resolveCanonicalWidgetName: (requestedName: string, canonicalNames: ReadonlySet<string>) => string | undefined;
+/**
+ * Resolve a model-supplied ```widget `type` — or the name on a stored message's `::<Name>` node — to a registered
+ * widget name. `QuickReplies` matches exactly; the legacy `QuickRepliesDirective` resolves to the same canonical
+ * `QuickReplies`. Shared by the render plugin (which DROPS an unresolved block) and the unrendered-widget detector
+ * (which REPORTS it), so both agree exactly on what counts as a valid widget.
+ */
+export declare const resolveWidgetName: (type: string) => string | undefined;
+/**
+ * The closest VALID widget names to an unknown `type` the model emitted — a deterministic similarity shortlist (no
+ * LLM): substring containment + shared PascalCase tokens + edit-distance proximity as the tiebreaker. A candidate is
+ * kept only when it genuinely resembles the type (containment, a shared word, or a very close spelling) — proximity
+ * alone is too loose across ~60 widget names. Returned as the canonical (short) names, which is what a corrected
+ * emission should use; empty when nothing is close.
+ */
+export declare const closestWidgetNames: (type: string, limit?: number) => string[];

package/dist/types/renderer/widget-tree/bounded-json.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Bounded walks over decoded JSON: the widget payloads come from the model, so no
+ * walk may recurse without a bound, run in the size of a shared sub-structure, or throw. The depth rule is the
+ * backend's: a block is decoded with `json_decode(…, depth: 32)` (`WidgetBlocks.php`), which admits 31 nested
+ * containers — a deeper block is MALFORMED there and is dropped here the same way.
+ */
+/** The deepest container nesting `json_decode(…, 32)` admits (the top-level object counts as 1). */
+export declare const MAX_JSON_CONTAINER_DEPTH = 31;
+/** Whether `value` nests containers deeper than `maxDepth` — iterative, never throws. */
+export declare const exceedsJsonContainerDepth: (value: unknown, maxDepth?: number) => boolean;
+/**
+ * The value as `json_decode(…, true)` sees it: an object whose keys are `"0"`, `"1"`, … in order is a LIST there
+ * (`array_is_list`), so it becomes an array here. Bounded by the depth rule (call it on a value within the depth).
+ */
+export declare const normalizeToPhpArrays: (value: unknown, depth?: number) => unknown;
+/**
+ * The size of a value as a TREE (every container and scalar counted where it appears) — a shared sub-structure counts
+ * once per use, as serialising it would. Memoised per object, so the cost is the number of DISTINCT objects even for a
+ * DAG whose tree is exponential; the result saturates at `Number.MAX_SAFE_INTEGER`.
+ */
+export declare const structuralSizeOf: (value: unknown, depth?: number) => number;
+/** `JSON.stringify(value, null, 2)` — or undefined once the text would pass `maxLength` (checked before it is built). */
+export declare const stringifyWithinLimit: (value: unknown, maxLength: number) => string | undefined;

package/dist/types/renderer/widget-tree/composed-node-schema.d.ts

@@ -0,0 +1,143 @@
+/**
+ * THE schema of the `ComposedView` kit, GENERATED by the backend from its classes (`ComposedViewNodeSchema.php`) —
+ * never edited by hand. The committed file holds the types the package's own classes declare; an app adds the node
+ * types, widgets, data sources and entity types its classes declare as its part (`AgentsEnvironment.composedNodeSchemaApplicationPart`,
+ * generated by the app's backend the same way), and `getComposedNodeSchema()` reads both. The frontend parser, the
+ * renderer and the evaluator read the node types, slots, props, size classes and budgets from here, so both sides apply
+ * the same contract. `kit/_ComposedViewRenderer.spec.tsx` checks that every node type has a registered component and
+ * every component a node type.
+ */
+export type ComposedNodeCategory = "inline" | "block" | "data" | "media" | "input" | "layout" | "heavy";
+export type ComposedSizeClass = "compact" | "regular" | "full";
+export type ComposedPropType = "string" | "number" | "boolean" | "array" | "object" | "event";
+export interface ComposedNodeSlotSchema {
+    name: string;
+    acceptsCategories: ComposedNodeCategory[];
+    acceptsNodeTypes: string[];
+    minChildren: number;
+    maxChildren: number | null;
+    sizeClass: ComposedSizeClass;
+    description: string;
+    /** The node prop the slot's size class follows (a Grid's `columns`); absent = the size class is fixed. */
+    sizeClassFromProp?: string;
+    /** Prop value (as text) → size class; a value not listed keeps `sizeClass`. */
+    sizeClassesByPropValue?: Record<string, ComposedSizeClass>;
+    /** A heavy node (a map, an embedded widget) may sit in the slot while it is compact. */
+    acceptsHeavyWhenCompact?: boolean;
+}
+export interface ComposedNodePropSchema {
+    name: string;
+    types: ComposedPropType[];
+    isRequired: boolean;
+    isBindable: boolean;
+    allowedValues: Array<string | number | boolean> | null;
+    description: string;
+}
+/**
+ * The type's part in the source rule (`ComposedViewNode::buildSourcingSchemaArray()`): a data node that `needsSource`
+ * and holds inline figures in its subtree — written rows in a `rowsProps` prop, a written figure in a `figureProps`
+ * prop — needs its `source`, a source on a data node around it, or a node that `namesSources` in the tree.
+ */
+export interface ComposedNodeSourcingSchema {
+    needsSource: boolean;
+    namesSources: boolean;
+    rowsProps: string[];
+    figureProps: string[];
+}
+export interface ComposedNodeTypeSchema {
+    categories: ComposedNodeCategory[];
+    providesItemScope: boolean;
+    summary: string;
+    props: ComposedNodePropSchema[];
+    slots: ComposedNodeSlotSchema[];
+    /** Absent for a type that takes no part in the source rule. */
+    sourcing?: ComposedNodeSourcingSchema;
+    /** The prop that lists the node's choices (`ComposedViewNode::OPTIONS_PROP_NAME`); absent without choices. */
+    optionsProp?: string;
+    /** The prop a node that repeats its children repeats over (`ComposedViewNode::ITEMS_PROP_NAME`). */
+    itemsProp?: string;
+    /** The node sends the state of the inputs inside it (`Form`); absent otherwise. */
+    submitsInputs?: boolean;
+}
+export interface ComposedViewBudgets {
+    maxSourceBytes: number;
+    maxNodes: number;
+    maxDepth: number;
+    maxStateKeys: number;
+    maxStateStringLength: number;
+    maxComputedExpressions: number;
+    maxExpressionSourceLength: number;
+    maxExpressionAstNodes: number;
+    maxComputedDependencyDepth: number;
+    maxOperationsPerUpdate: number;
+    maxCollectionItems: number;
+    maxAllocatedItemsPerEvaluation: number;
+    maxRepeatRows: number;
+    maxRenderedNodes: number;
+    maxInlineArrayItems: number;
+    maxInlineCells: number;
+    maxTextLength: number;
+    maxActions: number;
+    maxInputUpdatesPerSecond: number;
+    maxSourceRequestsPerTreePerMinute: number;
+}
+export interface ComposedDataSourceSchema {
+    summary: string;
+    /** The client endpoint, method and path with `{param}` placeholders. */
+    clientEndpoint: string;
+    /** Where the rows sit in the response (`$` or `$.field`). */
+    rowsPath: string;
+    freshnessSeconds: number;
+    params: Array<{
+        name: string;
+        type: string;
+        isRequired: boolean;
+        description: string;
+    }>;
+    columns: Array<{
+        name: string;
+        type: string;
+        description: string;
+    }>;
+}
+export interface ComposedNodeSchema {
+    version: number;
+    budgets: ComposedViewBudgets;
+    categories: ComposedNodeCategory[];
+    sizeClasses: ComposedSizeClass[];
+    actionTypes: string[];
+    bindingKinds: string[];
+    findingCodes: string[];
+    /** The codes of findings that drop nothing — the block mounts with the code as a note. */
+    noteFindingCodes: string[];
+    nodeTypes: Record<string, ComposedNodeTypeSchema>;
+    embeddableWidgets: Record<string, {
+        sizeClass: ComposedSizeClass;
+    }>;
+    /** Every registered widget type: a `Widget` node naming one its slot refuses is lifted out of the tree. */
+    widgetTypes?: string[];
+    dataSources: Record<string, ComposedDataSourceSchema>;
+    entityTypes: string[];
+}
+/** The sections of the schema an app adds for the types its own classes declare; every section is optional. */
+export type ComposedNodeSchemaApplicationPart = Partial<Pick<ComposedNodeSchema, "nodeTypes" | "embeddableWidgets" | "widgetTypes" | "dataSources" | "entityTypes">>;
+/**
+ * The package's committed schema, typed: its budgets and rules and the types the package itself declares. A reader of
+ * types an app may add (node types, widgets, data sources, entity types) reads `getComposedNodeSchema()`.
+ */
+export declare const composedNodeSchema: ComposedNodeSchema;
+/** A schema with an app's part added: every section holds both sides' types, sorted by type name. */
+export declare const addComposedNodeSchemaApplicationPart: (schema: ComposedNodeSchema, applicationPart: ComposedNodeSchemaApplicationPart) => ComposedNodeSchema;
+/**
+ * The schema the readers apply: the package's schema with the part the app declares
+ * (`AgentsEnvironment.composedNodeSchemaApplicationPart`); the package's schema alone when the app declares none.
+ * Read at call time — an app installs its environment after this module is loaded. The same object while the part is.
+ */
+export declare const getComposedNodeSchema: () => ComposedNodeSchema;
+/**
+ * The slot of one node — `ComposedViewNodeSlot::buildForNodeProps()`: its size class read from the node's
+ * `sizeClassFromProp` (a Grid with `columns: 3` gives compact cells); the declaration itself otherwise.
+ */
+export declare const resolveComposedSlotForNodeProps: (slot: ComposedNodeSlotSchema, nodeProps: Record<string, unknown>) => ComposedNodeSlotSchema;
+/** Whether a size class fits a slot's size class (compact ≤ regular ≤ full). */
+export declare const sizeClassFitsSlot: (sizeClass: ComposedSizeClass, slotSizeClass: ComposedSizeClass) => boolean;

package/dist/types/renderer/widget-tree/composed-view-data-sources.d.ts

@@ -0,0 +1,41 @@
+import { ComposedNodeSchema } from "./composed-node-schema";
+import { ComposedViewTree, JsonValue } from "./composed-view-tree";
+import type { ExpressionValue } from "./expression/evaluate-expression";
+/**
+ * The frontend side of the `$source` data path: a registered source is read through the existing
+ * widget-hydration mechanism (`widget-hydration/`), so the e-mail capture waits for it like for any self-hydrating
+ * widget. A source is added with TWO files: the backend `<Name>ComposedViewDataSource` (endpoint, params,
+ * columns — exported into the schema) and the frontend fetcher `<name>.composed-data-source.ts` anywhere below
+ * `widgets/` exporting `composedViewDataSourceFetcher` (it reads the endpoint through the generated SDK store and returns
+ * the response; the rows are taken at the schema's `rowsPath`). The read rights are the endpoint's own entity rights,
+ * server-side — the fetcher passes the agent space key and the parameters, nothing else.
+ */
+export interface ComposedViewDataSourceFetcher {
+    /** The source name (the backend `NAME`). */
+    name: string;
+    /** Reads the source for an agent space and the resolved parameters; resolves with the endpoint's response. */
+    fetchResponse: (params: Record<string, ExpressionValue>, agentSpaceKey: number | undefined, signal: AbortSignal) => Promise<unknown>;
+}
+export interface ComposedViewDataSourcePayload {
+    params: Record<string, ExpressionValue>;
+    agentSpaceKey: number | undefined;
+}
+/** The hydration type a source registers under. */
+export declare const composedViewDataSourceHydrationType: (dataSourceName: string) => string;
+/** The rows at a schema `rowsPath` (`$`, `$.field`, `$.a.b`) of a response; undefined when the path does not hold a list. */
+export declare const readRowsAtPath: (response: unknown, rowsPath: string) => ExpressionValue[] | undefined;
+/** Registers a fetcher as a widget hydrator; the rows land in the hydration memory like any widget's data. */
+export declare const registerComposedViewDataSourceFetcher: (fetcher: ComposedViewDataSourceFetcher, schema?: ComposedNodeSchema) => void;
+/** Whether a fetcher is registered for a source name. */
+export declare const hasComposedViewDataSourceFetcher: (dataSourceName: string) => boolean;
+/** One `$source` binding of a tree, with its parameters as written (`$state` bindings inside). */
+export interface ComposedViewSourceBinding {
+    /** The binding's identity in the tree: name + parameters as written. */
+    bindingKey: string;
+    dataSourceName: string;
+    writtenParams: Record<string, JsonValue>;
+}
+/** Every distinct `$source` binding of a tree — its datasets and every node's props — in tree order. */
+export declare const collectComposedViewSourceBindings: (tree: ComposedViewTree) => ComposedViewSourceBinding[];
+/** The parameters with their `$state` bindings resolved against the instance state. */
+export declare const resolveComposedViewSourceParams: (writtenParams: Record<string, JsonValue>, state: Record<string, ExpressionValue>) => Record<string, ExpressionValue>;

package/dist/types/renderer/widget-tree/composed-view-tree.d.ts

@@ -0,0 +1,111 @@
+import { ComposedNodeSchema, ComposedNodeSlotSchema } from "./composed-node-schema";
+/**
+ * The `ComposedView` tree as typed objects: the frontend twin of the backend reader
+ * `ComposedViewTreeReading.php`. The fence plugin hands the widget its `payload` string; this module turns it into
+ * {@link ComposedViewTree} — state, datasets, computed expressions, actions and the node tree — and applies THE SAME
+ * rules as the backend, read from the generated schema: unknown types, slot mismatches, undeclared props, bad bindings,
+ * budgets and three backticks are dropped where they stand and reported as findings; the rest is kept. A `set` on an
+ * undeclared name declares it with null; a choice state outside its choices, a set state nothing reads and an `$item`
+ * field missing from resolved `$from` rows are kept with a note (`noteFindingCodes` of the schema). The shared
+ * fixture `composed-view-parity.json` holds both readers to the same kept tree and the same finding codes.
+ *
+ * Never throws, never evaluates anything (expressions are compiled by `expression/`).
+ */
+export type ComposedViewFindingCode = "INVALID_NODE" | "INVALID_PROP" | "UNKNOWN_BINDING" | "INVALID_EXPRESSION" | "INVALID_STATE" | "INVALID_ACTION" | "BUDGET_EXCEEDED" | "INLINE_VALUE_WITHOUT_SOURCE" | "INVALID_INITIAL_CHOICE" | "UNREAD_STATE" | "UNKNOWN_ITEM_KEY" | "INVALID_SLOT_NODE_COUNT" | "WIDGET_LIFTED";
+export interface ComposedViewFinding {
+    code: ComposedViewFindingCode;
+    path: string;
+    message: string;
+}
+export type ComposedViewBindingKind = "state" | "computed" | "data" | "item" | "from" | "source";
+/** A bound value (`{"$state":"x"}` …), see `ComposedViewBinding.php`. */
+export interface ComposedViewBinding {
+    kind: ComposedViewBindingKind | string;
+    target: string;
+    path: string | null;
+    sourceParams: Record<string, unknown>;
+    isWellFormed: boolean;
+    /** The wire value itself (a `$from` carries its resolution state and snapshot inside, written when the row is stored). */
+    wireValue: Record<string, unknown>;
+}
+export type JsonValue = string | number | boolean | null | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+export interface ComposedViewNode {
+    type: string;
+    id: string | null;
+    /** The kept props: literals and bindings as JSON values. */
+    props: Record<string, JsonValue>;
+    /** The kept nodes per slot name (`children` = the default slot), in wire order. */
+    nodesBySlotName: Record<string, ComposedViewNode[]>;
+}
+export interface ComposedViewAction {
+    type: string;
+    [field: string]: JsonValue;
+}
+/**
+ * A `Widget` node the reader LIFTED out of the tree (`ComposedViewTreeReading::$liftedWidgetNodesByPath`):
+ * its wire path, the widget's canonical name and its fields — shown as its own widget after the view.
+ */
+export interface ComposedViewLiftedWidget {
+    path: string;
+    widget: string;
+    fields: Record<string, JsonValue>;
+}
+export interface ComposedViewTree {
+    title: string | null;
+    state: Record<string, string | number | boolean | null>;
+    data: Record<string, JsonValue>;
+    computed: Record<string, string>;
+    actions: Record<string, ComposedViewAction>;
+    view: ComposedViewNode | null;
+    findings: ComposedViewFinding[];
+    /** The widgets lifted out of the tree, reading order — never part of `view`. */
+    liftedWidgets: ComposedViewLiftedWidget[];
+}
+/** The binding a wire value stands for, or null for a literal — `ComposedViewBinding::fromWireValue()`. */
+export declare const readComposedViewBinding: (wireValue: unknown) => ComposedViewBinding | null;
+/**
+ * The field an `$item` binding names in one row — `ComposedViewBinding::readRowField()`: the key as written, else for a
+ * dotted name (`author.name`) the path through the row's nested objects. `found` tells a null field from a missing one.
+ */
+export declare const readComposedViewRowField: (row: unknown, fieldName: string) => {
+    found: boolean;
+    value: unknown;
+};
+/** `ComposedViewTreeReading::findIdentifiersOfExpression()` — identifiers outside string literals, not after a `.`. */
+export declare const findComposedViewExpressionIdentifiers: (expressionSource: string) => string[];
+/** Nodes in a subtree, the node included. */
+export declare const countComposedViewNodes: (node: ComposedViewNode) => number;
+/**
+ * The tree of the decoded block fields (without `type`), read and checked against `schema`. Fields nested deeper than
+ * the backend decodes give no view; objects keyed `"0"`, `"1"`, … are lists, as `json_decode` makes them.
+ */
+export declare const readComposedViewTree: (widgetFields: Record<string, unknown>, schema?: ComposedNodeSchema) => ComposedViewTree;
+/**
+ * The tree of a widget `payload` (the fence's non-`type` fields as a JSON string). A payload that is not a JSON object
+ * gives an empty tree; one over the source budget (counted on the canonical bytes, `measureComposedViewSourceBytes`)
+ * gives no view and one `BUDGET_EXCEEDED` finding, as on the backend.
+ */
+export declare const parseComposedViewTree: (payload: string, schema?: ComposedNodeSchema) => ComposedViewTree;
+/**
+ * The bytes the source budget counts — `ComposedViewTreeReading::measureSourceBytes()`: the fields without `type` as
+ * compact JSON, so the written fence's whitespace never decides; the legacy `writtenSyntax` field some stored fences carry
+ * (`WidgetBlock::LEGACY_WRITTEN_SYNTAX_FIELD`) does not count.
+ */
+export declare const measureComposedViewSourceBytes: (widgetFields: Record<string, unknown>) => number;
+/** The node in its wire form — `ComposedViewNode::toWireArray()`. */
+export declare const composedViewNodeToWire: (node: ComposedViewNode) => Record<string, JsonValue>;
+/** The kept tree in its wire form — `ComposedViewConversationWidget::getWidgetFields()` (empty parts left out). */
+export declare const composedViewTreeToWire: (tree: ComposedViewTree) => Record<string, JsonValue>;
+/** `ComposedViewNode::getNodesOfSubtreeByPath()` — every node of a subtree with its kept-tree path, depth first. */
+export declare const getComposedViewSubtreeNodesByPath: (node: ComposedViewNode, path: string) => Array<[string, ComposedViewNode]>;
+/** Every node of a subtree, depth first, the node first. */
+export declare const getComposedViewSubtreeNodes: (node: ComposedViewNode) => ComposedViewNode[];
+/** The slot schema of a node type, or undefined. */
+export declare const findComposedViewSlotSchema: (nodeType: string, slotName: string, schema?: ComposedNodeSchema) => ComposedNodeSlotSchema | undefined;
+/**
+ * Whether a kept view shows nothing: every node of it is a layout node (a Grid, a Stack or a Surface without a node to
+ * hold). The renderer shows the explicit fallback line instead — never a title over an empty Grid.
+ */
+export declare const isComposedViewWithoutContent: (view: ComposedViewNode, schema?: ComposedNodeSchema) => boolean;

package/dist/types/renderer/widget-tree/expression/evaluate-expression.d.ts

@@ -0,0 +1,65 @@
+import type { ComposedViewBudgets } from "../composed-node-schema";
+/**
+ * The evaluator of the `ComposedView` expression language. Values are JSON values; one value
+ * means "empty": `undefined` — a missing name or member, a division by zero, a non-finite result, an operation on an
+ * empty or wrongly typed operand all give it, and it renders as nothing. Member access reads OWN properties of arrays and
+ * plain objects only (never `__proto__`, `constructor`, `prototype`, never a method). Every evaluated node and every
+ * element a function walks is charged against ONE operation budget per state update (`maxOperationsPerUpdate`), so a
+ * nested `map` / `filter` / `sortBy` cannot run away; collections are capped (`maxCollectionItems`), the elements
+ * allocated for intermediate collections are charged by their size as a tree (`maxAllocatedItemsPerEvaluation`), and a
+ * text result may not pass `maxTextLength`.
+ */
+export type ExpressionValue = string | number | boolean | null | undefined | ExpressionValue[] | {
+    [key: string]: ExpressionValue;
+};
+/** Why an expression gave no value: it did not compile, it ran over a budget, or it read itself (a cycle). */
+export type ExpressionErrorCode = "INVALID_EXPRESSION" | "BUDGET_EXCEEDED";
+export declare class ExpressionBudgetExceededError extends Error {
+}
+/** The budget counters of one state update, shared by every expression it evaluates. */
+export declare class ExpressionBudget {
+    readonly budgets: ComposedViewBudgets;
+    operationsLeft: number;
+    allocatedItemsLeft: number;
+    constructor(budgets: ComposedViewBudgets);
+    charge(operations?: number): void;
+    allocate(items: number): void;
+    checkCollection(items: ExpressionValue[]): void;
+    /** A text result may not pass `maxTextLength` — checked on the lengths BEFORE the text is built. */
+    checkTextLength(textLength: number): void;
+    /** The containers this update's expressions built, with their size as a tree (a shared one counted per use). */
+    protected readonly createdValueSizes: WeakMap<object, number>;
+    /**
+     * Charges a container an expression just built by its size as a TREE — a value built from earlier results counts
+     * them again wherever it repeats them, so `{l: o, r: o}` over `o` doubles and a chain of such values cannot grow
+     * past the allocation budget. A value the expression did not build (a dataset) counts 1.
+     */
+    allocateCreatedValue(createdValue: ExpressionValue[] | Record<string, ExpressionValue>): void;
+}
+/** Where a name comes from: lambda parameters first, then the tree's names (state, datasets, computed). */
+export type ExpressionNameResolver = (name: string) => ExpressionValue;
+export type ExpressionEvaluationResult = {
+    ok: true;
+    value: ExpressionValue;
+} | {
+    ok: false;
+    errorCode: ExpressionErrorCode;
+    message: string;
+};
+/** Compiles (cached) and evaluates one expression; never throws. */
+export declare const evaluateExpression: (source: string, resolveName: ExpressionNameResolver, budget: ExpressionBudget) => ExpressionEvaluationResult;
+export interface ComputedValuesResult {
+    values: Record<string, ExpressionValue>;
+    errors: Record<string, {
+        errorCode: ExpressionErrorCode;
+        message: string;
+    }>;
+}
+/**
+ * Every computed value of a tree for one state: each expression evaluated once, in dependency order (a computed value
+ * may read state, datasets and other computed values), under ONE budget. A cycle or a dependency chain deeper than
+ * `maxComputedDependencyDepth` leaves the values involved empty with `INVALID_EXPRESSION`.
+ */
+export declare const computeComposedViewValues: (computed: Record<string, string>, state: Record<string, ExpressionValue>, datasets: Record<string, ExpressionValue>, budgets: ComposedViewBudgets) => ComputedValuesResult;
+/** The tree names a computed expression reads, for its dependency list (empty when it does not compile). */
+export declare const findExpressionDependencies: (source: string, maxAstNodes: number) => string[];

package/dist/types/renderer/widget-tree/expression/parse-expression.d.ts

@@ -0,0 +1,71 @@
+/**
+ * The parser of the `ComposedView` expression language — our own tokenizer and recursive-descent
+ * parser, never `eval` or `new Function`. The language is closed:
+ *
+ *   literals      12, 3.5, "text", 'text', true, false, null, [a, b], {name: expr, "key": expr}
+ *   names         a state, dataset or computed name; a lambda parameter
+ *   member        a.b, a["b"], a[0]            (own properties of JSON values only — checked when evaluating)
+ *   operators     + - * / %   == != < <= > >=   && || !   unary -   cond ? a : b
+ *   calls         one of the closed functions (`EXPRESSION_FUNCTION_NAMES`), e.g. sum(rows, r => r.visits)
+ *   lambdas       x => expr, (x) => expr, (x, i) => expr — only as an argument of a call
+ *
+ * There are no statements, assignments, loops or method calls; a call names a function of the closed list, never a
+ * value. The AST node count is capped (`maxExpressionAstNodes`); an expression over it does not compile.
+ */
+export type ExpressionNode = {
+    kind: "literal";
+    value: string | number | boolean | null;
+} | {
+    kind: "name";
+    name: string;
+} | {
+    kind: "array";
+    elements: ExpressionNode[];
+} | {
+    kind: "object";
+    entries: Array<{
+        key: string;
+        value: ExpressionNode;
+    }>;
+} | {
+    kind: "member";
+    object: ExpressionNode;
+    property: ExpressionNode;
+} | {
+    kind: "unary";
+    operator: "!" | "-";
+    operand: ExpressionNode;
+} | {
+    kind: "binary";
+    operator: string;
+    left: ExpressionNode;
+    right: ExpressionNode;
+} | {
+    kind: "conditional";
+    test: ExpressionNode;
+    consequent: ExpressionNode;
+    alternate: ExpressionNode;
+} | {
+    kind: "call";
+    functionName: string;
+    args: ExpressionNode[];
+} | {
+    kind: "lambda";
+    params: string[];
+    body: ExpressionNode;
+};
+/** The closed function list (the evaluator implements exactly these). */
+export declare const EXPRESSION_FUNCTION_NAMES: readonly ["round", "floor", "ceil", "abs", "min", "max", "sum", "avg", "count", "len", "filter", "map", "sortBy", "first", "last", "concat", "join", "string", "number", "fixed", "percent"];
+export type ExpressionFunctionName = (typeof EXPRESSION_FUNCTION_NAMES)[number];
+export type ExpressionCompileResult = {
+    ok: true;
+    ast: ExpressionNode;
+    nodeCount: number;
+} | {
+    ok: false;
+    error: string;
+};
+/** Compiles an expression once (cached by source and node budget); never throws. */
+export declare const compileExpression: (source: string, maxAstNodes: number) => ExpressionCompileResult;
+/** The names an expression reads (lambda parameters excluded) — the computed dependency graph. */
+export declare const collectExpressionNames: (ast: ExpressionNode, boundNames?: ReadonlySet<string>) => Set<string>;

package/dist/types/renderer/widget-tree/resolve-composed-view-values.d.ts

@@ -0,0 +1,49 @@
+import type { ExpressionValue } from "./expression/evaluate-expression";
+import { JsonValue } from "./composed-view-tree";
+/**
+ * Turns bound props and datasets of a `ComposedView` tree into values. A binding is resolved in the
+ * browser from what the tree already holds: `$state` (the instance state), `$computed` (the evaluated expressions),
+ * `$data` (a dataset), `$item` (a field of the current row of an item scope — a dotted `author.name` reads a nested
+ * object, `readComposedViewRowField`), `$from` (the snapshot the backend writes INTO the
+ * binding when the row is stored — `{"$from": {"toolCall", "path", "state": "resolved", "value": …}}`;
+ * before that the binding is `pending`) and `$source` (a registered data source the frontend hydrates through the
+ * widget-hydration mechanism, `composed-view-data-sources.ts`; looked up by its binding key, `pending` until the rows
+ * arrive). A value that does not resolve is `undefined` and the prop renders empty.
+ */
+export type ResolvedBindingStatus = "resolved" | "pending" | "failed";
+export interface ComposedViewValueScope {
+    state: Record<string, ExpressionValue>;
+    computed: Record<string, ExpressionValue>;
+    datasets: Record<string, ExpressionValue>;
+    /**
+     * Each dataset's binding status (`resolveComposedViewDatasets().statusByDatasetName`): a prop bound with `$data` to a
+     * dataset whose `$from` / `$source` is still pending is pending itself, exactly like a direct `$from` binding.
+     */
+    datasetStatuses?: Record<string, ResolvedBindingStatus>;
+    /** The current row of the innermost item scope (`Repeat`), when inside one. */
+    item?: ExpressionValue;
+    /** The hydrated `$source` values, by binding key (`composedViewSourceBindingKey`). */
+    sources?: Record<string, ComposedViewSourceValue>;
+}
+export interface ComposedViewSourceValue {
+    status: ResolvedBindingStatus;
+    value: ExpressionValue;
+}
+/** The identity of a `$source` wire value — its name and parameters as written; null for another value. */
+export declare const composedViewSourceBindingKey: (wireValue: unknown) => string | null;
+export interface ResolvedComposedViewDatasets {
+    datasets: Record<string, ExpressionValue>;
+    statusByDatasetName: Record<string, ResolvedBindingStatus>;
+}
+/** The value and status a `$from` binding's stored snapshot carries. */
+export declare const readFromBindingSnapshot: (fromBindingObject: Record<string, unknown>) => {
+    status: ResolvedBindingStatus;
+    value: ExpressionValue;
+};
+/**
+ * The tree's datasets as values: inline rows as written, `$from` from its snapshot, `$source` from
+ * `sourceValuesByBindingKey` (filled by the data-source hydration; pending without).
+ */
+export declare const resolveComposedViewDatasets: (data: Record<string, JsonValue>, sourceValuesByBindingKey?: Record<string, ComposedViewSourceValue>) => ResolvedComposedViewDatasets;
+/** One prop value with its bindings resolved (nested bindings in inline data included). */
+export declare const resolveComposedViewValue: (wireValue: JsonValue | undefined, scope: ComposedViewValueScope, onBindingStatus?: (status: ResolvedBindingStatus) => void) => ExpressionValue;

package/dist/types/renderer/widget-tree/use-composed-view-state.d.ts

@@ -0,0 +1,16 @@
+import type { ComposedViewBudgets } from "./composed-node-schema";
+import type { ComposedViewTree } from "./composed-view-tree";
+/**
+ * The local state of one `ComposedView` instance: initialised from the tree's `state`, changed only by
+ * the tree's own inputs (`onChange: {"set": …}`) and the `resetState` action — never written anywhere, so a replayed
+ * message's inputs stay usable. Budgets: a string longer than `maxStateStringLength` is cut, a name the tree did
+ * not declare is ignored, and at most `maxInputUpdatesPerSecond` updates per second are applied (a dragged slider
+ * cannot flood the evaluator). A new tree (the payload changed under the same instance) starts from its own state.
+ */
+export type ComposedViewStateValue = string | number | boolean | null;
+export interface ComposedViewStateStore {
+    state: Record<string, ComposedViewStateValue>;
+    setStateValue: (name: string, value: unknown) => void;
+    resetState: () => void;
+}
+export declare const useComposedViewState: (tree: ComposedViewTree, budgets: ComposedViewBudgets) => ComposedViewStateStore;

package/dist/types/renderer/widget-windowing.d.ts

@@ -0,0 +1,25 @@
+import React, { RefObject } from "react";
+/**
+ * Viewport-windowing for chat widgets. Heavy interactive widgets (maps, lists, hydrating components) are mounted ONLY
+ * while near the viewport and unmounted back to a placeholder when far away — so a long conversation keeps a CONSTANT
+ * number of widgets mounted no matter how far you scroll. Two thresholds give hysteresis (reveal early, hide late) so a
+ * small scroll wobble never thrashes mount/unmount.
+ *
+ * The IntersectionObserver root is the chat scroll container, supplied via {@link WidgetWindowRootContext} by the chat
+ * host (ConversationViewBody). Observers are POOLED per (root, margin): all placeholders share two observers, not two each.
+ */
+export declare const WidgetWindowRootContext: React.Context<HTMLElement | null>;
+/**
+ * Drives a widget's mounted/unmounted state from its viewport proximity.
+ *
+ * - `pinned` (the freshly-delivered widget) → always revealed, never observed: a live widget must not unmount while its
+ *   one-shot effects (canvas auto-open) are in play, and re-mounting it later would re-fire them.
+ * - otherwise: starts at `initialRevealed` (the cheap index-window guess for first paint), then the reveal observer
+ *   mounts it when it scrolls within REVEAL_MARGIN and the hide observer unmounts it past HIDE_MARGIN.
+ *
+ * Returns `[revealed, reveal]` — `reveal` lets the placeholder force a manual mount (the "Show" affordance).
+ */
+export declare const useWidgetWindow: (targetRef: RefObject<HTMLElement | null>, options: {
+    initialRevealed: boolean;
+    pinned: boolean;
+}) => [boolean, () => void];