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

package/dist/types/widgets/ConversationSearchResultsConversationWidget/shared/search-hit-excerpt.d.ts

@@ -0,0 +1 @@
+export declare const normalizeSearchHitExcerpt: (rawExcerpt: unknown) => string;

package/dist/types/widgets/CurrencyConverterConversationWidget/CurrencyConverterConversationWidget.d.ts

@@ -0,0 +1,8 @@
+import type { PayloadConversationWidgetProps } from "../../renderer/conversation-widget-props";
+/**
+ * `CurrencyConverter`: a currency conversion at the dated rate `getCurrencyExchangeRate` returned.
+ * DATA-COMPLETE — the block carries the rate and its day; the widget never fetches. A block without a usable currency
+ * pair or rate renders nothing and reports `failed`, so the model answers in prose instead of pointing at a widget
+ * that is not there.
+ */
+export declare const CurrencyConverterConversationWidget: (props: PayloadConversationWidgetProps) => import("react/jsx-runtime").JSX.Element | null;

package/dist/types/widgets/CurrencyConverterConversationWidget/CurrencyConverterWidget/CurrencyConverterWidget.d.ts

@@ -0,0 +1,17 @@
+import { type CurrencyConverterPayload } from "../shared/currency-converter-widget-payload";
+export interface CurrencyConverterWidgetProps {
+    conversion: CurrencyConverterPayload;
+    /** The app's UI language (`de`, `en_US`); numbers, dates and currency names follow it. */
+    languageCode?: string;
+    /** The e-mail capture: the amount is plain text and there is no swap button. */
+    isStatic?: boolean;
+    testId?: string;
+}
+/**
+ * The currency converter (ChatGPT's `CurrencyConverterWidgetWithSource`): the title above one
+ * elevated card with two rows — the amount in the first currency (editable) and its value in the second, a round swap
+ * button on the hairline between them — and a footer with the rate and the day it is of. Changing the amount and
+ * swapping the currencies recompute in the browser from the one delivered rate; the rate is dated, so the widget says
+ * "Rate of <day>" and never "live". The currencies are the delivered pair only — there is no picker.
+ */
+export declare const CurrencyConverterWidget: (props: CurrencyConverterWidgetProps) => import("react/jsx-runtime").JSX.Element;

package/dist/types/widgets/CurrencyConverterConversationWidget/CurrencyConverterWidget/CurrencyLabel/CurrencyLabel.d.ts

@@ -0,0 +1,9 @@
+export interface CurrencyLabelProps {
+    currencyCode: string;
+    locale: string;
+    /** Id of the name line, so the amount field beside it can be named by it. */
+    nameId?: string;
+    testId?: string;
+}
+/** One currency of the converter: a round flag badge, the ISO code and the currency's name in the UI language. */
+export declare const CurrencyLabel: (props: CurrencyLabelProps) => import("react/jsx-runtime").JSX.Element;

package/dist/types/widgets/CurrencyConverterConversationWidget/shared/currency-converter-widget-payload.d.ts

@@ -0,0 +1,22 @@
+/**
+ * The `CurrencyConverter` payload: two ISO 4217 codes, the amount, the rate the tool returned and
+ * the day the rate is of. DATA-COMPLETE — the widget never re-fetches a rate. The parser is alias-tolerant (a model
+ * that transcribes the block may rename a field) and never throws: an unusable payload gives `null`.
+ */
+export interface CurrencyConverterPayload {
+    /** ISO 4217, upper case (`EUR`). */
+    fromCurrency: string;
+    /** ISO 4217, upper case (`USD`). */
+    toCurrency: string;
+    /** The amount in `fromCurrency` shown first; 1 when the block carries none. */
+    amount: number;
+    /** 1 `fromCurrency` = `rate` `toCurrency`; always finite and > 0. */
+    rate: number;
+    /** The day the rate is of (`Y-m-d`); `undefined` when the block carries no valid day. */
+    rateDate?: string;
+}
+/** The largest amount the widget accepts — beyond it the float maths stops being exact to the cent. */
+export declare const MAX_CURRENCY_CONVERTER_AMOUNT = 1000000000000;
+/** A finite number, or a numeric string (`"1,12"` and `"1.12"` both read as 1.12). */
+export declare const readCurrencyConverterNumber: (value: unknown) => number | undefined;
+export declare const parseCurrencyConverterPayload: (payload: string | undefined) => CurrencyConverterPayload | null;

package/dist/types/widgets/CurrencyConverterConversationWidget/shared/currency-display.d.ts

@@ -0,0 +1,30 @@
+/**
+ * How a currency and its numbers read for the owner — all from the browser's `Intl`, in the app's
+ * UI language: the currency's name ("US-Dollar"), its symbol ("$"), its flag, an amount, a rate and the day of a rate.
+ */
+/** The locale the numbers are written in: the app's UI language, `en` when it is unset or invalid. */
+export declare const toCurrencyLocale: (languageCode: string | undefined) => string;
+/** The currency's name in the locale ("Euro", "US-Dollar"); the code itself when the browser knows no name. */
+export declare const readCurrencyName: (currencyCode: string, locale: string) => string;
+/** The currency's narrow symbol ("€", "$", "CHF"); the code when there is none. */
+export declare const readCurrencySymbol: (currencyCode: string, locale: string) => string;
+/**
+ * The flag emoji of the currency's country — the first two letters of an ISO 4217 code are the ISO 3166 country
+ * (`USD` → US); the euro takes the EU flag. Decorative only: the name next to it carries the meaning.
+ */
+export declare const readCurrencyFlag: (currencyCode: string) => string;
+/** An amount with the currency's own number of decimals (2 for EUR, 0 for JPY), grouped for the locale. */
+export declare const formatCurrencyAmount: (amount: number, currencyCode: string, locale: string) => string;
+/** An exact figure without currency rounding (a rate, the exact product): up to six significant digits after rounding. */
+export declare const formatExactNumber: (value: number, locale: string) => string;
+/** The day of a rate (`2026-10-25`) in the locale's medium date style ("25.10.2026", "Oct 25, 2026"). */
+export declare const formatRateDate: (rateDate: string, locale: string) => string;
+/** The amount as it rests in the field: grouped for the locale (`1,250,000`, `1.250.000`), its decimals kept. */
+export declare const formatEditableAmount: (amount: number, locale: string) => string;
+/**
+ * The amount the owner typed, or undefined when it is no number: spaces and apostrophes are dropped. When both `.` and
+ * `,` occur the LAST one is the decimal mark (`1,250.75`, `1.250,75`); a mark that repeats groups thousands; a lone
+ * mark is the decimal mark, except the locale's own grouping mark between a 1-3 digit head and exactly three digits
+ * (`1,250` in English is 1250, `1.250` in German too).
+ */
+export declare const parseTypedAmount: (typedText: string, locale?: string) => number | undefined;

package/dist/types/widgets/CustomVisualizationConversationWidget/CustomVisualizationConversationWidget.d.ts

@@ -0,0 +1,11 @@
+import type { PayloadConversationWidgetProps } from "../../renderer/conversation-widget-props";
+type CustomVisualizationConversationWidgetProps = PayloadConversationWidgetProps;
+/**
+ * A visualization the model wrote itself — its own HTML, CSS and JavaScript with the data in the block. DATA-COMPLETE and sandboxed: the code runs in an iframe without same-origin rights
+ * under a policy that loads nothing from the network; only allow-listed libraries come along. For what no kit node of
+ * `ComposedView` can express (a canvas animation, a custom projection) — never for a table, a chart or a map.
+ * Reports `pending` until the script ran, `mounted` then, `failed` for a block it does not run, a script error or a
+ * frame that stopped responding. In the e-mail it renders a static preview without the frame.
+ */
+export declare const CustomVisualizationConversationWidget: (props: CustomVisualizationConversationWidgetProps) => import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/types/widgets/CustomVisualizationConversationWidget/CustomVisualizationWidget/CustomVisualizationFrame.d.ts

@@ -0,0 +1,14 @@
+import type { CustomVisualizationPayload } from "../shared/custom-visualization-widget-payload";
+export interface CustomVisualizationFrameProps {
+    payload: CustomVisualizationPayload;
+    testId?: string;
+}
+/**
+ * The model's visualization in its sandbox: an iframe `sandbox="allow-scripts"` (never same-origin,
+ * top-navigation, popups or forms) on the configured frame page, which holds the policy `default-src 'none'`. The host
+ * sends ONE render message (html, css, script, the allow-listed library sources, the block's data, the chat's colours)
+ * and from then on only listens: heights (clamped, rate-limited), heartbeats, "ready" and script errors — from this
+ * frame's `contentWindow` with this instance's token only. A frame that stops beating (an endless loop) or never gets
+ * ready is removed and the block reports `failed`; a script error reports `failed` and leaves what rendered.
+ */
+export declare const CustomVisualizationFrame: (props: CustomVisualizationFrameProps) => import("react/jsx-runtime").JSX.Element;

package/dist/types/widgets/CustomVisualizationConversationWidget/CustomVisualizationWidget/CustomVisualizationWidget.d.ts

@@ -0,0 +1,15 @@
+import type { CustomVisualizationPayload } from "../shared/custom-visualization-widget-payload";
+/** The live widget: the header and the sandboxed frame on one elevated card. */
+export declare const CustomVisualizationWidget: (props: {
+    payload: CustomVisualizationPayload;
+    testId?: string;
+}) => import("react/jsx-runtime").JSX.Element;
+/**
+ * The e-mail form (in e-mail only a static preview renders): no frame and no script — the header and one
+ * flat tile saying the visualization is interactive and lives in the conversation.
+ */
+export declare const CustomVisualizationStaticPreview: (props: {
+    title: string;
+    description: string;
+    testId?: string;
+}) => import("react/jsx-runtime").JSX.Element;

package/dist/types/widgets/CustomVisualizationConversationWidget/shared/custom-visualization-frame-protocol.d.ts

@@ -0,0 +1,77 @@
+/**
+ * The message protocol between the chat and the sandbox frame of a CustomVisualization. The frame
+ * (`sandbox-frame/custom-visualization-frame.html`) runs the model's code on an opaque origin; everything it says is
+ * untrusted. The host therefore accepts a message only when it comes from the frame's own `contentWindow`, names the
+ * channel and the per-instance token, has exactly the keys of its type, stays under a size limit and — for a height —
+ * carries a finite number, which the host clamps. A message is never a command: the host reads a height, a heartbeat,
+ * "ready" and an error line, nothing else.
+ */
+export declare const CUSTOM_VISUALIZATION_FRAME_CHANNEL = "agents-custom-visualization";
+/** The global the visualization's script reads (`window.AGENTS_VISUALIZATION.data`, `.colorScheme`). */
+export declare const CUSTOM_VISUALIZATION_GLOBAL_NAME = "AGENTS_VISUALIZATION";
+/** The prefix of the theme variables the frame sets (`--agents-fg`, `--agents-accent`, …). */
+export declare const CUSTOM_VISUALIZATION_THEME_VARIABLE_PREFIX = "--agents-";
+/** The frame posts a heartbeat every second; this long without one (an endless loop) and the host removes the frame. */
+export declare const CUSTOM_VISUALIZATION_HEARTBEAT_TIMEOUT_MS = 5000;
+/** From the frame's mount until its "ready" (libraries + script ran); longer and the host removes the frame. */
+export declare const CUSTOM_VISUALIZATION_READY_TIMEOUT_MS = 15000;
+/** How often the host checks the two deadlines above. */
+export declare const CUSTOM_VISUALIZATION_WATCHDOG_INTERVAL_MS = 500;
+/** The frame's height is clamped to this range (CSS px). */
+export declare const CUSTOM_VISUALIZATION_MIN_HEIGHT_PX = 80;
+export declare const CUSTOM_VISUALIZATION_MAX_HEIGHT_PX = 1200;
+/** At most this many height messages are applied per second; the rest are ignored. */
+export declare const CUSTOM_VISUALIZATION_MAX_HEIGHT_MESSAGES_PER_SECOND = 20;
+/** A message whose JSON is longer than this is ignored. */
+export declare const CUSTOM_VISUALIZATION_MAX_MESSAGE_CHARS = 1024;
+/** The frame cuts an error line to this length; a longer one is ignored as malformed. */
+export declare const CUSTOM_VISUALIZATION_MAX_ERROR_MESSAGE_CHARS = 300;
+export type CustomVisualizationFrameMessage = {
+    type: "heartbeat";
+} | {
+    type: "ready";
+} | {
+    type: "height";
+    height: number;
+} | {
+    type: "error";
+    message: string;
+};
+/**
+ * The frame message `event` carries, or null when it is not one: another window sent it, the token or channel is not
+ * this instance's, a key is missing or extra, the message is too large, or a value has the wrong type.
+ */
+export declare const readCustomVisualizationFrameMessage: (event: Pick<MessageEvent, "data" | "source">, expectedSource: MessageEventSource | null, expectedToken: string) => CustomVisualizationFrameMessage | null;
+/** A height the frame asked for, as the host applies it: rounded up and clamped to the allowed range. */
+export declare const clampCustomVisualizationHeight: (requestedHeight: number) => number;
+/**
+ * Whether one more height message may be applied now: keeps the times of the applied ones of the last second in
+ * `appliedAtTimes` (mutated) and refuses beyond {@link CUSTOM_VISUALIZATION_MAX_HEIGHT_MESSAGES_PER_SECOND}.
+ */
+export declare const admitCustomVisualizationHeightMessage: (appliedAtTimes: number[], now: number) => boolean;
+/** A fresh per-instance token: 128 random bits as hex. */
+export declare const createCustomVisualizationInstanceToken: () => string;
+/** The one message the host sends: everything the frame shows and runs. */
+export interface CustomVisualizationRenderMessage {
+    channel: typeof CUSTOM_VISUALIZATION_FRAME_CHANNEL;
+    type: "render";
+    token: string;
+    html: string;
+    css: string;
+    script: string;
+    librarySources: string[];
+    data: unknown;
+    /** The theme variables under the package's prefix (`--agents-fg` → a resolved colour). */
+    theme: Record<string, string>;
+    colorScheme: "light" | "dark";
+    /**
+     * Further names the frame defines the same frozen global under, beside `AGENTS_VISUALIZATION` — the names the app
+     * declares (`AgentsEnvironment.sandboxLegacyAliases.visualizationGlobalNames`). Empty without a declaration.
+     */
+    visualizationGlobalNames: string[];
+    /**
+     * Further prefixes the frame sets every theme variable under, beside `--agents-` — the prefixes the app declares
+     * (`AgentsEnvironment.sandboxLegacyAliases.themeVariablePrefixes`). Empty without a declaration.
+     */
+    themeVariablePrefixes: string[];
+}

package/dist/types/widgets/CustomVisualizationConversationWidget/shared/custom-visualization-libraries.d.ts

@@ -0,0 +1,25 @@
+/**
+ * The fixed allow-list of libraries a CustomVisualization may ask for (libraries from a fixed allow-list
+ * served by us). Each bundle is a pinned copy in `sandbox-frame/libraries/` (stored as `.txt`, so linters and type
+ * checks skip the minified code), loaded lazily into its own chunk of our build and handed to the sandbox frame inside
+ * the render message — the frame loads no script from any URL. The SHA-256 of each file is pinned here and checked by
+ * `sandbox-frame/_custom-visualization-frame.spec.ts`, so a changed bundle is a deliberate re-pin. A block that names a
+ * library outside this list is not run (it reports `failed`).
+ */
+export interface CustomVisualizationLibrary {
+    /** The name the block writes in `libraries`. */
+    name: string;
+    version: string;
+    /** The global the bundle defines in the frame (`window.d3`). */
+    globalName: string;
+    /** The bundle file in `sandbox-frame/libraries/`. */
+    fileName: string;
+    /** SHA-256 of the file, hex. */
+    sha256: string;
+    loadSource: () => Promise<string>;
+}
+export declare const CUSTOM_VISUALIZATION_LIBRARIES: readonly CustomVisualizationLibrary[];
+export declare const CUSTOM_VISUALIZATION_LIBRARY_NAMES: readonly string[];
+export declare const findCustomVisualizationLibrary: (libraryName: string) => CustomVisualizationLibrary | undefined;
+/** The sources of the named libraries, in the given order; every name must be on the allow-list. */
+export declare const loadCustomVisualizationLibrarySources: (libraryNames: readonly string[]) => Promise<string[]>;

package/dist/types/widgets/CustomVisualizationConversationWidget/shared/custom-visualization-sandbox-config.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Where the sandbox frame of a CustomVisualization is served from — committed configuration, no
+ * environment switch.
+ *
+ * `frameUrl: null` (the default) uses the frame page our own build emits (`app-build/assets/custom-visualization-frame-
+ * <hash>.html`, the Vite dev server's copy locally): the app's own origin. The frame is still sandboxed
+ * (`sandbox="allow-scripts"`, an opaque origin: no cookies, no storage, no access to the chat's DOM), and Chromium puts
+ * a sandboxed frame into a process of its own; a browser that does not (Safari, a Chromium without site isolation) runs
+ * it in the chat's process, so an endless loop in the model's script can freeze the chat before the watchdog removes
+ * the frame.
+ *
+ * Set `frameUrl` to the absolute URL of the same `custom-visualization-frame.html` on a host of ANOTHER registrable
+ * domain (a separate site — a subdomain of the app's domain is the same site) to have every browser with site isolation
+ * run it out of process. The file is self-contained (no relative references); the libraries travel in the render
+ * message, so that host serves this one static file and nothing else.
+ */
+export declare const CUSTOM_VISUALIZATION_SANDBOX_CONFIG: {
+    frameUrl: string | null;
+};
+/** The frame URL the widget loads. */
+export declare const resolveCustomVisualizationFrameUrl: () => string;

package/dist/types/widgets/CustomVisualizationConversationWidget/shared/custom-visualization-widget-payload.d.ts

@@ -0,0 +1,55 @@
+/**
+ * The payload of a CustomVisualization block: the model's own HTML, CSS and JavaScript plus the data the
+ * script draws, run in a sandboxed frame. DATA-COMPLETE: the block carries everything; the frame fetches nothing.
+ * Mirrors the backend class `CustomVisualizationConversationWidget` (fields, the source cap and its measure).
+ */
+export interface CustomVisualizationPayload {
+    title: string;
+    description: string;
+    html: string;
+    css: string;
+    script: string;
+    /** Names on the allow-list (`custom-visualization-libraries.ts`), loaded before the script. */
+    libraries: string[];
+    /** Any JSON the script reads as `window.AGENTS_VISUALIZATION.data`; null when the block has none. */
+    data: unknown;
+    /** The frame's height before the frame reports its own (CSS px, clamped). */
+    initialHeight: number;
+}
+export type CustomVisualizationPayloadProblem = {
+    code: "NO_CONTENT";
+    detail: string;
+} | {
+    code: "SOURCE_TOO_LARGE";
+    detail: string;
+} | {
+    code: "UNKNOWN_LIBRARY";
+    detail: string;
+};
+export type ParsedCustomVisualizationPayload = {
+    isValid: true;
+    payload: CustomVisualizationPayload;
+    sourceBytes: number;
+} | {
+    isValid: false;
+    problem: CustomVisualizationPayloadProblem;
+    title: string;
+};
+/**
+ * The most source a block may carry: the UTF-8 bytes of `html` + `css` + `script` + the JSON of `data`. Backend twin:
+ * `CustomVisualizationConversationWidget::MAX_SOURCE_BYTES`.
+ */
+export declare const CUSTOM_VISUALIZATION_MAX_SOURCE_BYTES = 65536;
+/** The frame's height when the block names none. */
+export declare const CUSTOM_VISUALIZATION_DEFAULT_HEIGHT_PX = 360;
+/**
+ * The bytes the source cap counts: `html`, `css`, `script` and the compact JSON of `data` (nothing for no data), as
+ * UTF-8 — the backend's `measureSourceBytes()` counts the same.
+ */
+export declare const measureCustomVisualizationSourceBytes: (payload: Pick<CustomVisualizationPayload, "html" | "css" | "script" | "data">) => number;
+/**
+ * Reads a block's payload. Alias-tolerant (`markup` / `styles` / `js` / `code`, `subtitle` / `caption`, `libs`,
+ * `initialHeight`), never throws: a malformed payload, a block without HTML and script, a source above the cap or a
+ * library outside the allow-list comes back invalid with the problem the widget reports.
+ */
+export declare const parseCustomVisualizationPayload: (rawPayload: string | undefined) => ParsedCustomVisualizationPayload;

package/dist/types/widgets/CustomVisualizationConversationWidget/shared/read-custom-visualization-theme.d.ts

@@ -0,0 +1,5 @@
+export interface CustomVisualizationTheme {
+    variables: Record<string, string>;
+    colorScheme: "light" | "dark";
+}
+export declare const readCustomVisualizationTheme: (themeScopeElement: HTMLElement | null) => CustomVisualizationTheme;

package/dist/types/widgets/EntityMentionConversationWidget/EntityMentionAskButton/EntityMentionAskButton.d.ts

@@ -0,0 +1,13 @@
+import type { EntityMentionTarget } from "../shared/entity-mention";
+export interface EntityMentionAskButtonProps extends EntityMentionTarget {
+    testId?: string;
+}
+/**
+ * The detail panel's "Ask about this" button (ChatGPT's "Anschlussfrage stellen"):
+ * puts the entity into the chat input as an `EntityMention` chip and sends NOTHING — the owner writes the question,
+ * the chip rides in that message as a fence, and the backend reads which entity the question is about. Not a
+ * next-step CTA: it posts no prompt. A second click on the same entity changes nothing; the
+ * label turns into "Added to your message". Mounted by the `entityDetail` canvas (the shell or a domain body) with
+ * the entity the panel shows; renders nothing in the e-mail capture or for a target that names no entity.
+ */
+export declare const EntityMentionAskButton: (props: EntityMentionAskButtonProps) => import("react/jsx-runtime").JSX.Element | null;

package/dist/types/widgets/EntityMentionConversationWidget/EntityMentionCard/EntityMentionCard.d.ts

@@ -0,0 +1,11 @@
+import type { EntityMentionFields } from "../shared/entity-mention";
+export interface EntityMentionCardProps {
+    mention: EntityMentionFields;
+    testId?: string;
+}
+/**
+ * The read-only echo of ONE mentioned entity above the owner's own message: a small elevated card with the entity
+ * type's icon in a rounded tile, the caption "Asking about" and the entity's name below it. The name is business
+ * content (`ModelText`: never translated, never parsed as markup); without one the line names the type ("This review").
+ */
+export declare const EntityMentionCard: (props: EntityMentionCardProps) => import("react/jsx-runtime").JSX.Element;

package/dist/types/widgets/EntityMentionConversationWidget/EntityMentionConversationWidget.d.ts

@@ -0,0 +1,9 @@
+import type { PayloadConversationWidgetProps } from "../../renderer/conversation-widget-props";
+/**
+ * The registry `component` of `EntityMention`: the read-only echo of the entity the owner asked
+ * about, shown above the prose of the owner's OWN message (`ConversationMessageUserWidgets`) — the entity's card (type icon,
+ * "Asking about", name) in place of the composer's chip. The owner put it there with the detail panel's "Ask about this" button
+ * (`EntityMentionAskButton`); the agent never writes it. A payload that names no entity renders nothing and reports
+ * `failed INVALID_PROP`.
+ */
+export declare const EntityMentionConversationWidget: (props: PayloadConversationWidgetProps) => import("react/jsx-runtime").JSX.Element | null;

package/dist/types/widgets/EntityMentionConversationWidget/shared/entity-mention-presentation.d.ts

@@ -0,0 +1,4 @@
+import { type AgentsIconName } from "../../../provider/components";
+export declare const FALLBACK_ENTITY_LABEL = "About this entry";
+export declare const entityTypeIcon: (entityType: string) => AgentsIconName;
+export declare const entityTypeFallbackLabel: (entityType: string) => string;

package/dist/types/widgets/EntityMentionConversationWidget/shared/entity-mention.d.ts

@@ -0,0 +1,33 @@
+export declare const ENTITY_MENTION_WIDGET_NAME = "EntityMention";
+/** Most entities one message mentions — one more "Ask about this" drops the oldest mention. */
+export declare const MAX_ENTITY_MENTIONS_PER_MESSAGE = 5;
+/** Longest display name carried into the message (the name is shown, never trusted — the id identifies). */
+export declare const MAX_ENTITY_MENTION_LABEL_LENGTH = 120;
+export interface EntityMentionFields {
+    entityType: string;
+    entityId: string;
+    /** The entity's name as the panel showed it; null when the opener knew none. */
+    label: string | null;
+    /** The key of the agent space the entity belongs to; null = the chat's agent space. */
+    agentSpaceKey: number | null;
+}
+/** What an opener (the detail panel's button) knows about the entity. */
+export interface EntityMentionTarget {
+    entityType: string;
+    entityId: string | number;
+    label?: string | null;
+    agentSpaceKey?: number | null;
+}
+/**
+ * The mention a fence's fields (or a composer widget's fields) carry, or null when they name no entity. Tolerates the
+ * spellings a copy might use (`type`/`kind` for the type, `id` for the id, `name`/`title` for the label).
+ */
+export declare const normalizeEntityMentionFields: (fields: unknown) => EntityMentionFields | null;
+/** The mention a widget `payload` (the fence's JSON string) carries, or null. */
+export declare const parseEntityMentionPayload: (payload: string | undefined) => EntityMentionFields | null;
+/** The composer widget's fields for an opener's target, or null for a target that names no entity. */
+export declare const buildEntityMentionFields: (target: EntityMentionTarget) => EntityMentionFields | null;
+/** The fields as the fence carries them: a null label or agent space key is not written. */
+export declare const toEntityMentionWireFields: (mention: EntityMentionFields) => Record<string, unknown>;
+/** Identity of a mention: one entity is mentioned once per message. */
+export declare const entityMentionKey: (mention: Pick<EntityMentionFields, "entityType" | "entityId">) => string;

package/dist/types/widgets/EntityMentionConversationWidget/shared/use-entity-mention-composer.d.ts

@@ -0,0 +1,17 @@
+import { EntityMentionTarget } from "./entity-mention";
+export interface UseEntityMentionComposerResult {
+    /** Whether this entity is already mentioned in the composer. */
+    isMentioned: (target: EntityMentionTarget) => boolean;
+    /**
+     * Puts the entity into the composer as an `EntityMention` chip — once per entity (a second click is a no-op); past
+     * {@link MAX_ENTITY_MENTIONS_PER_MESSAGE} the new entity takes the place of the oldest mention (one write: a remove
+     * and an add in one event would both read the list before either). Sends nothing: the owner writes the question.
+     * Returns false for a target that names no entity.
+     */
+    mentionEntity: (target: EntityMentionTarget) => boolean;
+}
+/**
+ * The opener side of the `EntityMention` composer widget: what the detail panel's "Ask about this"
+ * button calls. Reads and writes the composer widgets of the chat's widget context; the composer strip renders them.
+ */
+export declare const useEntityMentionComposer: () => UseEntityMentionComposerResult;

package/dist/types/widgets/MultiChoiceConversationWidget/MultiChoiceConversationWidget.d.ts

@@ -0,0 +1,2 @@
+import { PayloadConversationWidgetProps } from "../../renderer/conversation-widget-props";
+export declare const MultiChoiceConversationWidget: (props: PayloadConversationWidgetProps) => import("react/jsx-runtime").JSX.Element | null;

package/dist/types/widgets/MultiChoiceConversationWidget/shared/multi-choice-widget-payload.d.ts

@@ -0,0 +1,16 @@
+export interface MultiChoiceOption {
+    label: string;
+    sublabel?: string;
+    value: string;
+    selected?: boolean;
+}
+export interface MultiChoicePayload {
+    title?: string;
+    subtitle?: string;
+    options: MultiChoiceOption[];
+    selectAllLabel?: string;
+    confirmLabelTemplate?: string;
+    confirmAction?: string;
+}
+/** The `MultiChoice` fence payload: an object with an `options` list; anything else renders nothing. */
+export declare const parseMultiChoicePayload: (raw: string) => MultiChoicePayload | null;

package/dist/types/widgets/QuickRepliesConversationWidget/QuickRepliesConversationWidget.d.ts

@@ -0,0 +1,38 @@
+import { PayloadConversationWidgetProps } from "../../renderer/conversation-widget-props";
+type QuickRepliesConversationWidgetProps = PayloadConversationWidgetProps;
+/**
+ * A "placeholder option" is a QuickReplies option that is a TEMPLATE with a blank rather than a complete answer the
+ * owner could send as-is (the backend has a hard rule against this — this predicate is the widget's
+ * own backstop, since a malformed agent turn can still emit one). Three tells, any one is enough: an ellipsis
+ * (`…` or `...`), a bracketed/underscore blank (`[...]`, `[…]`, `___`),
+ * or the option simply ending in a colon (introduces an answer it never supplies). Clicking such an option must
+ * never send its literal text — see `handleClick` below.
+ */
+export declare const isQuickReplyPlaceholderOption: (option: string) => boolean;
+/**
+ * The text a placeholder-option click puts into the composer: every blank marker removed, trailing whitespace
+ * trimmed, then ONE trailing space so the owner's cursor lands ready to type (e.g. `"Yes, we deliver to these
+ * areas: …"` → `"Yes, we deliver to these areas: "`). A colon-only ending (no separate marker) is left as-is before
+ * the trailing space is added — the colon is the prompt, not the blank.
+ */
+export declare const stripQuickReplyPlaceholderMarker: (option: string) => string;
+/**
+ * The closed-question answer pills (a backend hard rule): two to five short options, each a
+ * complete answer the owner could also type. A click posts that option's text as the owner's message — single pick,
+ * never a multi-select (that is `MultiChoiceConversationWidget`).
+ *
+ * A placeholder option (`isQuickReplyPlaceholderOption`) is the one exception: it never sends. The click instead
+ * puts the stripped text into the composer and focuses it (`prefillComposer`), so the owner completes the sentence
+ * themselves instead of the literal blank going out as their message.
+ *
+ * Locks only once the host CONFIRMS the send was accepted (`sendMessageToChat`'s `void | Promise<boolean>`
+ * contract) — a rejected send (a closed conversation, an in-flight start) leaves the pills clickable again, and a
+ * second click while one is already in flight is ignored. Once locked, the pills give way to one pill naming the
+ * chosen answer (`DonePill`).
+ *
+ * Bound to its own host message (`messageId`): once a NEWER owner message exists in the conversation (the owner
+ * typed past it, or answered a later question), the widget goes inert — `interactive` alone does not catch this,
+ * since it stays true for the rest of the live session, not just until the next owner message.
+ */
+export declare const QuickRepliesConversationWidget: (props: QuickRepliesConversationWidgetProps) => import("react/jsx-runtime").JSX.Element | null;
+export {};

package/dist/types/widgets/QuickRepliesConversationWidget/shared/quick-replies-widget-payload.d.ts

@@ -0,0 +1,20 @@
+/**
+ * The `QuickReplies` fence payload (a backend hard rule): a closed question answered by SHORT
+ * pills, each a complete answer the owner could also type. Validated strictly — an invalid payload renders nothing
+ * (the widget's own kill switch, same as an unresolved wire name).
+ */
+export interface QuickRepliesPayload {
+    options: string[];
+}
+export declare const QUICK_REPLIES_MIN_OPTIONS = 2;
+export declare const QUICK_REPLIES_MAX_OPTIONS = 5;
+/** Longer options are cut with an ellipsis for DISPLAY only — the click still sends the option in full. */
+export declare const QUICK_REPLIES_MAX_DISPLAY_LENGTH = 60;
+/**
+ * `options` must be an array of 2 to 5 strings, each non-empty after trimming and unique (case-insensitive) — a
+ * malformed shape or a violated bound drops the whole widget. Options are NOT silently deduplicated: a payload the
+ * agent got wrong (two options that only differ by case) is invalid, not quietly repaired.
+ */
+export declare const parseQuickRepliesPayload: (raw: string) => QuickRepliesPayload | null;
+/** The rendered pill label — never what is sent (the click always sends the full, untruncated option text). */
+export declare const truncateQuickReplyLabel: (option: string) => string;

package/dist/types/widgets/SuggestedActions/SuggestedActions.d.ts

@@ -0,0 +1,10 @@
+import { BaseConversationWidgetProps } from "../../renderer/conversation-widget-props";
+export interface SuggestedAction {
+    displayText: string;
+    userAction: string;
+}
+interface SuggestedActionsProps extends BaseConversationWidgetProps {
+    options: string;
+}
+export declare const SuggestedActions: ({ options, interactive }: SuggestedActionsProps) => import("react/jsx-runtime").JSX.Element | null;
+export {};

package/dist/types/widgets/ToolTraceConversationWidget/ToolTraceConversationWidget.d.ts

@@ -0,0 +1,8 @@
+import { PayloadConversationWidgetProps } from "../../renderer/conversation-widget-props";
+type ToolTraceConversationWidgetProps = PayloadConversationWidgetProps;
+/**
+ * Renders a muted single-line trace for a tool_use assistant part.
+ * Renders both on live delivery and history replay — never executes.
+ */
+export declare const ToolTraceConversationWidget: (props: ToolTraceConversationWidgetProps) => import("react/jsx-runtime").JSX.Element | null;
+export {};

package/dist/types/widgets/WebSearchResultsConversationWidget/SourceFavicon.d.ts

@@ -0,0 +1,10 @@
+/** Best-effort hostname for an untitled source, so the link still reads as a place rather than a raw URL. */
+export declare const hostnameOf: (url: string) => string;
+/**
+ * The site's favicon (the small per-site icon WhatsApp/Slack show on a link), resolved from the Google favicon service
+ * by domain. Falls back to the generic link glyph if the icon fails to load (no favicon, offline) — never a broken
+ * image.
+ */
+export declare const SourceFavicon: ({ hostname }: {
+    hostname: string;
+}) => import("react/jsx-runtime").JSX.Element;

package/dist/types/widgets/WebSearchResultsConversationWidget/WebSearchAnswer.d.ts

@@ -0,0 +1,6 @@
+type WebSearchAnswerProps = {
+    answer: string;
+};
+/** The answer body — rendered as markdown so headings, lists and inline links from the provider show properly. */
+export declare const WebSearchAnswer: (props: WebSearchAnswerProps) => import("react/jsx-runtime").JSX.Element | null;
+export {};

package/dist/types/widgets/WebSearchResultsConversationWidget/WebSearchReferences.d.ts

@@ -0,0 +1,12 @@
+import { WebSearchResultSource } from "./shared/web-search-results-widget-payload";
+export interface WebSearchReferencesProps {
+    sources: WebSearchResultSource[];
+    testId?: string;
+}
+/**
+ * The references of a web research answer the agent wrote itself: one link chip per page it used — the
+ * site's favicon and its name (the page title instead when several pages of one site are listed, so no two chips read
+ * the same), the page title on hover — placed by the agent under its own prose answer. Each opens the
+ * page in a new tab. A chip wears the agent tray pill surface (Scheduled / Done) so the sources belong to the board.
+ */
+export declare const WebSearchReferences: (props: WebSearchReferencesProps) => import("react/jsx-runtime").JSX.Element | null;

package/dist/types/widgets/WebSearchResultsConversationWidget/WebSearchResultsCanvas.d.ts

@@ -0,0 +1,10 @@
+import { WebSearchResultSource } from "./shared/web-search-results-widget-payload";
+type WebSearchResultsCanvasProps = {
+    query: string;
+    answer: string;
+    sources: WebSearchResultSource[];
+    provider?: string;
+};
+/** The canvas body — the full answer + sources, scrollable + inset like the other canvas widgets. */
+export declare const WebSearchResultsCanvas: (props: WebSearchResultsCanvasProps) => import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/types/widgets/WebSearchResultsConversationWidget/WebSearchResultsCanvasBody.d.ts

@@ -0,0 +1,7 @@
+import type { CanvasBodyProps } from "../../renderer/canvas/canvas-body-props";
+/**
+ * The `webSearchResults` CANVAS BODY (`canvasBodies.tsx`): re-reads the `WebSearchResults` fence of the anchor message
+ * — the answer and its cited sources the inline widget rendered from — and shows them in the canvas. Renders nothing
+ * when the anchor message no longer carries the fence.
+ */
+export declare const WebSearchResultsCanvasBody: ({ canvas, anchorMessageMarkdown }: CanvasBodyProps) => import("react/jsx-runtime").JSX.Element | null;

package/dist/types/widgets/WebSearchResultsConversationWidget/WebSearchResultsConversationWidget.d.ts

@@ -0,0 +1,14 @@
+import { PayloadConversationWidgetProps } from "../../renderer/conversation-widget-props";
+type WebSearchResultsConversationWidgetProps = PayloadConversationWidgetProps;
+/**
+ * The references of a web research answer: the agent writes its answer as prose and puts this widget under it with the
+ * pages it used (`sources` only) — rendered as link chips with each site's favicon ({@link WebSearchReferences}).
+ * DATA-COMPLETE: it renders entirely from the payload; it NEVER re-runs the search.
+ *
+ * Legacy form (older stored messages): a payload with an `answer` renders the full answer card below.
+ *
+ * Renders INLINE in the message (answer markdown + the cited sources, each with its site favicon). It only opens in the
+ * canvas side panel if the agent explicitly sets `display: "canvas"` — by default a web answer stays inline.
+ */
+export declare const WebSearchResultsConversationWidget: (props: WebSearchResultsConversationWidgetProps) => import("react/jsx-runtime").JSX.Element | null;
+export {};

package/dist/types/widgets/WebSearchResultsConversationWidget/WebSearchSourcesList.d.ts

@@ -0,0 +1,10 @@
+import { WebSearchResultSource } from "./shared/web-search-results-widget-payload";
+type WebSearchSourcesListProps = {
+    sources: WebSearchResultSource[];
+    provider?: string;
+    testId?: string;
+};
+/** The cited sources — a numbered list of links, each opening in a new tab with the site's favicon; falls back to the
+ *  hostname when untitled. */
+export declare const WebSearchSourcesList: (props: WebSearchSourcesListProps) => import("react/jsx-runtime").JSX.Element | null;
+export {};