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

package/dist/types/provider/environment.d.ts

@@ -0,0 +1,262 @@
+import type { ComponentType, ErrorInfo, ReactNode } from "react";
+import type { AgentsComponents } from "./components/types";
+import type { ConversationWidgetStatePartition } from "../renderer/conversation-widget-state-partition";
+import type { ChatAssistantCategory } from "../chat/chat-assistant-identity";
+import type { ComposedNodeSchemaApplicationPart } from "../renderer/widget-tree/composed-node-schema";
+import type { CanvasBehaviour } from "../renderer/canvas/canvas-behaviours";
+/** Translates interface copy. The key is the English source text. */
+export interface AgentsTexts {
+    translate: (key: string, replacements?: Record<string, string | number>, context?: string) => string;
+}
+/** One image of a gallery the app opens over the page. */
+export interface AgentsGalleryImage {
+    /** Identifies the image within the gallery. */
+    id: string;
+    url: string;
+    name?: string;
+}
+/** An action the package dispatches into the state store. */
+export interface AgentsStateAction {
+    type: string;
+    payload?: unknown;
+}
+/**
+ * A state store as React hooks: the package keeps its widget hydration state in it, and an app's older chat state
+ * partitions are read through it (`defaultChatStatePartition`). Without an app store the package uses its own.
+ */
+export interface AgentsStateStore {
+    useSelector: <Selected>(selector: (state: any) => Selected) => Selected;
+    useDispatch: () => (action: AgentsStateAction) => unknown;
+}
+/** The owner's language and the active agent space's date and time settings. Every field may be missing. */
+export interface AgentsOwnerSettings {
+    /** The owner's language (`de`). */
+    languageCode?: string | null;
+    /** The owner's locale (`de-DE`). */
+    locale?: string | null;
+    /** The date locale of the active agent space (`de-DE`). */
+    dateLocale?: string | null;
+    /** The time zone of the active agent space. */
+    timeZone?: string | null;
+    /** The active agent space writes times with AM/PM. */
+    usesAmPm?: boolean | null;
+}
+/** What the error card of a reached budget offers (the error card's upgrade data). */
+export interface AgentsBudgetLimit {
+    /** An upgrade lifts the limit: the card offers it. */
+    canUpgrade: boolean;
+    /** Opens the app's upgrade flow. */
+    openUpgrade: () => void;
+    /** The app presents the budget as a fair-use allowance (the card uses that wording). */
+    showsFairUseWording: boolean;
+}
+/** The badge of a named assistant's icon (its intro card, its openings). */
+export interface AgentsAssistantIconBadgeProps {
+    /** The icon's name in the app's icon set (`ChatAssistantIdentity.iconClass`). */
+    iconName: string;
+    color: string;
+    backgroundColor: string;
+    /** Larger on the intro card than on an opening. */
+    isLarge?: boolean;
+}
+/** The background of a chat with a named assistant's category (or with none, the overview of every category). */
+export interface AgentsAssistantBackgroundProps {
+    category?: ChatAssistantCategory;
+    /** The category's alias; undefined for a chat without a category. */
+    categoryAlias?: string;
+}
+/** The state of the app's map script loader. */
+export interface AgentsMapsLoaderState {
+    isLoaded: boolean;
+    loadError: Error | undefined;
+    languageCode: string | undefined;
+}
+/**
+ * Further names of the sandbox and readiness signals that an app declares beside the package's own (`AGENTS_VISUALIZATION`,
+ * `--agents-*`, `__AGENTS_WIDGET_IMAGE_V1__`, `__AGENTS_WIDGET_PREVIEW_V1__`): the names its stored visualization scripts,
+ * its skill texts or its headless capture already use. Every list is optional; the package's names always exist.
+ */
+export type AgentsSandboxLegacyAliases = {
+    /** Further names of the sandbox global, e.g. the name stored scripts of the app read. */
+    visualizationGlobalNames?: string[];
+    /** Further prefixes of the frame's theme variables, e.g. `--app-` (each variable is set under every prefix). */
+    themeVariablePrefixes?: string[];
+    /** Further names of the image-capture readiness signal on `window`. */
+    imageReadinessGlobalNames?: string[];
+    /** Further names of the preview readiness signal on `window`. */
+    previewReadinessGlobalNames?: string[];
+};
+/**
+ * Everything an app supplies to the package. Every member is optional: the package has a default for each.
+ * An app sets it once at start (`setAgentsEnvironment`) or per subtree (`AgentsProvider`); the functions are read
+ * from the app-wide environment only.
+ */
+export interface AgentsEnvironment {
+    /**
+     * The state store hooks (see `AgentsStateStore`). Default: the package's own widget hydration store (one per page,
+     * `createAgentsWidgetHydrationStateStore`). An app supplies its own to keep the hydration state in its store
+     * (host application: its Redux store, which mounts `WidgetHydrationReducer` under `AIExtensionsWidgetHydration`).
+     */
+    stateStore?: AgentsStateStore;
+    /**
+     * The partition of the app's own chat state a widget provider reads when its host passes neither a chat store nor a
+     * partition (host application: the AI-Extensions chat's slice). Default: none — such a provider keeps a store of its own.
+     */
+    defaultChatStatePartition?: ConversationWidgetStatePartition;
+    /** A React hook returning the owner's settings. Default: none known (the browser's language stands in). */
+    useOwnerSettings?: () => AgentsOwnerSettings;
+    /**
+     * A React hook returning the key of the agent space the owner works in. The key of an agent space is what the
+     * client knows it by: the id of the space, unless the app's backend hands out another key
+     * (`AgentSpace::getWidgetSelfHydrationKey()`). Default: no agent space.
+     */
+    useActiveAgentSpaceKey?: () => number | undefined;
+    /** Reads the display name of an agent space (the header of a widget of another agent space). Default: no name. */
+    readAgentSpaceName?: (agentSpaceKey: number, signal: AbortSignal) => Promise<string | undefined>;
+    /**
+     * The field of a widget block that carries the key of the block's agent space, as the app's backend writes it
+     * (`WidgetBlockFieldNames::WIDGET_SELF_HYDRATION_KEY`). An app whose stored conversations use another field name
+     * declares it here and in its backend class. Default: `agentSpaceId`.
+     */
+    widgetSelfHydrationKeyFieldName?: string;
+    /**
+     * The owner's text for a click on a widget of another agent space than the active one: returns the text with the
+     * suffix the app's backend reads that agent space from
+     * (`WidgetBlockFieldNames::OWNER_TEXT_SUFFIX_PATTERN_OF_ANOTHER_SPACE`). Default: the text unchanged.
+     */
+    appendAnotherAgentSpaceToOwnerText?: (ownerText: string, anotherAgentSpaceKey: number) => string;
+    /** The label of an agent space whose name is not known. Default: `#<key>`. */
+    buildUnnamedAgentSpaceLabel?: (agentSpaceKey: number) => string;
+    /**
+     * The sentence that tells the owner that a widget shows another agent space than the active one; `agentSpaceLabel`
+     * is its name or the label above. Default: a sentence that names no kind of agent space.
+     */
+    buildWidgetOfAnotherAgentSpaceExplanation?: (agentSpaceLabel: string) => string;
+    /** The name the owner knows the agent by, for the interface texts that name it. Default: `the assistant`. */
+    agentDisplayName?: string;
+    /** A React hook returning what the error card of a reached budget offers. Default: no upgrade, the plain wording. */
+    useBudgetLimit?: () => AgentsBudgetLimit;
+    /** A React hook returning the map script loader's state. Default: no maps. */
+    useMapsLoader?: () => AgentsMapsLoaderState;
+    /**
+     * The action that tells the app whether an agent chat surface is open (dispatched into the state store when the
+     * first surface mounts and the last unmounts). Default: nothing is dispatched.
+     */
+    buildChatSurfaceOpenChangedAction?: (isOpen: boolean) => AgentsStateAction;
+    components?: Partial<AgentsComponents>;
+    texts?: AgentsTexts;
+    /**
+     * Prepares a plain text (a model's words, a business name) for the app's `Text`, `Button` and `StatusBadge`
+     * replacements, which may read a string as markup. Default: the text unchanged.
+     */
+    escapePlainTextForText?: (text: string) => string;
+    /** Opens the images in the app's lightbox, starting at `startIndex`. Default: the start image in a new tab. */
+    openImageGallery?: (images: AgentsGalleryImage[], startIndex: number) => void;
+    /** Reports a widget that crashed while rendering. Default: nothing (the crash is logged to the console). */
+    reportWidgetCrash?: (widgetName: string, error: Error, errorInfo: ErrorInfo) => void;
+    /**
+     * The footer under an assistant message (host application: the admin's forensics panel, which gates itself). Receives the
+     * message as the message view got it. Default: none.
+     */
+    MessageFooter?: ComponentType<{
+        message?: unknown;
+    }>;
+    /**
+     * The colour theme class of a named assistant's category (the assistant identity and theme). Default:
+     * none — the generic chat colours.
+     */
+    readAssistantThemeClassName?: (categoryAlias: string) => string;
+    /** The badge of a named assistant's icon. Default: none. */
+    AssistantIconBadge?: ComponentType<AgentsAssistantIconBadgeProps>;
+    /** The chat's own background when the host paints none (host application: the category illustrations). Default: none. */
+    AssistantBackground?: ComponentType<AgentsAssistantBackgroundProps>;
+    /**
+     * Wraps the body of an open canvas (host application: page components inside a canvas must not mirror their filters into
+     * the page URL). Default: no wrapper.
+     */
+    CanvasBodyContainer?: ComponentType<{
+        children: ReactNode;
+    }>;
+    /**
+     * Tells the app that a turn of the agent runs in an open chat (the host application keeps the tab "ambient active" then);
+     * returns the release the chat calls when the turn ends. Default: nothing.
+     */
+    reportRunningTurn?: () => () => void;
+    /**
+     * Further names of the CustomVisualization sandbox (its global, its theme variable prefixes) and of the image and
+     * preview readiness signals, beside the package's own names (see `AgentsSandboxLegacyAliases`). An app whose stored
+     * scripts or capture read older names declares them here. Default: none — only the package's names exist.
+     */
+    sandboxLegacyAliases?: AgentsSandboxLegacyAliases;
+    /**
+     * The app's part of the ComposedView node schema: the node types, widgets (which embed, at which size), data sources
+     * and entity types its own classes declare, as its backend generates them beside the package's
+     * `composed-node-schema.json`. The tree readers and the kit read the package's schema with this part added
+     * (`getComposedNodeSchema`). Default: none — only the package's own types exist.
+     */
+    composedNodeSchemaApplicationPart?: ComposedNodeSchemaApplicationPart;
+    /**
+     * The path prefix of the app's API reads a live widget image capture lets through (same origin, GET only, sent with
+     * the capture's bearer; every other request of the capture fails it). Default: `/api/`.
+     */
+    widgetImageCaptureReadPathPrefix?: string;
+    /**
+     * The app's widgets that draw a Google map: a widget image capture of one of them, or of a `ComposedView` that embeds
+     * one, may load the Maps SDK (the narrow transport exception of the capture; the twin of the backend's list that opens
+     * the capture page's CSP). A `ComposedView` holding a `Map` node always may. Default: none.
+     */
+    googleMapWidgetNames?: string[];
+    /**
+     * Further `signalSource`s a widget click of the app posts (`injectSignal`), beside the package's own
+     * (`FRONTEND_WIDGET_CLICK`, `OWNER_ACTION_CONFIRM`): the message list reads every one of them as the owner's answer to
+     * a widget, so an answered widget never comes back interactive after a reload. Default: none.
+     */
+    furtherWidgetClickSignalSources?: string[];
+    /**
+     * The canvases of the app's widgets (canvas id → behaviour), beside the package's own (`packageCanvasBehaviours`):
+     * every canvas an app widget lists in `opensCanvases`. The app registers each one's body with `registerCanvasBodies`
+     * and, when gated, its requirement with `registerCanvasFeatureFlags`. A package canvas id here is ignored. Default:
+     * none.
+     */
+    furtherCanvasBehaviours?: Readonly<Record<string, CanvasBehaviour>>;
+}
+/** Sets the app-wide environment. Call it once before the first render; a later call re-renders the readers. */
+export declare const setAgentsEnvironment: (environment: AgentsEnvironment) => void;
+export declare const getAgentsEnvironment: () => AgentsEnvironment;
+export declare const subscribeToAgentsEnvironment: (listener: () => void) => (() => void);
+/** The package default: the English key with its placeholders substituted. */
+export declare const DEFAULT_AGENTS_TEXTS: AgentsTexts;
+/** Translates an interface text through the app-wide environment, for a string a component hands on (a label). */
+export declare const translateText: (key: string, replacements?: Record<string, string | number>, context?: string) => string;
+/** A plain text as the app's text components take it (`AgentsEnvironment.escapePlainTextForText`). */
+export declare const escapePlainTextForText: (text: string) => string;
+/** Opens an image gallery over the page (`AgentsEnvironment.openImageGallery`). */
+export declare const openImageGallery: (images: AgentsGalleryImage[], startIndex: number) => void;
+/** The block field of the package's backend default (`WidgetBlockFieldNames::WIDGET_SELF_HYDRATION_KEY`). */
+export declare const DEFAULT_WIDGET_SELF_HYDRATION_KEY_FIELD_NAME = "agentSpaceId";
+/** The field of a widget block that carries the key of its agent space (`AgentsEnvironment.widgetSelfHydrationKeyFieldName`). */
+export declare const getWidgetSelfHydrationKeyFieldName: () => string;
+/** The owner's text for a click on a widget of another agent space (`AgentsEnvironment.appendAnotherAgentSpaceToOwnerText`). */
+export declare const appendAnotherAgentSpaceToOwnerText: (ownerText: string, anotherAgentSpaceKey: number) => string;
+/** The label of an agent space without a known name (`AgentsEnvironment.buildUnnamedAgentSpaceLabel`). */
+export declare const buildUnnamedAgentSpaceLabel: (agentSpaceKey: number) => string;
+/** The sentence under a widget of another agent space (`AgentsEnvironment.buildWidgetOfAnotherAgentSpaceExplanation`). */
+export declare const buildWidgetOfAnotherAgentSpaceExplanation: (agentSpaceLabel: string) => string;
+/** The further sandbox and readiness names the app declares (`AgentsEnvironment.sandboxLegacyAliases`). */
+export declare const getSandboxLegacyAliases: () => AgentsSandboxLegacyAliases;
+/** The package default of `AgentsEnvironment.widgetImageCaptureReadPathPrefix`. */
+export declare const DEFAULT_WIDGET_IMAGE_CAPTURE_READ_PATH_PREFIX = "/api/";
+/** The path prefix of the API reads a live widget image capture lets through (`AgentsEnvironment.widgetImageCaptureReadPathPrefix`). */
+export declare const getWidgetImageCaptureReadPathPrefix: () => string;
+/** The app's widgets that draw a Google map (`AgentsEnvironment.googleMapWidgetNames`). */
+export declare const getGoogleMapWidgetNames: () => readonly string[];
+/** The app's further widget click signal sources (`AgentsEnvironment.furtherWidgetClickSignalSources`). */
+export declare const getFurtherWidgetClickSignalSources: () => readonly string[];
+/** The canvases of the app's widgets (`AgentsEnvironment.furtherCanvasBehaviours`). */
+export declare const getFurtherCanvasBehaviours: () => Readonly<Record<string, CanvasBehaviour>>;
+/** The name the owner knows the agent by (`AgentsEnvironment.agentDisplayName`). */
+export declare const getAgentDisplayName: () => string;
+/** Reports a running turn of an open chat (`AgentsEnvironment.reportRunningTurn`); returns the release. */
+export declare const reportRunningTurn: () => (() => void) | undefined;
+/** Reports a crashed widget (`AgentsEnvironment.reportWidgetCrash`). */
+export declare const reportWidgetCrash: (widgetName: string, error: Error, errorInfo: ErrorInfo) => void;

package/dist/types/provider/index.d.ts

@@ -0,0 +1,4 @@
+export { AgentsProvider, type AgentsProviderProps, useAgentsActiveAgentSpaceKey, useAgentsBudgetLimit, useAgentsComponents, useAgentsEnvironment, useAgentsMapsLoader, useAgentsOwnerSettings, useAgentsStateDispatch, useAgentsStateSelector, useAgentsTexts, } from "./AgentsProvider";
+export { type AgentsAssistantBackgroundProps, type AgentsAssistantIconBadgeProps, type AgentsBudgetLimit, type AgentsEnvironment, type AgentsGalleryImage, type AgentsMapsLoaderState, type AgentsOwnerSettings, type AgentsSandboxLegacyAliases, type AgentsStateAction, type AgentsStateStore, type AgentsTexts, appendAnotherAgentSpaceToOwnerText, buildUnnamedAgentSpaceLabel, buildWidgetOfAnotherAgentSpaceExplanation, DEFAULT_AGENTS_TEXTS, DEFAULT_WIDGET_IMAGE_CAPTURE_READ_PATH_PREFIX, DEFAULT_WIDGET_SELF_HYDRATION_KEY_FIELD_NAME, escapePlainTextForText, getAgentDisplayName, getAgentsEnvironment, getFurtherCanvasBehaviours, getFurtherWidgetClickSignalSources, getGoogleMapWidgetNames, getSandboxLegacyAliases, getWidgetImageCaptureReadPathPrefix, getWidgetSelfHydrationKeyFieldName, openImageGallery, reportRunningTurn, reportWidgetCrash, setAgentsEnvironment, translateText, } from "./environment";
+export { classNames } from "./class-names";
+export * from "./components";

package/dist/types/renderer/ConversationDeepLinkedWidget.d.ts

@@ -0,0 +1,18 @@
+export interface ConversationDeepLinkedWidgetProps {
+    /** Canonical registry wire name, from `?agentWidget=` or a restored pinned canvas. Unknown / not deep-linkable → nothing renders. */
+    widgetName?: string;
+    /** The key of the chat's agent space, forwarded to the widget exactly as a markdown attribute would carry it. */
+    agentSpaceKey?: number;
+}
+/**
+ * Mounts ONE registered widget outside the message list — the customer opened it from a page (`?agentWidget=`). The
+ * widget receives `openedByPage` (plus `interactive` / `justDelivered`), so a canvas-opening widget (an app's editor
+ * widget, `ExampleWidget`) opens its canvas with origin `openedByPage` and a page anchor; nothing is written to the
+ * conversation, no message and no signal. (A canvas that was open before a reload comes back through
+ * `CanvasRestoreOnMount`, not through this mount.)
+ *
+ * Rendered with the entry's feature gate and the shared error boundary, but WITHOUT the viewport windowing of
+ * {@link ConversationWidgetHost}: there is no message to scroll past here, and a windowed wrapper would unmount a
+ * zero-height widget (these widgets render `null` and live entirely in the canvas), taking its canvas with it.
+ */
+export declare const ConversationDeepLinkedWidget: ({ widgetName, agentSpaceKey }: ConversationDeepLinkedWidgetProps) => import("react/jsx-runtime").JSX.Element | null;

package/dist/types/renderer/ConversationMarkdown.d.ts

@@ -0,0 +1,21 @@
+export interface ConversationMarkdownProps {
+    markdown: string;
+    /**
+     * Forwarded into every widget instance as `interactive` (and its deprecated alias `fresh`): the widget's controls
+     * may be used. True for a live-delivered message and for the newest assistant reply after a reload.
+     */
+    interactive?: boolean;
+    /**
+     * Forwarded into every widget instance as `justDelivered`: the message was delivered live right now. The only gate
+     * for one-shot side effects (canvas open, draft creation); never true after a reload or on replay.
+     */
+    justDelivered?: boolean;
+    /** Id of the host message, forwarded so a widget can identify the canvas it opens. */
+    messageId?: string | number;
+    /**
+     * When true, widgets are replaced with a lightweight placeholder.
+     * Used for old messages to keep the chat scroll cheap.
+     */
+    hideWidgets?: boolean;
+}
+export declare const ConversationMarkdown: (props: ConversationMarkdownProps) => import("react/jsx-runtime").JSX.Element;

package/dist/types/renderer/ConversationWidgetActions/ConversationWidgetActions.d.ts

@@ -0,0 +1,7 @@
+import type { ReactNode } from "react";
+interface ConversationWidgetActionsProps {
+    children: ReactNode;
+}
+/** Wrap the entire action area, including its footer/divider, to omit it from email images. */
+export declare const ConversationWidgetActions: (props: ConversationWidgetActionsProps) => import("react/jsx-runtime").JSX.Element | null;
+export {};

package/dist/types/renderer/ConversationWidgetCallbacksContext.d.ts

@@ -0,0 +1,234 @@
+import { ReactNode } from "react";
+import { ConversationComposerWidget } from "./conversation-composer-widget";
+import { CanvasOpenRequest, CanvasState, LastClosedCanvas } from "./canvas/canvas-state";
+import type { CanvasCreatedEntity } from "./canvas/canvas-reducers";
+/** A message of the transcript a widget reads (its id and author role); the chat's messages carry more. */
+export interface ConversationWidgetTranscriptMessage {
+    id?: number | string | null;
+    role?: string | null;
+}
+export type ChatEngagementMediaItem = {
+    id?: number;
+    publicUrl: string;
+    publicThumbnailUrl?: string;
+    type?: string;
+};
+export type ChatEngagementMediaItems = ChatEngagementMediaItem[];
+/** A post or event the owner edits from the chat — the fields the edit widget reads off its payload. */
+export type ChatEngagementTarget = {
+    kind: "post";
+    id: number;
+    title?: string;
+    content?: string;
+    status?: string;
+    scheduleAt?: string;
+    startDate?: string;
+    endDate?: string;
+    mediaItems?: ChatEngagementMediaItems;
+} | {
+    kind: "event";
+    id: number;
+    title?: string;
+    content?: string;
+    status?: string;
+    scheduleAt?: string;
+    startDate?: string;
+    endDate?: string;
+    mediaItems?: ChatEngagementMediaItems;
+};
+export interface OpenEngagementEditConversationWidgetPayload {
+    target: ChatEngagementTarget;
+    mode: "edit";
+}
+/**
+ * What an opener passes to `openCanvas`: the request minus the two facts the PROVIDER knows better than any widget —
+ * whether the viewport is wide enough for the split, and whether the host renders a canvas surface at all.
+ */
+export type CanvasOpenRequestFromOpener = Omit<CanvasOpenRequest, "viewportViable" | "hostHasCanvasSurface">;
+export type InjectSignalOptions = {
+    /**
+     * The signal is context for the CURRENT turn (e.g. specialist instructions riding along a just-posted user
+     * message) and must NOT drive its own agent turn / produce its own reply. The chat host delivers it only while a
+     * turn is observed running — a signal appended mid-turn lands in the conversation history without re-driving the
+     * agent (the backend only re-drives when the LAST message is an unanswered inbound). If no turn starts, the signal
+     * is dropped.
+     */
+    withoutOwnAgentTurn?: boolean;
+    /**
+     * Overrides the server-side default signal source (FRONTEND_WIDGET_CLICK), e.g. the business-basics form
+     * submit's own source.
+     */
+    signalSource?: string;
+    /**
+     * Who produced the signal. CUSTOMER_CLICK (the default when omitted): the customer pressed a widget button or CTA,
+     * so the chat scrolls to follow the turn and a refusal (closed conversation, backend 400) goes on the error card.
+     * PROGRAMMATIC: an effect or ride-along emitted it without a customer action (store-diff feedback, the
+     * widget-invalid corrective, specialist instructions) — refusals are dropped silently, nothing scrolls.
+     */
+    signalOrigin?: "CUSTOMER_CLICK" | "PROGRAMMATIC";
+};
+export interface ConversationWidgetCallbacks {
+    /**
+     * THE CANVAS MODEL. The canvas is data in the chat's slice
+     * partition: a pointer to its anchor message (or page), an identity and a render generation — see
+     * `canvas/canvas-state.ts`. `openCanvas` is the one way to open for all four origins; the opening rule
+     * (`canvas/decide-canvas-open.ts`) decides inside the reducer. `closeCanvas(byCustomer)` keeps the canvas re-openable
+     * as `lastClosedCanvas`. The shell (`CanvasPane`) renders the body from `canvasBodies`; nothing else
+     * holds a canvas.
+     */
+    canvas: CanvasState | null;
+    /**
+     * Whether this host renders a canvas surface at all. A mount-time opener reads it to tell "the customer has no
+     * canvas here" from "my request was dropped while the host was still coming up" — the latter is worth asking again.
+     */
+    hostHasCanvasSurface: boolean;
+    lastClosedCanvas: LastClosedCanvas | null;
+    openCanvas: (request: CanvasOpenRequestFromOpener) => void;
+    closeCanvas: (byCustomer: boolean) => void;
+    /**
+     * Re-open `lastClosedCanvas` as a customer action (origin `cardClick`): the canvas toggle button on the divider, the
+     * narrow-viewport re-open control, the compact → expand path. No-op when nothing was closed.
+     */
+    reopenLastClosedCanvas: () => void;
+    /**
+     * A body created its entity (the post editor's draft): remember the id on the canvas it was created for, so a
+     * re-open or a restore edits that entity instead of creating another. Identity + generation checked in the reducer.
+     */
+    setCanvasCreatedEntityId: (created: CanvasCreatedEntity) => void;
+    /**
+     * Contracts (minimizes) the host drawer/modal so the app behind stays
+     * visible during navigation. Called by the Navigate tool before animating.
+     * No-op by default; hosts that support compacting override this.
+     */
+    minimizeChatHost: () => void;
+    /**
+     * Forget the canvas and the last closed one — a conversation switch, where the previous conversation's canvas is
+     * stale outright (`clearCanvas` in the canvas model; the LEFT conversation keeps its stored pointer).
+     */
+    resetCanvas: () => void;
+    /**
+     * The SEND boundary of the canvas model, called by the shell on a typed send (the hosts call it for widget sends
+     * too): a `turn` canvas is over for good, a `pinned` canvas stays open — see `canvas-reducers.ts`.
+     */
+    resetCanvasForNewTurn: () => void;
+    /**
+     * Post the message as a visible USER bubble and drive one agent turn — the widget-button twin of the typed input.
+     * Mirrors `injectSignal`'s contract: a host may return a promise resolving to `true` only once the send was
+     * actually accepted (dispatched/posted), `false` when a caller-side guard dropped it (a closed conversation, an
+     * in-flight start). `void`/no result counts as accepted for a host that doesn't report (e.g. Conversation.tsx) —
+     * only a widget that explicitly awaits `false` must keep its controls usable.
+     */
+    sendMessageToChat: (message: string) => void | Promise<boolean>;
+    /**
+     * Put text into the chat's composer (the message input) and focus it, WITHOUT sending — the widget-button twin
+     * of a host-owned control using `ConversationMessageInputHandle.insertTextIntoInput` directly (e.g. the agent "+"
+     * menu's "Generate image" entry). Used by a widget option that is a TEMPLATE with a blank the owner must still
+     * fill in (QuickReplies' placeholder-option pill): sending it as-is would post the literal blank as the owner's
+     * message. No-op by default; hosts that own a chat input wire it to that input's imperative handle.
+     */
+    prefillComposer: (text: string) => void;
+    /**
+     * Inject a model-visible / user-invisible SIGNAL into the CURRENT conversation and drive one agent turn. Unlike
+     * `sendMessageToChat` (which posts a visible USER message), this does NOT render a chat bubble — it tells the agent
+     * something happened (e.g. "User selected image A") and lets it continue. The reply lands via the existing realtime
+     * signal, exactly like a posted message. Set by chat hosts that own a conversation id; no-op by default.
+     * Hosts may return a promise resolving to true only after the signal was accepted. False or no result
+     * means delivery is not confirmed; callers that retire controls must wait for true.
+     */
+    injectSignal: (signalText: string, options?: InjectSignalOptions) => void | Promise<boolean>;
+    /**
+     * Key of the agent space the chat is scoped to. Set by hosts that mount the chat outside a
+     * route of the agent space (e.g. a host whose panel opens on a page with no agent space
+     * in the URL). Widget hydrators fall back to this when the URL path / active-agent-space
+     * store can't supply one — without it they fetch with a missing key and every section 404s.
+     * Undefined for in-route hosts, which keep their existing behavior.
+     */
+    chatAgentSpaceKey?: number;
+    /**
+     * Whether the chat's agent turn is RUNNING right now (the slice partition's `aiThinking`). A status widget whose
+     * backing run is still open reads this to tell "being applied" from "paused — waiting for the owner's reply": the
+     * turn ended (a question, a step budget notice) while the run stays open. Read from the provider's slice, never
+     * passed by a host.
+     */
+    isConversationRunning: boolean;
+    /**
+     * The conversation's run is over (`runState` COMPLETED or CANCELLED): the backend rejects further input. Read from
+     * the provider's slice, for a canvas body, which gets no per-message `interactive` flag.
+     */
+    isConversationClosed: boolean;
+    /**
+     * Conversation id the chat is currently showing. Set by hosts that know it (AgentChat). Scopes the stored canvas
+     * pointer (`canvas/canvasStorage.ts`) — undefined on hosts that don't set it simply means the canvas does not come
+     * back after a reload there.
+     */
+    conversationId?: number;
+    /**
+     * Composer widgets currently held in the chat input — the composer-side twin of a rendered widget (a widget
+     * instance that lives in the input before send; see `ConversationComposerWidget`). Rendered by the generic
+     * `ConversationMessageInputComposerWidgets` strip via each entry's registry `composerComponent`.
+     *
+     * Always a concrete array (never undefined on the context value itself — only the CALLBACKS prop a host supplies
+     * is optional, deciding ownership):
+     *  - **Controlled** — a host passes `composerWidgets` (e.g. an app's builder page, whose preview
+     *    is a *sibling* of `<Conversation>`). Every mutation below is then routed to the host's
+     *    `onComposerWidgetsChange(next)` instead of local state.
+     *  - **Uncontrolled** — the host omits it (every chat-as-host surface today). The provider owns a
+     *    `useState<ConversationComposerWidget[]>([])` and a *descendant* (e.g. an app's editor drawer) mutates it
+     *    directly via the functions below.
+     */
+    composerWidgets: ConversationComposerWidget[];
+    /** Add a new composer widget (or the first element of one); returns its client-only `composerWidgetId`. */
+    addComposerWidget: (widgetName: string, fields: Record<string, unknown>) => string;
+    /** Replace one composer widget's fields in place (e.g. drop one element out of several). */
+    replaceComposerWidgetFields: (composerWidgetId: string, fields: Record<string, unknown>) => void;
+    /** Remove one composer widget entirely (its ✕, or Backspace when it has no removable parts left). */
+    removeComposerWidget: (composerWidgetId: string) => void;
+    /** Remove every composer widget — called on send. */
+    clearComposerWidgets: () => void;
+    /**
+     * Controlled-mode sink: called with the FULL next array on every composer-widget mutation
+     * (add/replace/remove/clear). Ignored (mutations apply to local state instead) when the host doesn't also pass
+     * `composerWidgets`.
+     */
+    onComposerWidgetsChange?: (next: ConversationComposerWidget[]) => void;
+    onOpenConversation?: (conversationId: number, messageId?: number) => void;
+    /**
+     * Switch THIS chat to another conversation of the same agent space in place (no new tab) — the door a widget that links
+     * to related work ("Open the conversation") takes when that conversation belongs to the agent space the chat is open
+     * on. Undefined on hosts without a conversation switcher.
+     */
+    onSwitchConversation?: (conversationId: number) => void;
+    /**
+     * True while the chat is the guided first-run setup: the host mounts the agent on ONE conversation it may not
+     * leave (the full-page setup route) AND that conversation's purpose declares a customer progress stepper — the
+     * same presence contract the stepper itself renders on (no purpose-name checks in the frontend). Widgets read it
+     * to offer setup-only affordances, e.g. a connect widget's "Skip for now" deferral. False on every
+     * other surface (the floating widget, the website builder, a purposed setup conversation reopened from history).
+     */
+    isOnboardingSetupConversation?: boolean;
+    /**
+     * The transcript this widget lives in, read from the door's own partition (`sliceInstance.selectState`) — the same
+     * source `canvas` above reads. `null` before the conversation loads. A one-shot widget (e.g. QuickReplies) reads
+     * this to tell "the owner already answered a later question" from its own `messageId`: any message with
+     * `role === "USER"` AFTER the widget's host message means the widget is stale, regardless of `interactive` (which
+     * stays true for the whole live session, not just until the next owner message).
+     */
+    messages: ConversationWidgetTranscriptMessage[] | null;
+}
+export declare const defaultConversationWidgetCallbacks: ConversationWidgetCallbacks;
+/** The widget callbacks a chat host (or a standalone host) supplies to every widget below it. */
+export declare const ConversationWidgetContext: import("react").Context<ConversationWidgetCallbacks>;
+/** Static capture host: no conversation, persistence, canvas effects or action callbacks. */
+export declare const ReadOnlyConversationWidgetProvider: (props: {
+    children: ReactNode;
+    agentSpaceKey: number;
+}) => import("react/jsx-runtime").JSX.Element;
+/**
+ * A host outside the chat that supplies its OWN callbacks — the widget preview keeps its canvas and its
+ * composer log itself. Every callback it leaves out keeps the no-op default; no conversation slice is involved.
+ */
+export declare const StandaloneConversationWidgetProvider: (props: {
+    children: ReactNode;
+    callbacks: Partial<ConversationWidgetCallbacks>;
+}) => import("react/jsx-runtime").JSX.Element;
+export declare const useConversationWidgetContext: () => ConversationWidgetCallbacks;

package/dist/types/renderer/ConversationWidgetContext.d.ts

@@ -0,0 +1,32 @@
+import { ReactNode } from "react";
+import type { ConversationWidgetStatePartition } from "./conversation-widget-state-partition";
+import type { AgentsChatStore } from "../chat/store/create-agents-chat-store";
+import { type ConversationWidgetCallbacks } from "./ConversationWidgetCallbacksContext";
+export * from "./ConversationWidgetCallbacksContext";
+export interface ConversationWidgetProviderProps {
+    children: ReactNode;
+    callbacks: Partial<ConversationWidgetCallbacks>;
+    /**
+     * The chat slice partition this provider's canvas lives in. The shell is shared by the two chat doors, so the door
+     * says which partition: `AgentChat` passes `AgentChatInstance`; the AI-Extensions chat, every story and every spec
+     * keep the default. A prop, not a callback — `callbacks` is `Partial`, and the partition is not optional.
+     */
+    sliceInstance?: ConversationWidgetStatePartition;
+    /**
+     * The package chat store of the chat: the agent chat passes its window's store and the provider reads
+     * and writes the canvas there. Without it the provider reads a partition of the app's own chat state
+     * (`sliceInstance`, else the environment's `defaultChatStatePartition`).
+     */
+    chatStore?: AgentsChatStore;
+    /**
+     * False for a host that renders the chat without the split (`ConversationView.disableSplitView`): there is nowhere
+     * to open a canvas, so every open request is ignored with reason `noSurface`. Default true.
+     */
+    hostHasCanvasSurface?: boolean;
+}
+/**
+ * The widget callbacks of one chat, the canvas model included. Reads the chat's state from the package chat store when
+ * the host passes one (`chatStore`), else from a partition of the app's own chat state (`sliceInstance`, or the
+ * environment's `defaultChatStatePartition` — host application: the AI-Extensions chat), else from a store of its own.
+ */
+export declare const ConversationWidgetProvider: (props: ConversationWidgetProviderProps) => import("react/jsx-runtime").JSX.Element;

package/dist/types/renderer/ConversationWidgetErrorBoundary.d.ts

@@ -0,0 +1,25 @@
+import React from "react";
+interface Props {
+    /** Canonical widget name, for the error log. */
+    widgetName: string;
+    /** Called once when the widget threw — the render report marks the block `failed`. */
+    onCrash?: () => void;
+    children: React.ReactNode;
+}
+interface State {
+    hasError: boolean;
+}
+/**
+ * Per-widget error boundary. Widget props originate from LLM output, so a
+ * malformed payload can throw anywhere in a widget's render/effects — without a
+ * boundary one bad widget unmounts the entire chat message. On error the
+ * widget renders nothing (the surrounding prose stays intact) and the failure
+ * is logged with the widget name.
+ */
+export declare class ConversationWidgetErrorBoundary extends React.Component<Props, State> {
+    state: State;
+    static getDerivedStateFromError(): State;
+    componentDidCatch(error: Error, errorInfo: React.ErrorInfo): void;
+    render(): React.ReactNode;
+}
+export {};

package/dist/types/renderer/ConversationWidgetHost.d.ts

@@ -0,0 +1,36 @@
+import React from "react";
+import { ConversationWidgetEntry } from "./conversationWidgetRegistry";
+export type ConversationWidgetRenderProps = Record<string, unknown> & {
+    children?: React.ReactNode;
+    fresh?: boolean;
+    interactive?: boolean;
+    justDelivered?: boolean;
+    messageId?: string | number;
+};
+interface ConversationWidgetHostProps {
+    widget: ConversationWidgetEntry;
+    /** Forwarded into the widget (and as its deprecated alias `fresh`): the widget's controls may be used. */
+    interactive: boolean;
+    /** Forwarded into the widget: the host message was delivered live right now — the one-shot side-effect gate. */
+    justDelivered: boolean;
+    /** Id of the host message, forwarded so a widget can identify the canvas it opens. */
+    messageId?: string | number;
+    /** When true, the widget renders as a lightweight placeholder (cheap scroll). */
+    hideWidgets: boolean;
+    /** Parsed markdown attributes for this widget instance. */
+    conversationWidgetRenderProps: ConversationWidgetRenderProps;
+}
+/**
+ * Single render path for every widget. Each concern is applied as a sequential gate
+ * (innermost → outermost):
+ *   1. the widget itself, with `interactive` / `justDelivered`
+ *   2. feature-flag gate
+ *   3. viewport-windowing (mount near the viewport, placeholder when far — WindowedWidget)
+ *   4. block spacing wrapper
+ *
+ * A block of a JUST-DELIVERED message is also registered with the chat's render-report collector: it
+ * counts as `mounted` unless the widget reports otherwise through `useReportWidgetRenderStatus`, and a crash caught by
+ * the error boundary reports `failed` (`RENDER_FAILED`). A replayed message reports nothing.
+ */
+export declare const ConversationWidgetHost: ({ widget, interactive, justDelivered, messageId, hideWidgets, conversationWidgetRenderProps, }: ConversationWidgetHostProps) => import("react/jsx-runtime").JSX.Element;
+export {};