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

package/dist/types/image-render/WidgetImageRender.d.ts

@@ -0,0 +1,55 @@
+import React from "react";
+import type { WidgetImageRenderBootstrap } from "./widget-image-render.types";
+import type { createWidgetImageReadiness } from "./widget-image-readiness";
+/**
+ * Capture-only components by wire name: a frozen render shows the widget's visual from its complete snapshot, without
+ * mounting the live fetch / OAuth / polling wrappers. An app adds its own with `registerStaticWidgetImageComponents`.
+ */
+export declare const staticWidgetImageComponents: Record<string, React.ComponentType<Record<string, unknown>>>;
+/** Adds an app's capture-only components (wire name → component). Runs outside React, before the first render. */
+export declare const registerStaticWidgetImageComponents: (components: Readonly<Record<string, React.ComponentType<Record<string, unknown>>>>) => void;
+type Readiness = ReturnType<typeof createWidgetImageReadiness>;
+type HostProps = {
+    bootstrap: WidgetImageRenderBootstrap;
+    readiness: Readiness;
+};
+export declare class WidgetImageCaptureBoundary extends React.Component<{
+    children: React.ReactNode;
+    fail: Readiness["fail"];
+}, {
+    failed: boolean;
+}> {
+    state: {
+        failed: boolean;
+    };
+    static getDerivedStateFromError(): {
+        failed: boolean;
+    };
+    componentDidCatch(): void;
+    render(): React.ReactNode;
+}
+/**
+ * The static image render of one widget (the e-mail capture): the registered widget in its e-mail presentation, inside
+ * the read-only widget context, with the capture's frozen or live hydration. A frozen render takes the widget's static
+ * capture component when the app registered one (`registerStaticWidgetImageComponents`). The app mounts it inside its
+ * own store and theme (`WidgetImageCaptureBoundary` around it).
+ */
+export declare const WidgetImageRender: (props: HostProps) => import("react/jsx-runtime").JSX.Element | null;
+/** The slice the capture reads its hydration state from; any store that carries it (the capture's, a spec's). */
+interface StoreWithWidgetHydration {
+    getState: () => {
+        AIExtensionsWidgetHydration: {
+            widgets: Record<string, {
+                status: string;
+            }>;
+        };
+    };
+    subscribe: (listener: () => void) => () => void;
+}
+/**
+ * Holds the capture's readiness open while any widget hydration is idle or loading, and fails it on a hydration error.
+ * Every shared hydrator counts — a widget's own, and each `$source` binding of a `ComposedView` tree, which reads through
+ * the same slice (`ComposedViewDataSource:<name>`), so the shot waits for the tree's mail-time rows.
+ */
+export declare const followWidgetHydrationReadiness: (store: StoreWithWidgetHydration, readiness: Readiness) => () => void;
+export {};

package/dist/types/image-render/WidgetImageRenderContext.d.ts

@@ -0,0 +1,14 @@
+/** Null in the regular app. Supplied results apply only in explicit frozen-test mode. */
+export declare const WidgetImageRenderContext: import("react").Context<Record<string, unknown> | null>;
+export declare const useWidgetImageRender: () => Record<string, unknown> | null;
+export declare const WidgetImageLiveHydrationContext: import("react").Context<boolean>;
+export declare const useWidgetImageLiveHydration: () => boolean;
+export declare const WidgetImageReadinessContext: import("react").Context<{
+    ready: (element: HTMLElement, isCurrent?: () => boolean) => Promise<void>;
+    observe: (element: HTMLElement) => () => void;
+    fail: (code: string) => void;
+    isFailed: () => boolean;
+    beginRequest: () => () => void;
+    setHydrationPending: (pending: boolean) => void;
+} | null>;
+export declare const readFrozenHydration: (hydration: Record<string, unknown>, type: string, key: string) => unknown;

package/dist/types/image-render/composed-view-data-times.d.ts

@@ -0,0 +1,20 @@
+import { ComposedViewTree } from "../renderer/widget-tree/composed-view-tree";
+/**
+ * Which data paths of a `ComposedView` tree carry a time the report e-mail must state: the turn-time
+ * `$from` snapshots (the tool results the backend wrote into the block when the report message was stored) and the
+ * mail-time reads (a `$source` binding or an embedded domain widget, both read live while the e-mail is captured).
+ * Inline data carries its own source line and no time.
+ */
+export interface ComposedViewDataTimes {
+    /** The tree binds at least one `$from` tool result. */
+    hasTurnTimeSnapshot: boolean;
+    /**
+     * The newest `resolvedAt` (ISO 8601) the persist-time resolution wrote into a resolved `$from` snapshot, when it
+     * wrote one; otherwise undefined and the caption names the report time without a clock time.
+     */
+    turnTimeResolvedAt: string | undefined;
+    /** The tree reads at least one `$source` or embeds a self-hydrating domain widget. */
+    hasMailTimeRead: boolean;
+}
+/** The data paths with a time of a checked tree: its datasets and every node's props, embedded widgets included. */
+export declare const readComposedViewDataTimes: (tree: ComposedViewTree) => ComposedViewDataTimes;

package/dist/types/image-render/frozen-widget-requests.d.ts

@@ -0,0 +1,2 @@
+/** The capture page serves supplied GET results in memory. It never lends the render token to the SDK. */
+export declare const installFrozenWidgetRequests: (responses: Record<string, unknown>, fail: (code: string) => void) => () => void;

package/dist/types/image-render/live-widget-requests.d.ts

@@ -0,0 +1,4 @@
+import type { WidgetImageRenderBootstrap } from "./widget-image-render.types";
+import type { createWidgetImageReadiness } from "./widget-image-readiness";
+/** Loaded only by the capture entry. SDK signatures stay unchanged; no ambient credentials are sent. */
+export declare const installLiveWidgetRequests: (bootstrap: WidgetImageRenderBootstrap, readiness: ReturnType<typeof createWidgetImageReadiness>) => () => void;

package/dist/types/image-render/widget-image-google-map.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Whether a capture renders a Google map and so may load the Maps SDK (the narrow CSP and transport exception).
+ * The twin of the backend's check that opens the page's CSP: the app's map widgets themselves
+ * (`AgentsEnvironment.googleMapWidgetNames`), and a `ComposedView` whose tree holds a `Map` node or embeds one of them.
+ * The payload is read as written; a payload that does not parse renders no map.
+ */
+export declare const isGoogleMapCapture: (widgetName: string, props: Record<string, unknown>) => boolean;

package/dist/types/image-render/widget-image-readiness-signal.d.ts

@@ -0,0 +1,16 @@
+import type { WidgetImageReadiness } from "./widget-image-render.types";
+/** The `window` property the image capture waits on. */
+export declare const WIDGET_IMAGE_READINESS_GLOBAL_NAME = "__AGENTS_WIDGET_IMAGE_V1__";
+/**
+ * Every name the image readiness signal is published under: the package's own, then each name the app declares
+ * (`AgentsEnvironment.sandboxLegacyAliases.imageReadinessGlobalNames`) — read at each publish, so an app may declare
+ * them after a readiness was created.
+ */
+export declare const readWidgetImageReadinessGlobalNames: () => string[];
+/** Publishes (or with `undefined` clears) the image readiness signal under every name. */
+export declare const publishWidgetImageReadiness: (readiness: WidgetImageReadiness | undefined) => void;
+/**
+ * The published image readiness signal. A `failed` value under ANY name wins — the app's own capture code may have
+ * written it under a name it declared — otherwise the value under the package's name, otherwise the first value found.
+ */
+export declare const readWidgetImageReadiness: () => WidgetImageReadiness | undefined;

package/dist/types/image-render/widget-image-readiness.d.ts

@@ -0,0 +1,9 @@
+import type { WidgetImageRenderBootstrap } from "./widget-image-render.types";
+export declare const createWidgetImageReadiness: (bootstrap: WidgetImageRenderBootstrap) => {
+    ready: (element: HTMLElement, isCurrent?: () => boolean) => Promise<void>;
+    observe: (element: HTMLElement) => () => void;
+    fail: (code: string) => void;
+    isFailed: () => boolean;
+    beginRequest: () => () => void;
+    setHydrationPending: (pending: boolean) => void;
+};

package/dist/types/image-render/widget-image-render.types.d.ts

@@ -0,0 +1,47 @@
+export interface WidgetImageRenderInput {
+    mode?: "live" | "frozen";
+    widgetName: string;
+    props: Record<string, unknown>;
+    /** Hydrator type (or exact derived cache key) → already resolved, authorized result. */
+    hydration: Record<string, unknown>;
+    /** Optional frozen GET responses for older widgets that do not use the shared hydrator. */
+    responses?: Record<string, unknown>;
+    settings: Record<string, unknown>;
+    locale: string;
+    translations?: Record<string, string>;
+    width?: number;
+    maxHeight?: number;
+}
+export interface WidgetImageRenderBootstrap {
+    snapshotId: string;
+    attemptId: string;
+    inputSha256: string;
+    renderVersion: string;
+    userId: number;
+    siteId: number;
+    expiresAt: number;
+    /** Account bearer token for live hydration; frozen renders have no API credentials. */
+    authToken: string | null;
+    input: WidgetImageRenderInput;
+}
+export interface WidgetImageReadiness {
+    version: 1;
+    state: "loading" | "ready" | "failed";
+    snapshot_id?: string;
+    attempt_id?: string;
+    input_sha256?: string;
+    render_version?: string;
+    rect?: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    error_code?: string;
+}
+declare global {
+    interface Window {
+        /** The image capture's readiness signal (`publishWidgetImageReadiness` also writes it under the app's declared names). */
+        __AGENTS_WIDGET_IMAGE_V1__?: WidgetImageReadiness;
+    }
+}

package/dist/types/kit/ComposedViewConversationWidget.d.ts

@@ -0,0 +1,14 @@
+import type { PayloadConversationWidgetProps } from "../renderer/conversation-widget-props";
+/**
+ * The composable widget kit: the model composes a TREE of kit components — layout, text, data,
+ * media, inputs — with local state, computed values and a closed list of actions, in one ```widget fence of type
+ * `ComposedView`. The payload is read into typed objects and checked against the generated node schema
+ * (`widget-tree/composed-view-tree.ts`, the twin of the backend reader); what is invalid is dropped and reported, the
+ * rest renders. Inputs change local state only (no chat turn, no write), so a replay stays usable; the e-mail capture
+ * freezes them at their initial state.
+ *
+ * The kit's components register themselves by folder (`components/**\/*.composed.tsx`); this widget only parses,
+ * renders, reports and opens the `entityDetail` canvas for an `openEntity` action whose reference the backend resolved
+ * (a reference still unresolved opens nothing; without a message id — a streaming reply — nothing opens either).
+ */
+export declare const ComposedViewConversationWidget: (props: PayloadConversationWidgetProps) => import("react/jsx-runtime").JSX.Element;

package/dist/types/kit/ComposedViewDataSourceLoader.d.ts

@@ -0,0 +1,20 @@
+import { ComposedViewSourceBinding } from "../renderer/widget-tree/composed-view-data-sources";
+import type { ExpressionValue } from "../renderer/widget-tree/expression/evaluate-expression";
+import type { ComposedViewSourceValue } from "../renderer/widget-tree/resolve-composed-view-values";
+interface ComposedViewDataSourceLoaderProps {
+    sourceBinding: ComposedViewSourceBinding;
+    state: Record<string, ExpressionValue>;
+    agentSpaceKey: number | undefined;
+    /** Whether this tree may start another read (the per-tree budget); a refused change keeps the last parameters. */
+    mayRead: () => boolean;
+    onValue: (bindingKey: string, sourceValue: ComposedViewSourceValue) => void;
+}
+/**
+ * Reads ONE `$source` binding of a tree through the widget-hydration mechanism and hands the rows up.
+ * Renders nothing; one component per binding, so the number of hooks never depends on the tree. The hydration reads
+ * again whenever the payload changes, so a parameter change is first debounced, then counted against the tree's budget
+ * (`maxSourceRequestsPerTreePerMinute`); a refused change keeps the rows of the last accepted parameters. A source
+ * without a registered frontend fetcher fails at once (`UNRESOLVED_BINDING` in the report).
+ */
+export declare const ComposedViewDataSourceLoader: (props: ComposedViewDataSourceLoaderProps) => null;
+export {};

package/dist/types/kit/ComposedViewRenderer.d.ts

@@ -0,0 +1,30 @@
+import { ComposedViewAction, ComposedViewTree } from "../renderer/widget-tree/composed-view-tree";
+import { ExpressionValue } from "../renderer/widget-tree/expression/evaluate-expression";
+import type { WidgetRenderReportEntry } from "../renderer/render-report/widget-render-report";
+/**
+ * Renders a checked `ComposedView` tree: one state store per instance, the datasets and computed
+ * values for the current state, then the node tree — each node through its registered component, each slot node in its
+ * own error boundary, the slot's size class handed down. The renderer folds the tree's findings, the expression
+ * errors, the nodes' own reports and the pending bindings into ONE block status for the render report. A finding that
+ * drops nothing (the schema's `noteFindingCodes`: figures without a source, a choice state outside its choices, a set
+ * state nothing reads, an `$item` field the rows lack, a slot under its minimum) never fails the block: a block that rendered reports `mounted`
+ * with that code as a note, which the chat tells the model.
+ */
+export interface ComposedViewRendererProps {
+    tree: ComposedViewTree;
+    interactive: boolean;
+    isEmailRender: boolean;
+    messageId?: string | number;
+    agentSpaceKey?: string | number;
+    /** The block status, whenever it changes. */
+    onReport: (entry: WidgetRenderReportEntry) => void;
+    /**
+     * Runs an `openEntity` action — the `entityDetail` canvas. A platform-minted reference carries the entity the backend
+     * resolved it to; a row-bound action (`ref: {"$item":"entityRef"}`) comes with `currentRow`, the row it fired in,
+     * whose `entity` it opens (`readOpenEntityActionTarget(action, currentRow)`).
+     */
+    onOpenEntity?: (action: ComposedViewAction, currentRow?: ExpressionValue) => void;
+    testId?: string;
+}
+/** The `ComposedView` tree, rendered. */
+export declare const ComposedViewRenderer: (props: ComposedViewRendererProps) => import("react/jsx-runtime").JSX.Element;

package/dist/types/kit/ComposedViewSlotErrorBoundary.d.ts

@@ -0,0 +1,23 @@
+import React from "react";
+interface ComposedViewSlotErrorBoundaryProps {
+    /** Where the node sits in the tree (`view.children[2]`), for the report. */
+    nodePath: string;
+    nodeType: string;
+    onRenderFailed: (nodePath: string, nodeType: string) => void;
+    children: React.ReactNode;
+}
+interface ComposedViewSlotErrorBoundaryState {
+    hasFailed: boolean;
+}
+/**
+ * One node of a `ComposedView` tree inside its own error boundary (per-slot context): a node that throws
+ * renders nothing and is reported `failed` (`RENDER_FAILED`), the rest of the tree stays. React error boundaries
+ * require a class.
+ */
+export declare class ComposedViewSlotErrorBoundary extends React.Component<ComposedViewSlotErrorBoundaryProps, ComposedViewSlotErrorBoundaryState> {
+    state: ComposedViewSlotErrorBoundaryState;
+    static getDerivedStateFromError(): ComposedViewSlotErrorBoundaryState;
+    componentDidCatch(error: Error): void;
+    render(): React.ReactNode;
+}
+export {};

package/dist/types/kit/ModelText/ModelText.d.ts

@@ -0,0 +1,12 @@
+import { Text } from "../../provider/components";
+import type { ComponentProps } from "react";
+export type ModelTextProps = Omit<ComponentProps<typeof Text>, "children" | "translate"> & {
+    /** The model's words — shown as written: never translated, never parsed as markup. */
+    children: string;
+};
+/**
+ * The component library's `Text` for a string the MODEL wrote (`model-text.ts`): `translate={false}` and the string
+ * escaped, so `<b onmouseover="…">` or `<link href="…">` in a model's label renders as those characters. Every other
+ * `Text` prop passes through.
+ */
+export declare const ModelText: (props: ModelTextProps) => import("react/jsx-runtime").JSX.Element;

package/dist/types/kit/components/embedding/EmbeddedConversationWidget.d.ts

@@ -0,0 +1,26 @@
+import { WidgetRenderReportCode, WidgetRenderStatus } from "../../../renderer/render-report/widget-render-report";
+export interface EmbeddedConversationWidgetProps {
+    /** The wire name as written (a legacy `…Directive` name resolves as everywhere). */
+    widgetName: string;
+    /** The widget's own fields — its `payload`, exactly as its own fence would carry them next to `type`. */
+    fields: Record<string, unknown>;
+    /** The key of the tree's agent space; the key in the fields wins. */
+    agentSpaceKey?: string | number;
+    interactive: boolean;
+    messageId?: string | number;
+    /**
+     * Where the widget's own render report goes — the tree's report at the node's path, never the host block's reporter
+     * (an embedded widget and the tree would otherwise overwrite each other's report).
+     */
+    reportStatus: (status: WidgetRenderStatus, code?: WidgetRenderReportCode, detail?: string) => void;
+}
+/**
+ * A domain widget rendered inside a `ComposedView` — as a `Widget` node in the tree, or as a widget the readers LIFTED
+ * out of it and show after the view. It renders the registered component with the tree's
+ * context: `interactive` and `messageId` of the host message, the agent space, and `justDelivered = false`, so it never
+ * auto-opens a canvas (the owner opens it by clicking). It gets its OWN render-report context, which forwards its
+ * statuses into the tree's report, names the widget in the detail, and turns a crash (`RENDER_FAILED`) or an unknown
+ * name (`INVALID_NODE`) into a report instead of a silent nothing. The registry's feature gate applies as it does to
+ * the widget's own fence. The registry is read at render time, never at module load (the registry imports this kit).
+ */
+export declare const EmbeddedConversationWidget: (props: EmbeddedConversationWidgetProps) => import("react/jsx-runtime").JSX.Element | null;

package/dist/types/kit/components/map/map-full-screen-instance.d.ts

@@ -0,0 +1,26 @@
+import { type ComposedViewNode, type ComposedViewTree } from "../../../renderer/widget-tree/composed-view-tree";
+/**
+ * Which `Map` node a `mapFullScreen` canvas shows. A canvas is a pointer to its anchor message, so the
+ * instance id carries only the message and a short hash of the node — its id and its
+ * wire props — and the body finds the node again in the message's `ComposedView` fences. Two identical maps in one
+ * message are one canvas; a map whose message no longer carries it opens nothing.
+ *
+ * Format `mapFullScreen:message:<messageId>:map-<hash>` — the `map-` part keeps it apart from the payload-hash form
+ * (`payloadHashOfInstanceId`), which the shared canvas helpers would otherwise read as a fence hash.
+ */
+export declare const MAP_NODE_TYPE = "Map";
+/** The short hash of a map node: its id and its props as written (bindings unresolved), so it is stable across renders. */
+export declare const buildMapNodeKey: (mapNode: ComposedViewNode) => string;
+export declare const canvasInstanceIdForMapFullScreen: (messageId: number, mapNode: ComposedViewNode) => string;
+/** The map node key a `mapFullScreen` instance id carries, or undefined for another shape. */
+export declare const readMapNodeKeyOfInstanceId: (instanceId: string) => string | undefined;
+export interface MapNodeInComposedView {
+    /** The whole tree the map sits in — its state, data, computed values and actions resolve the map's bindings. */
+    tree: ComposedViewTree;
+    mapNode: ComposedViewNode;
+}
+/**
+ * The `Map` node with this key among the `ComposedView` fences of a message, with its tree. Total: an unparsable
+ * message or a missing map gives undefined, never a throw (a canvas body runs outside the message's error boundary).
+ */
+export declare const findMapNodeInMarkdown: (markdown: string, mapNodeKey: string) => MapNodeInComposedView | undefined;

package/dist/types/kit/components/map/map-presentation-context.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Where a `Map` node renders: `inline` in the chat (the map card with its carousel and the expand
+ * control), or `fullScreen` in the `mapFullScreen` canvas (the map filling the pane beside the list of points). The
+ * canvas body renders the same node through the same renderer and provides `fullScreen`; nothing else changes.
+ */
+export type MapPresentation = "inline" | "fullScreen";
+export declare const MapPresentationContext: import("react").Context<MapPresentation>;
+export declare const useMapPresentation: () => MapPresentation;

package/dist/types/kit/components/text/shared/text-node-values.d.ts

@@ -0,0 +1,39 @@
+import type { ExpressionValue } from "../../../../renderer/widget-tree/expression/evaluate-expression";
+import type { ComposedViewRuntime } from "../../../composed-view-component-types";
+/**
+ * The value readers the text components of the `ComposedView` kit share. A prop arrives with its binding
+ * resolved, so it may be anything an expression yields — every reader takes `ExpressionValue` and never throws: a value
+ * that does not fit gives `invalid`, a missing one `missing`, and the component renders nothing for both and reports it.
+ */
+/** What a text prop holds: the text to show, nothing, or a value no text can be made of (an object, a list). */
+export type TextNodeContent = {
+    kind: "text";
+    text: string;
+} | {
+    kind: "missing";
+} | {
+    kind: "invalid";
+};
+/** A string, a finite number or a boolean is text; `null`, `undefined` and the empty string are missing; the rest is invalid. */
+export declare const readTextNodeContent: (value: ExpressionValue) => TextNodeContent;
+/** The value when it is one of `allowedValues`, else `fallback` — an enum prop bound to state may hold anything. */
+export declare const readAllowedValue: <T extends string>(value: ExpressionValue, allowedValues: readonly T[], fallback: T) => T;
+/**
+ * The address when it is an absolute http(s) URL, else null — `javascript:`, `data:`, `mailto:`, a relative path and a
+ * malformed string are never a link target in the kit (the `openUrl` action holds the same rule).
+ */
+export declare const readSafeHttpUrl: (value: ExpressionValue) => string | null;
+/** The site's host name (without `www.`) of an http(s) URL or a bare domain (`wdr.de`), else null. */
+export declare const readSiteHostname: (value: ExpressionValue) => string | null;
+/** The favicon of a host, from the Google favicon service — the source the web search references use. */
+export declare const buildFaviconUrl: (hostname: string) => string;
+/** What one text node reports: still waiting for a bound value, shown, nothing to show, or a value it cannot show. */
+export type TextNodeRenderState = "pending" | "shown" | "empty" | "invalid";
+/**
+ * Reports a text node's render state into the block report whenever it changes — never a silent nothing:
+ * `empty` when there is nothing to show, `failed INVALID_PROP` when the value cannot be shown, `pending` while a bound
+ * value waits for its data.
+ */
+export declare const useReportTextNodeRenderState: (runtime: ComposedViewRuntime, renderState: TextNodeRenderState, nodeType: string, invalidDetail?: string) => void;
+/** The render state of a node whose one text prop decides it. */
+export declare const readTextNodeRenderState: (isPending: boolean, content: TextNodeContent) => TextNodeRenderState;

package/dist/types/kit/composed-view-component-types.d.ts

@@ -0,0 +1,61 @@
+import type React from "react";
+import type { ComposedSizeClass } from "../renderer/widget-tree/composed-node-schema";
+import type { ComposedViewNode } from "../renderer/widget-tree/composed-view-tree";
+import type { ExpressionValue } from "../renderer/widget-tree/expression/evaluate-expression";
+import type { WidgetRenderReportCode, WidgetRenderStatus } from "../renderer/render-report/widget-render-report";
+/**
+ * The contract between the `ComposedView` renderer and ONE kit component. A component is added as
+ * one file `components/<group>/<Name>.composed.tsx` that exports `composedViewComponent` — the folder glob of
+ * `composed-view-components.ts` registers it; no list is edited. The component receives its node, its props with every
+ * binding resolved, its slots already rendered (each slot node inside its own error boundary), the size class of the
+ * slot it sits in and the runtime of the tree instance.
+ */
+export interface ComposedViewRuntime {
+    /** The instance state, read-only (inputs write through {@link setStateValue}). */
+    state: Record<string, ExpressionValue>;
+    /** Write a state value (an input's `onChange: {"set": "<name>"}`); ignored when the tree is frozen (email). */
+    setStateValue: (stateName: string, value: unknown) => void;
+    /**
+     * Run an event prop (`{"set": …}` with a value, or `{"action": …}`). `eventRow` is the row the event fires for when
+     * it is not {@link currentRow} (a `Map` point); an `openEntity` action bound to the row (`ref: {"$item":"entityRef"}`)
+     * opens that row's `entity`.
+     */
+    runEvent: (eventWireValue: unknown, eventValue?: unknown, eventRow?: ExpressionValue) => void;
+    /**
+     * The row of the innermost item scope this node renders in (`$item` of a `Repeat`, a table row), undefined outside
+     * one — the row a row-bound `openEntity` action opens the `entity` of.
+     */
+    currentRow?: ExpressionValue;
+    /** The controls may be used (a live message or the newest reply; a replay keeps local inputs usable). */
+    interactive: boolean;
+    /** The e-mail capture renders the tree: inputs frozen at their initial state, no controls. */
+    isEmailRender: boolean;
+    /** The host message (canvas anchor) and the key of the agent space the tree is scoped to. */
+    messageId?: string | number;
+    agentSpaceKey?: string | number;
+    /** The tree's named action (an own property of `actions`), or undefined — lets a node tell a resolvable `openEntity` from a dangling name. */
+    findAction?: (actionName: string) => Record<string, unknown> | undefined;
+    /** Report this node's render status into the block's report. */
+    reportNodeStatus: (status: WidgetRenderStatus, code?: WidgetRenderReportCode, detail?: string) => void;
+}
+export interface ComposedViewComponentProps {
+    node: ComposedViewNode;
+    /** The node's props, bindings resolved; an unresolved binding is `undefined`. */
+    props: Record<string, ExpressionValue>;
+    /** Whether a bound prop is still waiting for its data (`$from` before its snapshot, `$source` before hydration) — render a skeleton. */
+    isPending: boolean;
+    /** The rendered nodes of each slot (`children` = the default slot). A slot of an item-scope node is rendered per row through {@link renderSlotForItem}. */
+    slots: Record<string, React.ReactNode[]>;
+    /** The room this node has, from the slot it sits in (`full` at the root). */
+    sizeClass: ComposedSizeClass;
+    /** Renders a slot once per row with `$item` bound to the row — for item-scope nodes (`Repeat`, table bodies). */
+    renderSlotForItem: (slotName: string, item: ExpressionValue, itemIndex: number) => React.ReactNode[];
+    runtime: ComposedViewRuntime;
+    /** QA selector of this node: `<widget test id>-<node type>-<node id or tree path>`; the component derives its parts from it. */
+    testId: string;
+}
+export interface ComposedViewComponentDefinition {
+    /** The node type (the backend `NODE_TYPE`). */
+    nodeType: string;
+    component: React.ComponentType<ComposedViewComponentProps>;
+}

package/dist/types/kit/composed-view-components.d.ts

@@ -0,0 +1,7 @@
+import type { ComposedViewComponentDefinition } from "./composed-view-component-types";
+export declare const buildComposedViewComponentRegistry: (definitions: ComposedViewComponentDefinition[]) => Readonly<Record<string, ComposedViewComponentDefinition>>;
+/** Node type → component, from the folder. */
+export declare const composedViewComponents: Readonly<Record<string, ComposedViewComponentDefinition>>;
+/** The registry the renderer uses — the folder's by default; a story or a spec may provide its own stub components. */
+export declare const ComposedViewComponentsContext: import("react").Context<Readonly<Record<string, ComposedViewComponentDefinition>>>;
+export declare const useComposedViewComponents: () => Readonly<Record<string, ComposedViewComponentDefinition>>;

package/dist/types/kit/composed-view-tones.d.ts

@@ -0,0 +1,20 @@
+/**
+ * The ONE tone list of the composable kit (the backend twin is `ComposedViewTone.php`):
+ * the judgement or role a text, a badge, a value, an icon or a map status line takes. Every node with a `tone` prop
+ * reads it through {@link readComposedViewTone}, so a model that learned one word uses it everywhere. The words some
+ * nodes accepted before the list existed stay accepted on the wire (both tree readers list them as allowed values) and
+ * read as their tone here: `default` (Text) is `neutral`, `positive` / `negative` (Map status lines) are `success` /
+ * `danger`.
+ */
+export declare const COMPOSED_VIEW_TONES: readonly ["neutral", "muted", "success", "warning", "danger", "info"];
+export type ComposedViewTone = (typeof COMPOSED_VIEW_TONES)[number];
+/** The older words, accepted on the wire and read as their tone. */
+export declare const COMPOSED_VIEW_TONE_ALIASES: Readonly<Record<string, ComposedViewTone>>;
+/** The tone a prop names — one of the list or an alias — else `fallback` (a bound value may hold anything). */
+export declare const readComposedViewTone: (value: unknown, fallback?: ComposedViewTone) => ComposedViewTone;
+/** The tone a prop names, or `undefined` when it names none (a status line without a tone stays plain). */
+export declare const readOptionalComposedViewTone: (value: unknown) => ComposedViewTone | undefined;
+/** The text colour of a tone, for the component library's `Text`'s `color` prop — judgement text in the 900 step (500 on dark). */
+export declare const COMPOSED_VIEW_TONE_TEXT_COLOR: Readonly<Record<ComposedViewTone, string>>;
+/** The graphic colour of a tone — an icon fill in the 500 step. */
+export declare const COMPOSED_VIEW_TONE_GRAPHIC_COLOR: Readonly<Record<ComposedViewTone, string>>;

package/dist/types/kit/entity-detail/EntityDetailCanvasBody.d.ts

@@ -0,0 +1,9 @@
+import type { CanvasBodyProps } from "../../renderer/canvas/canvas-body-props";
+/**
+ * The `entityDetail` CANVAS BODY (`canvasBodies.tsx`): the shell around one entity's detail. It reads
+ * WHICH entity from the canvas instance id (`entityDetail:<entityType>:<id>`) and mounts the body registered for that
+ * entity type; the body self-hydrates by id. An entity type without a body renders a short notice instead of nothing,
+ * so a click never lands on an empty pane. "Ask about this" stays at the pane's foot while the detail scrolls and
+ * names the entity in its chip once the body reported the name (`useReportEntityDetailName`).
+ */
+export declare const EntityDetailCanvasBody: ({ canvas, agentSpaceKey }: CanvasBodyProps) => import("react/jsx-runtime").JSX.Element | null;

package/dist/types/kit/entity-detail/entity-detail-bodies.d.ts

@@ -0,0 +1,32 @@
+import type React from "react";
+/**
+ * The bodies of the `entityDetail` canvas, one per entity type: every `*.entity-detail-body.tsx` below
+ * `widgets/` that exports `entityDetailBody` registers itself by folder glob — an entity type is added with
+ * the backend `<Type>EntityReferenceResolver` and this one file, and edits no list. A second body for one entity type
+ * is a build error (thrown at module load).
+ */
+export interface EntityDetailBodyProps {
+    entityType: string;
+    /** The id as the backend resolved it (a row id or an external id). */
+    entityId: string;
+    /** The key of the agent space the chat is scoped to, for a body whose read endpoint is agent-space-scoped. */
+    agentSpaceKey?: number;
+}
+export interface EntityDetailBodyDefinition {
+    /** The backend resolver's `ENTITY_TYPE`. */
+    entityType: string;
+    /** Self-hydrates the entity by id through its own read endpoint (the endpoint's entity rights apply). */
+    component: React.ComponentType<EntityDetailBodyProps>;
+}
+export declare const buildEntityDetailBodyRegistry: (definitions: EntityDetailBodyDefinition[]) => Readonly<Record<string, EntityDetailBodyDefinition>>;
+/** The body definitions a set of `*.entity-detail-body.tsx` modules export (the package's or an app's glob). */
+export declare const readEntityDetailBodyDefinitions: (modules: Record<string, {
+    entityDetailBody?: EntityDetailBodyDefinition;
+}>) => EntityDetailBodyDefinition[];
+/** Entity type → body: the package's folder, then what an app registers (`registerEntityDetailBodies`). */
+export declare const entityDetailBodies: Record<string, EntityDetailBodyDefinition>;
+/** Adds an app's entity detail bodies. Runs outside React, before the first render; an entity type registers once. */
+export declare const registerEntityDetailBodies: (definitions: readonly EntityDetailBodyDefinition[]) => void;
+/** The registry the canvas body uses — the folder's by default; a spec or a story may provide stubs. */
+export declare const EntityDetailBodiesContext: React.Context<Readonly<Record<string, EntityDetailBodyDefinition>>>;
+export declare const useEntityDetailBodies: () => Readonly<Record<string, EntityDetailBodyDefinition>>;

package/dist/types/kit/entity-detail/entity-detail-name.d.ts

@@ -0,0 +1,9 @@
+/**
+ * The name of the entity the `entityDetail` canvas shows: a detail body knows it only once it hydrated,
+ * the shell needs it for the "Ask about this" chip — ChatGPT's follow-up chip names the business, a chip without it
+ * says "About this entry". A body reports the name with {@link useReportEntityDetailName}; outside the shell (a story,
+ * a spec of the body alone) the report goes nowhere.
+ */
+export declare const EntityDetailNameReportContext: import("react").Context<(entityName: string | undefined) => void>;
+/** Reports the shown entity's name (the hydrated business, keyword or review title) to the `entityDetail` shell. */
+export declare const useReportEntityDetailName: (entityName: string | undefined) => void;

package/dist/types/kit/hooks/use-debounced-value.d.ts

@@ -0,0 +1,2 @@
+/** The value as it was `delayMs` after its last change. */
+export declare const useDebouncedValue: <T>(value: T, delayMs: number) => T;

package/dist/types/kit/map-full-screen/MapFullScreenCanvasBody.d.ts

@@ -0,0 +1,11 @@
+import type { CanvasBodyProps } from "../../renderer/canvas/canvas-body-props";
+/**
+ * The `mapFullScreen` CANVAS BODY (`canvasBodies.tsx`): one `Map` node of the anchor
+ * message, full screen — the map filling the pane beside the list of its points. It finds the node through the
+ * message's `ComposedView` fences and the node key its instance id carries (`map-full-screen-instance.ts`), then
+ * renders it through the same `ComposedViewRenderer` with the node's own tree, so its bindings (`$data`, `$from`,
+ * `$source`, `$computed`, `$state` at its initial value) and its actions resolve exactly as inline; the
+ * `MapPresentationContext` switches the node to its full-screen layout. A point's `openEntity` action opens the
+ * `entityDetail` canvas on the same anchor message (it replaces this canvas, as a click on an inline point would).
+ */
+export declare const MapFullScreenCanvasBody: (props: CanvasBodyProps) => import("react/jsx-runtime").JSX.Element;

package/dist/types/preview/WidgetPreviewHost.d.ts

@@ -0,0 +1,20 @@
+import type { WidgetPreviewReadiness } from "./widget-preview-readiness";
+import type { WidgetPreviewBootstrap, WidgetPreviewFixture } from "./widget-preview.types";
+/**
+ * The widget preview host: ONE widget from ONE fixture, outside the chat, in the mode the script
+ * asks for. Unlike the e-mail capture host it keeps a working canvas pane (an `openCanvas` request mounts the canvas
+ * body beside the widget, its anchor message being the fixture's fence) and a composer log (what the widget sent,
+ * prefilled or signalled), so the interactions of the ChatGPT reference can be driven and checked. The app mounts it in
+ * its store (the capture's store state); every request is served from the fixture (`widget-preview-requests.ts`). The fixture's
+ * `hydration` is the capture's frozen hydration only in `email` mode; `interactive` and `replay` serve it through the
+ * preview's hydrators (`widget-preview-hydration.ts`), so the widget runs as in the chat (a canvas auto-opens).
+ */
+/** The key of the agent space a fixture without its own renders for. */
+export declare const PREVIEW_AGENT_SPACE_KEY = 1;
+export interface WidgetPreviewProps {
+    bootstrap: WidgetPreviewBootstrap;
+    fixture: WidgetPreviewFixture;
+    readiness: WidgetPreviewReadiness;
+    hasHydrationError: () => boolean;
+}
+export declare const WidgetPreview: (props: WidgetPreviewProps) => import("react/jsx-runtime").JSX.Element | null;

package/dist/types/preview/preview-stub-components.d.ts

@@ -0,0 +1,3 @@
+import type { ComposedViewComponentDefinition } from "../kit/composed-view-component-types";
+/** The folder registry with a stub for every node type that has no component of its own. */
+export declare const buildPreviewComposedViewComponents: () => Readonly<Record<string, ComposedViewComponentDefinition>>;

package/dist/types/preview/widget-preview-fixtures.d.ts

@@ -0,0 +1,17 @@
+import type { WidgetPreviewFixture, WidgetPreviewFixtureFile } from "./widget-preview.types";
+/** Every fixture file, sorted by wire name; filled in place by `registerWidgetPreviewFixtureFiles`. */
+export declare const widgetPreviewFixtureFiles: WidgetPreviewFixtureFile[];
+/** Adds an app's fixture files (its glob stays in its code). Runs before the preview reads a fixture. */
+export declare const registerWidgetPreviewFixtureFiles: (fixtureFiles: readonly WidgetPreviewFixtureFile[]) => void;
+/**
+ * The fixtures of a widget from EVERY file naming it — a `ComposedView` component can add its own file next to it
+ * instead of editing the widget's — or an empty list. A fixture an app registers under the name of a package fixture
+ * of the same widget replaces it in place (an app's copy with its own entity types and endpoints). Each is read under
+ * the agent space key field the app declares (`mapFixtureToDeclaredAgentSpaceKeyFieldName`; the package's files name
+ * `agentSpaceId`), at call time: an app installs its environment after this module is loaded.
+ */
+export declare const findWidgetPreviewFixtures: (widgetName: string) => readonly WidgetPreviewFixture[];
+/** One named fixture, or undefined. */
+export declare const findWidgetPreviewFixture: (widgetName: string, fixtureName: string) => WidgetPreviewFixture | undefined;
+/** The fence the fixture stands for — what a canvas body re-reads as its anchor message. */
+export declare const buildWidgetPreviewFence: (widgetName: string, fixture: WidgetPreviewFixture) => string;