@marketrix.ai/widget 3.8.492 → 3.8.494

package/dist/src/context/sseReducer.d.ts

@@ -1,3 +1,23 @@
+/**
+ * Pure state machine behind `ChatContext`: folds SSE `WidgetEvent`s and local transitions into `{messages,
+ * task}` (`SseState`; `TaskPhase`/`TaskState` carry the mode the run was dispatched in) and returns the tool
+ * runs the caller must perform (`SseEffect`, `ReduceResult`). No I/O, no React.
+ *
+ * `reduceToolProgress` writes a tool's progress line and sets the bubble's spinner, judging by the mode the
+ * run STARTED in, not what the composer shows now; `FINISH_TOOL` gets no line, only ending the run, though a
+ * failed finish is still stamped failed, and a `show`-mode DOM-mutating tool parks on "waiting-for-user".
+ * `reduceToolDone` stamps done and drops the progress parts, scaffolding for "still working" not answer.
+ * `reduceStop` stamps stopped and a stopped task STAYS stopped, so late `tool/call`s are ignored until
+ * `reduceDispatch` appends the next placeholder and returns to `idle`, reopening the task for the next turn.
+ *
+ * Terminal transitions clear `isPlaceholder` — the composer is disabled while any message is one, and
+ * `has_question` would otherwise ask for an answer the visitor could not type. `isTerminalTaskStatus` reads
+ * the very map that stamps the status, so a fourth reaches every caller at once. `reduceError` settles one
+ * pending message as a failed bubble, `reduceTransportFailure` does it to every placeholder since after a
+ * give-up no id-bearing event is coming, and `reduceStaleReply` covers a HEALTHY stream whose one reply
+ * never arrives and nothing else can see (a `waiting-for-user` pause is not stale). `reduceSse` switches:
+ * `chat/delta` accumulates, `chat/response` replaces, `tool/call` ACTIVATES the task before `task/status`.
+ */
 import type { WidgetEvent } from '../sdk';
 import { type ChatMessage, type InstructionType } from '../types';
 export type TaskPhase = 'idle' | 'running' | 'stopped';
@@ -32,17 +52,8 @@ declare const TASK_STATUS: {
     readonly stopped: "stopped";
 };
 export declare const isTerminalTaskStatus: (status: string) => status is keyof typeof TASK_STATUS;
-/** Settles a pending message into a plain error bubble — the one shape for both a failed POST and a chat/error. */
 export declare function reduceError(state: SseState, messageId: string, text: string): SseState;
-/** The transport gave up, so no id-bearing event is coming for whatever is still pending. */
 export declare function reduceTransportFailure(state: SseState, text: string): SseState;
-/**
- * The stream can stay healthy (no `StreamGaveUpError`) while a single dispatch's reply never arrives —
- * a dropped correlation, a silent backend failure before it ever acknowledges the request, or a reload
- * into the gap where the api has no tab to push to. `reduceTransportFailure` cannot see that, since
- * nothing told the transport it failed, so without this the bubble sits on "thinking" and the composer
- * stays disabled forever.
- */
 export declare function reduceStaleReply(state: SseState, messageId: string, text: string): SseState;
 export declare function reduceSse(state: SseState, event: WidgetEvent, currentMode: InstructionType): ReduceResult;
 export {};

package/dist/src/design-system/component-tokens.d.ts

@@ -1,5 +1,16 @@
+/**
+ * Every fixed design token the widget's components read, in one home: the `RADIUS`, `TEXT_TONE`,
+ * `TEXT_LEADING` and `SHADOW` scales, `TAB_BAR_HEIGHT`, `LAYER_TOKENS`, the `notificationToneStyles`
+ * palette per notification tone, and `getElevationStyle`, which turns a `ShadowToken` into a `boxShadow`
+ * (none → undefined so a caller can spread it). Each radius value has exactly one name — a test pins that
+ * no two tokens are synonyms. Per-tenant values are NOT here: `semantic-tokens.ts` owns everything derived
+ * from widget settings, and this file is only what no tenant can change.
+ *
+ * `LAYER_TOKENS` is the z-index ladder (screen-edge glow < panel < dialog < toast), based just above the
+ * 2^31-ish ceiling most host pages use so the widget sits over everything without the values overflowing a
+ * 32-bit int.
+ */
 import type { CSSProperties } from 'react';
-import { type ShadowToken } from './shadows';
 export type RadiusToken = 'none' | 'sm' | 'md' | 'lg' | 'xl' | 'pill';
 export type TextTone = 'default' | 'muted' | 'faint' | 'primary' | 'inherit';
 export type TextLeading = 'tight' | 'snug' | 'normal' | 'relaxed';
@@ -7,7 +18,22 @@ export type NotificationTone = 'info' | 'error' | 'neutral';
 export declare const RADIUS: Record<RadiusToken, string>;
 export declare const TEXT_TONE: Record<TextTone, string>;
 export declare const TEXT_LEADING: Record<TextLeading, string>;
+export declare const SHADOW: {
+    readonly none: "none";
+    readonly card: "0 1px 4px rgba(0,0,0,0.1)";
+    readonly section: "0 2px 8px rgba(0,0,0,0.06)";
+    readonly panel: "0 12px 40px rgba(0,0,0,0.16), 0 4px 12px rgba(0,0,0,0.08)";
+    readonly fab: "0 2px 8px rgba(0,0,0,0.18), 0 0 0 1px rgba(0,0,0,0.04)";
+    readonly button: "0 4px 6px -1px rgba(0,0,0,0.1)";
+};
+export type ShadowToken = keyof typeof SHADOW;
 export declare const TAB_BAR_HEIGHT = 48;
+export declare const LAYER_TOKENS: {
+    screenEdgeGlow: number;
+    panel: number;
+    dialog: number;
+    toast: number;
+};
 export declare const notificationToneStyles: Record<NotificationTone, {
     background: string;
     border: string;

package/dist/src/design-system/semantic-tokens.d.ts

@@ -1,3 +1,21 @@
+/**
+ * The one home for turning per-tenant widget settings into semantic design tokens and the CSS custom
+ * properties inlined on the widget root — the widget's entire theming mechanism (no dark mode, no
+ * class-based themes).
+ *
+ * Contents: the `SemanticTokens` shape (color / radius / motion); `WIDGET_RADIUS_PX`, exported because
+ * `WidgetFab` needs the raw number for its SVG `rx`/`ry`, not a CSS string; `DURATION_ANIMATION` and
+ * `DURATION_FADE`; `WidgetStyleSettingsDefaults` and `WIDGET_STYLE_SETTINGS_DEFAULTS`, the five colour
+ * settings this file consumes and their fallbacks; `createSemanticTokens`, which resolves a partial
+ * settings object against those defaults and derives the muted/faint/hover/contrast variants;
+ * `semanticTokensToCssCustomProperties`, the token → `--var` map.
+ *
+ * Radius and both durations are fixed rather than per-tenant: every widget row in production holds these
+ * values and no surface writes them. Settings are filtered for explicit `undefined` before merging —
+ * a plain spread would let an `undefined` key shadow its default instead of falling back to it. The
+ * `--var` map must cover every variable `index.css` `:host` declares, or that hardcoded fallback palette
+ * shows through on the widget root.
+ */
 import type { WidgetSettingsData } from '../sdk';
 type SemanticTokens = {
     color: {

package/dist/src/hooks/useDragSnap.d.ts

@@ -1,3 +1,16 @@
+/**
+ * `useDragSnap` — drag the launcher (FAB) and snap it to the nearest corner. Pointer events are tracked
+ * in a ref; movement under DRAG_THRESHOLD_PX stays a click, beyond it the wrapper is translated on a
+ * rAF loop with velocity sampled so a flick lands where it was heading. On release
+ * `getNearestCornerByTranslation` picks the corner, the wrapper animates there for SNAP_DURATION_MS via
+ * `left`/`top` transitions, and `commitPositionAfterAnimation` calls `onPositionCommit` on
+ * `transitionend` (with a timeout fallback, since a hidden tab fires no transition events) — the
+ * committed corner is the one being animated TO, so two snaps in flight cannot commit the abandoned
+ * one (`abandonSnapRef`). `suppressUntilRef` stamps a time after which a click may open the widget
+ * again, so the pointer-up that ends a drag is not read as a tap. The wrapper is measured with a
+ * ResizeObserver in a layout effect so the pixel position is right on the first paint; preview mode
+ * disables everything.
+ */
 import React from 'react';
 import type { WidgetPosition } from '../types';
 export interface UseDragSnapOptions {

package/dist/src/hooks/useFocusTrap.d.ts

@@ -1,3 +1,23 @@
+/**
+ * Focus trap for the messenger panel: while `isActive`, focus starts inside `containerRef`, Tab cycles
+ * within it, Escape calls `onEscape`, and on deactivation focus returns to whatever held it before.
+ *
+ * The tabbable-candidate query is `utils/dom`'s shared `TABBABLE_SELECTOR`; `activeElementIn` reads the
+ * focused element as seen from a container's own root; `getFocusables` lists a container's visible tabbable elements; and
+ * `useFocusTrap(containerRef, isActive, {onEscape, focusTargetRef})` focuses `focusTargetRef` (else the
+ * first focusable), installs one capture-phase `keydown` listener on `document`, and restores focus on
+ * the active→inactive edge.
+ *
+ * Inside the widget's closed shadow root `document.activeElement` retargets to the HOST, never naming
+ * an element of the widget's own tree; `activeElementIn` reads through `container.getRootNode()`
+ * instead and is the ONE home for that retargeting — eslint's `no-restricted-properties` bans the bare
+ * read everywhere else. Hand-rolled on purpose: `MessengerShell` is a NON-modal panel, not a Dialog,
+ * and Base UI exposes no standalone focus trap; reaching it by making the panel a Dialog would inert
+ * the customer's page. Both key arms bail unless focus is currently inside the container, since the
+ * listener sits on `document` ahead of host-page handlers and an unguarded Escape would close the
+ * widget mid-typing. Tab `preventDefault`s only at the two ends; `previousActiveRef` edge-triggers the
+ * restore once on close, and `getFocusables` drops hidden/`aria-hidden` elements the selector can't express.
+ */
 export declare function useFocusTrap(containerRef: React.RefObject<HTMLElement | null>, isActive: boolean, options?: {
     onEscape?: () => void;
     focusTargetRef?: React.RefObject<HTMLElement | null>;

package/dist/src/hooks/useWidget.d.ts

@@ -1,5 +1,15 @@
+/**
+ * The two context hooks every widget component reads: `useWidgetConfig` for settings, `useWidget` for the store.
+ *
+ * `WidgetConfigContext` publishes every setting resolved — API settings plus the position and z-index `WidgetRoot`
+ * layers on top — and `useWidgetConfig` reads it, throwing outside `WidgetRoot` rather than defaulting, so nothing
+ * below ever touches the raw config prop or threads it down as props. `useWidget` folds the two independent stores
+ * (`UIStateContext`, `ChatContext`) into one memoized `{state, actions}`: `isTaskRunning` reads the canonical *wire*
+ * status `'running'`, never the UI-only `ChatMessage.taskStatus` vocabulary, and `isAwaitingReply` the placeholder
+ * message held open while a reply streams. `clearChatHistory` resets messages, task and the UI error together — an
+ * error left standing would outlive the chat it described.
+ */
 import type { ValidWidgetConfig, WidgetState } from '../types';
-/** Every setting resolved: API settings plus the position and script-tag overrides WidgetRoot layers on top. */
 export declare const WidgetConfigContext: import("react").Context<ValidWidgetConfig | null>;
 export declare const useWidgetConfig: () => ValidWidgetConfig;
 export declare const useWidget: () => {

package/dist/src/index.d.ts

@@ -1,3 +1,23 @@
+/**
+ * Public entry point of `@marketrix.ai/widget`: the imperative lifecycle API, the `MarketrixWidgetPreview`
+ * dashboard wrapper and the script-tag auto-init hook. `README.md` is the customer-facing surface these
+ * exports make up, named and default alike. `initWidget` is the guarded, coalescing production entry over
+ * `initWidgetInternal`; `mount` builds the shadow-DOM container; `unmountWidget` tears down stream,
+ * recorder, screen share and tree;
+ * `updateMarketrixConfig` re-mounts with client settings merged in, on whichever path the current mount
+ * came from; `mountWidget` dispatches on shape — `settings` → preview (no network), credentials → live.
+ *
+ * `previewConfig` is the one home for the preview path's validate-then-resolve, shared by the React
+ * component and the imperative `mountWidget`; a null return means it has already reported why. There is
+ * no default api host, so an unconfigured SDK would resolve every request against the HOST PAGE's origin
+ * and `configureSdk` runs before anything else on the production path. `widget_enabled` is the kill switch:
+ * unlike `show_widget`/`widget_appearance`, hidden but initialized, disabled means no chat id, stream or
+ * recording. `window.__mtx` guards the singleton because it survives ES-module re-execution, and every init
+ * and unmount bumps `lifecycleGeneration` so in-flight work abandons itself rather than mounting over a
+ * newer one. Preview with no `container` mounts into the div it renders, never the parent, which would size
+ * the widget to the wrong box. Auto-init runs on import, browser-guarded so the package stays importable from
+ * a server render, deferred a tick so every export exists before the tag scan.
+ */
 declare global {
     interface Window {
         __mtx?: {

package/dist/src/sdk/contracts/common.d.ts

@@ -33,14 +33,6 @@ export declare const PaginationSchema: z.ZodObject<{
     offset: z.ZodDefault<z.ZodOptional<z.ZodCoercedNumber<unknown>>>;
 }, z.core.$strip>;
 type StripDefault<T> = T extends z.ZodDefault<infer Inner> ? Inner : T;
-/**
- * The ONE way to build a PATCH schema from an entity/input schema. Zod's `.partial()` makes every
- * field optional but does NOT stop a `.default(...)` field from being backfilled when omitted — an
- * update caller who sends only `{ title }` gets `options: []`/`config: {}` re-applied by parsing, so a
- * `field !== undefined` merge guard downstream never sees the omission and silently wipes the column.
- * This strips each field's default before making it optional, so "not sent" really does parse to
- * `undefined`.
- */
 export declare function partialPatch<Shape extends z.ZodRawShape>(schema: z.ZodObject<Shape>): z.ZodObject<{
     [K in keyof Shape]: z.ZodOptional<StripDefault<Shape[K]>>;
 }>;
@@ -128,14 +120,6 @@ export declare const GraphSchema: z.ZodObject<{
     }, z.core.$loose>>;
 }, z.core.$strip>;
 export type GraphData = z.infer<typeof GraphSchema>;
-export declare const NotificationResolvedReasonSchema: z.ZodEnum<{
-    answered: "answered";
-    dismissed: "dismissed";
-    cancelled: "cancelled";
-}>;
-export type NotificationResolvedReason = z.infer<typeof NotificationResolvedReasonSchema>;
-/** Every live-progress stream the api opens. The app keys `useAgentProgress` on these, so a kind it
- *  cannot name is a generator whose progress never renders. */
 export declare const AGENT_PROGRESS_KINDS: readonly ["study_plan", "qa_generate_journeys", "qa_prefill_values", "persona_generate", "persona_from_description", "persona_autocomplete"];
 export declare const AgentProgressKindSchema: z.ZodEnum<{
     study_plan: "study_plan";

package/dist/src/sdk/index.d.ts

@@ -1,4 +1,3 @@
-/** Must be called before any SDK operation — the widget has no baked-in API host. */
 export declare const configureSdk: (apiUrl: string) => void;
 export declare const sdk: {
     activityLogCreate: import("@orpc/contract").ContractProcedureClient<Record<never, never>, import("zod").ZodObject<{

package/dist/src/services/BrowserToolService.d.ts

@@ -1,3 +1,23 @@
+/**
+ * Every browser action the agent can ask the widget to take on the HOST page, as one name → handler
+ * registry: `tools` holds label, wait-for-user flag and handler together so no parallel list can drift, and
+ * `executeTool` in `show` mode highlights the target and waits for the visitor before running the handler.
+ *
+ * `typeText` trails a `blur` because some frameworks validate only on it. `extract` truncates at 10k while
+ * `getHtml` is uncapped — the agent's parser indexes by `data-id`, and a trimmed tree loses elements the
+ * loop then cannot click. `getScreenshot` reads the EXISTING share, since a fresh prompt bypasses an
+ * earlier Deny. `FINISH_TOOL` is one named export so dispatch, progress lines and the settlement check read
+ * one string. `sendKeys` dispatches the KeyboardEvent and delegates the default action the browser
+ * withholds to `keySimulation`. `deferred` reports an action DISPATCHED, never completed: a click or
+ * navigation can tear the page down before the report is read.
+ *
+ * `element` / `selectElement` are the ONE way a handler reaches a host-page node: they resolve an index
+ * through `domService` and THROW. `executeTool`'s catch is this file's ONLY error handler and no handler
+ * may add a second — a throw already reaches the agent verbatim, so a local try/catch just rewrites the
+ * same failure. `httpUrl` admits only http(s) — `extract` feeds the model page-controlled hrefs, so a raw
+ * target would let `javascript:` run in the HOST origin; its bare catch is the same verdict as a rejected
+ * protocol, an unparseable string being exactly a value that is not a URL.
+ */
 import type { InstructionType } from '../types';
 export interface TextData {
     text: string;
@@ -26,7 +46,13 @@ export type ToolExecutionResult<T = TextData> = {
     data: T;
     afterResponseAttempt?: () => void;
 } | ToolFailure;
+export declare const FINISH_TOOL = "finish";
 export declare class BrowserToolService {
+    private readonly tools;
+    private element;
+    private selectElement;
+    getFriendlyToolName(browserToolName: string): string;
+    isWaitForUserTool(browserToolName: string): boolean;
     executeTool(browserToolName: string, args: Record<string, unknown>, mode: InstructionType, explanation?: string): Promise<ToolExecutionResult<unknown>>;
     private navigate;
     private search;
@@ -40,11 +66,6 @@ export declare class BrowserToolService {
     private selectDropdownOption;
     private getDropdownOptions;
     private sendKeys;
-    /** Programmatic KeyboardEvents aren't "trusted", so manually reproduce each key's expected behavior. */
-    private simulateKeyAction;
-    /** Native value setter so React/Vue controlled inputs pick up the change. */
-    private setNativeValue;
-    private setValueAndCaret;
     private closeTab;
     private done;
     private getHtml;

package/dist/src/services/ChatService.d.ts

@@ -1,4 +1,18 @@
+/**
+ * Sends one visitor turn to the api. `chatPost` mints or reuses the chat id, files a `widget_question`
+ * activity-log row, then POSTs a `chat/${mode}` `WidgetCommand` over the stream.
+ *
+ * The reply never comes back from here — it arrives asynchronously on the SSE stream as `chat/delta`
+ * fragments and a final `chat/response`, matched by `request_id` (the caller's placeholder message id).
+ * That is why `StreamClient.ready` must resolve BEFORE the POST: registration is what gives the reply
+ * somewhere to land.
+ *
+ * The logged `chat_id` is read back from `storageService` rather than passed, so it is only correct
+ * after `getOrCreateChatId()` has resolved and written it. `user_id` is omitted, never sent null, when
+ * the host supplied no visitor identity. The activity log is telemetry and is deliberately not awaited:
+ * it can neither delay nor fail the send, and a rejection warns and stops there — whereas a failed
+ * `send` propagates to `ChatContext`, which renders the error turn.
+ */
 import { type InstructionType } from '../sdk';
 import { type CredentialedConfig } from './StorageService';
-/** The reply does not come back from here — it arrives asynchronously as a chat/response event on the stream. */
 export declare function chatPost(config: CredentialedConfig, message: string, mode: InstructionType, requestId: string): Promise<void>;

package/dist/src/services/ChatSessionManager.d.ts

@@ -1,8 +1,6 @@
 declare class ChatSessionManager {
     private creation;
-    /** Promise-based lock: concurrent callers all await the same creation. */
     getOrCreateChatId(): Promise<string>;
-    private createChatId;
 }
 export declare const chatSessionManager: ChatSessionManager;
 export {};

package/dist/src/services/DomService.d.ts

@@ -1,3 +1,21 @@
+/**
+ * The numbered address space the agent drives the host page by: `reindexAndSnapshot` walks the live document and
+ * returns a clone stamped with `data-id="<n>"` on every interactive element; `getSequenceForElement` is the reverse
+ * lookup; `getValidatedElement` resolves an index back to a live element or a `ValidatedElementResult` error;
+ * `notInteractableReason` phrases why an element cannot be acted on; `generateAnchoredSelector` and `indexElements`
+ * build the walk and its body-anchored selectors. `domService` is the process-wide singleton.
+ *
+ * `data-id` is the whole contract with the agent, so the clone is tagged by re-querying each stored selector rather
+ * than walking the two trees in step — a synced walk breaks on modals and fixed elements. Indices are addresses the
+ * agent holds across turns: each entry snapshots IDENTITY_ATTRIBUTES so a changed element reads as DOM_CHANGED
+ * rather than silently acting on a control the agent no longer means.
+ *
+ * The tree walker keeps an element with a null `offsetParent` when it or an ancestor is fixed/sticky, since the
+ * browser reports no offsetParent for those even when visible. The obscured test ignores Marketrix's own chrome
+ * (Show-mode highlight/popup, the widget's shadow host) since those legitimately sit over the element they point
+ * at. `notInteractableReason`'s `document.body.contains` check must stay first: ShowModeService uses it as its
+ * removal watchdog and keeps no identity snapshot of its own.
+ */
 export interface ValidatedElementResult {
     element: HTMLElement | null;
     error?: string;
@@ -6,12 +24,9 @@ export declare class DomService {
     private index;
     private elementToSequence;
     private generateAnchoredSelector;
-    private staleReason;
     private indexElements;
-    /** `data-id` is the whole contract: the agent parses the snapshot for `[data-id]` and reads nothing else off it. */
     reindexAndSnapshot(): string;
     getSequenceForElement(element: Element): number | undefined;
-    private clearIndex;
     notInteractableReason(element: HTMLElement, index: number): string | null;
     getValidatedElement(index: number): ValidatedElementResult;
 }

package/dist/src/services/RrwebSessionRecorder.d.ts

@@ -10,6 +10,5 @@ export declare class RrwebSessionRecorder {
     constructor(chatId: string, applicationId: number);
     start(): Promise<void>;
     stop(): void;
-    private buffer;
     private flush;
 }

package/dist/src/services/ShowModeService.d.ts

@@ -1,3 +1,23 @@
+/**
+ * Show mode's on-page coaching overlay: highlights one host-page element, explains the step beside it and
+ * returns a promise that settles when the visitor acts, so `BrowserToolService` can await a `show`-mode tool
+ * call before running the tool. `showToolAction` mounts highlight and popup and returns the pending promise,
+ * or the in-flight one for an identical restage (a duplicate tool call); `cleanup` cancels and unwinds;
+ * `showModeService` is the singleton every caller uses.
+ *
+ * Exactly one settle: the element click, the Continue button and both watchdog branches race, so both
+ * settlers are DETACHED before either fires and the off-screen branch returns rather than falling through.
+ * The highlight is `pointer-events:none` so the visitor's click reaches the real element; click and
+ * reposition handlers sit on `document` in the CAPTURE phase — the former tests `composedPath`, which sees
+ * through Shadow DOM retargeting, and prevents default so navigation cannot precede the result; the latter
+ * tracks a scrolling container, not just the window. `#marketrix-show-highlight` and `#marketrix-show-popup`
+ * are load-bearing ids: `DomService.notInteractableReason` allowlists them so the overlay never reads as an
+ * obscuring modal, and cleanup re-finds them because an interrupted node outlives its handle. The highlight's
+ * cssText is one line because template-literal whitespace is not minified. `trackElement` is the one place the
+ * highlight is sized and placed over its element, so the first paint and every reposition run through it;
+ * placement takes the first of right/left/above/below that fits then clamps, its 120px height an assumption,
+ * and the watchdog tests `document.body.contains` first, covering removal as well as occlusion.
+ */
 export interface ShowModeOptions {
     element: HTMLElement;
     explanation: string;
@@ -17,18 +37,15 @@ export declare class ShowModeService {
     private visibilityCheckInterval;
     showToolAction(options: ShowModeOptions): Promise<void>;
     cleanup(): void;
-    private completeAction;
-    /** Detach both settlers before calling one — the click handler, the Continue button and the two watchdogs race. */
+    private settle;
     private takeSettlers;
     private createHighlight;
+    private trackElement;
     private createPopup;
     private setupPositionUpdates;
     private updatePopupPosition;
     private setupClickHandler;
-    private setupContinueButton;
-    /** notInteractableReason's first test is `document.body.contains`, so this one watchdog also covers removal. */
     private setupVisibilityMonitoring;
-    private failShowAction;
     private escapeHtml;
 }
 export declare const showModeService: ShowModeService;

package/dist/src/services/StorageService.d.ts

@@ -1,3 +1,23 @@
+/**
+ * Browser-local persistence for the widget: the one door to `localStorage`, and the per-tenant chat context
+ * (chat_id, transcript, composer mode, open state, resolved config) behind the `storageService` singleton.
+ * `tenantScope` is the scope suffix for every browser-local key — the credential id, else the application id, else
+ * `default` — shared with the drag-position and resize keys so all of them partition the same way. `readLocal` /
+ * `writeLocal` are the only `localStorage` access in `src/`; a host page can deny storage outright (third-party
+ * cookies off, sandboxed iframe) where even reading throws, so both degrade to a warn and the widget keeps working
+ * unpersisted. `loadContext` parses one key merged over `DEFAULT_CONTEXT`, so a payload from an older widget
+ * version reads as incomplete rather than corrupt, and discards anything older than `CONTEXT_EXPIRY_MS` (7 days).
+ * `StorageService`'s `getContext`, `updateContext` (merges, restamps `timestamp`, writes through), `getChatId` /
+ * `setChatId`, `getCredentialedConfig` (null unless both `mtxId` and `mtxKey` are present, so callers cannot
+ * dispatch half-credentialed) and `setConfig` sit behind the singleton; `readChatSnapshot` / `writeChatSnapshot`
+ * are the UI-facing view of the context. `setConfig` re-keys storage to `${STORAGE_KEY}_${tenantScope}` and
+ * reloads from that key, since without it two applications embedded on one origin would share a stored chat_id and
+ * one tenant's transcript would leak into another's.
+ *
+ * The snapshot is `{messages, currentMode, isOpen}` — chat_id, config and timestamp are deliberately excluded.
+ * Reading revives `timestamp` to a `Date` and backfills a text part for messages stored before `parts` existed;
+ * writing drops `videoStream` (unserializable, dead on reload), rewriting it as `Screen sharing ended`.
+ */
 import type { ChatMessage, InstructionType, MarketrixConfig, ValidWidgetConfig } from '../types';
 export type StoredMessage = Omit<ChatMessage, 'videoStream' | 'timestamp'> & {
     timestamp: string;
@@ -17,7 +37,6 @@ export type MarketrixChatContext = Omit<ChatSnapshot, 'messages'> & {
     config: MarketrixConfig | null;
     timestamp: number;
 };
-/** Per-tenant scope for browser-local keys: the credential id, else the application id. */
 export declare function tenantScope(config: MarketrixConfig): string;
 export declare function readLocal(key: string): string | null;
 export declare function writeLocal(key: string, value: string): void;

package/dist/src/services/StreamClient.d.ts

@@ -1,5 +1,24 @@
+/**
+ * Singleton SSE transport between the widget and the api: `StreamClient.getInstance` drains one `widgetStream`
+ * iterator in the background, `send` posts via `widgetMessagePost`, `ready` connects then waits,
+ * `waitUntilRegistered` parks a caller, `canReconnect`/`reconnectNow` back the Retry affordance, `disconnect`
+ * tears down and rejects parked callers, and `StreamGaveUpError` marks a stream that has stopped retrying.
+ *
+ * `open` is the transport, `registered` is the chat: only the latter can carry a reply, so `isConnected` reads
+ * `registered` and nothing waits on `open`. Backoff counters reset only on `registered` — resetting at `open` would
+ * defeat the max-attempts cap if registration never lands and the stream flaps open→closed. Tabs share the
+ * localStorage chat id, so the server keys SSE by (chat_id, tab_id) and `tabId` stops tabs evicting each other's
+ * stream. Credentials are read at connect time, not captured at init, so a reconnect after `updateMarketrixConfig`
+ * dials with the current ones.
+ *
+ * A `chat/error` whose `request_id === 'auth'` is non-retriable: `chat/error` otherwise settles the message whose
+ * id is the request id, and no message is ever id `'auth'`, so without the explicit `giveUp` here the widget went
+ * permanently silent — no toast, no bubble, and (console dropped by terser) no trace. Both give-up messages are
+ * read by a visitor on a customer's page, so they name the state and the way out rather than the counter, and
+ * `giveUp` needs no console line of its own for the same reason. A dial or stream that will be retried warns;
+ * only the rejected credential is an error, being the one failure nothing here recovers from.
+ */
 import { type WidgetCommand, type WidgetEvent } from '../sdk';
-/** The stream has stopped retrying, so nothing further will arrive for anything still in flight. */
 export declare class StreamGaveUpError extends Error {
 }
 export interface StreamClientCallbacks {
@@ -36,6 +55,7 @@ export declare class StreamClient {
     private consumeEvents;
     disconnect(): void;
     send(command: WidgetCommand): Promise<void>;
+    private resetBackoff;
     private notifyError;
     private settleWaiters;
     private giveUp;

package/dist/src/services/keySimulation.d.ts

@@ -0,0 +1,3 @@
+export declare const isTextField: (el: Element) => el is HTMLInputElement | HTMLTextAreaElement;
+export declare function simulateKeyAction(element: HTMLElement, key: string): string | null;
+export declare function setNativeValue(el: HTMLInputElement | HTMLTextAreaElement, value: string): void;

package/dist/src/test/fixtures.d.ts

@@ -1,4 +1,15 @@
-import type { MarketrixConfig, WidgetSettingsData } from '../types';
-type MockWidgetConfig = MarketrixConfig & Pick<WidgetSettingsData, 'widget_border_radius' | 'widget_font_size' | 'widget_animation_duration' | 'widget_fade_duration'>;
+/**
+ * The shared widget-settings fixture the config-driven tests build from: `getMockWidgetConfig(overrides)`
+ * returns a complete, schema-valid tenant config — every rendered setting plus the `mtxId`/`mtxKey` credential,
+ * api host and preview flag a mounted widget needs — shallow-merged with `overrides`.
+ *
+ * `MockWidgetConfig` widens `ValidWidgetConfig` with the four render constants (`widget_border_radius`,
+ * `widget_font_size`, `widget_animation_duration`, `widget_fade_duration`). `ValidWidgetConfig` is built on
+ * `WidgetRenderedSettings`, which omits them, but callers hand this fixture straight to
+ * `WidgetSettingsDataSchema.parse()`, which demands the whole wire shape. It is `Valid`, not partial, so
+ * `renderWidget` can hand it to `WidgetRoot` without a cast — the fixture really does set every field.
+ */
+import type { ValidWidgetConfig, WidgetSettingsData } from '../types';
+type MockWidgetConfig = ValidWidgetConfig & Pick<WidgetSettingsData, 'widget_border_radius' | 'widget_font_size' | 'widget_animation_duration' | 'widget_fade_duration'>;
 export declare function getMockWidgetConfig(overrides?: Partial<MockWidgetConfig>): MockWidgetConfig;
 export {};

package/dist/src/test/renderWidget.d.ts

@@ -0,0 +1,6 @@
+import { getMockWidgetConfig } from './fixtures';
+export declare function renderWidget(overrides?: Parameters<typeof getMockWidgetConfig>[0], { previewMode }?: {
+    previewMode?: boolean;
+}): import("@testing-library/react").RenderResult<typeof import("@testing-library/dom/types/queries"), HTMLElement, HTMLElement>;
+export declare const openWidget: () => void;
+export declare const openChatTab: () => void;

package/dist/src/test/setup.d.ts

@@ -1 +1,15 @@
+/**
+ * Vitest global setup (`setupFiles` in `vitest.config.ts`), run once per test file before any suite:
+ * registers the jest-dom matchers and fills the three browser globals jsdom does not usably provide here.
+ *
+ * `localStorage` — a Map-backed `Storage` (getItem/setItem/removeItem/clear/length/key). jsdom defines it
+ * on the prototype, and that does not transfer to vitest's `globalThis`, leaving `StorageService` — the one
+ * door to it in `src/` — an object with no `setItem`; hence the guard probes for the method, not the property.
+ * `matchMedia` — a never-matching `MediaQueryList` with inert listener registration, required by
+ * `useScrollLock`. `ResizeObserver` — an inert observe/unobserve/disconnect class, required by
+ * `useDragSnap`.
+ *
+ * Every fill is conditional, so a real implementation — a future jsdom, or a per-test override
+ * installed before this file — wins.
+ */
 import '@testing-library/jest-dom/vitest';

package/dist/src/types/index.d.ts

@@ -1,3 +1,23 @@
+/**
+ * Widget-wide shared types: the config shapes a host supplies, the chat message/part model, the UI
+ * store shape, and `messageText` — the one place a message's displayed text is derived.
+ *
+ * `ClientOwnedConfig` holds host-supplied knobs the api never sends (`show_widget: false` still
+ * initializes the widget fully and only hides its UI; `use_screenshare: false` auto-denies
+ * screen-access requests and hides the Share Screen button; both default true). `MarketrixConfig` is
+ * deliberately FLAT so api settings spread straight in — `mtxId`+`mtxKey` is the credential, while
+ * `mtxApp` is stamped internally after validation and never an input, since an application id is
+ * guessable and authenticates nothing. `ValidWidgetConfig` is a `MarketrixConfig` run through
+ * `parseWidgetSettings`, so every rendered setting is present. `ChatMessage`+`MessagePart` are the chat
+ * model; `WidgetState` is the flattened read model `useWidget()` folds from `UIStateContext`+
+ * `ChatContext`; `WidgetPosition` re-aliases `widget_position` as the drag-snap/resize corner
+ * vocabulary; `AddWidgetConfig`'s union makes `settings` and `mtxId`/`mtxKey` mutually exclusive.
+ * `ChatMessage.pendingContent` queues a message behind an open screen-access request, sent once it
+ * resolves. A `streaming` `MessagePart` accumulates `chat/delta` fragments until the final
+ * `chat/response` replaces it. `taskStatus`/`MessagePart.status` are presentational only, not the wire
+ * vocabulary (`task/status.status`). `messageText` joins text parts and IS the text; `content` is kept
+ * equal to it by every writer.
+ */
 import type { InstructionType, WidgetSettingsData } from '../sdk';
 import type { WidgetRenderedSettings } from '../utils/validation';
 export type { InstructionType, WidgetSettingsData } from '../sdk';
@@ -5,9 +25,7 @@ export interface ClientOwnedConfig {
     mtxApiHost?: string;
     userId?: number;
     widget_position_z_index?: number;
-    /** When false, widget initializes fully but UI is hidden. Default: true */
     show_widget?: boolean;
-    /** When false, screen access requests are auto-denied and Share Screen button is hidden. Default: true */
     use_screenshare?: boolean;
 }
 export type MarketrixConfig = Partial<WidgetRenderedSettings> & ClientOwnedConfig & {
@@ -16,7 +34,6 @@ export type MarketrixConfig = Partial<WidgetRenderedSettings> & ClientOwnedConfi
     mtxApp?: number;
     isPreviewMode?: boolean;
 };
-/** A MarketrixConfig that has been through parseWidgetSettings — every rendered setting present. */
 export type ValidWidgetConfig = MarketrixConfig & Required<Pick<MarketrixConfig, keyof WidgetRenderedSettings>>;
 export interface ChatMessage {
     id: string;
@@ -27,7 +44,6 @@ export interface ChatMessage {
     videoStream?: MediaStream;
     isScreenAccessRequest?: boolean;
     screenShareStatus?: 'allowed' | 'denied';
-    /** The message queued behind an open screen-access request, sent once it resolves. */
     pendingContent?: string;
     isSystemMessage?: boolean;
     isPlaceholder?: boolean;
@@ -40,11 +56,8 @@ export interface MessagePart {
     content: string;
     status?: 'in_progress' | 'completed' | 'failed';
     browserToolName?: string;
-    /** chat/delta fragments accumulate into this part; the final chat/response replaces it. */
     streaming?: boolean;
 }
-/** A message's text is the text it shows: its text parts joined. `content` is this value, kept by the
- *  writers, so a reader never has to know which of the two fields is authoritative. */
 export declare const messageText: (parts: MessagePart[]) => string;
 export type WidgetView = 'home' | 'chat';
 export interface WidgetState {

package/dist/src/utils/chat.d.ts

@@ -1,3 +1,22 @@
+/**
+ * Pure helpers for the chat message list — the mode label, the hh:mm timestamp, the newest-first
+ * `lastIndexWhere` (also used by `useScreenShare`), and `addProgressLine` / `markProgressLineComplete` /
+ * `markProgressLineFailed`, which append or settle the open progress part for one `browserToolName` via
+ * `openLineFor` and the shared `patchPart` copy-on-write. `createMessage` and its per-sender constructors are
+ * the ONLY way a `ChatMessage` is built: ids are `<prefix>-<uuid>` since two messages minted in one millisecond
+ * used to collide, and empty content yields no `text` part, the screen-share bubble rendering from `videoStream`
+ * alone and a placeholder having nothing to say yet. `SCREEN_ACCESS_PROMPT` is the one wording of the
+ * screen-access ask, the transcript card and the toolbar dialog being two renderings of one question.
+ *
+ * `findMessageForProgress` picks the agent reply a `tool/call` or progress event renders into, by ranked
+ * predicates: the first rank matching anything wins, within a rank the newest message, and no match at all is a
+ * legitimate outcome, warned not thrown. Every rank is bounded to messages after the last agent message carrying
+ * a `taskStatus`, since a terminal stamp means that run already ended — unbounded, a late event reaches back past
+ * the stamp onto an already-settled reply and a late `completed` overwrites a `stopped` icon. Placeholders with
+ * `mode` still undefined match leniently and a mode-agnostic rank is always appended, since a `tool/call` can
+ * arrive before the mode is set. `filterCancellationText` strips "cancelled by cleanup" from progress content
+ * and error text — chatter from a torn-down run a visitor should never see.
+ */
 import type { ChatMessage, InstructionType } from '../types';
 export declare const getModeDisplayName: (mode: InstructionType) => string;
 export declare const formatMessageTime: (date: Date | undefined) => string;
@@ -7,19 +26,17 @@ export interface FindMessageOptions {
     currentMode: InstructionType;
 }
 export declare function lastIndexWhere<T>(items: T[], matches: (item: T) => boolean): number;
-/** Ranked predicates: the first rank matching anything wins, and within it the newest message. */
 export declare function findMessageForProgress({ messages, isTaskRunning, currentMode, }: FindMessageOptions): {
     index: number;
     message: ChatMessage;
 } | null;
-export declare const WAIT_FOR_USER_TOOLS: Set<string>;
 export declare function addProgressLine(message: ChatMessage, browserToolName: string, explanation: string): ChatMessage;
 export declare const markProgressLineComplete: (message: ChatMessage, browserToolName: string) => ChatMessage;
 export declare function markProgressLineFailed(message: ChatMessage, browserToolName: string, error: string): ChatMessage;
-export declare const TOOL_LABELS: Map<string, string>;
-export declare const getFriendlyToolName: (browserToolName: string) => string;
 export declare const createUserMessage: (content: string, mode?: InstructionType, idPrefix?: string) => ChatMessage;
 export declare const createAgentMessage: (content: string) => ChatMessage;
 export declare const createSystemMessage: (content: string, idPrefix: string) => ChatMessage;
+export declare const SCREEN_ACCESS_PROMPT = "Can I take a look at your screen?";
 export declare const createScreenAccessRequestMessage: (mode: InstructionType | undefined, pendingContent?: string) => ChatMessage;
 export declare const createScreenshareMessage: (stream: MediaStream, mode?: InstructionType) => ChatMessage;
+export declare const createPlaceholderMessage: (mode: InstructionType) => ChatMessage;