@marketrix.ai/widget 4.0.123 → 4.0.125

package/dist/src/components/base/Flex.d.ts

@@ -16,7 +16,7 @@ interface FlexProps extends SurfaceProps {
     direction?: 'row' | 'column';
     children?: ReactNode;
 }
-export type StackProps = Omit<FlexProps, 'direction'>;
+type StackProps = Omit<FlexProps, 'direction'>;
 export declare const Flex: import("react").ForwardRefExoticComponent<FlexProps & import("react").RefAttributes<HTMLElement>>;
 export declare const Stack: import("react").ForwardRefExoticComponent<StackProps & import("react").RefAttributes<HTMLElement>>;
 export {};

package/dist/src/components/base/Surface.d.ts

@@ -16,6 +16,12 @@
  * resolving `display` itself because `resolveLayoutStyle` is applied ahead of it. `resolveLayoutStyle`
  * is handed the whole `props` (it reads only layout keys), while the DOM spread goes through
  * `stripLayoutProps` — a layout token left on the props bag reaches the element as an unknown attribute.
+ *
+ * `forwardRef<HTMLElement, SurfaceProps>` is fixed, not generic per `as`: `forwardRef` cannot be made
+ * generic across call sites without its own internal cast, so a caller holding a `RefObject` typed to
+ * its specific element (`HTMLDivElement`, …) casts at the call site instead — `RefObject.current` is
+ * mutable and therefore invariant, so no subtyping relationship lets a `RefObject<HTMLDivElement>` stand
+ * in for `Ref<HTMLElement>` without one. `WidgetFab.tsx`, `MessageList.tsx` (×2) are the three sites.
  */
 import { type ElementType } from 'react';
 import { type ShadowToken } from '../../design-system/component-tokens';

package/dist/src/components/blocks/WidgetFab.d.ts

@@ -13,12 +13,15 @@
  * unify both). Pointer state is 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 into `velocityHistoryRef` so a flick
  * lands where it was heading — `projectFlickVelocity` (module-level, pure) turns that sample history into
- * a projected pixel delta. On release
+ * a projected pixel delta: zero with fewer than two samples, else the average px/ms over the sampled span
+ * projected forward in px/s. 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,
+ * (`abandonSnapRef`), which the unmount effect also calls so a snap animating when the widget is torn
+ * down does not leave its `transitionend` listener and fallback timer running past the component's life.
+ * `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. Exported so `WidgetFab.test.tsx`'s `renderHook` case can drive it directly.

package/dist/src/components/chat/MessageItem.d.ts

@@ -21,7 +21,7 @@
  * more work is coming; a message with no parts at all falls back to a bare `Surface`.
  */
 import React from 'react';
-import type { ChatMessage } from '../../types';
+import { type ChatMessage } from '../../types';
 interface MessageItemProps {
     message: ChatMessage;
     isLastMessage: boolean;

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

@@ -17,6 +17,12 @@
  * which carries no task id. Every failure on the tool and stop paths reaches `uiActions.setError` as well
  * as the console: an undelivered `tool/response` leaves the agent waiting on a reply that never comes, so
  * the run stalls with nothing on screen unless the visitor is told, and `do` mode may still be clicking.
+ *
+ * `event.type === 'task/status' && isTerminalTaskStatus(event.status)` reads `event.status` on every
+ * branch, but only the `task/status` variant of `WidgetEvent` carries a `status` field at all — on any
+ * other event it is `undefined`, which `isTerminalTaskStatus` (an `in` check against the status map)
+ * always reports as non-terminal. The `&&` can never observably differ from an `||` here; it stays `&&`
+ * because that is what a reader expects a type-narrowing guard to say.
  */
 import React from 'react';
 import type { ChatMessage, InstructionType } from '../types';

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

@@ -1,16 +1,14 @@
 /**
  * `UIStateProvider` / `useUIStateContext` — the widget's view state: open/closed, active view, current
  * mode (tell/show/do) and the error banner. Actions are stable (memoised once) so consumers can depend
- * on them without re-rendering; `applyState` merges a partial for restore-from-storage.
+ * on them without re-rendering; `applyState` merges a partial for restore-from-storage. `UIState` is a
+ * `Pick` of the public `WidgetState` (`../types`) rather than its own duplicate shape, and stays
+ * unexported — it never needs to be named outside this file, and `applyState`'s declaration-file
+ * emission resolves through the already-exported `WidgetState` instead.
  */
 import React from 'react';
-import type { InstructionType, WidgetView } from '../types';
-export interface UIState {
-    isOpen: boolean;
-    activeView: WidgetView;
-    currentMode: InstructionType;
-    error?: string | undefined;
-}
+import type { InstructionType, WidgetState, WidgetView } from '../types';
+type UIState = Pick<WidgetState, 'isOpen' | 'activeView' | 'currentMode' | 'error'>;
 interface UIStateActions {
     setActiveView: (view: WidgetView) => void;
     toggleWidget: () => void;

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

@@ -24,7 +24,7 @@
  * closed is noise, which is what a duplicated `chat/response` looks like.
  */
 import type { WidgetEvent } from '../sdk';
-import { type ChatMessage, type InstructionType } from '../types';
+import type { ChatMessage, InstructionType } from '../types';
 type TaskPhase = 'idle' | 'running' | 'stopped';
 export interface TaskState {
     phase: TaskPhase;
@@ -42,7 +42,7 @@ export interface SseEffect {
     mode: InstructionType;
     explanation: string;
 }
-interface ReduceResult {
+export interface ReduceResult {
     state: SseState;
     effects: SseEffect[];
 }

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

@@ -6,6 +6,11 @@
  * 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.
  *
+ * Every `notificationToneStyles` colour is fixed (no tenant setting touches a toast), so each pair is
+ * measured once here against the WCAG threshold it actually needs — `closeColor` is a UI icon (3:1
+ * against `background`), `titleColor`/`bodyColor` are text (4.5:1) — and a test pins every ratio so a
+ * future palette edit can't silently regress below it.
+ *
  * `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. `showHighlight`/`showPopup` are a separate, much higher pair near the int32 ceiling: Show

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

@@ -10,6 +10,14 @@
  * settings object against those defaults and derives the muted/faint/hover/contrast variants;
  * `semanticTokensToCssCustomProperties`, the token → `--var` map.
  *
+ * `color.ring` is NOT the raw accent — a customer's `widget_accent_color` has no contrast guarantee
+ * against whatever it sits next to (WCAG 2.4.11/1.4.11 need the focus indicator ≥3:1 against the colours
+ * adjacent to it on both sides), so it is `getContrastingColor(widget_background_color)`, the same
+ * black/white pick `primaryForeground`/`secondaryForeground` use. `index.css` pairs it with
+ * `--ring-offset` (the background colour itself) as a two-tone ring: an inset halo matching the surface,
+ * then the ring outside it, so both sides of the ring measure against the one colour it is guaranteed to
+ * clear against, whatever the outlined control's own colour is.
+ *
  * 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
@@ -31,6 +39,7 @@ type SemanticTokens = {
         secondaryForeground: string;
         secondaryBg: string;
         secondaryHover: string;
+        ring: string;
     };
     radius: string;
     motion: {

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

@@ -0,0 +1 @@
+export declare function useLatest<T>(value: T): React.RefObject<T>;

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

@@ -29,6 +29,11 @@ export declare const useWidget: () => {
         closeWidget: () => void;
         setMode: (mode: import("..").InstructionType) => void;
         setError: (error: string | undefined) => void;
-        applyState: (payload: Partial<import("../context/UIStateContext").UIState>) => void;
+        applyState: (payload: Partial<{
+            error?: string | undefined | undefined;
+            currentMode: import("..").InstructionType;
+            isOpen: boolean;
+            activeView: import("../types").WidgetView;
+        }>) => void;
     };
 };

package/dist/src/index.d.ts

@@ -3,7 +3,8 @@
  * 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;
+ * recorder, screen share, any in-flight show-mode overlay (which owns host-page listeners and DOM
+ * nodes outside the shadow root, so it does not go with `active.instance.unmount()`) 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.
  *
@@ -38,7 +39,7 @@ export { getCurrentConfig };
 export declare const MarketrixWidgetPreview: React.FC<MarketrixWidgetPreviewProps>;
 export declare const mountWidget: (config: AddWidgetConfig) => Promise<void>;
 export type { InstructionType } from './sdk';
-export type { AddWidgetConfig, ChatMessage, ClientOwnedConfig, MarketrixConfig, MarketrixWidgetPreviewProps, WidgetState, } from './types';
+export type { AddWidgetConfig, ChatMessage, ClientOwnedConfig, MarketrixConfig, MarketrixWidgetPreviewProps, WidgetSettingsData, WidgetState, } from './types';
 declare const _default: {
     MarketrixWidgetPreview: React.FC<MarketrixWidgetPreviewProps>;
     mountWidget: (config: AddWidgetConfig) => Promise<void>;

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

@@ -17,6 +17,10 @@
  * 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.
+ *
+ * `scrollToText`'s walker only ever yields a Text node from inside `document.body`'s tree, so
+ * `node.parentElement` is never null there — the optional-chained read is for TypeScript, not a runtime
+ * branch this loop can take.
  */
 import type { InstructionType } from '../types';
 interface TextData {

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

@@ -7,9 +7,9 @@
  * That is why `StreamClient.ready` must resolve BEFORE the POST: registration is what gives the reply
  * somewhere to land.
  *
- * The `widget_question` activity-log row is no longer filed from here — `StreamClient` sends `user_id`
+ * `ChatService` never files the `widget_question` activity-log row itself: `StreamClient` sends `user_id`
  * once, at `widgetStream` registration, and the api derives the row from `chat_id`'s bound application on
- * every Tell/Show/Do command, so a per-message credential re-send is gone.
+ * every Tell/Show/Do command, so no per-message credential re-send is needed here.
  */
 import type { InstructionType } from '../sdk';
 export declare function chatPost(message: string, mode: InstructionType, requestId: string): Promise<void>;

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

@@ -20,6 +20,12 @@
  * `ACCENT_COLOR`/`TEXT_COLOR` are raw literals rather than design-system tokens: the highlight and popup
  * mount to `document.body` on the HOST page, outside the shadow root, so `index.css`'s `:host`-scoped
  * CSS custom properties never reach them.
+ *
+ * `trackElement`'s `!this.currentElement || !this.currentHighlight` and the click handler's
+ * `!this.currentElement || !this.resolvePromise` cannot observe a mixed state: `showToolAction` sets
+ * every one of these fields together and `cleanup` clears every one of them together, so within a
+ * single stage they are always all-null or all-set. The guards stay as defensive redundancy against a
+ * future edit that breaks that pairing, not because either can independently be null today.
  */
 interface ShowModeOptions {
     element: HTMLElement;

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

@@ -15,18 +15,23 @@
  * another's.
  *
  * The chat 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".
+ * excluded. `StoredMessage` is the ONE place `content` still exists as a field: a live `ChatMessage` has
+ * none (every reader derives `messageText(parts)` instead), but a transcript written before `parts`
+ * existed has only `content` on disk, so `readChatSnapshot` backfills a text part from it and
+ * `writeChatSnapshot` derives `content` back from `parts` on the way out, keeping the persisted shape
+ * readable by an older widget version without carrying the redundant field in memory. Reading also
+ * revives `timestamp` to a `Date`; writing drops `videoStream` (unserializable, dead on reload),
+ * rewriting it as "Screen sharing ended".
  *
  * `sanitizeStoredContext` is hand-rolled, not zod, per the package-level rule that a schema imported as a
  * VALUE anywhere reachable from `src/index.tsx` pulls zod's whole runtime into the bundle. Each field
  * falls back to `DEFAULT_CONTEXT`'s value individually, so a partially-corrupt payload keeps the fields
  * that DID parse rather than discarding the whole context.
  */
-import type { ChatMessage, InstructionType, MarketrixConfig, ValidWidgetConfig } from '../types';
+import { type ChatMessage, type InstructionType, type MarketrixConfig, type ValidWidgetConfig } from '../types';
 type StoredMessage = Omit<ChatMessage, 'videoStream' | 'timestamp'> & {
     timestamp: string;
+    content: string;
 };
 export interface ChatSnapshot {
     messages: ChatMessage[];

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

@@ -17,6 +17,11 @@
  * 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.
+ *
+ * `send` never turns its own POST failure into a user-facing `onError` — the raw failure (network cause, a
+ * 4xx/5xx body) goes only to `logWarn`, since every caller already reports its own human sentence on the
+ * same catch (`ChatContext`'s message/tool-response/stop paths); notifying here too would have shown the
+ * caller's visitor a second, raw-text toast racing the first.
  */
 import { type WidgetCommand, type WidgetEvent } from '../sdk';
 export declare class StreamGaveUpError extends Error {

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

@@ -15,8 +15,10 @@
  * `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.
+ * vocabulary (`task/status.status`). `messageText` joins text parts and IS the text — `ChatMessage` has
+ * no `content` field of its own; a render site calls `messageText(msg.parts)` directly. The one
+ * exception is `StorageService`'s persisted `StoredMessage`, which keeps its own `content` string to
+ * migrate a transcript stored before `parts` existed — see that file's header.
  */
 import type { InstructionType, WidgetSettingsData } from '../sdk';
 import type { WidgetRenderedSettings } from '../utils/validation';
@@ -37,7 +39,6 @@ export type MarketrixConfig = Partial<WidgetRenderedSettings> & ClientOwnedConfi
 export type ValidWidgetConfig = MarketrixConfig & Required<Pick<MarketrixConfig, keyof WidgetRenderedSettings | 'isPreviewMode'>>;
 export interface ChatMessage {
     id: string;
-    content: string;
     sender: 'user' | 'agent';
     timestamp: Date;
     mode?: InstructionType | undefined;

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

@@ -3,10 +3,14 @@
  * `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`
+ * the ONLY way a `ChatMessage` is built: ids are `<prefix>-<uuid>` since two messages minted in the same millisecond
+ * would otherwise 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.
+ * `CHAT_FAILURE_TEXT` is the one human sentence for "the assistant could not process that turn" —
+ * `ChatContext`'s message-post catch and `sseReducer`'s `chat/error` case both settle a bubble with it
+ * rather than the raw POST failure or the raw server `error` string, which may carry request/response
+ * internals a visitor must never see.
  *
  * `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
@@ -37,7 +41,8 @@ export declare const createUserMessage: (content: string, mode?: InstructionType
 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 CHAT_FAILURE_TEXT = "I'm sorry, I encountered an error processing your request. Please try again.";
 export declare const createScreenAccessRequestMessage: (mode: InstructionType | undefined, pendingContent?: string) => ChatMessage;
-export declare const createScreenshareMessage: (stream: MediaStream, mode?: InstructionType) => ChatMessage;
+export declare const createScreenshareMessage: (stream: MediaStream) => ChatMessage;
 export declare const createPlaceholderMessage: (mode: InstructionType) => ChatMessage;
 export {};

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

@@ -6,12 +6,17 @@
  * `rgb()`/`rgba()` string into channels, and returns null for anything else. Only those two notations are
  * read: a named colour, `hsl()` or a `var(--…)` custom property is unreadable here by design, and a channel
  * above 255 is refused rather than clamped, so a malformed setting never silently becomes a valid colour.
- * `getContrastingColor` picks the black or white foreground for a background from that colour's WCAG
- * relative luminance — sRGB gamma-decoded per channel, weighted .2126/.7152/.0722, split at 0.5. An
- * unreadable background falls back to BLACK, never white: tenant surfaces skew light, so black stays
- * legible where white would vanish. `addOpacity` re-emits a colour as `rgba()` at the given alpha and
- * passes an unreadable one through UNCHANGED — it stays a CSS value the browser can still resolve, where
- * an `rgba(NaN, …)` would render nothing.
+ * `contrastRatio` is the one home for the WCAG formula — relative luminance is sRGB gamma-decoded per
+ * channel, weighted .2126/.7152/.0722, and the ratio is `(lighter + 0.05) / (darker + 0.05)`.
+ * `getContrastingColor` picks whichever of black or white scores higher against it: this is the single
+ * place a tenant colour without its own paired foreground setting (a button's accent, a status pill)
+ * gets one synthesized, and comparing the two ratios directly (rather than a `luminance > 0.5` split,
+ * whose crossover sits at ≈0.179, not 0.5) means every synthesized foreground clears the AA 4.5:1
+ * threshold by construction — the higher of the two ratios is never below ~4.6:1. An unreadable
+ * background falls back to BLACK, never white: tenant surfaces skew light, so black stays legible where
+ * white would vanish. `addOpacity` re-emits a colour as `rgba()` at the given alpha and passes an
+ * unreadable one through UNCHANGED — it stays a CSS value the browser can still resolve, where an
+ * `rgba(NaN, …)` would render nothing.
  *
  * `backgroundGradient` is the one home for `widget_background_color` as a `backgroundImage`: the setting may
  * already be a gradient, which is legal only as `backgroundImage`, so a flat colour is emitted as a same-stop
@@ -24,6 +29,7 @@ type Rgb = {
     b: number;
 };
 export declare function toRgb(color: string): Rgb | null;
+export declare function contrastRatio(a: string, b: string): number | null;
 export declare function getContrastingColor(color: string): string;
 export declare function addOpacity(color: string, opacity: number): string;
 export declare function backgroundGradient(color: string): string;

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

@@ -14,8 +14,8 @@
  * key — and `RENDER_CONSTANT_NAMES` mirrors api's `WIDGET_RENDER_CONSTANTS` by hand under the same check.
  *
  * `parseWidgetSettings` PICKS as well as validates: a widget's settings arrive carrying the render constants and the
- * result is spread into the widget config, so unknown keys passing through would leak them where zod used to drop
- * them. Render constants stay guarded, since a legacy bundle's stored value must keep passing, but are dropped
+ * result is spread into the widget config, so unknown keys passing through would leak them where a zod-parsed
+ * object would drop them. Render constants stay guarded, since a legacy bundle's stored value must keep passing, but are dropped
  * from the picked result, since nothing renders them.
  */
 import type { WidgetSettingsData } from '../sdk';