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

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

@@ -0,0 +1,79 @@
+import { type AgentsIconName } from "../../provider/components";
+import { ReactNode } from "react";
+import type { CanvasId } from "../../renderer/canvas/canvas-behaviours";
+import { CanvasAnchor } from "../../renderer/canvas/canvas-state";
+/**
+ * The canvas a card opens: which canvas, which instance, anchored on which message. The body comes from
+ * `canvasBodies` and re-reads its payload from the anchor message — the card carries no rendered node. Layout
+ * (width, narrow-viewport rule, full bleed) is the canvas's behaviour (`canvas-behaviours.ts`), not a card prop.
+ */
+export interface CanvasWidgetCardCanvas {
+    canvasId: CanvasId;
+    instanceId: string;
+    anchor: CanvasAnchor;
+}
+export interface CanvasWidgetCardProps {
+    /**
+     * Headline shown on the inline card (e.g. "Search results for 'X'"). Rendered through the component library's `Text`, so
+     * it auto-translates: keep dynamic values out of the string and pass them via `titleReplacements` (`%token%`).
+     */
+    title: string;
+    /** `%token%` → value replacements for `title`, so an interpolated headline stays one stable translation key. */
+    titleReplacements?: Record<string, string | number>;
+    /** False when `title` is a business/user value that must render as-is (not a translation key). Default true. */
+    translateTitle?: boolean;
+    /** Optional second line (e.g. "5 conversations", a filter summary). Auto-translates — interpolate via `subtitleReplacements`. */
+    subtitle?: string;
+    /** `%token%` → value replacements for `subtitle`, so an interpolated second line stays one stable translation key. */
+    subtitleReplacements?: Record<string, string | number>;
+    /** False when `subtitle` is a business/user value that must render as-is (not a translation key). Default true. */
+    translateSubtitle?: boolean;
+    /** Optional leading icon (a glyph hinting what the canvas holds). Falls back to a generic panel glyph. */
+    icon?: AgentsIconName;
+    /**
+     * A preview of the picture the canvas opens with. Set → the RICH card: the thumbnail replaces the icon badge, the
+     * title gets more weight, and the hover is the component library's `GlobalStateComponent` layer (e.g. an app's closing summary
+     * card with a hero picture).
+     */
+    thumbnail?: ReactNode;
+    /** True when the host message was delivered live right now — auto-opens the canvas once. Never true after a reload or on history replay. */
+    justDelivered?: boolean;
+    /**
+     * The canvas this card opens (`canvasForMessageWidget`). Undefined while the widget does not know its message (the
+     * reply is still streaming, a composer echo): the card renders but opens nothing.
+     */
+    canvas?: CanvasWidgetCardCanvas;
+    /**
+     * The other agent space the canvas shows, when it is not the active one. The named card shows that agent space's chip on
+     * a row above it: floating over the card's corner, the chip would cover the open affordance, and inside the card
+     * (a `<button>`) its focusable popover trigger would nest one control in another. A `preview` names the agent space
+     * itself, so the narrow viewport's preview branch adds nothing.
+     */
+    anotherAgentSpaceKey?: number;
+    /**
+     * The real widget content (the lightweight inline list). Rendered directly in the chat on a NARROW viewport (no side
+     * canvas) so the user still sees the data; on a wide viewport the content lives only in the side canvas and this is
+     * not rendered — the card is just the card.
+     */
+    preview?: ReactNode;
+    /**
+     * The widget's root test id. The named card carries it, its open control `<testId>-open-canvas`; with a `preview`
+     * the preview carries the root id itself and only the open control is marked.
+     */
+    testId?: string;
+}
+/**
+ * The standard inline representation of a CANVAS widget in the conversation — ONE component shared by every canvas
+ * widget (web search, conversation search, and every list, gallery or summary canvas an app's widgets open).
+ *
+ * Wide viewport: a compact card (icon badge + title + subtitle + "open" affordance) that opens the canvas as the side
+ * split, auto-opening once on a just-delivered message. The opening rule (`decideCanvasOpen`) decides in the reducer:
+ * replay, the narrow-viewport rule of the canvas's behaviour and the customer's veto all live there.
+ *
+ * Narrow viewport (no side split, the canvas opens as a full-screen overlay), two shapes:
+ *  - with a `preview`: the real inline content is rendered in the chat so the user sees the data, plus an "Open in
+ *    canvas" affordance to open the full view over the chat. Tap to open — a live delivery is not a takeover.
+ *  - without a `preview` (the canvas is the widget's only surface, behaviour `narrowViewport: "overlay"`): the same
+ *    named card as on the wide viewport, so closing the canvas leaves a card to re-open.
+ */
+export declare const CanvasWidgetCard: ({ title, titleReplacements, translateTitle, subtitle, subtitleReplacements, translateSubtitle, icon, thumbnail, justDelivered, canvas, anotherAgentSpaceKey, preview, testId, }: CanvasWidgetCardProps) => import("react/jsx-runtime").JSX.Element;

package/dist/types/widgets/CanvasWidgetCard/CanvasWidgetSwitch.d.ts

@@ -0,0 +1,61 @@
+import { type AgentsIconName } from "../../provider/components";
+import { ReactNode } from "react";
+import { CanvasWidgetCardCanvas } from "./CanvasWidgetCard";
+export interface CanvasWidgetInlineRenderOptions {
+    /**
+     * True only when the inline render is the narrow-viewport preview inside the {@link CanvasWidgetCard}, above its
+     * "Open in canvas" button, so the canvas holds the full content. False in the chat's inline branch and in email /
+     * image renders, where no canvas exists and the inline render is the whole widget: never shorten it there.
+     */
+    isWidgetPreview: boolean;
+}
+export interface CanvasWidgetSwitchProps {
+    /**
+     * Agent hint that forces the branch. Normally OMITTED — the switch auto-picks by content size.
+     * `"canvas"` forces the canvas; `"inline"` keeps the content inline regardless of size.
+     */
+    display?: "inline" | "canvas";
+    /**
+     * The per-widget content rule: true when the content is larger than fits comfortably inline (more items / a longer
+     * answer than the widget's inline limit). Combined with `display` to decide whether this is a canvas widget. Ignored
+     * when `display` is set. Canvas-only widgets pass `display="canvas"` instead of this.
+     */
+    exceedsInlineLimit?: boolean;
+    /** Headline on the inline card (e.g. "Search results for 'X'"). Used only when it opens as a canvas. */
+    title: string;
+    /** `%token%` → value replacements for `title`, so an interpolated headline stays one stable translation key. */
+    titleReplacements?: Record<string, string | number>;
+    /** Optional second line on the card (e.g. "5 sources", a filter summary). Used only when it opens as a canvas. */
+    subtitle?: string;
+    /** `%token%` → value replacements for `subtitle`, so an interpolated second line stays one stable translation key. */
+    subtitleReplacements?: Record<string, string | number>;
+    /** False when `subtitle` is already resolved text (a business value, a singular/plural value). Default true. */
+    translateSubtitle?: boolean;
+    /** Optional leading icon on the card. Used only when it opens as a canvas. */
+    icon?: AgentsIconName;
+    /** True when the host message was delivered live right now — auto-opens the canvas once. Never true after a reload or on history replay. */
+    justDelivered?: boolean;
+    /** The canvas the card opens (see {@link CanvasWidgetCardProps.canvas}). */
+    canvas?: CanvasWidgetCardCanvas;
+    /**
+     * The other agent space the content belongs to, when it is not the active one: the named card shows its chip (see
+     * {@link CanvasWidgetCardProps.anotherAgentSpaceKey}). The inline render names it itself.
+     */
+    anotherAgentSpaceKey?: number;
+    /**
+     * The inline render of the widget. Shown directly in the chat when the content is small enough to stay inline, and
+     * reused by the {@link CanvasWidgetCard} as the narrow-viewport inline render below its card. Called once per render.
+     * A widget that shortens its content for the widget preview does so only when `isWidgetPreview` is true.
+     */
+    renderInline: (options: CanvasWidgetInlineRenderOptions) => ReactNode;
+    /** The widget's root test id (`<kebab wire name>-widget`), handed to the {@link CanvasWidgetCard}. */
+    testId?: string;
+}
+/**
+ * The single switch shared by every canvas widget. It owns the one decision — is this a CANVAS widget at all: the
+ * agent forced it (`display`) or the content exceeds the widget's inline limit. Small content renders inline in the
+ * chat. A canvas widget hands off to {@link CanvasWidgetCard}, which itself decides the viewport-dependent shape: on a
+ * wide viewport a clickable card (opens the side split), on a narrow viewport the inline render plus an "Open in
+ * canvas" CTA (opens over the chat). Centralising this here keeps all widgets consistent and free of the branch.
+ */
+export declare const CanvasWidgetSwitch: ({ display, exceedsInlineLimit, title, titleReplacements, subtitle, subtitleReplacements, translateSubtitle, icon, justDelivered, canvas, anotherAgentSpaceKey, renderInline, testId, }: CanvasWidgetSwitchProps) => import("react/jsx-runtime").JSX.Element;

package/dist/types/widgets/CanvasWidgetCard/canvas-for-message-widget.d.ts

@@ -0,0 +1,8 @@
+import type { CanvasId } from "../../renderer/canvas/canvas-behaviours";
+import type { CanvasWidgetCardCanvas } from "./CanvasWidgetCard";
+/**
+ * The canvas a payload widget in a message opens: anchored on the host message, one instance per message + payload.
+ * Undefined while the widget does not know its message (the reply is still streaming, a composer echo, a story that
+ * mounts the widget without a message) — the card then renders but opens nothing.
+ */
+export declare const canvasForMessageWidget: (canvasId: CanvasId, messageId: string | number | undefined, payload: string) => CanvasWidgetCardCanvas | undefined;

package/dist/types/widgets/CanvasWidgetCard/use-canvas-viable.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Min viewport width (px) at which the canvas side-panel split is usable. Mirrors the ModalSplitView `autoCloseWidth`
+ * in ConversationView — below it the split auto-collapses, so a canvas widget must render its content inline instead of opening
+ * a panel that immediately closes.
+ */
+export declare const CANVAS_VIABLE_MIN_WIDTH = 850;
+/**
+ * True when the viewport is wide enough for the canvas side panel. Re-renders the consumer ONLY when the boolean
+ * crosses {@link CANVAS_VIABLE_MIN_WIDTH} — NOT on every resize pixel. This matters because the consumers (the canvas
+ * widgets, ConversationView) re-mount heavy, self-fetching lists; a width-tracking
+ * hook would re-render them on every resize tick and make dragging the window janky. We store the derived boolean and
+ * skip the state update when it hasn't flipped, so React bails out and a drag that stays on one side of the threshold
+ * costs zero re-renders.
+ */
+export declare const useCanvasViable: () => boolean;

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

@@ -0,0 +1,11 @@
+import type { PayloadConversationWidgetProps } from "../../renderer/conversation-widget-props";
+type ClockConversationWidgetProps = PayloadConversationWidgetProps;
+/**
+ * The `Clock` widget: the live time of one place or a world clock of several, from the
+ * IANA zone ids and labels the model passes. DATA-COMPLETE without data: the time is computed in the browser every
+ * second (`Intl`), nothing is fetched. A zone id the browser does not know is dropped and reported `failed`
+ * (`INVALID_PROP`, the dropped ids in the detail) while the other clocks render; a payload without clocks reports
+ * `empty`. In the e-mail capture the clocks freeze at the capture moment and an "As of" line names it. Inline only.
+ */
+export declare const ClockConversationWidget: (props: ClockConversationWidgetProps) => import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/types/widgets/ClockConversationWidget/ClockWidget/AnalogClockFace.d.ts

@@ -0,0 +1,12 @@
+import { type ZonedWallClock } from "../shared/clock-time";
+export interface AnalogClockFaceProps {
+    wallClock: ZonedWallClock;
+    /** The accessible name — the digital time it shows, already formatted. */
+    accessibleLabel: string;
+}
+/**
+ * The analog dial of one clock: twelve ticks (the quarters longer), hour and minute hand in the text colour, the second
+ * hand and the hub in the call-to-action colour — every colour a theme token, so it flips with the scheme. Purely a
+ * picture of the digital time next to it: `role="img"` with that time as its name.
+ */
+export declare const AnalogClockFace: (props: AnalogClockFaceProps) => import("react/jsx-runtime").JSX.Element;

package/dist/types/widgets/ClockConversationWidget/ClockWidget/ClockRow.d.ts

@@ -0,0 +1,23 @@
+import type { ClockTimeFormat } from "../shared/clock-widget-payload";
+/** One clock ready to render: a zone the browser knows and the place's label. */
+export interface ClockWidgetEntry {
+    timeZone: string;
+    /** The place — the model's label, or the city derived from the zone id; business content, never translated. */
+    label: string;
+    /** The model's zone abbreviation; undefined → the browser's short zone name. */
+    abbreviation?: string;
+}
+export interface ClockRowProps {
+    clock: ClockWidgetEntry;
+    now: Date;
+    ownerTimeZone: string;
+    timeFormat: ClockTimeFormat;
+    language: string;
+    dateLocale: string;
+    testId?: string;
+}
+/**
+ * One place: the digital time as the hero, the place with its zone abbreviation, the day there and the hour difference
+ * to the owner's zone, then the date, the UTC offset and day or night; the analog dial on the right.
+ */
+export declare const ClockRow: (props: ClockRowProps) => import("react/jsx-runtime").JSX.Element;

package/dist/types/widgets/ClockConversationWidget/ClockWidget/ClockWidget.d.ts

@@ -0,0 +1,21 @@
+import type { ClockTimeFormat } from "../shared/clock-widget-payload";
+import { type ClockWidgetEntry } from "./ClockRow";
+export interface ClockWidgetProps {
+    clocks: ClockWidgetEntry[];
+    /** The model's headline, shown as written. */
+    title?: string;
+    now: Date;
+    ownerTimeZone: string;
+    timeFormat: ClockTimeFormat;
+    language: string;
+    dateLocale: string;
+    /** Set in an e-mail render: the frozen capture moment the "As of" line names. */
+    captureMoment?: string;
+    testId?: string;
+}
+/**
+ * The presentational clock: one elevated surface, one row per place divided by hairlines (one row = the single clock,
+ * several = the world clock), the optional title above and, in an e-mail, the "As of" line below. Knows nothing about
+ * payloads or the registry.
+ */
+export declare const ClockWidget: (props: ClockWidgetProps) => import("react/jsx-runtime").JSX.Element;

package/dist/types/widgets/ClockConversationWidget/ClockWidget/DayNightGlyph.d.ts

@@ -0,0 +1,8 @@
+export interface DayNightGlyphProps {
+    isDaytime: boolean;
+}
+/**
+ * A sun or a moon (the component library has neither icon) beside the "Day" / "Night" word — decoration only, the word carries the
+ * meaning, so the glyph is hidden from assistive technology.
+ */
+export declare const DayNightGlyph: (props: DayNightGlyphProps) => import("react/jsx-runtime").JSX.Element;

package/dist/types/widgets/ClockConversationWidget/shared/clock-time.d.ts

@@ -0,0 +1,52 @@
+/**
+ * The time arithmetic of the `Clock` widget — pure functions over a `Date` and IANA zone ids, computed from the
+ * browser's own time-zone data (`Intl.DateTimeFormat`), so nothing is fetched and daylight-saving changes come with the
+ * browser. Every function is total: an unknown zone is filtered out before (see {@link isKnownTimeZone}).
+ */
+/** One zone's wall clock at one instant. */
+export interface ZonedWallClock {
+    year: number;
+    month: number;
+    day: number;
+    hour: number;
+    minute: number;
+    second: number;
+    /** Minutes east of UTC at that instant (Berlin in winter: 60, New York in summer: -240). */
+    utcOffsetMinutes: number;
+}
+/** Whether the place there is today, yesterday or tomorrow, seen from the owner's zone. */
+export type ClockRelativeDay = "today" | "yesterday" | "tomorrow";
+/** True when the browser knows the zone — the widget drops (and reports) every other id. */
+export declare const isKnownTimeZone: (timeZone: string) => boolean;
+/** The zone's wall clock at `instant`; the UTC offset is the difference between that wall clock and UTC. */
+export declare const readZonedWallClock: (instant: Date, timeZone: string) => ZonedWallClock;
+/** The calendar day at the clock's place compared with the owner's: one day apart at most (UTC−12 … UTC+14). */
+export declare const readRelativeDay: (clockWallClock: ZonedWallClock, ownerWallClock: ZonedWallClock) => ClockRelativeDay;
+/** `+0`, `+8`, `−5`, `+5:30` — hours (and minutes) the clock's zone is ahead of the owner's. */
+export declare const formatHourDifference: (differenceMinutes: number) => string;
+/** `UTC+1`, `UTC−4`, `UTC+5:30`, and `UTC` for no offset. */
+export declare const formatUtcOffset: (utcOffsetMinutes: number) => string;
+/** The sun is shown from 06:00 to 19:59 local time, the moon otherwise. */
+export declare const isDaytime: (wallClock: ZonedWallClock) => boolean;
+/** The place a zone id names: `America/New_York` → `New York`, `UTC` → `UTC`. */
+export declare const readCityOfTimeZone: (timeZone: string) => string;
+/**
+ * The browser's short zone name in the owner's locale (`MEZ`), else in US English (`EDT` — most locales name foreign
+ * zones only by offset), or undefined when both know only an offset (`GMT+9`): the UTC offset has its own line anyway.
+ */
+export declare const readZoneAbbreviation: (instant: Date, timeZone: string, locale: string) => string | undefined;
+/** The digital time: `02:58` (24 h, zero-padded) or `2:58` plus the locale's day period (`AM`, `PM`) for 12 h. */
+export declare const formatDigitalTime: (wallClock: ZonedWallClock, timeFormat: "24h" | "12h", instant: Date, timeZone: string, locale: string) => {
+    time: string;
+    dayPeriod?: string;
+};
+/** The date at the clock's place in the owner's date locale: `So., 26. Okt.` / `Sun, Oct 26`. */
+export declare const formatZonedDate: (instant: Date, timeZone: string, dateLocale: string) => string;
+/** The capture moment of an e-mail render, in the owner's zone and date locale: `26.10.2026, 02:58`. */
+export declare const formatCaptureMoment: (instant: Date, timeZone: string, dateLocale: string, timeFormat: "24h" | "12h") => string;
+/** The angles of the three hands in degrees, clockwise from 12. */
+export declare const readHandAngles: (wallClock: ZonedWallClock) => {
+    hour: number;
+    minute: number;
+    second: number;
+};

package/dist/types/widgets/ClockConversationWidget/shared/clock-widget-payload.d.ts

@@ -0,0 +1,23 @@
+/**
+ * The `Clock` payload (DATA-COMPLETE: zone ids and labels only, the time is computed in the browser). The parser is
+ * alias-tolerant (weak models rename fields while they write: `tz_name`, `city`, `zones`, …), caps every list and every
+ * string, and never throws — malformed JSON gives an empty payload, which the widget reports as `empty`.
+ */
+/** At most this many clocks render; the rest are dropped silently, as every list cap in the widgets. */
+export declare const MAX_CLOCKS = 8;
+export type ClockTimeFormat = "24h" | "12h";
+/** One clock as the model wrote it — the time zone not yet checked against the browser's zone data. */
+export interface ClockPayloadEntry {
+    /** The IANA time zone id exactly as written (trimmed): "Europe/Berlin". */
+    timeZone: string;
+    /** The place in the owner's language; undefined → derived from the zone id. */
+    label?: string;
+    /** The zone abbreviation the model passed ("CET"); undefined → the browser's short zone name. */
+    abbreviation?: string;
+}
+export interface ClockPayload {
+    title?: string;
+    timeFormat?: ClockTimeFormat;
+    clocks: ClockPayloadEntry[];
+}
+export declare const parseClockPayload: (payload: string | undefined) => ClockPayload;

package/dist/types/widgets/ClockConversationWidget/shared/use-clock-settings.d.ts

@@ -0,0 +1,18 @@
+import type { ClockTimeFormat } from "./clock-widget-payload";
+export interface ClockSettings {
+    /** The owner's own zone: the one of the owner settings, else the browser's, else UTC. */
+    ownerTimeZone: string;
+    /** The owner's language — zone names and the 12 h day period. */
+    language: string;
+    /** The owner's date locale (`de-DE`) — the date lines. */
+    dateLocale: string;
+    /** `12h` when the owner settings use AM/PM. */
+    ownerTimeFormat: ClockTimeFormat;
+}
+/** The owner's settings come from the app, read defensively: the widget renders in hosts that know only some of them. */
+export declare const useClockSettings: () => ClockSettings;
+/**
+ * The current instant, re-read at every full second while `isTicking` — the one timer of the widget, cleared on unmount.
+ * Not ticking (the e-mail capture) keeps the instant of the first render: the capture time the "As of" line names.
+ */
+export declare const useClockNow: (isTicking: boolean) => Date;

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

@@ -0,0 +1,14 @@
+import type { PayloadConversationWidgetProps } from "../../renderer/conversation-widget-props";
+type ConceptExplainerConversationWidgetProps = PayloadConversationWidgetProps;
+/**
+ * The `ConceptExplainer` widget (ChatGPT's LearningViz — as the interaction model): an
+ * interactive explanation of how something works for the business, with a slider over the states, a picture per state
+ * and a caption. Each explainer TYPE is one `*.concept-explainer.tsx` file in its domain, found by folder glob
+ * (`shared/concept-explainer-types.ts`). DATA-COMPLETE and small: the block names the type and, where the type can
+ * show the business's own figures, the few numbers it computes from (copied from a read of this conversation) —
+ * without them the type shows an illustration that claims no number. The slider and the variants only change local
+ * state, so they stay usable on a replay; the e-mail capture shows one step without controls. Reports `empty` for a
+ * block without a type, `failed` for an unknown type (nothing shown) or dropped values (the illustration shown).
+ */
+export declare const ConceptExplainerConversationWidget: (props: ConceptExplainerConversationWidgetProps) => import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/types/widgets/ConceptExplainerConversationWidget/ConceptExplainerWidget/ConceptExplainerWidget.d.ts

@@ -0,0 +1,27 @@
+import type { ConceptExplainerStep, ConceptExplainerTypeDefinition, ConceptExplainerValuesReading, ConceptExplainerVariant } from "../shared/concept-explainer-type";
+/** At most this many steps get a labelled button under the slider; more steps are reached by the slider alone. */
+export declare const MAX_LABELLED_STEPS = 6;
+export interface ConceptExplainerWidgetProps {
+    definition: ConceptExplainerTypeDefinition;
+    /** The model's headline; undefined → the type's default title. */
+    modelTitle?: string;
+    valuesReading: ConceptExplainerValuesReading;
+    steps: ConceptExplainerStep[];
+    stepIndex: number;
+    onStepIndexChange: (stepIndex: number) => void;
+    variants: ConceptExplainerVariant[];
+    variantId: string | undefined;
+    onVariantIdChange: (variantId: string) => void;
+    languageCode: string;
+    /** The static render (the report e-mail capture): the picture of one step, no controls. */
+    isStatic: boolean;
+    testId?: string;
+}
+/**
+ * The ConceptExplainer frame — ChatGPT's LearningViz as the interaction model, our design: one
+ * elevated surface with the title, the type's picture on a flat tile, the caption of the current state under it, the
+ * variant pills (effect-free, so rounded), the slider over the states with its label and the current state's name,
+ * labelled step buttons under the slider, and a footer naming the source and whether the picture carries the
+ * business's numbers or is an illustration. Presentational: the outer widget owns the step and the variant.
+ */
+export declare const ConceptExplainerWidget: (props: ConceptExplainerWidgetProps) => import("react/jsx-runtime").JSX.Element;

package/dist/types/widgets/ConceptExplainerConversationWidget/shared/ConceptExplainerTextView.d.ts

@@ -0,0 +1,11 @@
+import { Text } from "../../../provider/components";
+import type { ComponentProps } from "react";
+import type { ConceptExplainerText } from "./concept-explainer-type";
+export type ConceptExplainerTextViewProps = Omit<ComponentProps<typeof Text>, "children" | "translate" | "replacements" | "context"> & {
+    text: ConceptExplainerText;
+};
+/**
+ * One translated text of an explainer: the key through the component library's `Text`, its `%placeholders%` from `replacements`, the
+ * singular / plural value picked by `context`. Never model text — that goes through `ModelText`.
+ */
+export declare const ConceptExplainerTextView: (props: ConceptExplainerTextViewProps) => import("react/jsx-runtime").JSX.Element;

package/dist/types/widgets/ConceptExplainerConversationWidget/shared/concept-explainer-type.d.ts

@@ -0,0 +1,89 @@
+import type { ComponentType } from "react";
+/**
+ * The contract of one ConceptExplainer TYPE. The `ConceptExplainer` widget is a frame — title,
+ * the type's picture, the caption of the current state, a slider over the states — and every explainer type is one
+ * file `*.concept-explainer.tsx` in the app's domain folder that owns its content, exporting `conceptExplainerType`;
+ * the app registers them (`registerConceptExplainerTypes`), and the backend declares each type in a class of its own
+ * — no list to edit.
+ */
+/** The numbers and words a type reads from the block's `values` (after its own alias-tolerant reading). */
+export type ConceptExplainerValues = Readonly<Record<string, number | string>>;
+/**
+ * A text the frame renders through the component library's `Text`: `key` is a translation key (the English source string), never
+ * model text — a model-written word reaches a text only as a `replacements` value the type escaped itself.
+ */
+export interface ConceptExplainerText {
+    key: string;
+    replacements?: Readonly<Record<string, string | number>>;
+    /** Singular / plural of one key (`"one"` default, `"other"` = the key's MANY value). */
+    context?: "one" | "other";
+}
+/** One state of the explainer — one position of the slider. */
+export interface ConceptExplainerStep {
+    /** Stable id (the payload's `step` may name it to start there). */
+    id: string;
+    /** Short label of the slider position ("Reviews", "+5"). */
+    label: ConceptExplainerText;
+    /** The state's name, shown large under the picture (ChatGPT's "New moon"). */
+    caption: ConceptExplainerText;
+    /** One or two sentences: what changes in this state and why. */
+    description: ConceptExplainerText;
+}
+/** One alternative the owner can switch between beside the slider (the star rating of the new reviews). */
+export interface ConceptExplainerVariant {
+    id: string;
+    label: ConceptExplainerText;
+}
+/** The values as read: the kept values, the problems of the dropped ones, and whether real numbers are present. */
+export interface ConceptExplainerValuesReading {
+    values: ConceptExplainerValues;
+    /** One short English line per dropped value ("currentAverage 7 is not between 1 and 5") — reported to the model. */
+    droppedValueProblems: string[];
+    /**
+     * False = the picture is an ILLUSTRATION without the business's numbers: the frame says so under the picture, and
+     * the type shows no figure it would otherwise have to invent.
+     */
+    carriesBlockNumbers: boolean;
+}
+export interface ConceptExplainerVisualProps {
+    values: ConceptExplainerValues;
+    carriesBlockNumbers: boolean;
+    steps: ConceptExplainerStep[];
+    stepIndex: number;
+    variantId: string | undefined;
+    /** The owner's language (`de`, `en-GB`) for number formatting. */
+    languageCode: string;
+}
+export interface ConceptExplainerStepsInput {
+    values: ConceptExplainerValues;
+    carriesBlockNumbers: boolean;
+    variantId: string | undefined;
+    languageCode: string;
+}
+export interface ConceptExplainerTypeDefinition {
+    /** The wire id the block names in `explainer` (lower camel, e.g. `rankingFactors`) = the backend `TYPE_ID`. */
+    typeId: string;
+    /** The title when the block brings none. */
+    defaultTitle: ConceptExplainerText;
+    /** The sub-line under the title. */
+    subtitle: ConceptExplainerText;
+    /** The slider's label ("Step", "New reviews"). */
+    controlLabel: ConceptExplainerText;
+    /** The label of the variant row, when the type has variants. */
+    variantLabel?: ConceptExplainerText;
+    /** Where the explanation comes from; one line in the footer. */
+    sourceLine?: ConceptExplainerText;
+    /** The footer line when the picture carries no numbers of the business. */
+    illustrationLine: ConceptExplainerText;
+    /** The footer line when it does (how the figures were derived). */
+    computedLine?: ConceptExplainerText;
+    /** Reads the block's `values` — alias-tolerant, never throws. */
+    readValues: (rawValues: Readonly<Record<string, unknown>>) => ConceptExplainerValuesReading;
+    /** The variants in display order, the first picked at the start; none = no variant row. */
+    buildVariants?: (values: ConceptExplainerValues, carriesBlockNumbers: boolean) => ConceptExplainerVariant[];
+    buildSteps: (stepsInput: ConceptExplainerStepsInput) => ConceptExplainerStep[];
+    /** The step a static render (the report e-mail) shows; default the first. */
+    emailStepIndex?: (steps: ConceptExplainerStep[]) => number;
+    /** The picture of the current state. */
+    Visual: ComponentType<ConceptExplainerVisualProps>;
+}

package/dist/types/widgets/ConceptExplainerConversationWidget/shared/concept-explainer-types.d.ts

@@ -0,0 +1,17 @@
+import type { ConceptExplainerTypeDefinition } from "./concept-explainer-type";
+export declare const buildConceptExplainerTypeRegistry: (definitions: readonly ConceptExplainerTypeDefinition[]) => Readonly<Record<string, ConceptExplainerTypeDefinition>>;
+/** The type definitions a set of `*.concept-explainer.tsx` modules export (the package's or an app's glob). */
+export declare const readConceptExplainerTypeDefinitions: (modules: Record<string, {
+    conceptExplainerType?: ConceptExplainerTypeDefinition;
+}>) => ConceptExplainerTypeDefinition[];
+/** Type id → type: the package's folders, then what an app registers (`registerConceptExplainerTypes`). */
+export declare const conceptExplainerTypes: Record<string, ConceptExplainerTypeDefinition>;
+/** Adds an app's ConceptExplainer types. Runs outside React, before the first render; a type id registers once. */
+export declare const registerConceptExplainerTypes: (definitions: readonly ConceptExplainerTypeDefinition[]) => void;
+/** `rankingFactors`, `RankingFactors`, `ranking_factors` and `ranking-factors` all read as `rankingfactors`. */
+export declare const normalizeConceptExplainerTypeId: (typeId: string) => string;
+/**
+ * The registered type of an id — exact first, then ignoring case, `_` and `-` (a model writes `RankingFactors` or
+ * `ranking_factors`; the backend's `ConceptExplainerTypes::findTypeClass()` applies the same rule); else undefined.
+ */
+export declare const findConceptExplainerType: (typeId: string, registry?: Readonly<Record<string, ConceptExplainerTypeDefinition>>) => ConceptExplainerTypeDefinition | undefined;

package/dist/types/widgets/ConceptExplainerConversationWidget/shared/concept-explainer-widget-payload.d.ts

@@ -0,0 +1,25 @@
+/**
+ * The `ConceptExplainer` payload — DATA-COMPLETE and small: which explainer, an optional title,
+ * the few numbers the type may show (copied from a read of this conversation) and an optional start step. Alias-
+ * tolerant (weak models rename fields, and ChatGPT's own LearningViz writes `type_id` inside `parameters`), capped,
+ * never throws: a payload that is not JSON reads as the empty shape.
+ */
+export interface ConceptExplainerPayload {
+    /** The explainer type id as written (`rankingFactors`); "" when the payload names none. */
+    explainer: string;
+    /** The headline in the owner's language, model-written; undefined → the type's default title. */
+    title?: string;
+    /** The raw values for the type to read — every key kept as written, scalars only. */
+    values: Readonly<Record<string, unknown>>;
+    /** The step id or index to start at; undefined → the first step. */
+    step?: string | number;
+}
+/** The backend's `ConceptExplainerConversationWidget::MAX_TITLE_LENGTH`. */
+export declare const MAX_TITLE_LENGTH = 160;
+/** The backend's `ConceptExplainerConversationWidget::MAX_VALUES`. */
+export declare const MAX_VALUES = 20;
+export declare const parseConceptExplainerPayload: (payload: string | undefined) => ConceptExplainerPayload;
+/** Reads a finite number from a value the model wrote as a number or a numeric string (`"4,3"` included). */
+export declare const readConceptExplainerNumber: (value: unknown) => number | undefined;
+/** The first value present under one of the aliases. */
+export declare const readConceptExplainerValue: (rawValues: Readonly<Record<string, unknown>>, aliases: readonly string[]) => unknown;

package/dist/types/widgets/ConceptExplainerConversationWidget/shared/use-concept-explainer-language.d.ts

@@ -0,0 +1,8 @@
+/**
+ * The owner's language for the numbers an explainer formats, from the app (`useOwnerSettings`). Read defensively — the
+ * widget renders in hosts that know no language (the e-mail capture, the preview, a spec), and there the browser's
+ * language stands in.
+ */
+export declare const useConceptExplainerLanguage: () => string;
+/** A number in the owner's language with a fixed count of decimals (`4,3` in German, `4.3` in English). */
+export declare const formatConceptExplainerNumber: (value: number, decimals: number, languageCode: string) => string;

package/dist/types/widgets/ConversationSearchResultsConversationWidget/ConversationSearchResultsCanvas.d.ts

@@ -0,0 +1,9 @@
+import { parseConversationSearchResultsPayload } from "./shared/conversation-search-results-widget-payload";
+type ConversationSearchResultsCanvasProps = {
+    query: string;
+    groups: ReturnType<typeof parseConversationSearchResultsPayload>["groups"];
+    onOpenConversation: (conversationId: number, messageId?: number) => void;
+};
+/** The canvas body — a titled wrapper around the same grouped results, scrollable + inset like the other canvas widgets. */
+export declare const ConversationSearchResultsCanvas: (props: ConversationSearchResultsCanvasProps) => import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/types/widgets/ConversationSearchResultsConversationWidget/ConversationSearchResultsCanvasBody.d.ts

@@ -0,0 +1,7 @@
+import type { CanvasBodyProps } from "../../renderer/canvas/canvas-body-props";
+/**
+ * The `conversationSearchResults` CANVAS BODY (`canvasBodies.tsx`): re-reads the `ConversationSearchResults` fence of
+ * the anchor message — the same payload the inline widget rendered from — and shows the grouped results. Nothing was
+ * stored for it but the pointer. Renders nothing when the anchor message no longer carries the fence.
+ */
+export declare const ConversationSearchResultsCanvasBody: ({ canvas, anchorMessageMarkdown }: CanvasBodyProps) => import("react/jsx-runtime").JSX.Element | null;

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

@@ -0,0 +1,15 @@
+import { PayloadConversationWidgetProps } from "../../renderer/conversation-widget-props";
+type ConversationSearchResultsConversationWidgetProps = PayloadConversationWidgetProps;
+/**
+ * Renders the result of `searchConversations` (cross-chat semantic recall) — the grouped "search all my chats" view
+ * (the replaceable `ConversationSearchResultsList`; the app supplies the component its chat's own search panel uses). DATA-COMPLETE: it
+ * renders entirely from the payload the agent passes (query + grouped hits); it NEVER re-runs the search.
+ *
+ * Few groups → inline in the message; many → opens in the canvas side panel (or whatever `display` forces). The
+ * open-conversation arrow jumps to the source chat via the widget context's `onOpenConversation` seam.
+ *
+ * The canvas is `conversationSearchResults`: the body (`ConversationSearchResultsCanvasBody`) re-reads this payload
+ * from the anchor message. Without a message id (a composer echo, a streaming reply) the card opens nothing.
+ */
+export declare const ConversationSearchResultsConversationWidget: (props: ConversationSearchResultsConversationWidgetProps) => import("react/jsx-runtime").JSX.Element | null;
+export {};

package/dist/types/widgets/ConversationSearchResultsConversationWidget/shared/conversation-search-results-widget-payload.d.ts

@@ -0,0 +1,42 @@
+/**
+ * One matched message inside a conversation group — the fields the search results list renders
+ * (`ConversationSearchResultsList`, a replaceable component).
+ */
+export interface ConversationSearchResultHit {
+    role?: string;
+    excerpt?: string;
+    indexInConversation?: number;
+    messageId?: number;
+    created?: string;
+    updated?: string;
+    dateTime?: string;
+}
+/** One conversation's worth of matches. */
+export interface ConversationSearchResultGroup {
+    conversationId?: number;
+    title?: string;
+    summary?: string;
+    created?: string;
+    updated?: string;
+    dateTime?: string;
+    hits: ConversationSearchResultHit[];
+}
+/**
+ * Payload carried by `::ConversationSearchResults{payload='...'}` — the result of `searchConversations`.
+ *
+ * DATA-COMPLETE: the widget renders ENTIRELY from this payload — it never re-runs the search or fetches anything
+ * (unlike a self-hydrating widget that reads its rows by id). The agent copies the `query` + the grouped `groups` from
+ * the `searchConversations` tool result straight into here.
+ *
+ * `display` lets the agent force inline vs canvas; omitted → the widget auto-picks (few groups inline, many in the
+ * canvas side panel).
+ */
+export interface ConversationSearchResultsPayload {
+    query: string;
+    /** The LLM-written headline for the canvas card (e.g. "Past chats about Facebook"); falls back to the query. */
+    title?: string;
+    display?: "inline" | "canvas";
+    /** The matched conversations, as the search results list takes them. */
+    groups: ConversationSearchResultGroup[];
+}
+export declare const parseConversationSearchResultsPayload: (payload: string | undefined) => ConversationSearchResultsPayload;