@marketrix.ai/widget 3.8.492 → 3.8.494

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

@@ -1,3 +1,23 @@
+/**
+ * Colour handling for tenant widget settings: the one home for reading a settings colour into channels,
+ * picking text that reads over it, and re-emitting it with an alpha.
+ *
+ * `toRgb` parses a hex (3- or 6-digit, leading `#` optional — the dashboard accepts both spellings) or an
+ * `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.
+ *
+ * `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
+ * gradient and one declaration covers both spellings. Panel and transcript both paint through it, so there is
+ * no second expansion to drift from.
+ */
 type Rgb = {
     r: number;
     g: number;
@@ -6,4 +26,5 @@ type Rgb = {
 export declare function toRgb(color: string): Rgb | null;
 export declare function getContrastingColor(color: string): string;
 export declare function addOpacity(color: string, opacity: number): string;
+export declare function backgroundGradient(color: string): string;
 export {};

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

@@ -1,3 +1,24 @@
+/**
+ * Predicates the agent's element index runs against the HOST page's DOM — what counts as a control and
+ * whether it is reachable — plus `WIDGET_SHADOW_HOST_CLASS`, set by `bootstrap` on the shadow host so
+ * `DomService` can recognise its own overlay chrome instead of reporting it as obscuring the host page, and
+ * `TABBABLE_SELECTOR`, the one tab-order candidate query: `send_keys`' Tab simulation walks the host page
+ * with it and `useFocusTrap` the widget's own tree, and they must agree on what the browser would focus next.
+ *
+ * `ancestry` walks element → `parentElement`, crossing each shadow boundary at its host; a bare
+ * `parentElement` walk stops dead at a `ShadowRoot`, so a control inside a host-page web component
+ * would read as top-level. `disabledReason` names why an element cannot be operated (disabled control,
+ * `aria-disabled`, or an `inert` ancestor) as a sentence fragment completing `DomService`'s
+ * `Element <n> …` message — reword both together; `disabled` is read duck-typed since it sits on
+ * several unrelated control interfaces. `isIndexable`, checked against `INTERACTIVE_ROLES`, is
+ * `DomService`'s geometry-aware fallback after its cheap selector/handler checks. Visibility there is more
+ * than computed style: an element scrolled out of an `overflow: hidden|clip` ancestor is unreachable despite
+ * a non-zero rect (that walk stops at `document.body`), and a zero-size shadow host hides its whole tree, so
+ * both chains are climbed. Its one `try` is deliberate — the host page owns this DOM and may have patched
+ * anything on it, so a poisoned element is logged with the real error and skipped rather than aborting the
+ * whole indexing pass.
+ */
 export declare const WIDGET_SHADOW_HOST_CLASS = "marketrix-widget-container";
+export declare const TABBABLE_SELECTOR = "a[href], button:not([disabled]), input:not([disabled]), select:not([disabled]), textarea:not([disabled]), [tabindex]:not([tabindex=\"-1\"])";
 export declare function disabledReason(el: Element): string | null;
 export declare function isIndexable(el: Element | null): boolean;

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

@@ -0,0 +1,12 @@
+/**
+ * The one home for turning an unknown throw into something a caller can read. `errorMessage` returns an
+ * `Error`'s message, a thrown string as-is, and `fallback` for anything else — the fallback is a parameter
+ * because a widget-init failure names itself on the host page while a tool failure has nothing better than
+ * "Unknown error". `withCause` wraps a caller-facing message around a throw while retaining the original as
+ * `cause`, so nothing that reports a failure swallows the one underneath it.
+ *
+ * `cause` is assigned rather than passed to the constructor because this package targets es2020, whose
+ * `Error` signature has no options argument.
+ */
+export declare function errorMessage(error: unknown, fallback?: string): string;
+export declare function withCause(message: string, cause: unknown): Error;

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

@@ -1,3 +1,14 @@
+/**
+ * The suggested-action chips the home view offers a visitor: one per tenant-configured `widget_chips`
+ * entry, or the built-in `DEFAULT_CHIPS` when the tenant configured none. `SuggestedActionItem` is what a
+ * chip renders and dispatches as; `getSuggestedActionsFromConfig` maps a `MarketrixConfig`'s chips onto it.
+ *
+ * A chip's caption doubles as the instruction dispatched on click, so a `show`/`do` caption missing its
+ * mode prefix is given one. The strip patterns demand whitespace after the mode word so re-prefixing
+ * cannot eat letters from a caption that merely begins with it ("Download…" stays "Do Download…", not
+ * "Do wnload…"). `tell` captions are free text and take no prefix. The id carries the chip's index
+ * because two chips may share a caption and the slug alone would collide.
+ */
 import type { InstructionType, MarketrixConfig } from '../types';
 export interface SuggestedActionItem {
     id: string;

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

@@ -1,8 +1,27 @@
+/**
+ * Runtime validation of the widget's untrusted inputs: two DOM type guards (`isHTMLElement`, `isHTMLScriptElement`,
+ * narrowing a possibly-null `Element` off a host-page lookup), and the one home for settings validation —
+ * `parseWidgetSettings`, checking a value against the widget audience's `WidgetSettingsData` and returning either
+ * the picked settings or the offending field names, via the per-field predicates behind `FIELD_GUARDS` /
+ * `FIELD_NAMES`. `RENDER_CONSTANT_NAMES` / `RENDER_CONSTANT_SET` name the fields the widget renders from its own
+ * constants; `WidgetRenderedSettings` is the wire shape minus those, `WidgetSettingsResult` the
+ * settings-or-invalidFields union returned, and `invalidSettingsMessage` folds invalid field names into one message.
+ *
+ * Hand-written rather than a zod `safeParse` because importing a schema as a VALUE anywhere reachable from
+ * `src/index.tsx` pulls zod's whole runtime into every host page: rolldown cannot prove `z.object(...)` pure, so
+ * one value import retains the entire mirror's schema graph. `satisfies Record<keyof WidgetSettingsData, …>` keeps
+ * the table honest — a field added api-side fails to compile here until guarded, one removed fails as an unknown
+ * key — and `RENDER_CONSTANT_NAMES` mirrors api's `WIDGET_RENDER_CONSTANTS` by hand under the same check.
+ *
+ * `parseWidgetSettings` PICKS as well as validates: `widgetDefaultGet` returns the render constants too 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
+ * from the picked result, since nothing renders them.
+ */
 import type { WidgetSettingsData } from '../sdk';
 export declare function isHTMLElement(element: Element | null): element is HTMLElement;
 export declare function isHTMLScriptElement(element: Element | null): element is HTMLScriptElement;
 declare const RENDER_CONSTANT_NAMES: readonly ["widget_border_radius", "widget_font_size", "widget_animation_duration", "widget_fade_duration"];
-/** The wire shape minus the fields the widget renders from its own constants — see WIDGET_RENDER_CONSTANTS. */
 export type WidgetRenderedSettings = Omit<WidgetSettingsData, (typeof RENDER_CONSTANT_NAMES)[number]>;
 export type WidgetSettingsResult = {
     settings: WidgetRenderedSettings;
@@ -11,12 +30,6 @@ export type WidgetSettingsResult = {
     settings?: undefined;
     invalidFields: string[];
 };
-/**
- * Validates and PICKS, because stripping is load-bearing: `widgetDefaultGet` returns the render
- * constants too, and the settings object is spread into the widget config — passing unknown keys
- * through would leak them where zod used to drop them. The render constants are guarded (a legacy
- * bundle's stored value must still pass) but dropped from the picked result, since nothing renders them.
- */
 export declare function parseWidgetSettings(value: unknown): WidgetSettingsResult;
 export declare const invalidSettingsMessage: (invalidFields: string[]) => string;
 export {};

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

@@ -1,3 +1,23 @@
+/**
+ * Corner geometry for the widget: the four pinnable corners, the CSS offsets that place launcher and
+ * panel at one, the resize grip each corner implies, and the drag-snap math.
+ *
+ * `getCorner` maps a `WidgetPosition` to its `{vertical, horizontal}` CSS sides. `isWidgetPosition`
+ * narrows an unknown — a value read back out of localStorage — to one of the four, testing a list of
+ * names rather than `in CORNERS`, so the keys every object inherits (`toString`, `__proto__`) are
+ * rejected. `getPanelPositionStyle` turns a corner into the inline style pinning an element to it.
+ * `getResizeGrip`, whose return type is exported as `ResizeGrip`, describes the handle on the corner
+ * diagonally OPPOSITE the pinned one — the panel grows away from its anchor, so that is the only
+ * corner free to move; `growX`/`growY` are the signs converting pointer delta into size delta, and
+ * `cursor` is the diagonal the grip itself lies on. `getAnchorTopLeft` resolves a corner to viewport
+ * top-left pixels so drag math runs in one coordinate space, and `getNearestCornerByTranslation` adds
+ * a drag's translation to that anchor and returns the corner whose own anchor is nearest by
+ * straight-line distance — proximity, never per-axis resolution.
+ *
+ * EDGE_OFFSET_PX is the one edge offset: launcher and panel both position through
+ * `getPanelPositionStyle`, so there is no second declaration to drift from — it used to be pinned
+ * against a Tailwind class string.
+ */
 import type React from 'react';
 import type { WidgetPosition } from '../types';
 export declare const getCorner: (position: WidgetPosition) => {