@opencx/widget-core 4.0.60 → 5.0.0-beta.0

package/dist/src/context/contact.ctx.d.ts

@@ -25,6 +25,15 @@ export declare class ContactCtx {
     shouldCollectData: () => boolean;
     private autoCreateUnverifiedUserIfNotExists;
     createUnverifiedContact: (payload: Dto["CreateUnverifiedContactDto"], extraCollectedData?: Record<string, string>) => Promise<void>;
+    /**
+     * A persisted contact token can go stale — it no longer resolves to a
+     * contact and the backend answers 401 "Invalid token". Drop the dead token,
+     * clear auth, and mint a fresh anonymous contact so the widget self-heals
+     * instead of getting stuck on create-session. No-op for a config-provided
+     * verified token (authoritative — re-minting it is not ours to do).
+     * Returns true if a fresh contact token was obtained.
+     */
+    recoverFromStaleToken: () => Promise<boolean>;
     setUnverifiedContact: (token: string) => Promise<void>;
 }
 export {};

package/dist/src/context/contact.ctx.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"contact.ctx.d.ts","sourceRoot":"","sources":["../../../src/context/contact.ctx.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AACzD,OAAO,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAC9C,OAAO,EAAE,KAAK,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAC3D,OAAO,EAAE,KAAK,GAAG,EAAE,MAAM,eAAe,CAAC;AACzC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAGhD,KAAK,YAAY,GAAG;IAClB,OAAO,EAAE;QACP,KAAK,EAAE,MAAM,CAAC;QACd,UAAU,EAAE,MAAM,GAAG,SAAS,CAAC;KAChC,GAAG,IAAI,CAAC;IACT,kBAAkB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,CAAC;IACvD,2BAA2B,EAAE,OAAO,CAAC;IACrC,gCAAgC,EAAE,OAAO,CAAC;CAC3C,CAAC;AAEF,qBAAa,UAAU;IACrB,OAAO,CAAC,MAAM,CAAe;IAC7B,OAAO,CAAC,UAAU,CAAC,CAAa;IAChC,OAAO,CAAC,GAAG,CAAY;IACvB,KAAK,EAAE,cAAc,CAAC,YAAY,CAAC,CAAC;gBAExB,EACV,MAAM,EACN,GAAG,EACH,UAAU,GACX,EAAE;QACD,GAAG,EAAE,SAAS,CAAC;QACf,MAAM,EAAE,YAAY,CAAC;QACrB,UAAU,CAAC,EAAE,UAAU,CAAC;KACzB;IAqBD,iBAAiB,QAAO,OAAO,CAK7B;IAEF,OAAO,CAAC,mCAAmC,CAqDzC;IAEF,uBAAuB,GACrB,SAAS,GAAG,CAAC,4BAA4B,CAAC,EAC1C,qBAAqB,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,KAC1C,OAAO,CAAC,IAAI,CAAC,CAkBd;IAEF,oBAAoB,GAAU,OAAO,MAAM,mBAUzC;CACH"}
+{"version":3,"file":"contact.ctx.d.ts","sourceRoot":"","sources":["../../../src/context/contact.ctx.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AACzD,OAAO,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAC9C,OAAO,EAAE,KAAK,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAC3D,OAAO,EAAE,KAAK,GAAG,EAAE,MAAM,eAAe,CAAC;AACzC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAIhD,KAAK,YAAY,GAAG;IAClB,OAAO,EAAE;QACP,KAAK,EAAE,MAAM,CAAC;QACd,UAAU,EAAE,MAAM,GAAG,SAAS,CAAC;KAChC,GAAG,IAAI,CAAC;IACT,kBAAkB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,CAAC;IACvD,2BAA2B,EAAE,OAAO,CAAC;IACrC,gCAAgC,EAAE,OAAO,CAAC;CAC3C,CAAC;AAEF,qBAAa,UAAU;IACrB,OAAO,CAAC,MAAM,CAAe;IAC7B,OAAO,CAAC,UAAU,CAAC,CAAa;IAChC,OAAO,CAAC,GAAG,CAAY;IACvB,KAAK,EAAE,cAAc,CAAC,YAAY,CAAC,CAAC;gBAExB,EACV,MAAM,EACN,GAAG,EACH,UAAU,GACX,EAAE;QACD,GAAG,EAAE,SAAS,CAAC;QACf,MAAM,EAAE,YAAY,CAAC;QACrB,UAAU,CAAC,EAAE,UAAU,CAAC;KACzB;IAqBD,iBAAiB,QAAO,OAAO,CAK7B;IAEF,OAAO,CAAC,mCAAmC,CAqDzC;IAEF,uBAAuB,GACrB,SAAS,GAAG,CAAC,4BAA4B,CAAC,EAC1C,qBAAqB,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,KAC1C,OAAO,CAAC,IAAI,CAAC,CA6Bd;IAEF;;;;;;;OAOG;IACH,qBAAqB,QAAa,OAAO,CAAC,OAAO,CAAC,CAyBhD;IAEF,oBAAoB,GAAU,OAAO,MAAM,mBAUzC;CACH"}

package/dist/src/context/csat.ctx.d.ts

@@ -1,15 +1,12 @@
 import { ApiCaller } from '../api/api-caller';
 import { Dto } from '../api/client';
-import { WidgetConfig } from '../types/widget-config';
 import { MessageCtx } from './message.ctx';
 import { SessionCtx } from './session.ctx';
 export declare class CsatCtx {
-    private config;
     private api;
     private sessionCtx;
     private messageCtx;
-    constructor({ config, api, sessionCtx, messageCtx, }: {
-        config: WidgetConfig;
+    constructor({ api, sessionCtx, messageCtx, }: {
         api: ApiCaller;
         sessionCtx: SessionCtx;
         messageCtx: MessageCtx;
@@ -20,7 +17,7 @@ export declare class CsatCtx {
     } | {
         data: {
             success: boolean;
-            reason?: "rescore_locked";
+            reason?: "rescore_locked" | "request_cancelled";
         } | undefined;
         error: {
             statusCode?: number;

package/dist/src/context/csat.ctx.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"csat.ctx.d.ts","sourceRoot":"","sources":["../../../src/context/csat.ctx.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AACnD,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,eAAe,CAAC;AAEzC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAE3D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAEhD,qBAAa,OAAO;IAClB,OAAO,CAAC,MAAM,CAAe;IAC7B,OAAO,CAAC,GAAG,CAAY;IACvB,OAAO,CAAC,UAAU,CAAa;IAC/B,OAAO,CAAC,UAAU,CAAa;gBAEnB,EACV,MAAM,EACN,GAAG,EACH,UAAU,EACV,UAAU,GACX,EAAE;QACD,MAAM,EAAE,YAAY,CAAC;QACrB,GAAG,EAAE,SAAS,CAAC;QACf,UAAU,EAAE,UAAU,CAAC;QACvB,UAAU,EAAE,UAAU,CAAC;KACxB;IAOD,UAAU,GACR,MAAM,IAAI,CAAC,GAAG,CAAC,0BAA0B,CAAC,EAAE,OAAO,GAAG,UAAU,CAAC;;;;;;;;;;;;;OAgCjE;CACH"}
+{"version":3,"file":"csat.ctx.d.ts","sourceRoot":"","sources":["../../../src/context/csat.ctx.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AACnD,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,eAAe,CAAC;AAEzC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAEhD,qBAAa,OAAO;IAClB,OAAO,CAAC,GAAG,CAAY;IACvB,OAAO,CAAC,UAAU,CAAa;IAC/B,OAAO,CAAC,UAAU,CAAa;gBAEnB,EACV,GAAG,EACH,UAAU,EACV,UAAU,GACX,EAAE;QACD,GAAG,EAAE,SAAS,CAAC;QACf,UAAU,EAAE,UAAU,CAAC;QACvB,UAAU,EAAE,UAAU,CAAC;KACxB;IAMD,UAAU,GACR,MAAM,IAAI,CAAC,GAAG,CAAC,0BAA0B,CAAC,EAAE,OAAO,GAAG,UAAU,CAAC;;;;;;;;;;;;;OAgCjE;CACH"}

package/dist/src/context/dictation.ctx.d.ts

@@ -0,0 +1,67 @@
+import { ApiCaller } from '../api/api-caller';
+import { DictationErrorCode } from '../dictation/dictation-session';
+import { WidgetConfig } from '../types/widget-config';
+import { PrimitiveState } from '../utils/PrimitiveState';
+export type DictationStatus = 'idle' | 'connecting' | 'listening';
+export type DictationCtxState = {
+    status: DictationStatus;
+    /** Last failure, cleared on the next start. */
+    error: DictationErrorCode | null;
+};
+/**
+ * Where dictated text lands. The widget composer is a plain textarea whose
+ * value is React state, so the target is just "what is there now" and "set
+ * it". Text is appended after whatever the visitor already typed; a manual
+ * edit inside the dictated region ends the session (their edit wins).
+ */
+export interface DictationTarget {
+    getValue: () => string;
+    setValue: (value: string) => void;
+    /** Fired for the spoken "send message" command, after the text is final. */
+    onSend?: (() => void) | undefined;
+}
+/**
+ * Voice dictation for the composer: mic → realtime transcription → the
+ * textarea, with the spoken-command grammar ("new line",
+ * "scratch that", "send it") and paced word reveal. One session per widget;
+ * `start` on a live session restarts it against the new target.
+ */
+export declare class DictationCtx {
+    state: PrimitiveState<DictationCtxState>;
+    /** 0..1 mic level — read inside a rAF loop, never during render. */
+    readonly levelRef: {
+        current: number;
+    };
+    private readonly api;
+    private readonly config;
+    private readonly mintCache;
+    private session;
+    private target;
+    private language;
+    /** Composer content when dictation started — dictated text follows it. */
+    private prefix;
+    private raw;
+    private processed;
+    private displayed;
+    private dripTimer;
+    private silenceTimer;
+    constructor({ api, config }: {
+        api: ApiCaller;
+        config: WidgetConfig;
+    });
+    isActive: () => boolean;
+    /** Fire-and-forget token pre-mint (mic hover) so the click starts instantly. */
+    prewarm: () => void;
+    start: (target: DictationTarget) => void;
+    stop: () => void;
+    private mintToken;
+    /** Applied text = prefix + dictated. A mismatch means the visitor edited. */
+    private isConsistent;
+    private applyDisplayed;
+    /** Process the transcript and apply the outcome. Shared by the delta path,
+     * the silence timer, and (with `final`) teardown. Returns the control. */
+    private ingest;
+    private stopSilenceTimer;
+    private teardown;
+}
+//# sourceMappingURL=dictation.ctx.d.ts.map

package/dist/src/context/dictation.ctx.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dictation.ctx.d.ts","sourceRoot":"","sources":["../../../src/context/dictation.ctx.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAOnD,OAAO,EAEL,KAAK,kBAAkB,EAGxB,MAAM,gCAAgC,CAAC;AACxC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAC3D,OAAO,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AAGzD,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,YAAY,GAAG,WAAW,CAAC;AAElE,MAAM,MAAM,iBAAiB,GAAG;IAC9B,MAAM,EAAE,eAAe,CAAC;IACxB,+CAA+C;IAC/C,KAAK,EAAE,kBAAkB,GAAG,IAAI,CAAC;CAClC,CAAC;AAEF;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,MAAM,MAAM,CAAC;IACvB,QAAQ,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IAClC,4EAA4E;IAC5E,MAAM,CAAC,EAAE,CAAC,MAAM,IAAI,CAAC,GAAG,SAAS,CAAC;CACnC;AAQD;;;;;GAKG;AACH,qBAAa,YAAY;IAChB,KAAK,oCAA+C;IAC3D,oEAAoE;IACpE,SAAgB,QAAQ;;MAAkB;IAE1C,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAY;IAChC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAe;IACtC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA4B;IAEtD,OAAO,CAAC,OAAO,CAAiC;IAChD,OAAO,CAAC,MAAM,CAAgC;IAC9C,OAAO,CAAC,QAAQ,CAAqB;IACrC,0EAA0E;IAC1E,OAAO,CAAC,MAAM,CAAM;IACpB,OAAO,CAAC,GAAG,CAAM;IACjB,OAAO,CAAC,SAAS,CAAM;IACvB,OAAO,CAAC,SAAS,CAAM;IACvB,OAAO,CAAC,SAAS,CAA+C;IAChE,OAAO,CAAC,YAAY,CAA8C;gBAEtD,EAAE,GAAG,EAAE,MAAM,EAAE,EAAE;QAAE,GAAG,EAAE,SAAS,CAAC;QAAC,MAAM,EAAE,YAAY,CAAA;KAAE;IAKrE,QAAQ,QAAO,OAAO,CAA0B;IAEhD,gFAAgF;IAChF,OAAO,aAOL;IAEF,KAAK,GAAI,QAAQ,eAAe,UA2F9B;IAEF,IAAI,aAEF;IAEF,OAAO,CAAC,SAAS,CAGb;IAEJ,6EAA6E;IAC7E,OAAO,CAAC,YAAY;IAKpB,OAAO,CAAC,cAAc;IAMtB;8EAC0E;IAC1E,OAAO,CAAC,MAAM;IAcd,OAAO,CAAC,gBAAgB;IAKxB,OAAO,CAAC,QAAQ;CAmCjB"}

package/dist/src/context/message.ctx.d.ts

@@ -1,10 +1,101 @@
 import { ApiCaller } from '../api/api-caller';
-import { WidgetConfig } from '../types/widget-config';
-import { WidgetMessageU } from '../types/messages';
+import { WidgetConfig, WidgetMention } from '../types/widget-config';
+import { WidgetAiMessage, WidgetMessageU, WidgetUserMessage } from '../types/messages';
 import { SendMessageDto } from '../types/dtos';
 import { PrimitiveState } from '../utils/PrimitiveState';
 import { SessionCtx } from './session.ctx';
 import { ContactCtx } from './contact.ctx';
+/** The shape a caller passes to `sendMessage` (and `stageUserTurn`). */
+export type SendMessageInput = {
+    content: SendMessageDto['content'];
+    attachments?: SendMessageDto['attachments'];
+    customData?: SendMessageDto['custom_data'];
+    /**
+     * Per-message AI-visible context (e.g. the composer's picked page elements),
+     * merged over the config-level `context` on the wire.
+     */
+    clientContext?: Record<string, unknown>;
+    /**
+     * What the visitor @-mentioned (host items picked from `config.mentions`).
+     * Sent as `clientContext.mentions`.
+     */
+    mentions?: WidgetMention[];
+    /**
+     * False when the visitor dismissed the page's entity pill for this message:
+     * the send goes out without `context.entity`, everything else intact.
+     * @default true
+     */
+    withPageEntity?: boolean;
+    exitModePrompt?: string;
+    /**
+     * Signals that the send has passed validation, has a session, and is owned
+     * by a send engine. This lets composers clear immediately without changing
+     * the existing blocking `sendMessage` promise (which still waits for a bot
+     * reply). It is lifecycle-only and is never sent over the wire.
+     *
+     * @internal
+     */
+    onAccepted?: () => void;
+};
+/** What `stageUserTurn` hands the engine that finishes the send. */
+export type StagedUserTurn = {
+    sessionId: string;
+    userMessage: WidgetUserMessage;
+    /** Persistent greetings riding a fresh conversation's first turn. */
+    initialMessages: WidgetAiMessage[];
+};
+/**
+ * The seam the headless agent-chat provider registers so the shared
+ * `sendMessage` entry point routes to its `useChat` streaming engine. Core
+ * stays framework-neutral and owns only the blocking bot-chat path plus the
+ * shared persisted message list.
+ */
+export type AgentChatHandlers = {
+    send: (input: SendMessageInput) => Promise<void> | void;
+};
+/**
+ * The per-message wire context shared by both send engines: the host's
+ * config-level `context` (resolved fresh when it is a function) with the
+ * widget's own per-send page context merged over it.
+ *
+ * `sendsPageContext` is `WidgetCtx.features.pageContext` — the org's
+ * page-context feature narrowed by the embed. Off → the widget adds nothing
+ * of its own (no page marks, no picked elements) but the host's `context`
+ * still rides along exactly as it did in v4; `custom_data` is unaffected.
+ */
+export declare const mergeSendContext: (config: WidgetConfig, input: SendMessageInput, { sendsPageContext }: {
+    sendsPageContext: boolean;
+}) => {
+    clientContext: Record<string, unknown> | undefined;
+    custom_data: Record<string, unknown>;
+};
+export declare const resolveConfigContext: (config: WidgetConfig) => Record<string, unknown> | undefined;
+/** Wire shape of the per-embed feature toggles (`config.features`). */
+type SendFeaturesBody = NonNullable<SendMessageDto['features']>;
+/**
+ * `config.features` (camelCase) → the snake_cased `features` field both send
+ * engines carry. Undefined when the embedder set nothing, so the body stays
+ * byte-identical to before for embeds that never touch the option.
+ */
+export declare const resolveSendFeatures: (config: WidgetConfig) => SendFeaturesBody | undefined;
+/**
+ * Everything one send carries on the wire — the SAME body for the blocking
+ * send and the streaming turn (both endpoints take `WidgetSendMessageInputDto`).
+ * Config is read at call time so function-form `context` and a refreshed
+ * embedder config are reflected on every request.
+ */
+export declare const buildSendMessageBody: ({ config, input, uuid, sessionId, content, initialMessages, sendsPageContext, }: {
+    config: WidgetConfig;
+    input: SendMessageInput;
+    /** The user message's wire id (a retry sends a fresh one). */
+    uuid: string;
+    sessionId: string;
+    /** The rendered user message text (extra collected data already prepended). */
+    content: string;
+    /** Persistent greetings riding a fresh conversation's first turn. */
+    initialMessages: readonly WidgetAiMessage[];
+    sendsPageContext: boolean;
+}) => SendMessageDto;
 type MessageCtxState = {
     messages: WidgetMessageU[];
     /** Regardless of assignee */
@@ -19,15 +110,62 @@ export declare class MessageCtx {
     private contactCtx;
     private sessionCtx;
     state: PrimitiveState<MessageCtxState>;
+    /**
+     * The org's web channel runs the streaming engine — turns stream over the
+     * AI SDK `useChat` surface instead of the blocking send. Decided by the
+     * server at init and constant for the widget's whole lifetime.
+     */
+    readonly streaming: boolean;
+    /**
+     * `WidgetCtx.features.pageContext`: whether the widget's own page context
+     * (page marks, picked elements) rides along with each message. Off → the
+     * user bubble shows no page-mark chips either.
+     */
+    readonly sendsPageContext: boolean;
+    /** Registered by the headless agent engine for the WidgetProvider lifetime. */
+    private agentHandlers;
+    /** Sends issued before the agent-chat surface mounts, oldest first. */
+    private bufferedAgentSends;
     private sendMessageAbortController;
     private messageIdsDispatchedToOnMessageReceivedHook;
-    constructor({ config, api, sessionCtx, contactCtx, }: {
+    /**
+     * Text of messages sent in THIS conversation, oldest first, for the
+     * composer's ↑/↓ recall. Lives here rather than in the composer because the
+     * quick-ask bar and the full chat composer are different mounts of the same
+     * component and recall must survive the morph between them — while staying
+     * scoped to one widget instance and one conversation (`reset` clears it, so
+     * a new chat never recalls the previous visitor's or session's text).
+     * Deliberately NOT part of `state`: nothing renders it, so it must not
+     * re-render the transcript on every send.
+     */
+    private sentTextHistory;
+    private static readonly SENT_TEXT_HISTORY_MAX;
+    constructor({ config, api, sessionCtx, contactCtx, streaming, sendsPageContext, }: {
         config: WidgetConfig;
         api: ApiCaller;
         sessionCtx: SessionCtx;
         contactCtx: ContactCtx;
+        streaming: boolean;
+        sendsPageContext: boolean;
     });
     reset: () => void;
+    /**
+     * Record sent text for ↑/↓ recall. Consecutive duplicates collapse — the
+     * common case is re-sending the same line after a failure.
+     */
+    rememberSentText: (text: string) => void;
+    /** Sent text for this conversation, oldest first. */
+    getSentTextHistory: () => readonly string[];
+    /**
+     * Wiring for the headless agent engine: WidgetProvider registers its useChat
+     * `send` here and clears it on unmount, so every streaming headless or
+     * styled consumer shares the same lifecycle. Imperative sends can arrive in
+     * the render gap before registration; drain those in FIFO order once ready.
+     */
+    registerAgentHandlers: (handlers: AgentChatHandlers) => void;
+    /** Hand a send to the streaming engine; its failure can never propagate. */
+    private static dispatchToEngine;
+    unregisterAgentHandlers: (handlers: AgentChatHandlers) => void;
     /**
      * Fires `config.hooks.onMessageReceived` for AI or human-agent messages exactly
      * once per id. Safe to call from any path that ingests messages from the server
@@ -41,12 +179,74 @@ export declare class MessageCtx {
      * receiving new messages. Subsequent polls still dedupe against these ids.
      */
     markAsDispatchedToOnMessageReceivedHook: (messageIds: string[]) => void;
-    sendMessage: (input: {
-        content: SendMessageDto["content"];
-        attachments?: SendMessageDto["attachments"];
-        customData?: SendMessageDto["custom_data"];
-        exitModePrompt?: string;
-    }) => Promise<void>;
+    /**
+     * On the very first turn of a fresh conversation, the configured persistent
+     * initial messages are inserted into the transcript above the user's first
+     * message (and posted to the backend so they persist in history). Any later
+     * turn returns an empty array.
+     */
+    private buildPersistentInitialMessages;
+    /**
+     * Create the session on the conversation's first send; refreshes the
+     * sessions list so the new session shows up immediately. Returns `null`
+     * when creation fails.
+     */
+    private ensureSessionId;
+    /** Remove only this failed attempt's optimistic rows, preserving poll merges. */
+    private rollbackOptimisticMessages;
+    /**
+     * Fire the caller's `onAccepted` once a send is validated, has a session,
+     * and is owned by an engine. A consumer callback must never be able to
+     * break an accepted send.
+     */
+    notifySendAccepted: (input: SendMessageInput) => void;
+    /**
+     * The front half every send shares, whichever engine finishes it: validate,
+     * build the user message (plus the persistent greetings on a fresh
+     * conversation's first turn), render it optimistically, and make sure a
+     * session exists — rolling the optimistic rows back if it cannot. Returns
+     * `null` when there is nothing to send or no session could be created.
+     */
+    stageUserTurn: (input: SendMessageInput, { pending }: {
+        pending: boolean;
+    }) => Promise<StagedUserTurn | null>;
+    /**
+     * Build the user message for a QUEUED (multi-send) turn WITHOUT rendering
+     * it into the transcript. A queued message must not appear above the still-
+     * streaming response of the active turn — the surface renders it below the
+     * live overlay (dimmed via `pending`) and only `appendUserMessageIfAbsent`s
+     * it into `messages` when its own turn actually starts (see `useAgentChat`).
+     * A session already exists here (a turn is in flight), so this never creates
+     * one.
+     */
+    buildQueuedUserMessage: (input: SendMessageInput) => {
+        sessionId: string;
+        userMessage: WidgetUserMessage;
+    } | null;
+    /** Validate the input and build its user message; `null` when empty. */
+    private buildUserMessage;
+    /**
+     * Defensive read of `clientContext.page_marks` → the user bubble's context
+     * chips: each mark contributes the element it was placed on, the note the
+     * visitor wrote, and a reference back to the mark itself (the UI renders
+     * the same presentation the composer showed, thumbnail included). Entries
+     * without a usable name are dropped.
+     */
+    private static markedElementNames;
+    /** Append a user message to the transcript once, ignoring a duplicate id. */
+    appendUserMessageIfAbsent: (userMessage: WidgetUserMessage) => void;
+    /**
+     * Clear the `pending` flag for the user message owned by one streamed turn.
+     * Later queued bubbles must remain pending until their own turn reaches the
+     * server.
+     */
+    markUserMessageDelivered: (messageId: string) => void;
+    /**
+     * The blocking engine refuses a send while the AI reply is pending unless
+     * the embed opted out. The streaming engine never blocks (it queues).
+     */
+    get blocksSendWhileAwaitingReply(): boolean;
+    sendMessage: (input: SendMessageInput) => Promise<void>;
     private toUserMessage;
     private toBotMessage;
     private toBotErrorMessage;

package/dist/src/context/message.ctx.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"message.ctx.d.ts","sourceRoot":"","sources":["../../../src/context/message.ctx.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAC9C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAC3D,OAAO,EAEL,KAAK,cAAc,EAEpB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EAEV,cAAc,EAEf,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AAEzD,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAC3C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAEhD,KAAK,eAAe,GAAG;IACrB,QAAQ,EAAE,cAAc,EAAE,CAAC;IAC3B,6BAA6B;IAC7B,gBAAgB,EAAE,OAAO,CAAC;IAC1B,oBAAoB,EAAE,OAAO,CAAC;IAC9B,4BAA4B,EAAE,OAAO,CAAC;IACtC,qBAAqB,EAAE,OAAO,CAAC;CAChC,CAAC;AAEF,qBAAa,UAAU;IACrB,OAAO,CAAC,MAAM,CAAe;IAC7B,OAAO,CAAC,GAAG,CAAY;IACvB,OAAO,CAAC,UAAU,CAAa;IAC/B,OAAO,CAAC,UAAU,CAAa;IAExB,KAAK,kCAMT;IAEH,OAAO,CAAC,0BAA0B,CAAyB;IAE3D,OAAO,CAAC,2CAA2C,CAAqB;gBAE5D,EACV,MAAM,EACN,GAAG,EACH,UAAU,EACV,UAAU,GACX,EAAE;QACD,MAAM,EAAE,YAAY,CAAC;QACrB,GAAG,EAAE,SAAS,CAAC;QACf,UAAU,EAAE,UAAU,CAAC;QACvB,UAAU,EAAE,UAAU,CAAC;KACxB;IAOD,KAAK,aAIH;IAEF;;;;OAIG;IACH,+BAA+B,GAAI,SAAS,cAAc,KAAG,IAAI,CAO/D;IAEF;;;;;OAKG;IACH,uCAAuC,GAAI,YAAY,MAAM,EAAE,KAAG,IAAI,CAIpE;IAEF,WAAW,GAAU,OAAO;QAC1B,OAAO,EAAE,cAAc,CAAC,SAAS,CAAC,CAAC;QACnC,WAAW,CAAC,EAAE,cAAc,CAAC,aAAa,CAAC,CAAC;QAC5C,UAAU,CAAC,EAAE,cAAc,CAAC,aAAa,CAAC,CAAC;QAC3C,cAAc,CAAC,EAAE,MAAM,CAAC;KACzB,KAAG,OAAO,CAAC,IAAI,CAAC,CAyLf;IAEF,OAAO,CAAC,aAAa,CA8BnB;IAEF,OAAO,CAAC,YAAY,CAgClB;IAEF,OAAO,CAAC,iBAAiB,CAYvB;CACH"}
+{"version":3,"file":"message.ctx.d.ts","sourceRoot":"","sources":["../../../src/context/message.ctx.ts"],"names":[],"mappings":"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"}

package/dist/src/context/router.ctx.d.ts

@@ -17,13 +17,35 @@ export declare class RouterCtx {
     private contactCtx;
     private sessionCtx;
     private resetChat;
+    /**
+     * Whether a reload returns the visitor to the conversation they were in.
+     * Off by default: the home screen is the sessions list. Embedders whose
+     * widget is a continuous assistant (an empty panel beside a live
+     * conversation reads as data loss) opt in via `router.restoreLastSession`.
+     */
+    private readonly shouldRestoreLastSession;
+    /** The stored pointer, until it is used or found unusable. */
+    private restorableSessionId;
+    /** Has the (async) storage read settled? Automatic routing waits for it. */
+    private didReadStoredSession;
     constructor({ config, contactCtx, sessionCtx, resetChat, }: {
         config: WidgetConfig;
         contactCtx: ContactCtx;
         sessionCtx: SessionCtx;
         resetChat: WidgetCtx['resetChat'];
     });
+    /**
+     * Read the remembered conversation before any automatic routing runs. The
+     * read is async (the storage adapter may be), and the sessions list can land
+     * first — so routing is re-run once the pointer is known.
+     */
+    private readStoredSession;
     private registerRoutingListener;
+    /**
+     * Every automatic route the sessions list can trigger, in one place so the
+     * restore can re-run it once the stored pointer is known.
+     */
+    private routeFromSessions;
     toSessionsScreen: () => void;
     /**
      * @param sessionId The ID of the session to open, or `undefined` if it is a new chat session

package/dist/src/context/router.ctx.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"router.ctx.d.ts","sourceRoot":"","sources":["../../../src/context/router.ctx.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAC3D,OAAO,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AACzD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAE9C,MAAM,MAAM,OAAO,GACf,yFAAyF,CAC3F,SAAS;AACT,kDAAkD;GAChD,UAAU;AACZ,uBAAuB;GACrB,MAAM,CAAC;AAEX,KAAK,WAAW,GAAG;IACjB,MAAM,EAAE,OAAO,CAAC;CACjB,CAAC;AAEF,qBAAa,SAAS;IACpB,KAAK,EAAE,cAAc,CAAC,WAAW,CAAC,CAAC;IAEnC,OAAO,CAAC,MAAM,CAAe;IAC7B,OAAO,CAAC,UAAU,CAAa;IAC/B,OAAO,CAAC,UAAU,CAAa;IAC/B,OAAO,CAAC,SAAS,CAAyB;gBAE9B,EACV,MAAM,EACN,UAAU,EACV,UAAU,EACV,SAAS,GACV,EAAE;QACD,MAAM,EAAE,YAAY,CAAC;QACrB,UAAU,EAAE,UAAU,CAAC;QACvB,UAAU,EAAE,UAAU,CAAC;QACvB,SAAS,EAAE,SAAS,CAAC,WAAW,CAAC,CAAC;KACnC;IAgBD,OAAO,CAAC,uBAAuB,CAiC7B;IAEF,gBAAgB,aAGd;IAEF;;OAEG;IACH,YAAY,GAAI,YAAY,MAAM,UAmBhC;CACH"}
+{"version":3,"file":"router.ctx.d.ts","sourceRoot":"","sources":["../../../src/context/router.ctx.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAC3D,OAAO,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AACzD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAE9C,MAAM,MAAM,OAAO,GACf,yFAAyF,CAC3F,SAAS;AACT,kDAAkD;GAChD,UAAU;AACZ,uBAAuB;GACrB,MAAM,CAAC;AAEX,KAAK,WAAW,GAAG;IACjB,MAAM,EAAE,OAAO,CAAC;CACjB,CAAC;AAEF,qBAAa,SAAS;IACpB,KAAK,EAAE,cAAc,CAAC,WAAW,CAAC,CAAC;IAEnC,OAAO,CAAC,MAAM,CAAe;IAC7B,OAAO,CAAC,UAAU,CAAa;IAC/B,OAAO,CAAC,UAAU,CAAa;IAC/B,OAAO,CAAC,SAAS,CAAyB;IAC1C;;;;;OAKG;IACH,OAAO,CAAC,QAAQ,CAAC,wBAAwB,CAAU;IACnD,8DAA8D;IAC9D,OAAO,CAAC,mBAAmB,CAAuB;IAClD,4EAA4E;IAC5E,OAAO,CAAC,oBAAoB,CAAS;gBAEzB,EACV,MAAM,EACN,UAAU,EACV,UAAU,EACV,SAAS,GACV,EAAE;QACD,MAAM,EAAE,YAAY,CAAC;QACrB,UAAU,EAAE,UAAU,CAAC;QACvB,UAAU,EAAE,UAAU,CAAC;QACvB,SAAS,EAAE,SAAS,CAAC,WAAW,CAAC,CAAC;KACnC;IAmBD;;;;OAIG;IACH,OAAO,CAAC,iBAAiB,CAcvB;IAEF,OAAO,CAAC,uBAAuB,CAW7B;IAEF;;;OAGG;IACH,OAAO,CAAC,iBAAiB,CAkDvB;IAEF,gBAAgB,aAGd;IAEF;;OAEG;IACH,YAAY,GAAI,YAAY,MAAM,UAmBhC;CACH"}

package/dist/src/context/session.ctx.d.ts

@@ -4,6 +4,7 @@ import { SessionDto } from '../types/dtos';
 import { WidgetConfig } from '../types/widget-config';
 import { PrimitiveState } from '../utils/PrimitiveState';
 import { ContactCtx } from './contact.ctx';
+import { StorageCtx } from './storage.ctx';
 type SessionState = {
     /**
      * The currently selected session.
@@ -28,52 +29,41 @@ export declare class SessionCtx {
     private config;
     private api;
     private contactCtx;
+    private storageCtx?;
     private sessionsPollingIntervalSeconds;
     private sessionsRefresher;
+    /** The session id currently written to storage (null = none written). */
+    private persistedSessionId;
     sessionState: PrimitiveState<SessionState>;
     sessionsState: PrimitiveState<SessionsState>;
-    constructor({ config, api, contactCtx, sessionsPollingIntervalSeconds, }: {
+    constructor({ config, api, contactCtx, storageCtx, sessionsPollingIntervalSeconds, }: {
         config: WidgetConfig;
         api: ApiCaller;
         contactCtx: ContactCtx;
+        storageCtx?: StorageCtx;
         sessionsPollingIntervalSeconds: number;
     });
+    /**
+     * Remember which conversation the visitor is in, so a page reload can put
+     * them back into it (`RouterCtx` does the restoring). Only OPEN sessions are
+     * remembered — a closed one would reopen as a dead transcript — and the
+     * pointer is dropped the moment the visitor leaves for a new chat.
+     *
+     * The boot value is deliberately NOT written: `subscribe` fires on changes
+     * only, and clearing on a null we never set would wipe the pointer the
+     * restore is about to read.
+     */
+    private registerActiveSessionPersistence;
+    /** The conversation the visitor was last in, from a previous page load. */
+    getLastActiveSessionId: () => Promise<string | null>;
     /** Clears the session and stops polling */
     reset: () => Promise<void>;
     private registerSessionsRefresherWrapper;
     private registerSessionsRefresher;
     private getParsedCustomData;
-    createSession: () => Promise<{
-        id: string;
-        ticketNumber: number;
-        title: string | null;
-        createdAt: string;
-        updatedAt: string;
-        isHandedOff: boolean;
-        isOpened: boolean;
-        assignee: {
-            kind: import('../api/schema').components["schemas"]["AssigneeKindEnum"];
-            name: string | null;
-            avatarUrl: string | null;
-        };
-        channel: string;
-        isVerified: boolean;
-        lastMessage: string | null;
-        modeId: string | null;
-        latestStateCheckpointPayload: {
-            [key: string]: unknown;
-        } | null;
-        sessionAttributes: {
-            [key: string]: string | number | boolean;
-        };
-        customStatus: {
-            id: string;
-            name: string;
-            description: string | null;
-            color: string | null;
-            icon: string | null;
-        } | null;
-    } | null>;
+    createSession: () => Promise<SessionDto | null>;
+    /** One create-session request; on success the session is stored and the hook fires. */
+    private requestSession;
     loadMoreSessions: () => Promise<void>;
     private getSessions;
     setSessions: (data: SessionDto[]) => void;

package/dist/src/context/session.ctx.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"session.ctx.d.ts","sourceRoot":"","sources":["../../../src/context/session.ctx.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AACnD,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,eAAe,CAAC;AACzC,OAAO,KAAK,EAAoB,UAAU,EAAE,MAAM,eAAe,CAAC;AAClE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAE3D,OAAO,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AAEzD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAEhD,KAAK,YAAY,GAAG;IAClB;;;OAGG;IACH,OAAO,EAAE,UAAU,GAAG,IAAI,CAAC;IAC3B,iBAAiB,EAAE,OAAO,CAAC;IAC3B,kBAAkB,EAAE,OAAO,CAAC;CAC7B,CAAC;AACF,KAAK,aAAa,GAAG;IACnB,gCAAgC;IAChC,IAAI,EAAE,UAAU,EAAE,CAAC;IACnB,gDAAgD;IAChD,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3B,0CAA0C;IAC1C,UAAU,EAAE,OAAO,CAAC;IACpB,mCAAmC;IACnC,oBAAoB,EAAE,OAAO,CAAC;IAC9B,qBAAqB,EAAE,OAAO,CAAC;CAChC,CAAC;AAEF,qBAAa,UAAU;IACrB,OAAO,CAAC,MAAM,CAAe;IAC7B,OAAO,CAAC,GAAG,CAAY;IACvB,OAAO,CAAC,UAAU,CAAa;IAC/B,OAAO,CAAC,8BAA8B,CAAS;IAC/C,OAAO,CAAC,iBAAiB,CAAgB;IAElC,YAAY,+BAIhB;IACI,aAAa,gCASjB;gBAES,EACV,MAAM,EACN,GAAG,EACH,UAAU,EACV,8BAA8B,GAC/B,EAAE;QACD,MAAM,EAAE,YAAY,CAAC;QACrB,GAAG,EAAE,SAAS,CAAC;QACf,UAAU,EAAE,UAAU,CAAC;QACvB,8BAA8B,EAAE,MAAM,CAAC;KACxC;IASD,2CAA2C;IAC3C,KAAK,sBAGH;IAEF,OAAO,CAAC,gCAAgC,CAetC;IAEF,OAAO,CAAC,yBAAyB,CAY/B;IAEF,OAAO,CAAC,mBAAmB,CAczB;IAEF,aAAa;;;;;;;;;kBA8G4+gB,6CAAsB;;;;;;;;;;;;;;;;;;;;;cAzF7ghB;IAEF,gBAAgB,sBAoBd;IAEF,OAAO,CAAC,WAAW,CAYjB;IAEF,WAAW,GAAI,MAAM,UAAU,EAAE,UAK/B;IAEF,eAAe,sBAKb;IAEF,cAAc;;;;;;;;;;;;;;;sBAqC2+gB,6CAAsB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAlB7ghB;IAEF,qBAAqB,GACnB,SAAS,GAAG,CAAC,qCAAqC,CAAC,CAAC,SAAS,CAAC;;;;mBAa9D;CACH"}
+{"version":3,"file":"session.ctx.d.ts","sourceRoot":"","sources":["../../../src/context/session.ctx.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AACnD,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,eAAe,CAAC;AACzC,OAAO,KAAK,EAAoB,UAAU,EAAE,MAAM,eAAe,CAAC;AAClE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAE3D,OAAO,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AAEzD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAGhD,KAAK,YAAY,GAAG;IAClB;;;OAGG;IACH,OAAO,EAAE,UAAU,GAAG,IAAI,CAAC;IAC3B,iBAAiB,EAAE,OAAO,CAAC;IAC3B,kBAAkB,EAAE,OAAO,CAAC;CAC7B,CAAC;AACF,KAAK,aAAa,GAAG;IACnB,gCAAgC;IAChC,IAAI,EAAE,UAAU,EAAE,CAAC;IACnB,gDAAgD;IAChD,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3B,0CAA0C;IAC1C,UAAU,EAAE,OAAO,CAAC;IACpB,mCAAmC;IACnC,oBAAoB,EAAE,OAAO,CAAC;IAC9B,qBAAqB,EAAE,OAAO,CAAC;CAChC,CAAC;AAEF,qBAAa,UAAU;IACrB,OAAO,CAAC,MAAM,CAAe;IAC7B,OAAO,CAAC,GAAG,CAAY;IACvB,OAAO,CAAC,UAAU,CAAa;IAC/B,OAAO,CAAC,UAAU,CAAC,CAAa;IAChC,OAAO,CAAC,8BAA8B,CAAS;IAC/C,OAAO,CAAC,iBAAiB,CAAgB;IACzC,yEAAyE;IACzE,OAAO,CAAC,kBAAkB,CAAuB;IAE1C,YAAY,+BAIhB;IACI,aAAa,gCASjB;gBAES,EACV,MAAM,EACN,GAAG,EACH,UAAU,EACV,UAAU,EACV,8BAA8B,GAC/B,EAAE;QACD,MAAM,EAAE,YAAY,CAAC;QACrB,GAAG,EAAE,SAAS,CAAC;QACf,UAAU,EAAE,UAAU,CAAC;QACvB,UAAU,CAAC,EAAE,UAAU,CAAC;QACxB,8BAA8B,EAAE,MAAM,CAAC;KACxC;IAWD;;;;;;;;;OASG;IACH,OAAO,CAAC,gCAAgC,CAoBtC;IAEF,2EAA2E;IAC3E,sBAAsB,QAAa,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAOvD;IAEF,2CAA2C;IAC3C,KAAK,sBAGH;IAEF,OAAO,CAAC,gCAAgC,CAetC;IAEF,OAAO,CAAC,yBAAyB,CAY/B;IAEF,OAAO,CAAC,mBAAmB,CAczB;IAEF,aAAa,QAAa,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CA0BlD;IAEF,uFAAuF;IACvF,OAAO,CAAC,cAAc,CA0BpB;IAEF,gBAAgB,sBAoBd;IAEF,OAAO,CAAC,WAAW,CAYjB;IAEF,WAAW,GAAI,MAAM,UAAU,EAAE,UAK/B;IAEF,eAAe,sBAKb;IAEF,cAAc;;;;;;;;;;;;;;;sBAqCi5iB,6CAAsB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAlBn7iB;IAEF,qBAAqB,GACnB,SAAS,GAAG,CAAC,qCAAqC,CAAC,CAAC,SAAS,CAAC;;;;mBAa9D;CACH"}

package/dist/src/context/storage.ctx.d.ts

@@ -1,5 +1,6 @@
 import { ExternalStorage } from '../types/external-storage';
-import { WidgetConfig } from '../types/widget-config';
+import { WidgetCompanionDefaultLayoutU, WidgetConfig, WidgetSidebarModeU } from '../types/widget-config';
+import { WidgetSidebarSideResolvedU } from '../utils/companion-layout';
 export declare class StorageCtx {
     private storage;
     private config;
@@ -10,7 +11,45 @@ export declare class StorageCtx {
     });
     setContactToken: (token: string) => Promise<void>;
     getContactToken: () => Promise<string | null>;
+    clearContactToken: () => Promise<void>;
+    /**
+     * The conversation the visitor was last in. Only a POINTER lives here — the
+     * messages themselves are on the backend — but without it a page reload
+     * drops the visitor into an empty composer beside a conversation that is
+     * still very much alive.
+     */
+    private activeSessionKey;
+    getActiveSessionId: () => Promise<string | null>;
+    setActiveSessionId: (sessionId: string) => Promise<void>;
+    clearActiveSessionId: () => Promise<void>;
     setExternalContactId: (id: string) => Promise<void>;
     getExternalContactId: () => Promise<string | null>;
+    private companionKey;
+    private getFiniteNumber;
+    getCompanionPillOffsetX: () => Promise<number | null>;
+    setCompanionPillOffsetX: (offset: number) => Promise<void>;
+    getCompanionSidebarWidth: () => Promise<number | null>;
+    setCompanionSidebarWidth: (width: number) => Promise<void>;
+    /**
+     * The visitor's own sidebar side/mode, once they have picked one in the
+     * layout menu. Absent until then, so `companion.sidebar.*` config keeps
+     * deciding for a visitor who never touched the control. Unrecognized stored
+     * values read as absent rather than poisoning the layout.
+     */
+    getCompanionSidebarSide: () => Promise<WidgetSidebarSideResolvedU | null>;
+    setCompanionSidebarSide: (side: WidgetSidebarSideResolvedU) => Promise<void>;
+    /**
+     * The RESTING layout the visitor last picked in the layout menu. Absent
+     * until they pick one, so `companion.defaultLayout` keeps deciding for a
+     * visitor who never touched the control.
+     *
+     * `fullscreen` is deliberately unstorable: it is a mode the visitor enters
+     * on top of a resting layout (Escape drops back out of it), so persisting
+     * it would reopen every future visit full-screen over the host page.
+     */
+    getCompanionLayout: () => Promise<WidgetCompanionDefaultLayoutU | null>;
+    setCompanionLayout: (layout: WidgetCompanionDefaultLayoutU) => Promise<void>;
+    getCompanionSidebarMode: () => Promise<WidgetSidebarModeU | null>;
+    setCompanionSidebarMode: (mode: WidgetSidebarModeU) => Promise<void>;
 }
 //# sourceMappingURL=storage.ctx.d.ts.map

package/dist/src/context/storage.ctx.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"storage.ctx.d.ts","sourceRoot":"","sources":["../../../src/context/storage.ctx.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AACjE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAE3D,qBAAa,UAAU;IACrB,OAAO,CAAC,OAAO,CAAkB;IACjC,OAAO,CAAC,MAAM,CAAe;IAE7B,OAAO,CAAC,IAAI,CAKV;gBAEU,EACV,OAAO,EACP,MAAM,GACP,EAAE;QACD,OAAO,EAAE,eAAe,CAAC;QACzB,MAAM,EAAE,YAAY,CAAC;KACtB;IAKD,eAAe,GAAU,OAAO,MAAM,mBAEpC;IACF,eAAe,+BAEb;IAEF,oBAAoB,GAAU,IAAI,MAAM,mBAEtC;IACF,oBAAoB,+BAElB;CACH"}
+{"version":3,"file":"storage.ctx.d.ts","sourceRoot":"","sources":["../../../src/context/storage.ctx.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AACjE,OAAO,KAAK,EACV,6BAA6B,EAC7B,YAAY,EACZ,kBAAkB,EACnB,MAAM,wBAAwB,CAAC;AAChC,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,2BAA2B,CAAC;AAU5E,qBAAa,UAAU;IACrB,OAAO,CAAC,OAAO,CAAkB;IACjC,OAAO,CAAC,MAAM,CAAe;IAE7B,OAAO,CAAC,IAAI,CASV;gBAEU,EACV,OAAO,EACP,MAAM,GACP,EAAE;QACD,OAAO,EAAE,eAAe,CAAC;QACzB,MAAM,EAAE,YAAY,CAAC;KACtB;IAKD,eAAe,GAAU,OAAO,MAAM,mBAEpC;IACF,eAAe,+BAEb;IACF,iBAAiB,sBAEf;IAEF;;;;;OAKG;IACH,OAAO,CAAC,gBAAgB,CACqB;IAE7C,kBAAkB,QAAa,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAEnD;IACF,kBAAkB,GAAU,WAAW,MAAM,KAAG,OAAO,CAAC,IAAI,CAAC,CAE3D;IACF,oBAAoB,QAAa,OAAO,CAAC,IAAI,CAAC,CAE5C;IAEF,oBAAoB,GAAU,IAAI,MAAM,mBAEtC;IACF,oBAAoB,+BAElB;IAEF,OAAO,CAAC,YAAY,CAC2C;IAE/D,OAAO,CAAC,eAAe,CAKrB;IAEF,uBAAuB,QAAa,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CACC;IAE3D,uBAAuB,GAAU,QAAQ,MAAM,KAAG,OAAO,CAAC,IAAI,CAAC,CAG7D;IAEF,wBAAwB,QAAa,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CACA;IAE3D,wBAAwB,GAAU,OAAO,MAAM,KAAG,OAAO,CAAC,IAAI,CAAC,CAG7D;IAEF;;;;;OAKG;IACH,uBAAuB,QACX,OAAO,CAAC,0BAA0B,GAAG,IAAI,CAAC,CAGlD;IAEJ,uBAAuB,GACrB,MAAM,0BAA0B,KAC/B,OAAO,CAAC,IAAI,CAAC,CAEd;IAEF;;;;;;;;OAQG;IACH,kBAAkB,QACN,OAAO,CAAC,6BAA6B,GAAG,IAAI,CAAC,CAGrD;IAEJ,kBAAkB,GAChB,QAAQ,6BAA6B,KACpC,OAAO,CAAC,IAAI,CAAC,CAEd;IAEF,uBAAuB,QAAa,OAAO,CAAC,kBAAkB,GAAG,IAAI,CAAC,CAGpE;IAEF,uBAAuB,GAAU,MAAM,kBAAkB,KAAG,OAAO,CAAC,IAAI,CAAC,CAEvE;CACH"}