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

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

@@ -0,0 +1,3 @@
+/** Presentation scope, independent of hydration and a conversation's interactive/replay state. */
+export declare const ConversationWidgetRenderContext: import("react").Context<"conversation" | "email">;
+export declare const useIsEmailWidgetRender: () => boolean;

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

@@ -0,0 +1,6 @@
+import React from "react";
+export type MarkdownLinkProps = React.AnchorHTMLAttributes<HTMLAnchorElement> & {
+    /** The hast node react-markdown passes to every custom component; not a valid DOM attribute. */
+    node?: unknown;
+};
+export declare const MarkdownLink: ({ node, children, ...anchorProps }: MarkdownLinkProps) => import("react/jsx-runtime").JSX.Element;

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

@@ -0,0 +1,16 @@
+import React from "react";
+export interface WindowedWidgetProps {
+    children: React.ReactNode;
+    /** First-paint guess from the index window: recent messages start mounted, older ones start as a placeholder. */
+    initialRevealed: boolean;
+    /** The freshly-delivered widget — kept mounted (never windowed out) so its one-shot effects don't re-fire. */
+    pinned: boolean;
+}
+/**
+ * Mounts a chat widget only while it is near the viewport (see {@link useWidgetWindow}); far from the viewport it
+ * collapses to a lightweight placeholder. The wrapper element is STABLE across the toggle so the shared
+ * IntersectionObserver keeps tracking it. The placeholder reserves the widget's last measured height, so re-hiding it
+ * causes ZERO layout shift (no scroll jump); revealing again restores the real widget (self-hydrating widgets re-fetch
+ * with a brief skeleton).
+ */
+export declare const WindowedWidget: ({ children, initialRevealed, pinned }: WindowedWidgetProps) => import("react/jsx-runtime").JSX.Element;

package/dist/types/renderer/_access/ConversationWidgetFeatureGate.d.ts

@@ -0,0 +1,21 @@
+import React from "react";
+/** Shared prop contract for any widget upgrade offer (a widget's own `upsellTrigger`); the flag is the app's object. */
+export interface ConversationWidgetUpsellProps {
+    flag: unknown;
+}
+interface ConversationWidgetFeatureGateProps {
+    /** The requirement the widget declares in the registry (an app feature flag, opaque to the package). */
+    featureFlag: string;
+    /** Optional per-widget upgrade offer; falls back to the app gate's own. */
+    UpsellTrigger?: React.ComponentType<ConversationWidgetUpsellProps>;
+    /** The widget's raw agent space key attribute (renders for another agent space). */
+    agentSpaceKeyAttribute?: string | number;
+    children: React.ReactNode;
+}
+/**
+ * Gates a widget on the requirement its registry entry declares, through the app's `WidgetFeatureGate` component (the
+ * environment's): the widget, a placeholder while the requirements load, or an upgrade offer. Without an app gate
+ * every widget renders.
+ */
+export declare const ConversationWidgetFeatureGate: (props: ConversationWidgetFeatureGateProps) => import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/types/renderer/_agent-space/ConversationWidgetAgentSpaceFrame.d.ts

@@ -0,0 +1,12 @@
+import React from "react";
+interface ConversationWidgetAgentSpaceFrameProps {
+    /** The key of another agent space than the active one: the frame shows its header chip. Undefined → no header. */
+    anotherAgentSpaceKey?: number;
+    /** Apply the shared wide layout — the frame becomes the wide bounds the chip anchors to. */
+    wide?: boolean;
+    /** Extra class on the frame — e.g. a widget that needs the frame to fill the drawer height. */
+    className?: string;
+    children: React.ReactNode;
+}
+export declare const ConversationWidgetAgentSpaceFrame: (props: ConversationWidgetAgentSpaceFrameProps) => import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/types/renderer/_agent-space/ConversationWidgetAgentSpaceHeader.d.ts

@@ -0,0 +1,15 @@
+export interface ConversationWidgetAgentSpaceHeaderProps {
+    agentSpaceKey: number;
+    /**
+     * Render the chip in the normal flow instead of floating it over the top-right corner of the enclosing frame — for a
+     * surface whose corner is taken (the open arrow of a canvas handle, a canvas heading). The parent places it.
+     */
+    inFlow?: boolean;
+}
+/**
+ * The chip above a widget whose block names another agent space than the one the owner works in. The name is read
+ * through the widget hydration, so several chips of one agent space share one read and the entry is cleared with the
+ * other widget data when the conversation changes. The app words what kind of thing an agent space is
+ * (`AgentsEnvironment.buildUnnamedAgentSpaceLabel`, `buildWidgetOfAnotherAgentSpaceExplanation`).
+ */
+export declare const ConversationWidgetAgentSpaceHeader: (props: ConversationWidgetAgentSpaceHeaderProps) => import("react/jsx-runtime").JSX.Element;

package/dist/types/renderer/_agent-space/agent-space-name.hydrator.d.ts

@@ -0,0 +1,7 @@
+export declare const AGENT_SPACE_NAME_WIDGET_TYPE = "__agent-space-name";
+export interface AgentSpaceNameHydrationInput {
+    agentSpaceKey: number;
+}
+export interface AgentSpaceNameData {
+    name?: string;
+}

package/dist/types/renderer/_agent-space/declared-agent-space-key-field-name.d.ts

@@ -0,0 +1,8 @@
+/**
+ * A fixture of the package as the app reads it. The package's fixtures name the key of a block's agent space with the
+ * package default field (`agentSpaceId`): as a key of an object, as a field in a block's JSON, as an attribute of a
+ * block's markdown. An app that declares another field name (`AgentsEnvironment.widgetSelfHydrationKeyFieldName`)
+ * reads every occurrence under its own name, so a fixture is mapped once, when it is loaded. Without a declaration
+ * the fixture is returned as it is.
+ */
+export declare const mapFixtureToDeclaredAgentSpaceKeyFieldName: <Fixture>(fixture: Fixture) => Fixture;

package/dist/types/renderer/_agent-space/use-resolved-conversation-widget-agent-space-key.d.ts

@@ -0,0 +1,16 @@
+export interface ResolvedConversationWidgetAgentSpaceKey {
+    /**
+     * The key of the agent space the widget renders for when the agent named ANOTHER one than the active one; undefined
+     * when the block names none or names the active one. A widget takes its chat-only read path for this key.
+     */
+    anotherAgentSpaceKey: number | undefined;
+    /** The key of the agent space the owner works in; undefined when the app has none selected. */
+    activeAgentSpaceKey: number | undefined;
+    isAnotherAgentSpace: boolean;
+}
+/**
+ * Resolves the agent space a widget block names (`readWidgetAgentSpaceKeyAttribute`) against the agent space the owner
+ * works in (`AgentsEnvironment.useActiveAgentSpaceKey`). Returns the key of another agent space only when the agent
+ * explicitly names a different one than the active one; otherwise undefined, so the widget keeps its regular behaviour.
+ */
+export declare const useResolvedConversationWidgetAgentSpaceKey: (agentSpaceKeyAttribute: unknown) => ResolvedConversationWidgetAgentSpaceKey;

package/dist/types/renderer/_agent-space/widget-agent-space-key-attribute.d.ts

@@ -0,0 +1,13 @@
+/** The key of a widget block's agent space as it arrives: a string from a markdown attribute, a number from a block field. */
+export type WidgetAgentSpaceKeyAttribute = string | number | undefined;
+/**
+ * Reads the key of the agent space a widget block names: the value of the block field the app declares
+ * (`AgentsEnvironment.widgetSelfHydrationKeyFieldName`), among a widget's props or a block's fields. Undefined when the
+ * block names none.
+ */
+export declare const readWidgetAgentSpaceKeyAttribute: (propsOrFields: object) => WidgetAgentSpaceKeyAttribute;
+/**
+ * The props that hand a widget the key of its agent space under the block field the app declares, exactly as a
+ * markdown attribute would carry it; no prop without a key.
+ */
+export declare const buildWidgetAgentSpaceKeyProps: (agentSpaceKeyAttribute: WidgetAgentSpaceKeyAttribute) => Record<string, string | number>;

package/dist/types/renderer/balanced-json-object.d.ts

@@ -0,0 +1,12 @@
+/**
+ * The one string-aware brace walk every "how far does this widget JSON payload extend" question in the pipeline
+ * needs — the malformed-fence repairer, the naked-JSON referencer and the unrendered-widget detector all call this
+ * single copy of the scan.
+ */
+/**
+ * The index of the `}` closing the first `{ … }` JSON object that begins (after optional whitespace) at or after
+ * `fromIndex` in `text`, or null when no object starts there or it never balances within `maxScanLength` characters
+ * of its start. Quotes and escapes are tracked so a `{`/`}` inside a JSON string value never affects the brace
+ * depth (e.g. a widget's `title` field containing literal `{braces}` text).
+ */
+export declare const findBalancedJsonObjectEnd: (text: string, fromIndex: number, maxScanLength?: number) => number | null;

package/dist/types/renderer/canvas/CanvasRestoreOnMount.d.ts

@@ -0,0 +1,19 @@
+import type { ChatMessage } from "../../chat/chat-message";
+export interface CanvasRestoreOnMountProps {
+    /** The conversation the host shows. Undefined for a cold chat — nothing to restore. */
+    conversationId?: number;
+    /** The host's loaded messages. A message-anchored restore waits for THIS conversation's page to be in. */
+    messages: ChatMessage[] | null;
+}
+/**
+ * Restores the canvas that was open in this conversation — on a reload, in a new tab, and when the customer comes
+ * back to the conversation (A → B → A alike). Must render INSIDE the provider (it dispatches
+ * through the context) and runs once per conversation, after the mount reset. A PAGE-anchored canvas (an app's
+ * editor opened from a page) needs no message and restores as soon as the conversation id is known. A MESSAGE-anchored
+ * canvas waits for the conversation's own messages and has three limits:
+ *  - the anchor message must be in the loaded page — otherwise the canvas is that far back and irrelevant: the pointer
+ *    is dropped, nothing is paged in;
+ *  - a `turn` canvas whose anchor message is no longer the newest assistant message is not restored — its turn is over;
+ *  - the anchor message must still carry a widget that opens this canvas (a stale or mangled pointer opens nothing).
+ */
+export declare const CanvasRestoreOnMount: ({ conversationId, messages }: CanvasRestoreOnMountProps) => null;

package/dist/types/renderer/canvas/canvas-behaviours.d.ts

@@ -0,0 +1,84 @@
+/**
+ * The CANVAS BEHAVIOURS — one declaration per canvas of how it lives on the surface: how long it stays (`lifetime`),
+ * how it takes the screen (`layout`), what happens on a narrow viewport and whether its body starts flush at the top.
+ *
+ * Keyed on a CANVAS id, not a widget name: one body may have several openers, and one widget can be inline with a
+ * detail canvas. The widget registry lists which canvases a widget may open (`opensCanvases`); the canvas BODIES (React
+ * components) live in `canvasBodies.tsx`, imported only by the shell. The package declares the canvases of its own
+ * widgets here (`packageCanvasBehaviours`); an app declares the canvases of its widgets on its agents environment
+ * (`AgentsEnvironment.furtherCanvasBehaviours`), read at every lookup. This module imports nothing but the environment
+ * module (which has no runtime imports), so the conversation slice and its specs can read it during store
+ * initialisation (the widget registry is downstream of the store; a slice → registry import forms a temporal-dead-zone
+ * cycle).
+ */
+/** The canvases of the package's own widgets. */
+export type PackageCanvasId = "conversationSearchResults" | "webSearchResults" | "entityDetail" | "mapFullScreen";
+/**
+ * The id of a canvas: one of the package's (`PackageCanvasId`) or one an app declares
+ * (`AgentsEnvironment.furtherCanvasBehaviours`). Append-only while a stored pointer (`canvasStorage.ts`) may still name
+ * the id. A string, because the app's ids are not known to the package; `isCanvasId` checks a value against both.
+ */
+export type CanvasId = PackageCanvasId | (string & {});
+/**
+ * `turn`: the canvas belongs to one question — the next SEND closes it for good (the card in the transcript is the
+ * way back). `pinned`: a work surface for the whole conversation — it stays through sends and stays re-openable after
+ * the customer closes it. Lifetime says nothing about a reload: the canvas open at reload time is restored for BOTH.
+ */
+export type CanvasLifetime = "turn" | "pinned";
+/**
+ * `split`: the canvas is the right pane beside the chat. `canvasFillsScreen`: the canvas takes the screen and the chat
+ * becomes the narrow companion (a full work surface such as an editor); the host's compact mode is overridden while it
+ * is open.
+ */
+export type CanvasLayout = "split" | "canvasFillsScreen";
+/**
+ * Below the viable split width (`CANVAS_VIABLE_MIN_WIDTH`): `none` — a live delivery does not take the phone screen
+ * over (the card stays, the customer taps it), and the wide → narrow crossing closes an open canvas; `overlay` — the
+ * canvas is the widget's only surface, so it opens as the full-screen overlay and survives the crossing.
+ */
+export type CanvasNarrowViewport = "none" | "overlay";
+export interface CanvasBehaviour {
+    readonly lifetime: CanvasLifetime;
+    readonly layout: CanvasLayout;
+    /** Width of the canvas pane as a percentage of the split. Only read for `layout: "split"`; default 50. */
+    readonly widthPercent?: number;
+    readonly narrowViewport: CanvasNarrowViewport;
+    /**
+     * The body starts flush at its top edge (a hero image, an iframe) — the pane keeps its gap under the close row, unless
+     * `overlayCloseButton` floats the row over the body.
+     */
+    readonly fullBleed: boolean;
+    /**
+     * The close button floats over the body's top edge instead of reserving a row of its own, and the pane drops its top
+     * and side padding — for a body whose top (a hero image) may sit under the button. The button is then muted
+     * `inverted` + `onDark`, since it sits on the dark image. Default false: the row stays in flow so it never covers
+     * content.
+     */
+    readonly overlayCloseButton?: boolean;
+}
+/** Width of the canvas pane (% of the split) when a behaviour declares none. */
+export declare const DEFAULT_CANVAS_WIDTH_PERCENT = 50;
+/** The narrowest the customer can pull the canvas (px); pulling further and holding folds the tab into "close". */
+export declare const CANVAS_MIN_WIDTH_PX = 420;
+/** What the chat column keeps beside the widest canvas (px). */
+export declare const CHAT_COLUMN_MIN_WIDTH_PX = 360;
+/**
+ * The boxed canvas card's inset from its pane edge (px) — the pull tab sits on the card's edge, not the pane's. The
+ * pane's padding reads it as `--agents-canvas-inset` (`.splitViewPaneBoxed`), so this is the one place it is set.
+ */
+export declare const CANVAS_BOXED_INSET_PX = 8;
+/** Width of the canvas pane for `layout: "canvasFillsScreen"` — the chat keeps a narrow companion column. */
+export declare const CANVAS_FILLS_SCREEN_WIDTH_PERCENT = 72;
+/** The canvases of the package's own widgets. */
+export declare const packageCanvasBehaviours: Readonly<Record<PackageCanvasId, CanvasBehaviour>>;
+/**
+ * The behaviour of a canvas: the package's own, else the one the app declares
+ * (`AgentsEnvironment.furtherCanvasBehaviours`); undefined for an id nobody declared (a stale stored pointer, a typo —
+ * the opening rule ignores it). An app cannot replace a package canvas's behaviour.
+ */
+export declare const canvasBehaviourOf: (canvasId: CanvasId) => CanvasBehaviour | undefined;
+/** Every declared canvas id: the package's own first, then the app's further ones. */
+export declare const getDeclaredCanvasIds: () => readonly CanvasId[];
+/** Type guard for a value read from untrusted input (`sessionStorage`, a URL): is it a declared canvas id? */
+export declare const isCanvasId: (value: unknown) => value is CanvasId;
+export declare const canvasWidthPercentOf: (behaviour: CanvasBehaviour) => number;

package/dist/types/renderer/canvas/canvas-body-props.d.ts

@@ -0,0 +1,18 @@
+import type { CanvasState } from "./canvas-state";
+/**
+ * What every canvas BODY receives from the shell. The body derives everything else itself: a message-anchored body
+ * parses its widget's fence out of the anchor message (the same parser the inline widget uses), a page-anchored body
+ * hydrates from the agent space. Nothing is handed over that the transcript already holds.
+ *
+ * A type-only module: bodies import it without touching `canvasBodies.tsx`, which stays imported by the shell alone.
+ */
+export interface CanvasBodyProps {
+    canvas: CanvasState;
+    /**
+     * The key of the agent space the chat is scoped to (`chatAgentSpaceKey`), for a body whose anchor is a message and
+     * whose fence names no other agent space. A page anchor carries its own agent space.
+     */
+    agentSpaceKey?: number;
+    /** Normalised markdown of the anchor message, for a body that parses its fence out of it. Null for a page anchor. */
+    anchorMessageMarkdown: string | null;
+}

package/dist/types/renderer/canvas/canvas-feature-flags.d.ts

@@ -0,0 +1,11 @@
+import type { CanvasId } from "./canvas-behaviours";
+/**
+ * The requirement (an app feature flag, opaque to the package) a CANVAS requires — the same one its opening widget
+ * declares in the registry. Owned by the canvas (not read off an opener) because a restored or page-opened canvas has
+ * no widget mount to inherit it from; the shell wraps a gated body in `ConversationWidgetFeatureGate`. An app names
+ * the requirements of its canvases with `registerCanvasFeatureFlags`; the package's own canvases are ungated.
+ */
+export declare const canvasFeatureFlags: Partial<Record<CanvasId, string>>;
+/** Adds the requirements of an app's canvases. Runs outside React, before the first render. */
+export declare const registerCanvasFeatureFlags: (featureFlags: Readonly<Partial<Record<CanvasId, string>>>) => void;
+export declare const canvasFeatureFlagOf: (canvasId: CanvasId) => string | undefined;

package/dist/types/renderer/canvas/canvas-reducers.d.ts

@@ -0,0 +1,46 @@
+import { CanvasOpenRequest, CanvasState, LastClosedCanvas } from "./canvas-state";
+import { CanvasOpenDecision } from "./decide-canvas-open";
+/**
+ * The canvas part of a chat slice partition — the two fields every transition reads and writes. Both chat doors carry
+ * them (`ConversationState`); the shell is shared, so the state must have the same shape in both partitions.
+ */
+export interface CanvasSliceState {
+    canvas: CanvasState | null;
+    lastClosedCanvas: LastClosedCanvas | null;
+    /**
+     * How many canvases this partition has mounted so far — the source of `mountGeneration`. Never reset by a close,
+     * a send or a clear (and exempt from `resetState`), so a late asynchronous write from a body that was replaced,
+     * cleared or belonged to the previous conversation can never match a new canvas's generation.
+     */
+    canvasMountCount: number;
+}
+/**
+ * Open a canvas — the ONE way to open, for all four origins. On Accept: the replaced canvas (a different identity)
+ * becomes `lastClosedCanvas`; a `lastClosedCanvas` of the accepted identity is consumed (its veto is cleared — the
+ * customer, the page or the restore decided to have it back); the created entity survives a re-open of the same
+ * identity so a restored editor keeps its draft.
+ */
+export declare const applyOpenCanvas: (state: CanvasSliceState, request: CanvasOpenRequest) => CanvasOpenDecision;
+/**
+ * Close the open canvas but keep it re-openable: it becomes `lastClosedCanvas`. `byCustomer` marks the customer's own
+ * close (the canvas close control) — a live delivery of the same identity is then ignored until a send, a card click
+ * or a page hand-over. A shell-driven close (compact mode, the side panel opening, a narrow crossing) passes false.
+ */
+export declare const applyCloseCanvas: (state: CanvasSliceState, byCustomer: boolean) => void;
+/**
+ * The SEND boundary: a new user message starts a new turn. A `turn` canvas is over for good — it leaves the open slot
+ * AND `lastClosedCanvas` (the card in the transcript is the way back). A `pinned` canvas stays open,
+ * and a closed pinned one stays re-openable with its customer veto cleared (the send is a clearing edge).
+ */
+export declare const applyResetCanvasForNewTurn: (state: CanvasSliceState) => void;
+/** Forget the canvas entirely — a conversation switch, `closeAgent`, the modal unmount. Nothing is re-openable. */
+export declare const applyClearCanvas: (state: CanvasSliceState) => void;
+export interface CanvasCreatedEntity {
+    readonly canvasId: CanvasState["canvasId"];
+    readonly instanceId: string;
+    /** The generation the body was mounted with — a late write from a body that was replaced meanwhile is dropped. */
+    readonly mountGeneration: number;
+    readonly createdEntityId: number;
+}
+/** A body created its entity (the post editor's draft): remember the id on the canvas it was created for. */
+export declare const applySetCanvasCreatedEntityId: (state: CanvasSliceState, created: CanvasCreatedEntity) => boolean;

package/dist/types/renderer/canvas/canvas-state.d.ts

@@ -0,0 +1,107 @@
+import type { CanvasId } from "./canvas-behaviours";
+/**
+ * The canvas STATE — plain, readonly, serialisable data (it lives in the Redux store, where RTK + Immer forbid class
+ * instances). The value-object behaviour — invariants, equality, the transitions — lives in the pure functions of this
+ * module and of `decide-canvas-open.ts` / `canvas-reducers.ts`.
+ *
+ * The canvas is a POINTER to its anchor: the data a canvas body needs already lives in the transcript — the
+ * widget's fence in the anchor message is persisted, loaded and rendered. The shell finds the anchor message in the
+ * loaded list, parses the fence with the widget's own parser and renders the body from the result. Nothing about the
+ * content is stored a second time. A page-opened canvas (an app's editor opened from its page) has no message; its
+ * anchor is the agent space and the body hydrates from it.
+ */
+export type CanvasAnchor = {
+    readonly kind: "message";
+    readonly messageId: number;
+} | {
+    readonly kind: "page";
+    readonly agentSpaceKey: number;
+};
+/**
+ * How a canvas came to be open — the one question the opening rule asks (`decide-canvas-open.ts`):
+ *  - `deliveredInMessage`  a canvas widget in a message delivered live (`justDelivered`); replay never opens one
+ *  - `cardClick`           the customer clicked a card in the transcript, or the canvas toggle button on the divider
+ *  - `openedByPage`        a page handed the tool over (`openAgentWithWidget` / `?agentWidget=`)
+ *  - `restoredAfterReload` the pointer stored for this conversation, on the mount of the conversation
+ * A restored or page-opened canvas never runs a body's creation side effects (a post editor with no created entity
+ * renders its empty state instead of creating a draft).
+ */
+export type CanvasOrigin = "deliveredInMessage" | "cardClick" | "openedByPage" | "restoredAfterReload";
+/** The identity of a canvas: WHICH canvas, and which instance of it. Two canvases with the same identity are one. */
+export interface CanvasIdentity {
+    readonly canvasId: CanvasId;
+    /**
+     * Distinguishes instances of one canvas: lists per message (+ occurrence in the message), a work surface per
+     * agent space, an entity editor or detail per entity. Built with the helpers below.
+     * Never includes the conversation id — a cold chat receives its id after the first send.
+     */
+    readonly instanceId: string;
+}
+export interface CanvasState extends CanvasIdentity {
+    readonly anchor: CanvasAnchor;
+    readonly origin: CanvasOrigin;
+    /**
+     * Bumped on every accepted open (also of the same identity from a card click) so the shell keys the body on it: a
+     * list re-opened with other filters remounts and re-runs its mount effects. Monotonic within the conversation.
+     */
+    readonly mountGeneration: number;
+    /**
+     * The one datum not in a message: the id of the entity a body CREATED after opening (the post editor's draft).
+     * Written back by `setCanvasCreatedEntityId`; a restored editor with no id renders its empty state.
+     */
+    readonly createdEntityId?: number;
+}
+/**
+ * The canvas that was open last and is not open now — what the canvas toggle button on the divider, the narrow-
+ * viewport re-open control and the compact → expand path re-open. `closedByCustomer` is the customer's veto: a live
+ * delivery of the SAME identity is ignored until a send, a card click or a page hand-over clears it.
+ */
+export interface LastClosedCanvas extends CanvasIdentity {
+    readonly anchor: CanvasAnchor;
+    readonly mountGeneration: number;
+    readonly closedByCustomer: boolean;
+    readonly createdEntityId?: number;
+}
+/** What an opener hands to `openCanvas` — everything the opening rule needs to decide, nothing more. */
+export interface CanvasOpenRequest extends CanvasIdentity {
+    readonly anchor: CanvasAnchor;
+    readonly origin: CanvasOrigin;
+    /** The host message was delivered live right now (the widget's `justDelivered`). Irrelevant for other origins. */
+    readonly justDelivered: boolean;
+    /** The viewport is wide enough for the side split (`useCanvasViable`). */
+    readonly viewportViable: boolean;
+    /** The host renders the split at all (`disableSplitView` hosts have no canvas surface). */
+    readonly hostHasCanvasSurface: boolean;
+    /** Carried by a restored pointer so a re-opened editor keeps its created entity. */
+    readonly createdEntityId?: number;
+}
+export declare const sameCanvasIdentity: (a: CanvasIdentity, b: CanvasIdentity) => boolean;
+export declare const sameCanvasAnchor: (a: CanvasAnchor, b: CanvasAnchor) => boolean;
+export declare const messageAnchor: (messageId: number) => CanvasAnchor;
+export declare const pageAnchor: (agentSpaceKey: number) => CanvasAnchor;
+/** A list-like canvas: one instance per message, and per occurrence when a message carries the widget twice. */
+export declare const canvasInstanceIdForMessage: (canvasId: CanvasId, messageId: number, occurrence?: number) => string;
+/** A work surface unique per agent space (an app's editor): a later card for the same agent space never replaces it. */
+export declare const canvasInstanceIdForAgentSpace: (canvasId: CanvasId, agentSpaceKey: number) => string;
+/**
+ * A short, stable, dependency-free hash of a string (djb2, base 36) — identifies a widget's payload inside a message
+ * without storing the payload. Not cryptographic; two payloads colliding would only merge two identical-looking
+ * canvases of one message.
+ */
+export declare const shortStringHash: (value: string) => string;
+/**
+ * A canvas opened by a widget WITH a payload (a list with filters, a search result): one instance per message and
+ * payload, so two different widgets of one kind in one message are two canvases while two identical ones are one.
+ * The body finds its fence again through the hash (`findWidgetFenceByPayloadHash`).
+ */
+export declare const canvasInstanceIdForMessagePayload: (canvasId: CanvasId, messageId: number, payload: string) => string;
+/** The payload hash a message+payload instance id carries, or undefined for another shape of instance id. */
+export declare const payloadHashOfInstanceId: (instanceId: string) => string | undefined;
+/** The same work surface when no agent space key is known at open time (the body resolves the active agent space itself). */
+export declare const canvasInstanceIdForActiveAgentSpace: (canvasId: CanvasId) => string;
+/** An editor / detail unique per entity (post, event, schedule). */
+export declare const canvasInstanceIdForEntity: (canvasId: CanvasId, entityId: number) => string;
+/** The entity id an entity instance id carries, or undefined for another shape of instance id. */
+export declare const entityIdOfInstanceId: (instanceId: string) => number | undefined;
+/** True when the anchor message of a canvas is among the loaded messages (a restored pointer must point somewhere). */
+export declare const isCanvasAnchorLoaded: (anchor: CanvasAnchor, loadedMessageIds: ReadonlyArray<number | undefined | null>) => boolean;

package/dist/types/renderer/canvas/canvasBodies.d.ts

@@ -0,0 +1,19 @@
+import type React from "react";
+import type { CanvasId } from "./canvas-behaviours";
+import type { CanvasBodyProps } from "./canvas-body-props";
+export type { CanvasBodyProps } from "./canvas-body-props";
+export { canvasFeatureFlagOf } from "./canvas-feature-flags";
+/**
+ * THE CANVAS BODIES — canvas id → the React component the shell mounts in the canvas pane. The one module that knows
+ * both the canvas ids and React components, and it is imported ONLY by `CanvasPane` (the shell), never by
+ * the slice, the behaviours or a widget — that is the import layering that keeps the store-init temporal-dead-zone
+ * cycle away. The bodies themselves are small: a body that hosts a heavy page (an app's list page or editor)
+ * lazy-loads that page, exactly as its widget did. Every canvas has a body; nothing
+ * else hands the pane a rendered node.
+ *
+ * The package's own bodies are listed here; an app adds the bodies of its canvases with `registerCanvasBodies` before
+ * the first render. The object is filled in place, so the shell reads every registration.
+ */
+export declare const canvasBodies: Record<CanvasId, React.ComponentType<CanvasBodyProps>>;
+/** Adds an app's canvas bodies (canvas id → body). Runs outside React, before the first render. */
+export declare const registerCanvasBodies: (bodies: Readonly<Partial<Record<CanvasId, React.ComponentType<CanvasBodyProps>>>>) => void;

package/dist/types/renderer/canvas/canvasStorage.d.ts

@@ -0,0 +1,25 @@
+import type { CanvasAnchor, CanvasState } from "./canvas-state";
+/**
+ * Where the open canvas of a conversation is remembered across a reload: `sessionStorage`, per conversation, holding
+ * the POINTER only — which canvas, which anchor, which instance, and the entity a body created. Never
+ * content: the anchor message's fence supplies the body's data on restore. Tab-local by design (the canvas is viewing
+ * state of this tab); a new tab starts with no canvas.
+ *
+ * Written on every change of the open canvas for ANY lifetime, cleared when the canvas closes; on read the pointer is
+ * validated shape by shape — a stale id or a mangled entry reads as "nothing stored". Every accessor is try/catch-
+ * guarded: a private window, blocked site data or a preview context can throw on the accessor itself.
+ */
+export interface StoredCanvasPointer {
+    readonly canvasId: CanvasState["canvasId"];
+    readonly anchor: CanvasAnchor;
+    readonly instanceId: string;
+    readonly createdEntityId?: number;
+}
+/** Validate an untrusted value into a pointer, or null. Exported for the spec and for the shell's restore path. */
+export declare const parseStoredCanvasPointer: (value: unknown) => StoredCanvasPointer | null;
+/** Remember the canvas open in this conversation. No-op without a conversation id (a cold chat has none yet). */
+export declare const storeOpenCanvas: (conversationId: number | undefined, canvas: CanvasState) => void;
+/** The canvas that was open in this conversation, validated, or null (nothing stored, stale, or storage unusable). */
+export declare const readStoredCanvas: (conversationId: number | undefined) => StoredCanvasPointer | null;
+/** Forget the canvas of this conversation — it closed, or its anchor is no longer among the loaded messages. */
+export declare const clearStoredCanvas: (conversationId: number | undefined) => void;

package/dist/types/renderer/canvas/decide-canvas-open.d.ts

@@ -0,0 +1,32 @@
+import type { CanvasBehaviour } from "./canvas-behaviours";
+import { CanvasOpenRequest, CanvasState, LastClosedCanvas } from "./canvas-state";
+/**
+ * Why an open request is ignored. Every reason is a sentence the shell could log:
+ *  - `unknownCanvas`               no behaviour is declared for the id (a stale stored pointer, a typo)
+ *  - `noSurface`                   the host renders no split (`disableSplitView`), so there is nowhere to open
+ *  - `replay`                      a delivery-origin request for a message that was NOT just delivered — history
+ *                                  replay, a reload, scroll-back; rejected BEFORE anything is read or written
+ *  - `alreadyOpen`                 a delivery-origin request for the identity that is already open (the agent re-emits
+ *                                  an editor widget after a rebuild) — the open canvas is kept, never remounted
+ *  - `customerClosedIt`            the customer closed exactly this identity and nothing has cleared the veto yet
+ *  - `noTakeoverOnNarrowViewport`  a live delivery on a narrow viewport of a canvas that declares no overlay — the
+ *                                  card stays, the customer taps it
+ */
+export type CanvasOpenIgnoreReason = "unknownCanvas" | "noSurface" | "replay" | "alreadyOpen" | "customerClosedIt" | "noTakeoverOnNarrowViewport";
+export type CanvasOpenDecision = {
+    readonly kind: "accept";
+} | {
+    readonly kind: "ignore";
+    readonly reason: CanvasOpenIgnoreReason;
+};
+/**
+ * THE opening rule — the one place that answers "may this canvas open now?". Pure: it reads the behaviour, the open
+ * canvas, the last closed one and the request, and returns Accept or Ignore. It never mutates; the reducer
+ * (`canvas-reducers.ts`) applies an Accept. There is no merge rung: the same identity opened again from a card click
+ * is a fresh Accept (remount), and the refresh contract of a pinned work surface is a value the body derives from the
+ * message list, not a reducer merge.
+ *
+ * A `cardClick`, an `openedByPage` and a `restoredAfterReload` request always open (the customer, the page or the
+ * stored pointer decided); only `deliveredInMessage` is judged.
+ */
+export declare const decideCanvasOpen: (behaviour: CanvasBehaviour | undefined, openCanvas: CanvasState | null, lastClosedCanvas: LastClosedCanvas | null, request: CanvasOpenRequest) => CanvasOpenDecision;

package/dist/types/renderer/canvas/entity-detail-instance.d.ts

@@ -0,0 +1,27 @@
+export interface EntityDetailTarget {
+    entityType: string;
+    entityId: string;
+}
+export declare const canvasInstanceIdForEntityDetail: (target: EntityDetailTarget) => string;
+/** The entity an `entityDetail` instance id names, or undefined for another instance id. */
+export declare const readEntityDetailInstanceId: (instanceId: string) => EntityDetailTarget | undefined;
+/** The `refState` the backend writes on an `openEntity` action whose `ref` is bound to the current row. */
+export declare const OPEN_ENTITY_REF_STATE_FROM_ROW = "row";
+/**
+ * Whether an `openEntity` action opens the entity of the row it fires in — its `ref` is a `{"$item": "<key>"}`
+ * binding (`{"$item":"entityRef"}` inside a `Repeat`, a `Map` point, a list row), or the backend marked it
+ * `refState: "row"` (`ComposedViewBindingResolution::STATE_FROM_ROW`). Such an action carries no entity of its own.
+ */
+export declare const isRowBoundOpenEntityAction: (action: Record<string, unknown>) => boolean;
+/**
+ * The entity an `openEntity` action opens, or undefined (the action then does nothing):
+ * - an action with a platform-minted reference — `{"type":"openEntity", "ref":"<toolCallId>:<entityType>:<index>",
+ *   "entity":{"entityType","entityId",<agent space key field>}}` — opens the `entity` the backend resolved it to; undefined while
+ *   the reference is unresolved;
+ * - a row-bound action ({@link isRowBoundOpenEntityAction}) opens the `entity` of `currentRow`, the row of the item
+ *   scope the event fires in (each row of a resolved `$from` list carries its own `entityRef` + `entity`) — NEVER an
+ *   `entity` written on the action; undefined without a row or for a row without an entity.
+ */
+export declare const readOpenEntityActionTarget: (action: Record<string, unknown>, currentRow?: unknown) => (EntityDetailTarget & {
+    agentSpaceKey?: number;
+}) | undefined;

package/dist/types/renderer/canvas/find-widget-fences-in-markdown.d.ts

@@ -0,0 +1,32 @@
+/** One widget the anchor message carries — what a canvas body parses its own payload from. */
+export interface WidgetFenceInMessage {
+    /** The CANONICAL wire name (a stored legacy `<Name>Directive` resolves onto it). */
+    readonly name: string;
+    /** The fence's non-`type` fields as the JSON string every widget parser takes (`payload`). */
+    readonly payload: string;
+    /** The agent space key the framework lifts out of the fence (the block field the app declares), when present. */
+    readonly agentSpaceKey?: string;
+    /** `shortStringHash(payload)` — what `canvasInstanceIdForMessagePayload` puts into the instance id. */
+    readonly payloadHash: string;
+    /** Every string attribute of the node (`target`, `mode`, … — widgets that do not use `payload`). */
+    readonly attributes: Readonly<Record<string, string>>;
+}
+/**
+ * Every widget in a message's markdown, in document order, through the SAME pipeline the message renders with
+ * (`remarkDirective` for the stored `::Name{payload='…'}` form, `remarkWidgetFencePlugin` for the ```widget fence and
+ * the bare `widget { … }` line) — so a canvas body re-reads exactly the payload its inline widget rendered from, in
+ * both the canonical and the legacy wire form. Malformed or unknown widgets are dropped, as when rendering.
+ *
+ * A `ComposedView` block is followed by the domain widgets its tree embeds (`Widget` nodes), each as if
+ * its own fence stood there — `payload` = the node's `fields` — so a canvas opened from a widget in a slot finds its
+ * payload like any other canvas body, and the reload restore finds the widget that opens the canvas.
+ *
+ * Shell-side only (the pipeline imports the widget registry through the name resolver): imported by canvas bodies,
+ * never by the slice or the canvas model modules.
+ */
+export declare const findWidgetFencesInMarkdown: (markdown: string) => WidgetFenceInMessage[];
+/**
+ * The fence a canvas is anchored on: the widget of `name` whose payload hash the canvas instance id carries
+ * (`canvasInstanceIdForMessagePayload`). Two identical widgets in one message share one canvas by design.
+ */
+export declare const findWidgetFenceByPayloadHash: (markdown: string, name: string, payloadHash: string) => WidgetFenceInMessage | undefined;

package/dist/types/renderer/canvas/use-anchor-widget-payload.d.ts

@@ -0,0 +1,8 @@
+import type { CanvasState } from "./canvas-state";
+/**
+ * The payload string of the widget a message-anchored canvas was opened from: the fence of `widgetName` in the anchor
+ * message whose payload hash the canvas instance id carries (`canvasInstanceIdForMessagePayload`); when the instance
+ * id carries no hash (one canvas per message), the first fence of that name. Undefined for a page anchor, a missing
+ * anchor message, or a message that no longer carries the fence — the body then renders nothing.
+ */
+export declare const useAnchorWidgetPayload: (canvas: CanvasState, anchorMessageMarkdown: string | null, widgetName: string) => string | undefined;

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

@@ -0,0 +1,30 @@
+import { ConversationComposerWidget } from "./conversation-composer-widget";
+/**
+ * The FE twin of the backend's `AIConversationMessage::buildWidgetFenceBlock` — assembles / disassembles the
+ * ```widget fence(s) a composer widget becomes inside the message TEXT (the record; no DB column, no DTO change). `buildComposerWidgetFenceBlock` / `buildMessageTextWithComposerWidgets` run on SEND;
+ * `splitComposerWidgetFencesFromMessageText` runs on the USER BUBBLE to pull the fence back out as a
+ * read-only widget above the prose.
+ */
+/** One ```widget fence block for a composer widget — `type` first, then its own fields, one line of JSON. */
+export declare const buildComposerWidgetFenceBlock: (widget: ConversationComposerWidget) => string;
+/**
+ * The message text a send assembles: the typed text first, then one fence block per composer widget in composer
+ * order, a blank line between blocks. Empty text + at least one widget is allowed (a fence-only send) — the result
+ * is non-empty as long as EITHER side has content; both empty yields `""`, the send guard's cue to no-op.
+ */
+export declare const buildMessageTextWithComposerWidgets: (text: string, widgets: ConversationComposerWidget[]) => string;
+export interface SplitComposerWidgetFencesResult {
+    /** The message text with every extracted fence removed, trimmed. */
+    text: string;
+    /** The extracted composer widgets, in the order they appeared. */
+    widgets: ConversationComposerWidget[];
+}
+/**
+ * The inverse of {@link buildMessageTextWithComposerWidgets}. Extracts every ```widget fence in `text` whose `type`
+ * resolves (canonical or legacy `Directive` form, see `widget-name-resolver.ts`) to a registered widget that
+ * declares a `composerComponent` — the only fences a user bubble renders as a read-only widget instead of leaving as
+ * text. Every other fence — prose, and fences for widgets WITHOUT a `composerComponent` — is left in `text`
+ * verbatim. Never throws: an unterminated fence, malformed JSON, or an unresolved/non-composable `type` just leaves
+ * that fence untouched.
+ */
+export declare const splitComposerWidgetFencesFromMessageText: (text: string) => SplitComposerWidgetFencesResult;