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

package/dist/types/renderer/conversation-composer-widget.d.ts

@@ -0,0 +1,13 @@
+/**
+ * A widget instance living in the chat input BEFORE the message is sent — the composer-side twin of a rendered
+ * widget: same wire name, same fields, structured (never raw text) until send assembles the fence
+ * (`buildMessageTextWithComposerWidgets`, `composer-widget-fence.ts`).
+ */
+export interface ConversationComposerWidget {
+    /** Client-only identity of this composer instance (`crypto.randomUUID()`); never sent. */
+    composerWidgetId: string;
+    /** The canonical wire name — becomes the fence `type`. */
+    widgetName: string;
+    /** The fence's non-`type` fields, structured. After the round-trip this is what the widget receives as `payload`. */
+    fields: Record<string, unknown>;
+}

package/dist/types/renderer/conversation-widget-props.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Common props injected into every widget component by ConversationMarkdown.
+ *
+ * Markdown attributes (the `key='value'` pairs inside `::Name{...}`) are spread as props by react-markdown.
+ * ConversationMarkdown additionally injects two flags derived from the host message, answering two
+ * separate questions:
+ *   - `interactive`   → the widget's controls may be used (buttons, forms, hydration refresh). True for a message
+ *                       delivered live in this session AND for the newest assistant reply after a reload, so a
+ *                       customer who reloads mid-setup still sees the question's buttons.
+ *   - `justDelivered` → the message was delivered live in this session, right now. NEVER true after a reload or on
+ *                       history replay. The ONLY gate for one-shot side effects: opening a canvas, creating a draft,
+ *                       generating a campaign, charging budget.
+ *
+ * `fresh` is kept as a deprecated alias of `interactive` so existing widgets keep working; a widget that opens a
+ * canvas or mutates anything on mount must read `justDelivered`.
+ */
+export interface BaseConversationWidgetProps {
+    /** @deprecated alias of `interactive` — read `interactive` (controls usable) or `justDelivered` (one-shot side effects). */
+    fresh?: boolean;
+    /** The widget's controls may be used; see the interface docblock. */
+    interactive?: boolean;
+    /** The host message was delivered live right now; the only gate for one-shot side effects. */
+    justDelivered?: boolean;
+    /** Id of the host message (undefined while it streams / for a composer echo). Identifies a canvas opened from it. */
+    messageId?: string | number;
+    /**
+     * The widget was mounted by a PAGE hand-over (`openAgentWithWidget` / `?agentWidget=`), not by a message. A canvas
+     * it opens has origin `openedByPage` and a page anchor (the agent space), and never runs creation side effects.
+     */
+    openedByPage?: boolean;
+}
+/**
+ * Standard widget shape: a JSON-string payload + the framework-injected `fresh`.
+ * Use this for any widget whose markdown carries a single `payload='...'` attribute.
+ */
+export interface PayloadConversationWidgetProps extends BaseConversationWidgetProps {
+    payload: string;
+}
+/**
+ * Props injected into a widget's `composerComponent` — the same widget rendered INSIDE the chat input, before send,
+ * editable instead of read-only. See `ConversationComposerWidget` and `ConversationWidgetEntry.composerComponent`
+ * (`conversationWidgetRegistry.ts`).
+ */
+export interface ComposerConversationWidgetProps {
+    /** Client-only identity of this composer instance; stable across `replaceFields` calls. */
+    composerWidgetId: string;
+    /** The widget's own fields (never includes `type`). */
+    fields: Record<string, unknown>;
+    /** Replace the fields (e.g. drop one element out of several). */
+    replaceFields: (nextFields: Record<string, unknown>) => void;
+    /** Remove the whole widget from the composer. */
+    remove: () => void;
+    testId?: string;
+}

package/dist/types/renderer/conversation-widget-state-partition.d.ts

@@ -0,0 +1,31 @@
+import type { AgentsStateAction } from "../provider/environment";
+import type { CanvasCreatedEntity } from "./canvas/canvas-reducers";
+import type { CanvasOpenRequest, CanvasState, LastClosedCanvas } from "./canvas/canvas-state";
+import type { ConversationWidgetTranscriptMessage } from "./ConversationWidgetCallbacksContext";
+/** What the widget provider reads from a partition of an app's own chat state. */
+export interface ConversationWidgetPartitionState {
+    canvas: CanvasState | null;
+    lastClosedCanvas: LastClosedCanvas | null;
+    aiThinking: boolean;
+    conversation: {
+        runState?: string | null;
+    } | null;
+    messages: ConversationWidgetTranscriptMessage[] | null;
+}
+/**
+ * A partition of an app's own chat state in its state store — an app's older chat that is not on the package chat
+ * store yet (host application: the AI-Extensions chat's slice partition). The widget provider reads it through the
+ * environment's `stateStore` and dispatches the canvas transitions as the partition's actions.
+ */
+export interface ConversationWidgetStatePartition {
+    actions: {
+        openCanvas: (request: CanvasOpenRequest) => AgentsStateAction;
+        closeCanvas: (payload: {
+            byCustomer: boolean;
+        }) => AgentsStateAction;
+        resetCanvasForNewTurn: () => AgentsStateAction;
+        clearCanvas: () => AgentsStateAction;
+        setCanvasCreatedEntityId: (created: CanvasCreatedEntity) => AgentsStateAction;
+    };
+    selectState: (state: any) => ConversationWidgetPartitionState;
+}

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

@@ -0,0 +1,11 @@
+/**
+ * Maps the `::Name` nodes a message carries onto the registered components by rewriting `data.hName` to the CANONICAL
+ * registry name — which is what `ConversationMarkdown` keys its component map by.
+ *
+ * The name on the node is whatever the message contains, so a stored conversation delivers the legacy
+ * `::ExampleWidgetDirective{payload='…'}` form (and stored server `component` parts carry `"name":"<Canonical>Directive"`,
+ * which `normalize-server-message-to-markdown` turns into exactly that). Resolution therefore goes
+ * through `resolveCanonicalWidgetName` — the one legacy rule — never a direct set lookup, or every old message would
+ * degrade to the `:name` plain-text fallback.
+ */
+export default function conversationWidgetAstPlugin(): (tree: any) => void;

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

@@ -0,0 +1,74 @@
+import type React from "react";
+import type { ConversationWidgetUpsellProps } from "./_access/ConversationWidgetFeatureGate";
+import type { CanvasId } from "./canvas/canvas-behaviours";
+import type { ComposerConversationWidgetProps } from "./conversation-widget-props";
+export interface ConversationWidgetEntry {
+    /**
+     * The CANONICAL wire name — short, never ending in `Directive` (that suffix is reserved as the legacy marker; see
+     * `widget-name-resolver.ts`). Stored messages that carry the old `<Name>Directive` form resolve onto this one.
+     */
+    name: string;
+    component: React.ComponentType<any>;
+    /**
+     * The app's requirement name (a feature flag) that gates this widget — opaque to the package, checked by the app's
+     * `WidgetFeatureGate`. Omit to render unconditionally (default).
+     */
+    featureFlag?: string;
+    /**
+     * May this widget be mounted by NAME from outside a conversation — the `?agentWidget=<name>` deep-link a page uses to
+     * open the chat with this widget's canvas already up, and the restore of a pinned canvas after a reload
+     * (`resolve-deep-linkable-widget.ts`). Opt-in per widget because a URL is untrusted input: everything else is mounted
+     * only from a message the agent wrote. Default false.
+     */
+    deepLinkable?: boolean;
+    /**
+     * The canvases (by canvas id, `canvas/canvas-behaviours.ts`) this widget may open. Documentation and the restore's
+     * validation: a stored canvas pointer is re-opened only when its anchor message carries a widget that lists the
+     * canvas. `_registry-wire-names.spec.ts` asserts every listed id is a declared canvas.
+     */
+    opensCanvases?: readonly CanvasId[];
+    /** Optional custom upgrade offer for the gated widget; defaults to the app gate's own. */
+    upsellTrigger?: React.ComponentType<ConversationWidgetUpsellProps>;
+    /**
+     * Renders this widget INSIDE the chat input (editable: per-part ✕ etc.). Present = the widget may be composed by
+     * the customer (see `ConversationComposerWidget`). An entry declaring this MUST also declare `component` (asserted
+     * in `_registry-wire-names.spec.ts`) — the message rendering.
+     */
+    composerComponent?: React.ComponentType<ComposerConversationWidgetProps>;
+    /**
+     * Backspace on an empty input removes the LAST removable part of the last composer widget. Returns the fields
+     * without that part, or `null` when nothing is left (the widget is then removed entirely). Omitted → Backspace
+     * removes the whole widget.
+     */
+    removeLastPartFromComposerWidgetFields?: (fields: Record<string, unknown>) => Record<string, unknown> | null;
+}
+/** The entries of a set of registration modules (`*.widget-registration.ts` files an app or the package globbed). */
+export declare const readConversationWidgetRegistrations: (registrationModules: Record<string, {
+    conversationWidgetRegistration?: ConversationWidgetEntry;
+}>) => ConversationWidgetEntry[];
+/** The package's own widgets registered by file. */
+export declare const readFolderRegisteredConversationWidgets: () => ConversationWidgetEntry[];
+/** Throws on a wire name registered twice — the written list and the registration files together. */
+export declare const assertUniqueConversationWidgetNames: (widgets: readonly ConversationWidgetEntry[]) => void;
+/** The package's own widgets: the written entries and every package widget registered by file. */
+export declare const packageConversationWidgets: readonly ConversationWidgetEntry[];
+/**
+ * ONE list — every registered widget, in no particular order. There are no kinds of widget here: inline vs canvas vs
+ * mount-time is the component's own choice, not a registry bucket. A widget that opens a canvas lists the canvas ids
+ * (`opensCanvases`); the canvas's behaviour lives in `canvas/canvas-behaviours.ts`, its body in `canvas/canvasBodies.tsx`.
+ * It starts with the package's own widgets; an app adds its widgets with `registerConversationWidgets` before the
+ * first render (outside React). The array is filled in place, so a reader that holds it sees every registration.
+ */
+export declare const conversationWidgetRegistry: {
+    widgets: ConversationWidgetEntry[];
+};
+/**
+ * Counts the registrations: a reader that caches something derived from the registry (a name set, a component map)
+ * rebuilds it when the revision moved.
+ */
+export declare const getConversationWidgetRegistryRevision: () => number;
+/**
+ * Adds an app's widgets to the registry. Runs outside React, before the first render; throws when a wire name is
+ * registered twice (with the package's own or an earlier registration).
+ */
+export declare const registerConversationWidgets: (widgets: readonly ConversationWidgetEntry[]) => void;

package/dist/types/renderer/detect-unrendered-widgets.d.ts

@@ -0,0 +1,42 @@
+/**
+ * The signal provenance for the widget-render-failure corrective signal — distinct from a widget CLICK. Mirrors the
+ * backend {@link AIConversationMessage::SIGNAL_SOURCE_FRONTEND_WIDGET_INVALID}; the admin inspector shows it as the
+ * signal source and the agent loop treats it as model-visible feedback.
+ */
+export declare const WIDGET_INVALID_SIGNAL_SOURCE = "FRONTEND_WIDGET_INVALID";
+export interface UnrenderedWidget {
+    /** The `type` the model wrote. */
+    type: string;
+    /**
+     * What went wrong:
+     * - `unknownType`: a widget block (fenced or bare `widget { … }` line) whose type is not a registered widget →
+     *   dropped, the customer sees NOTHING.
+     * - `missingFence`: widget JSON emitted as PLAIN TEXT (no ```widget fence, no `widget` prefix) → the customer sees
+     *   raw JSON prose.
+     */
+    kind: "unknownType" | "missingFence";
+    /** The closest valid widget names (deterministic similarity) for a "did you mean" — may be empty. */
+    suggestions: string[];
+}
+/**
+ * Find widget-emission failures in an assistant message — the cases where the customer does NOT get the intended
+ * widget. Uses the SAME resolveWidgetName as the render plugin, so "valid" means exactly "would have rendered".
+ * Three scan surfaces, two failure classes:
+ *
+ * 1. `unknownType` — a ```widget fence OR a bare `widget { … }` line (both forms remarkWidgetFencePlugin renders)
+ *    whose `type` is not a registered widget: the plugin silently DROPS it, the customer sees nothing and the model
+ *    gets no feedback (a model wrote `type: "example"` instead of `ExampleWidget`). A malformed-JSON
+ *    block is skipped (the plugin drops it too).
+ * 2. `missingFence` — widget JSON emitted as PLAIN prose (no fence, no `widget` prefix): nothing intercepts it, so
+ *    the customer sees raw JSON text (found live: `{ "type": "ExampleWidget", … }` as a paragraph of the final answer).
+ *    Reported when the naked JSON's `type` resolves to a VALID widget (the model clearly meant a widget) or is CLOSE
+ *    to one (similarity shortlist non-empty) — arbitrary JSON without a widget-like `type` is never flagged (no false
+ *    positives on legitimate JSON content).
+ */
+export declare const detectUnrenderedWidgets: (messageText: string) => UnrenderedWidget[];
+/**
+ * The user-INVISIBLE corrective SIGNAL text for one or more widget-emission failures — tells the model exactly what
+ * the customer experienced (nothing rendered / raw JSON prose) and how to fix it. Kept terse; the model already holds
+ * the full widget catalog in its instructions.
+ */
+export declare const buildUnrenderedWidgetSignal: (widgets: UnrenderedWidget[]) => string;

package/dist/types/renderer/markdown-contains-widget.d.ts

@@ -0,0 +1,13 @@
+/**
+ * True when the markdown contains at least one widget — either a `::Name` / `:::Name` node OR a closed ```widget
+ * fence whose `type` resolves to a registered widget. BOTH forms go through `resolveCanonicalWidgetName`, so a stored
+ * message written as `::ExampleWidgetDirective{…}` or `{"type":"ExampleWidgetDirective"}` counts exactly like the
+ * canonical `::ExampleWidget` — the drawer resets for old conversations too.
+ */
+export declare const markdownContainsWidget: (markdown: string) => boolean;
+/**
+ * The CANONICAL names of every registered widget the markdown carries, in order of appearance, one entry per
+ * occurrence (both syntaxes, legacy `…Directive` spellings resolved). The message list reads it to tell a superseded
+ * widget from the live one: a later message carrying a widget of the SAME name retires the earlier one's controls.
+ */
+export declare const widgetNamesInMarkdown: (markdown: string) => string[];

package/dist/types/renderer/reference-naked-widget-json.d.ts

@@ -0,0 +1 @@
+export declare const referenceNakedWidgetJson: (text: string) => string;

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

@@ -0,0 +1,22 @@
+/**
+ * Render a widget the agent emitted in either form:
+ *
+ *   1. a ```widget fenced code block (the base-prompt convention):
+ *        ```widget
+ *        { "type": "<WidgetName>", ...fields }
+ *        ```
+ *   2. a bare `widget { "type": "<WidgetName>", ...fields }` line (no fence) — the same intent when the model
+ *      drops the backticks, which happens in practice. Markdown parses this as a plain `paragraph`, so it never
+ *      reached the fence path and leaked as raw JSON to the customer (the block shown verbatim).
+ *
+ * Both are rewritten into the SAME `leafDirective` node that `::WidgetName{payload='…'}` produces, so the existing
+ * pipeline (conversationWidgetAstPlugin → ConversationWidgetHost → feature-gate → hydration) renders it unchanged —
+ * the non-`type` fields become the node's `payload` (a JSON string), exactly what the widgets parse.
+ *
+ * MUST run BEFORE conversationWidgetAstPlugin. The `type` is resolved through the ONE legacy rule
+ * (`resolveWidgetName`): the canonical `ExampleWidget` matches exactly, the legacy `ExampleWidgetDirective` resolves
+ * onto it. A block whose JSON decodes only without surplus trailing `}` / `]` renders like the backend reads it
+ * (`widget-fence-json.ts`). A malformed JSON block or an unknown widget name is dropped (renders nothing) — the kill switch; never leak
+ * raw JSON or a `:name` fallback to the user.
+ */
+export default function remarkWidgetFencePlugin(): (tree: any) => void;

package/dist/types/renderer/render-report/widget-render-report-collector.d.ts

@@ -0,0 +1,57 @@
+import type { WidgetRenderReporter, WidgetRenderReportEntry } from "./widget-render-report";
+/**
+ * The render reports of the widget blocks of live messages, collected per message. The chat host
+ * (`AgentChat`) owns one collector and hands it down; `ConversationWidgetHost` registers every block of a JUST-DELIVERED
+ * message (never a replayed one) and gives the widget a reporter for it. A block that reports nothing counts as
+ * `mounted`. Once a message's blocks have settled — none `pending` for `settleMs`, or `maxWaitMs` after the first block
+ * at the latest — the collector calls `onSettled` ONCE for that message with its blocks in document order; the host
+ * sends the signal only when a block is not `mounted` or rendered with a note (a `mounted` entry with a code: figures
+ * without a source), so a clean render costs nothing.
+ */
+export interface WidgetRenderBlockReport {
+    widgetName: string;
+    /** The block's offset in the message's markdown — document order, and the block's identity in the message. */
+    sourceOffset: number;
+    entry: WidgetRenderReportEntry;
+}
+export interface WidgetRenderReportCollector {
+    /** Counts one block of one live message as `mounted` unless it already reported (a child reports before its host mounts). */
+    registerBlock: (messageId: string | number, widgetName: string, sourceOffset: number) => void;
+    /** The reporter of one block of one live message. */
+    reporterForBlock: (messageId: string | number, widgetName: string, sourceOffset: number) => WidgetRenderReporter;
+    /** Forget every pending timer (the host unmounts or the conversation switches). */
+    dispose: () => void;
+}
+export interface WidgetRenderReportCollectorOptions {
+    onSettled: (messageId: string, blocks: WidgetRenderBlockReport[]) => void;
+    settleMs?: number;
+    maxWaitMs?: number;
+}
+export declare const createWidgetRenderReportCollector: (options: WidgetRenderReportCollectorOptions) => WidgetRenderReportCollector;
+/** The collector of the chat the widget lives in; absent = nobody listens (another host, a story, the e-mail capture). */
+export declare const WidgetRenderReportCollectorContext: import("react").Context<WidgetRenderReportCollector | null>;
+/** The stored prefix of a render-report signal — the inspector and the tests read it; never reworded. */
+export declare const WIDGET_RENDER_REPORT_SIGNAL_PREFIX = "Widget render report for message";
+/** The signal source (backend `AIConversationSignalSource::FRONTEND_WIDGET_RENDER_REPORT`). */
+export declare const WIDGET_RENDER_REPORT_SIGNAL_SOURCE = "FRONTEND_WIDGET_RENDER_REPORT";
+/**
+ * The model-visible signal for a settled message — null when every block mounted cleanly (nothing to tell). One line
+ * per block that is not `mounted`, or that mounted with a note (a code: `INLINE_VALUE_WITHOUT_SOURCE`): its position
+ * among the message's widgets, its name and its occurrence among widgets of that name, its status and code, the
+ * detail. The closing sentence asks for the honest answer about a block the owner did not see, and for
+ * a note that the next widget fixes it.
+ */
+export declare const buildWidgetRenderReportSignal: (messageId: string, blocks: WidgetRenderBlockReport[]) => string | null;
+export interface ParsedWidgetRenderReport {
+    messageId: string;
+    blocks: Array<{
+        position: number;
+        widgetName: string;
+        occurrence: number;
+        status: string;
+        code: string | null;
+        detail: string | null;
+    }>;
+}
+/** The report a stored signal text carries, or null for another text — the admin inspector's reader. */
+export declare const parseWidgetRenderReportSignal: (signalText: string) => ParsedWidgetRenderReport | null;

package/dist/types/renderer/render-report/widget-render-report.d.ts

@@ -0,0 +1,29 @@
+/**
+ * The render report of one widget block: after mount every block says whether it showed what it should —
+ * `mounted`, `empty` (hydrated, nothing to show), `failed` (error boundary, hydration error, invalid tree) or `pending`
+ * (still waiting for data; never a final answer). The chat host collects the statuses per message and tells the model
+ * about the blocks that are not `mounted` (the `FRONTEND_WIDGET_RENDER_REPORT` signal). A widget reports
+ * through {@link useReportWidgetRenderStatus}; a widget that reports nothing counts as `mounted` once it rendered
+ * without throwing.
+ */
+export type WidgetRenderStatus = "mounted" | "empty" | "failed" | "pending";
+/**
+ * Why a block is not `mounted`. The tree codes are the backend's (`ComposedViewValidationFinding`); the runtime codes
+ * name what went wrong in the browser.
+ */
+export type WidgetRenderReportCode = "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" | "UNRESOLVED_BINDING" | "UNRESOLVED_REF" | "HYDRATION_FAILED" | "RENDER_FAILED" | "NO_DATA";
+export interface WidgetRenderReportEntry {
+    status: WidgetRenderStatus;
+    code?: WidgetRenderReportCode;
+    /** One short English sentence for the model (what was dropped / what failed); never customer data beyond names. */
+    detail?: string;
+}
+/** What a block reports into — provided by the chat host per block; absent = nobody listens (a story, a test). */
+export interface WidgetRenderReporter {
+    report: (entry: WidgetRenderReportEntry) => void;
+}
+export declare const WidgetRenderReportContext: import("react").Context<WidgetRenderReporter | null>;
+/** Reports the block's status whenever it changes; a no-op without a reporter. */
+export declare const useReportWidgetRenderStatus: (status: WidgetRenderStatus, code?: WidgetRenderReportCode, detail?: string) => void;
+/** The reporter itself, for a widget that reports from an event (a failed action) rather than from a render. */
+export declare const useWidgetRenderReporter: () => WidgetRenderReporter | null;

package/dist/types/renderer/repair-malformed-widget-fences.d.ts

@@ -0,0 +1,11 @@
+/**
+ * The `[start, end)` ranges of every REAL fenced code block in `text` — ``` or ~~~, CommonMark's own rules (up to
+ * 3 spaces of indent, a closer using the same character with a run at least as long as the opener's, a backtick
+ * opener's info string never containing a backtick). An unclosed opener runs to end-of-text. The GENERAL-PURPOSE
+ * counterpart of this file's widget-fence-only scanning, built on the same {@link readLine} line walk — used by
+ * `referenceNakedWidgetJson` to skip content genuinely inside a fence: a `~~~widget` fence (no tilde support
+ * existed before), and content that follows a line which LOOKS like a backtick fence opener but isn't one per the
+ * info-string rule above (that line never opens anything, so it can no longer swallow the real fence after it).
+ */
+export declare const findFencedBlockRanges: (text: string) => Array<[number, number]>;
+export declare const repairMalformedWidgetFences: (text: string) => string;

package/dist/types/renderer/resolve-deep-linkable-widget.d.ts

@@ -0,0 +1,25 @@
+import type { CanvasId } from "./canvas/canvas-behaviours";
+import { ConversationWidgetEntry } from "./conversationWidgetRegistry";
+/**
+ * Resolves the widget a `?agentWidget=<name>` deep-link (or a restored pinned canvas) may mount, by its CANONICAL
+ * registry wire name.
+ *
+ * A URL is untrusted input, so this is an allow-list rather than a registry lookup: only an entry that declares
+ * `deepLinkable: true` can be opened this way. Every other widget is emitted by the agent inside a message, where the
+ * conversation itself is the authorisation — a link must not be able to mount an arbitrary widget (some carry
+ * mount-time side effects) just because its name was typed into the address bar.
+ *
+ * Returns the entry (the caller renders its `component`, applying the feature gate the entry declares) or null when the
+ * name is empty, unknown, or not deep-linkable.
+ */
+export declare const resolveDeepLinkableWidget: (widgetName?: string | null) => ConversationWidgetEntry | null;
+/**
+ * The reverse direction: which deep-linkable widget re-opens THIS canvas. The open canvas of the agent chat is
+ * mirrored into `?agentWidget=` (AgentTrigger) so a reload brings the customer back to the surface they were working
+ * on — an editor a cold chat opened has no conversation id yet, so the canvas model's own pointer storage
+ * has nothing to restore from.
+ *
+ * Null for every canvas no deep-linkable widget declares: it is the agent's to open inside a message, and a URL must
+ * not be able to mount it (the allow-list above).
+ */
+export declare const deepLinkableWidgetNameForCanvas: (canvasId: CanvasId | null | undefined) => string | null;

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

@@ -0,0 +1,12 @@
+/**
+ * remark-directive parses EVERY `:name` run as a text directive — including the `:00` / `:30` inside a time such as
+ * `08:00–16:30` (digits are valid directive names). Text directives are not part of our widget vocabulary (widgets
+ * travel as leaf directives only, see `conversationWidgetAstPlugin`), so a text directive is always prose that the
+ * parser misread: without this pass the customer chat rendered "Montag: 08:00–16:30" as "08" / "–16" (the `:00`
+ * and `:30` swallowed, the unknown nodes rendered as breaks) while the admin inspector, which does not load
+ * remark-directive, showed the line intact.
+ *
+ * Restores every text directive to the exact source slice it was parsed from, merging it into the neighbouring text
+ * nodes so the paragraph reads as one run again.
+ */
+export default function restoreTextDirectivesPlugin(): (tree: any, file: any) => void;

package/dist/types/renderer/widget-click-signal-sources.d.ts

@@ -0,0 +1,15 @@
+/**
+ * The `signalSource`s a widget CLICK posts into the conversation (`injectSignal`): the generic widget click and the
+ * dedicated source the former owner-action consent widget sent (no component posts it any more; stored rows keep it),
+ * plus the further sources an app's own widgets post (`AgentsEnvironment.furtherWidgetClickSignalSources`, e.g. a form
+ * submit that starts its own owner turn). The message list reads them to tell an answered widget from an open one after
+ * a reload — a widget the owner already clicked must never come back interactive (a consent widget re-armed is a second
+ * confirmation for a destructive tool). Add a source here when a widget of the package starts posting a new one.
+ */
+export declare const FRONTEND_WIDGET_CLICK_SIGNAL_SOURCE = "FRONTEND_WIDGET_CLICK";
+export declare const OWNER_ACTION_CONFIRM_SIGNAL_SOURCE = "OWNER_ACTION_CONFIRM";
+/** The package's own widget click sources (the backend's sources of the package that carry an owner statement). */
+export declare const PACKAGE_WIDGET_CLICK_SIGNAL_SOURCES: readonly string[];
+/** Every widget click source: the package's own and the app's further ones. */
+export declare const getWidgetClickSignalSources: () => readonly string[];
+export declare const isWidgetClickSignalSource: (signalSource: string | undefined | null) => boolean;

package/dist/types/renderer/widget-fence-json.d.ts

@@ -0,0 +1,16 @@
+/**
+ * The JSON of a widget block as every frontend reader decodes it — the twin of the backend's
+ * `WidgetBlocks::buildWidgetJsonWithoutSurplusClosers()`: a block whose JSON does not decode is read
+ * once more without the surplus closing brackets a model wrote at its end (one `}` too many after a correct tree), up to
+ * {@link MAX_SURPLUS_CLOSERS} trailing `}` / `]` dropped one by one. The parity fixture `composed-view-parity.json`
+ * (`surplusCloserCases`) holds both readers equal.
+ */
+/** The most trailing `}` / `]` a block read drops to decode a block (the backend's `WidgetBlocks::MAX_SURPLUS_CLOSERS`). */
+export declare const MAX_SURPLUS_CLOSERS = 3;
+/**
+ * The block JSON without its surplus trailing closers, or null when it decodes as written or when no shortened text
+ * decodes to a JSON object — exactly the backend's answer.
+ */
+export declare const readWidgetJsonWithoutSurplusClosers: (widgetJson: string) => string | null;
+/** The block's JSON object — as written, or without its surplus trailing closers; undefined for a malformed block. */
+export declare const parseWidgetJsonObject: (widgetJson: string) => Record<string, unknown> | undefined;

package/dist/types/renderer/widget-fence-syntax.d.ts

@@ -0,0 +1,25 @@
+/**
+ * WIRE SYNTAX — the ```widget fence and bare `widget { … }` forms, as import-free constants.
+ *
+ * Deliberately a leaf module (no imports): `widget-name-resolver.ts` reads the registry at module scope, and the
+ * registry pulls in every widget → AgentChat → the unrendered-widget detector, which builds a RegExp from
+ * WIDGET_FENCE_LANG at ITS module scope. When a story loads a widget before anything has evaluated the resolver, that
+ * chain reaches the detector while the resolver is still in its temporal dead zone ("Cannot access 'WIDGET_FENCE_LANG'
+ * before initialization"). Keeping the syntax here, outside the registry cycle, makes evaluation order irrelevant.
+ */
+/**
+ * The ```widget fence's info-string language — the ONE definition every fence regex in the pipeline (the render
+ * plugin's `node.lang` check, the malformed-fence repairer, the drawer-reset scan, the unrendered-widget detector)
+ * is built from, so "``` widget" (a space before the lang — remark accepts it, the model sometimes writes it) is
+ * recognized identically everywhere.
+ */
+export declare const WIDGET_FENCE_LANG = "widget";
+/**
+ * A bare `widget { …json… }` line (no ```widget fence) that IS the whole paragraph — the fallback form the model
+ * emits when it drops the backticks. Capture group 1 is the JSON object. Anchored to the whole paragraph text so a
+ * prose mention ("the widget shows…") never matches. Shared by the render plugin (rewrites it) so there is one
+ * definition of the bare form. The detector uses {@link BARE_WIDGET_LINE_GLOBAL} to scan a raw message the same way.
+ */
+export declare const BARE_WIDGET_PARAGRAPH: RegExp;
+/** The bare `widget { … }` form scanned line-by-line across a raw message string (detector side of {@link BARE_WIDGET_PARAGRAPH}). */
+export declare const BARE_WIDGET_LINE_GLOBAL: RegExp;

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

@@ -0,0 +1,8 @@
+export { WidgetHydrationReducer, WidgetHydrationSlice, useWidgetMemory } from "./widget-hydration.slice";
+export { AgentsWidgetHydrationStateContainer, createAgentsWidgetHydrationStateStore, getDefaultAgentsStateStore, type AgentsWidgetHydrationState, } from "./widget-hydration-state-store";
+export { registerWidgetHydrator, getWidgetHydrator, hasWidgetHydrator } from "./widget-hydration.registry";
+export { useWidgetHydration } from "./use-widget-hydration";
+export type { WidgetHydrator, WidgetHydratorContext, WidgetHydratorOptions, WidgetHydrationStatus, WidgetMemory, WidgetHydrationSliceState, } from "./widget-hydration.types";
+export type { UseWidgetHydrationResult, UseWidgetHydrationOptions } from "./use-widget-hydration";
+export { pickSection, isSectionLoading, mergeSection, mergeSectionValues, isSectionIncomplete, sectionCoversKeys, } from "./section-hydration";
+export type { SectionHydrationResult, SectionHydrator } from "./section-hydration";

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

@@ -0,0 +1,41 @@
+export interface SectionHydrationResult<T> {
+    data: T | null;
+    isLoading: boolean;
+    error?: string | null;
+}
+export type SectionHydrator<T> = () => SectionHydrationResult<T>;
+/**
+ * Prefer payload-provided value; fall back to a hydrator result; undefined otherwise.
+ * Callers should call the fallback hook unconditionally (React hook rules) and pass
+ * its result here.
+ */
+export declare const pickSection: <T>(payloadValue: T | undefined, fallback: SectionHydrationResult<T>) => T | undefined;
+/**
+ * True when payload is missing the value AND the fallback is still loading.
+ */
+export declare const isSectionLoading: <T>(payloadValue: T | undefined, fallback: SectionHydrationResult<T>) => boolean;
+/**
+ * Field-level merge of two section values. Payload fields (when defined) win
+ * over hydrated fields; undefined payload fields are filled from the hydrated
+ * value. Use when the agent sends partial section data (e.g. only a CTA) and
+ * the client hydrates the remaining fields.
+ */
+export declare const mergeSectionValues: <T extends object>(payloadValue: T | undefined, hydratedValue: T | undefined) => T | undefined;
+/**
+ * Field-level merge for object sections. Payload fields (when defined) win over
+ * fallback fields. Undefined payload fields are filled from the fallback. Use
+ * this when the agent sends partial section data (e.g. only a CTA) and the
+ * client needs to hydrate the remaining fields from app state.
+ */
+export declare const mergeSection: <T extends object>(payloadValue: T | undefined, fallback: SectionHydrationResult<T>) => T | undefined;
+/**
+ * True when the payload provides every field in `requiredKeys` — the section
+ * can render straight from the agent payload without waiting for hydration.
+ */
+export declare const sectionCoversKeys: <T extends object>(payloadValue: T | undefined, requiredKeys: ReadonlyArray<keyof T>) => boolean;
+/**
+ * True when the fallback is still loading AND the payload has not provided
+ * every expected field (listed in `requiredKeys`). Use together with
+ * `mergeSection` to decide whether to show a skeleton for the section.
+ */
+export declare const isSectionIncomplete: <T extends object>(payloadValue: T | undefined, fallback: SectionHydrationResult<T>, requiredKeys: ReadonlyArray<keyof T>) => boolean;

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

@@ -0,0 +1,27 @@
+import { WidgetHydrationStatus } from "./widget-hydration.types";
+export interface UseWidgetHydrationResult<TData> {
+    data: TData | null;
+    status: WidgetHydrationStatus;
+    isLoading: boolean;
+    isError: boolean;
+    error: string | null;
+    /** Generation of the request the memory last started or settled (0 = none): newer results carry a higher id. */
+    requestId: number;
+    refetch: () => void;
+}
+export interface UseWidgetHydrationOptions {
+    /**
+     * When true, force a fetch on the first render of this instance even if
+     * memory holds a successful result for the same key. Used to honor the
+     * `fresh` widget prop (streamed agent message → refetch; history
+     * replay → reuse cache).
+     */
+    forceRefresh?: boolean;
+    /**
+     * Keep rendering the last loaded data for this key while a fetch runs, instead of the loading state. The fetch still
+     * runs (and its result replaces the data); only a key with no data yet shows loading. For a snapshot whose copy may
+     * already be on screen elsewhere — another agent window opening the same briefing.
+     */
+    showLastDataWhileRefreshing?: boolean;
+}
+export declare const useWidgetHydration: <TData = unknown, TPayload = unknown>(type: string, payload: TPayload, options?: UseWidgetHydrationOptions) => UseWidgetHydrationResult<TData>;

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

@@ -0,0 +1,27 @@
+import type { AgentsStateAction, AgentsStateStore } from "../../provider/environment";
+import type { WidgetHydrationSliceState } from "./widget-hydration.types";
+/** The state of the package's default store: the widget hydration state under the key package code reads. */
+export interface AgentsWidgetHydrationState {
+    AIExtensionsWidgetHydration: WidgetHydrationSliceState;
+}
+/**
+ * The package's own state store (widget hydration is one store per app): the widget hydration reducer
+ * behind `useSyncExternalStore`, no Redux. Package code reads and dispatches through it whenever the app supplies no
+ * `AgentsEnvironment.stateStore` (the host application supplies its Redux store, which mounts the same reducer). Actions the
+ * reducer does not know (the app's "a chat surface is open" action) change nothing.
+ */
+export declare class AgentsWidgetHydrationStateContainer implements AgentsStateStore {
+    protected state: AgentsWidgetHydrationState;
+    protected readonly listeners: Set<() => void>;
+    getState: () => AgentsWidgetHydrationState;
+    subscribe: (listener: () => void) => (() => void);
+    dispatch: (action: AgentsStateAction) => AgentsStateAction;
+    /** `AgentsStateStore.useSelector`: one value of the state, re-rendering when it changes. */
+    useSelector: <Selected>(selector: (state: AgentsWidgetHydrationState) => Selected) => Selected;
+    /** `AgentsStateStore.useDispatch`. */
+    useDispatch: () => ((action: AgentsStateAction) => AgentsStateAction);
+}
+/** A new widget hydration store (a test, a second app on one page). */
+export declare const createAgentsWidgetHydrationStateStore: () => AgentsStateStore;
+/** The one default store of the page, created on first use. */
+export declare const getDefaultAgentsStateStore: () => AgentsStateStore;

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

@@ -0,0 +1,39 @@
+import type { AgentsStateAction } from "../../provider/environment";
+import { WidgetHydrationSliceState } from "./widget-hydration.types";
+interface MemoryEnsuredPayload {
+    key: string;
+}
+interface InstanceAttachedPayload {
+    key: string;
+    instanceId: string;
+}
+interface HydrationStartedPayload {
+    key: string;
+    instanceId: string;
+    requestId: number;
+}
+interface HydrationSucceededPayload {
+    key: string;
+    requestId: number;
+    data: unknown;
+}
+interface HydrationFailedPayload {
+    key: string;
+    requestId: number;
+    error: string;
+}
+interface WidgetResetPayload {
+    key: string;
+}
+/** The action creators (the action types are the ones the former Redux Toolkit slice used). */
+export declare const WidgetHydrationSlice: {
+    memoryEnsured: (payload: MemoryEnsuredPayload) => AgentsStateAction;
+    instanceAttached: (payload: InstanceAttachedPayload) => AgentsStateAction;
+    hydrationStarted: (payload: HydrationStartedPayload) => AgentsStateAction;
+    hydrationSucceeded: (payload: HydrationSucceededPayload) => AgentsStateAction;
+    hydrationFailed: (payload: HydrationFailedPayload) => AgentsStateAction;
+    widgetReset: (payload: WidgetResetPayload) => AgentsStateAction;
+    allWidgetsReset: () => AgentsStateAction;
+};
+export declare const WidgetHydrationReducer: (state: WidgetHydrationSliceState | undefined, action: AgentsStateAction) => WidgetHydrationSliceState;
+export {};