@revturbine/sdk 0.7.13 → 0.8.0

package/dist/types/web-sdk/placements/FixedSurfaceSlot.d.ts

@@ -23,11 +23,22 @@ export type FixedSurfaceSlotProps = {
     personalization?: PersonalizationContext;
     registry?: PlacementTypeRegistry;
     onCtaClick?: (uiPath: PlacementUiPath) => void;
+    /**
+     * Called after the user dismisses the placement (plan 233 TASK-9).
+     *
+     * `MessageSurfaceSlot` advertised this prop but never fired it — the handler
+     * was built and then discarded. It is wired for both slots now.
+     */
+    onDismissed?: () => void;
     className?: string;
     style?: React.CSSProperties;
     /**
-     * Content to display when no placement decision matches.
-     * Fixed slots always render something — either a placement or the fallback.
+     * Content to display when **no placement matches**.
+     *
+     * NOT shown after the user dismisses. Rendering the fallback on dismissal
+     * puts something back in the space the user just closed — the escalated
+     * integration called it a ghost popup and needed a MutationObserver to
+     * suppress it (plan 233 TASK-9).
      */
     fallback?: React.ReactNode;
 };
@@ -49,7 +60,7 @@ export type FixedSurfaceSlotProps = {
  * />
  * ```
  */
-export declare function FixedSurfaceSlot({ id, name, surfaceTemplateIds, metadata, fallback, ...options }: FixedSurfaceSlotProps): React.JSX.Element;
+export declare function FixedSurfaceSlot({ id, name, surfaceTemplateIds, metadata, fallback, ...options }: FixedSurfaceSlotProps): React.JSX.Element | null;
 export declare namespace FixedSurfaceSlot {
     var displayName: string;
 }

package/dist/types/web-sdk/placements/FixedSurfaceSlot.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"FixedSurfaceSlot.d.ts","sourceRoot":"","sources":["../../../../placements/FixedSurfaceSlot.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAkB,MAAM,OAAO,CAAC;AACvC,OAAO,KAAK,EAAE,sBAAsB,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AACvE,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AACxD,OAAO,KAAK,EACV,qBAAqB,EACrB,oCAAoC,EAErC,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EAAE,0BAA0B,EAAE,MAAM,0BAA0B,CAAC;AAEtE,OAAO,EAAE,0BAA0B,EAAE,CAAC;AAEtC,MAAM,MAAM,qBAAqB,GAAG;IAClC,uDAAuD;IACvD,EAAE,EAAE,MAAM,CAAC;IACX,uEAAuE;IACvE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;OAGG;IACH,kBAAkB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC9B,uEAAuE;IACvE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC,WAAW,CAAC,EAAE,qBAAqB,CAAC;IACpC,SAAS,CAAC,EAAE,oCAAoC,CAAC;IACjD,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,CAAC;IACnD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,eAAe,CAAC,EAAE,sBAAsB,CAAC;IACzC,QAAQ,CAAC,EAAE,qBAAqB,CAAC;IACjC,UAAU,CAAC,EAAE,CAAC,MAAM,EAAE,eAAe,KAAK,IAAI,CAAC;IAC/C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,KAAK,CAAC,aAAa,CAAC;IAC5B;;;OAGG;IACH,QAAQ,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;CAC5B,CAAC;AAEF;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,gBAAgB,CAAC,EAC/B,EAAE,EACF,IAAI,EACJ,kBAA2D,EAC3D,QAAQ,EACR,QAAe,EACf,GAAG,OAAO,EACX,EAAE,qBAAqB,qBAuBvB;yBA9Be,gBAAgB"}
+{"version":3,"file":"FixedSurfaceSlot.d.ts","sourceRoot":"","sources":["../../../../placements/FixedSurfaceSlot.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAkB,MAAM,OAAO,CAAC;AACvC,OAAO,KAAK,EAAE,sBAAsB,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AACvE,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AACxD,OAAO,KAAK,EACV,qBAAqB,EACrB,oCAAoC,EAErC,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EAAE,0BAA0B,EAAE,MAAM,0BAA0B,CAAC;AAEtE,OAAO,EAAE,0BAA0B,EAAE,CAAC;AAEtC,MAAM,MAAM,qBAAqB,GAAG;IAClC,uDAAuD;IACvD,EAAE,EAAE,MAAM,CAAC;IACX,uEAAuE;IACvE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;OAGG;IACH,kBAAkB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC9B,uEAAuE;IACvE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC,WAAW,CAAC,EAAE,qBAAqB,CAAC;IACpC,SAAS,CAAC,EAAE,oCAAoC,CAAC;IACjD,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,CAAC;IACnD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,eAAe,CAAC,EAAE,sBAAsB,CAAC;IACzC,QAAQ,CAAC,EAAE,qBAAqB,CAAC;IACjC,UAAU,CAAC,EAAE,CAAC,MAAM,EAAE,eAAe,KAAK,IAAI,CAAC;IAC/C;;;;;OAKG;IACH,WAAW,CAAC,EAAE,MAAM,IAAI,CAAC;IACzB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,KAAK,CAAC,aAAa,CAAC;IAC5B;;;;;;;OAOG;IACH,QAAQ,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;CAC5B,CAAC;AAEF;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,gBAAgB,CAAC,EAC/B,EAAE,EACF,IAAI,EACJ,kBAA2D,EAC3D,QAAQ,EACR,QAAe,EACf,GAAG,OAAO,EACX,EAAE,qBAAqB,4BA4BvB;yBAnCe,gBAAgB"}

package/dist/types/web-sdk/placements/MessageSurfaceSlot.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"MessageSurfaceSlot.d.ts","sourceRoot":"","sources":["../../../../placements/MessageSurfaceSlot.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAkD,MAAM,OAAO,CAAC;AACvE,OAAO,KAAK,EAAE,sBAAsB,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AACvE,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AACxD,OAAO,KAAK,EACV,qBAAqB,EACrB,oCAAoC,EAEpC,eAAe,EAChB,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EAAE,4BAA4B,EAAE,MAAM,0BAA0B,CAAC;AAExE,OAAO,EAAE,4BAA4B,EAAE,CAAC;AAIxC;;;;;;GAMG;AACH,MAAM,MAAM,kBAAkB,GAAG,UAAU,GAAG,UAAU,GAAG,aAAa,CAAC;AAEzE,MAAM,MAAM,uBAAuB,GAAG;IACpC,uDAAuD;IACvD,EAAE,EAAE,MAAM,CAAC;IACX,uEAAuE;IACvE,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,kBAAkB,CAAC;IAE7B;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;;OAGG;IACH,kBAAkB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC9B,uEAAuE;IACvE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC,WAAW,CAAC,EAAE,qBAAqB,CAAC;IACpC,SAAS,CAAC,EAAE,oCAAoC,CAAC;IACjD,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,CAAC;IACnD,eAAe,CAAC,EAAE,sBAAsB,CAAC;IACzC,QAAQ,CAAC,EAAE,qBAAqB,CAAC;IACjC,UAAU,CAAC,EAAE,CAAC,MAAM,EAAE,eAAe,KAAK,IAAI,CAAC;IAC/C,sDAAsD;IACtD,WAAW,CAAC,EAAE,CAAC,SAAS,EAAE,eAAe,KAAK,IAAI,CAAC;IACnD,8CAA8C;IAC9C,WAAW,CAAC,EAAE,MAAM,IAAI,CAAC;IACzB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,KAAK,CAAC,aAAa,CAAC;CAC7B,CAAC;AAEF,MAAM,MAAM,qBAAqB,GAAG;IAClC,mFAAmF;IACnF,YAAY,EAAE,MAAM,IAAI,CAAC;IACzB,oCAAoC;IACpC,OAAO,EAAE,MAAM,IAAI,CAAC;CACrB,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,eAAO,MAAM,kBAAkB,uGAwF7B,CAAC"}
+{"version":3,"file":"MessageSurfaceSlot.d.ts","sourceRoot":"","sources":["../../../../placements/MessageSurfaceSlot.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAkD,MAAM,OAAO,CAAC;AACvE,OAAO,KAAK,EAAE,sBAAsB,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AACvE,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AACxD,OAAO,KAAK,EACV,qBAAqB,EACrB,oCAAoC,EAEpC,eAAe,EAChB,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EAAE,4BAA4B,EAAE,MAAM,0BAA0B,CAAC;AAExE,OAAO,EAAE,4BAA4B,EAAE,CAAC;AAIxC;;;;;;GAMG;AACH,MAAM,MAAM,kBAAkB,GAAG,UAAU,GAAG,UAAU,GAAG,aAAa,CAAC;AAEzE,MAAM,MAAM,uBAAuB,GAAG;IACpC,uDAAuD;IACvD,EAAE,EAAE,MAAM,CAAC;IACX,uEAAuE;IACvE,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,kBAAkB,CAAC;IAE7B;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;;OAGG;IACH,kBAAkB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC9B,uEAAuE;IACvE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC,WAAW,CAAC,EAAE,qBAAqB,CAAC;IACpC,SAAS,CAAC,EAAE,oCAAoC,CAAC;IACjD,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,CAAC;IACnD,eAAe,CAAC,EAAE,sBAAsB,CAAC;IACzC,QAAQ,CAAC,EAAE,qBAAqB,CAAC;IACjC,UAAU,CAAC,EAAE,CAAC,MAAM,EAAE,eAAe,KAAK,IAAI,CAAC;IAC/C,sDAAsD;IACtD,WAAW,CAAC,EAAE,CAAC,SAAS,EAAE,eAAe,KAAK,IAAI,CAAC;IACnD,8CAA8C;IAC9C,WAAW,CAAC,EAAE,MAAM,IAAI,CAAC;IACzB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,KAAK,CAAC,aAAa,CAAC;CAC7B,CAAC;AAEF,MAAM,MAAM,qBAAqB,GAAG;IAClC,mFAAmF;IACnF,YAAY,EAAE,MAAM,IAAI,CAAC;IACzB,oCAAoC;IACpC,OAAO,EAAE,MAAM,IAAI,CAAC;CACrB,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,eAAO,MAAM,kBAAkB,uGAkF7B,CAAC"}

package/dist/types/web-sdk/placements/useSurfaceSlot.d.ts

@@ -23,14 +23,38 @@ export type UseSurfaceSlotOptions = {
     acceptedComponentTypes?: readonly RevTurbineComponentType[];
     /** Callback when CTA is clicked. Receives the parsed ui_path. */
     onCtaClick?: (uiPath: PlacementUiPath) => void;
+    /**
+     * Called after the user dismisses the placement (plan 233 TASK-9).
+     *
+     * Fires once per dismissal, after the interaction is recorded.
+     */
+    onDismissed?: () => void;
     /** Custom CSS class for the rendered placement. */
     className?: string;
     /** Custom inline styles for the rendered placement. */
     style?: React.CSSProperties;
 };
+/**
+ * Why a slot is rendering nothing.
+ *
+ * `null` while visible. The distinction matters because a slot that always
+ * renders `fallback` when `!visible` shows its fallback content the instant the
+ * user dismisses — a "ghost" that reappears in place of the thing just closed.
+ * The escalated integration needed three attempts and a MutationObserver to
+ * work around it (plan 233 TASK-9).
+ *
+ * @public
+ */
+export type SurfaceSlotHiddenReason = 'dismissed' | 'no_match' | null;
 export type UseSurfaceSlotResult = UsePlacementResult & {
     /** Pre-built React element that renders the placement using the correct slot type. */
     element: React.ReactNode;
+    /**
+     * Why nothing is rendering — `'dismissed'`, `'no_match'`, or `null` when
+     * visible. Lets a slot distinguish "the user closed this" from "nothing
+     * matched", which are the same `visible: false` but want opposite UI.
+     */
+    hiddenReason: SurfaceSlotHiddenReason;
 };
 /**
  * Hook that combines `usePlacement` decision loading with automatic

package/dist/types/web-sdk/placements/useSurfaceSlot.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useSurfaceSlot.d.ts","sourceRoot":"","sources":["../../../../placements/useSurfaceSlot.tsx"],"names":[],"mappings":"AAEA,OAAO,KAA+B,MAAM,OAAO,CAAC;AACpD,OAAO,KAAK,EACV,qBAAqB,EACrB,oCAAoC,EACpC,2BAA2B,EAC3B,uBAAuB,EACxB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAgB,KAAK,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAE9E,OAAO,KAAK,EAAE,sBAAsB,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AACnF,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAC;AAGpE,MAAM,MAAM,qBAAqB,GAAG;IAClC,WAAW,EAAE,2BAA2B,CAAC;IACzC,WAAW,CAAC,EAAE,qBAAqB,CAAC;IACpC,SAAS,CAAC,EAAE,oCAAoC,CAAC;IACjD,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,CAAC;IACnD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;OAIG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,wEAAwE;IACxE,eAAe,CAAC,EAAE,sBAAsB,CAAC;IACzC,gDAAgD;IAChD,QAAQ,CAAC,EAAE,qBAAqB,CAAC;IACjC,4DAA4D;IAC5D,sBAAsB,CAAC,EAAE,SAAS,uBAAuB,EAAE,CAAC;IAC5D,iEAAiE;IACjE,UAAU,CAAC,EAAE,CAAC,MAAM,EAAE,eAAe,KAAK,IAAI,CAAC;IAC/C,mDAAmD;IACnD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,uDAAuD;IACvD,KAAK,CAAC,EAAE,KAAK,CAAC,aAAa,CAAC;CAC7B,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG,kBAAkB,GAAG;IACtD,sFAAsF;IACtF,OAAO,EAAE,KAAK,CAAC,SAAS,CAAC;CAC1B,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,qBAAqB,GAAG,oBAAoB,CAuGnF"}
+{"version":3,"file":"useSurfaceSlot.d.ts","sourceRoot":"","sources":["../../../../placements/useSurfaceSlot.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAiD,MAAM,OAAO,CAAC;AACtE,OAAO,KAAK,EACV,qBAAqB,EACrB,oCAAoC,EACpC,2BAA2B,EAC3B,uBAAuB,EACxB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAgB,KAAK,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAE9E,OAAO,KAAK,EAAE,sBAAsB,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AACnF,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAC;AAGpE,MAAM,MAAM,qBAAqB,GAAG;IAClC,WAAW,EAAE,2BAA2B,CAAC;IACzC,WAAW,CAAC,EAAE,qBAAqB,CAAC;IACpC,SAAS,CAAC,EAAE,oCAAoC,CAAC;IACjD,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,CAAC;IACnD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;OAIG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,wEAAwE;IACxE,eAAe,CAAC,EAAE,sBAAsB,CAAC;IACzC,gDAAgD;IAChD,QAAQ,CAAC,EAAE,qBAAqB,CAAC;IACjC,4DAA4D;IAC5D,sBAAsB,CAAC,EAAE,SAAS,uBAAuB,EAAE,CAAC;IAC5D,iEAAiE;IACjE,UAAU,CAAC,EAAE,CAAC,MAAM,EAAE,eAAe,KAAK,IAAI,CAAC;IAC/C;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,IAAI,CAAC;IACzB,mDAAmD;IACnD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,uDAAuD;IACvD,KAAK,CAAC,EAAE,KAAK,CAAC,aAAa,CAAC;CAC7B,CAAC;AAEF;;;;;;;;;;GAUG;AACH,MAAM,MAAM,uBAAuB,GAAG,WAAW,GAAG,UAAU,GAAG,IAAI,CAAC;AAEtE,MAAM,MAAM,oBAAoB,GAAG,kBAAkB,GAAG;IACtD,sFAAsF;IACtF,OAAO,EAAE,KAAK,CAAC,SAAS,CAAC;IACzB;;;;OAIG;IACH,YAAY,EAAE,uBAAuB,CAAC;CACvC,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,qBAAqB,GAAG,oBAAoB,CAiInF"}

package/dist/types/web-sdk/react/InitFailureDiagnostic.d.ts

@@ -0,0 +1,35 @@
+import React from 'react';
+import type { RevTurbineInitStatus } from './init-status';
+/**
+ * Development-only visual surface for a failed SDK initialization.
+ *
+ * Plan 233 TASK-2. The provider renders this beside `children` when init threw
+ * and the build is not production. It exists because the app renders correctly
+ * without RevTurbine **by design** — a failed init changes nothing a developer
+ * can see, so the only prior signal was one `console.error` line competing with
+ * everything else in the log. That cost a customer 36 hours.
+ *
+ * Deliberately self-contained: inline styles, no theme tokens, no portal. The
+ * theme itself resolves during init, so a diagnostic that depended on it would
+ * be least reliable exactly when it is needed. It must never throw — a crashing
+ * error reporter is worse than none.
+ *
+ * @public
+ */
+export interface InitFailureDiagnosticProps {
+    /** The failed status. Rendering is the caller's decision; this only draws. */
+    status: RevTurbineInitStatus;
+}
+/**
+ * Render a development-only banner describing a failed SDK initialization.
+ *
+ * Returns `null` for a healthy status, so the caller can render it
+ * unconditionally in development without branching.
+ *
+ * @public
+ */
+export declare function InitFailureDiagnostic({ status }: InitFailureDiagnosticProps): React.JSX.Element | null;
+export declare namespace InitFailureDiagnostic {
+    var displayName: string;
+}
+//# sourceMappingURL=InitFailureDiagnostic.d.ts.map

package/dist/types/web-sdk/react/InitFailureDiagnostic.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"InitFailureDiagnostic.d.ts","sourceRoot":"","sources":["../../../../react/InitFailureDiagnostic.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,MAAM,OAAO,CAAC;AAC1B,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AAE1D;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,0BAA0B;IACzC,8EAA8E;IAC9E,MAAM,EAAE,oBAAoB,CAAC;CAC9B;AAuBD;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,EAAE,MAAM,EAAE,EAAE,0BAA0B,4BA2B3E;yBA3Be,qBAAqB"}

package/dist/types/web-sdk/react/RevTurbineProvider.d.ts

@@ -1,10 +1,11 @@
 import React from 'react';
-import { type RevTurbineInitInputOptions, type RevTurbinePlacementConfig, type RevTurbinePlacementDecisionInput, type RevTurbineUserContext, type Exact } from '../customer-side';
+import { type RevTurbineInitInputOptions, type RevTurbinePlacementConfig, type RevTurbinePlacementDecisionInput, type RevTurbineUserContext, type Exact, type ExactInitOptions } from '../customer-side';
+import { type RevTurbineColorScheme } from '../theme/defaults';
 import { type AnnotatedCaptureOptions } from '../telemetry';
 type BootstrapPlacementInput = Omit<RevTurbinePlacementDecisionInput, 'placementId'> & {
     placement: RevTurbinePlacementConfig;
 };
-export type RevTurbineProviderProps<TUser extends RevTurbineUserContext = RevTurbineUserContext> = {
+export type RevTurbineProviderProps<TUser extends RevTurbineUserContext = RevTurbineUserContext, TOptions extends RevTurbineInitInputOptions = RevTurbineInitInputOptions> = {
     /**
      * SDK initialization options. Accepts optional provider or factory.
      *
@@ -14,7 +15,7 @@ export type RevTurbineProviderProps<TUser extends RevTurbineUserContext = RevTur
      * in an un-annotated `useMemo`, which is precisely where TypeScript's own
      * excess-property check stops applying.
      */
-    options: RevTurbineInitInputOptions & {
+    options: TOptions & ExactInitOptions<TOptions> & {
         user?: Exact<RevTurbineUserContext, TUser>;
     };
     /** Placements to bootstrap (preload decisions) on mount. */
@@ -29,6 +30,19 @@ export type RevTurbineProviderProps<TUser extends RevTurbineUserContext = RevTur
      * Omit to disable. Memoize an object value to avoid re-installing.
      */
     domCapture?: boolean | AnnotatedCaptureOptions;
+    /**
+     * Light/dark palette for rendered placements (plan 233 TASK-6).
+     *
+     * Deliberately a provider prop rather than an SDK init option: `options`
+     * identity drives re-initialization, so a scheme toggle placed there would
+     * rebuild the SDK on every switch. That was the customer workaround this
+     * replaces. Defaults to `'system'`, which follows `prefers-color-scheme` and
+     * keeps following it.
+     *
+     * A branding theme still applies on top — the scheme only selects which base
+     * palette its tokens merge over.
+     */
+    colorScheme?: RevTurbineColorScheme;
     /** React children. */
     children: React.ReactNode;
 };
@@ -47,6 +61,6 @@ export type RevTurbineProviderProps<TUser extends RevTurbineUserContext = RevTur
  * </RevTurbineProvider>
  * ```
  */
-export declare function RevTurbineProvider<TUser extends RevTurbineUserContext = RevTurbineUserContext>({ options, bootstrapPlacements, domCapture, children, }: RevTurbineProviderProps<TUser>): React.JSX.Element;
+export declare function RevTurbineProvider<TUser extends RevTurbineUserContext = RevTurbineUserContext, TOptions extends RevTurbineInitInputOptions = RevTurbineInitInputOptions>({ options, bootstrapPlacements, domCapture, colorScheme, children, }: RevTurbineProviderProps<TUser, TOptions>): React.JSX.Element;
 export {};
 //# sourceMappingURL=RevTurbineProvider.d.ts.map

package/dist/types/web-sdk/react/RevTurbineProvider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"RevTurbineProvider.d.ts","sourceRoot":"","sources":["../../../../react/RevTurbineProvider.tsx"],"names":[],"mappings":"AAEA,OAAO,KAA4D,MAAM,OAAO,CAAC;AACjF,OAAO,EAGL,KAAK,0BAA0B,EAC/B,KAAK,yBAAyB,EAC9B,KAAK,gCAAgC,EACrC,KAAK,qBAAqB,EAC1B,KAAK,KAAK,EAGX,MAAM,kBAAkB,CAAC;AAK1B,OAAO,EAA2B,KAAK,uBAAuB,EAAE,MAAM,cAAc,CAAC;AAIrF,KAAK,uBAAuB,GAAG,IAAI,CAAC,gCAAgC,EAAE,aAAa,CAAC,GAAG;IACrF,SAAS,EAAE,yBAAyB,CAAC;CACtC,CAAC;AAEF,MAAM,MAAM,uBAAuB,CAAC,KAAK,SAAS,qBAAqB,GAAG,qBAAqB,IAAI;IACjG;;;;;;;;OAQG;IACH,OAAO,EAAE,0BAA0B,GAAG;QAAE,IAAI,CAAC,EAAE,KAAK,CAAC,qBAAqB,EAAE,KAAK,CAAC,CAAA;KAAE,CAAC;IACrF,4DAA4D;IAC5D,mBAAmB,CAAC,EAAE,uBAAuB,EAAE,CAAC;IAChD;;;;;;;;OAQG;IACH,UAAU,CAAC,EAAE,OAAO,GAAG,uBAAuB,CAAC;IAC/C,sBAAsB;IACtB,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAC;CAC3B,CAAC;AASF;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,SAAS,qBAAqB,GAAG,qBAAqB,EAAE,EAC9F,OAAO,EACP,mBAAmB,EACnB,UAAU,EACV,QAAQ,GACT,EAAE,uBAAuB,CAAC,KAAK,CAAC,qBA2LhC"}
+{"version":3,"file":"RevTurbineProvider.d.ts","sourceRoot":"","sources":["../../../../react/RevTurbineProvider.tsx"],"names":[],"mappings":"AAEA,OAAO,KAA4D,MAAM,OAAO,CAAC;AACjF,OAAO,EAGL,KAAK,0BAA0B,EAC/B,KAAK,yBAAyB,EAC9B,KAAK,gCAAgC,EACrC,KAAK,qBAAqB,EAC1B,KAAK,KAAK,EACV,KAAK,gBAAgB,EAEtB,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EAIL,KAAK,qBAAqB,EAC3B,MAAM,mBAAmB,CAAC;AAO3B,OAAO,EAA2B,KAAK,uBAAuB,EAAE,MAAM,cAAc,CAAC;AAWrF,KAAK,uBAAuB,GAAG,IAAI,CAAC,gCAAgC,EAAE,aAAa,CAAC,GAAG;IACrF,SAAS,EAAE,yBAAyB,CAAC;CACtC,CAAC;AAEF,MAAM,MAAM,uBAAuB,CACjC,KAAK,SAAS,qBAAqB,GAAG,qBAAqB,EAC3D,QAAQ,SAAS,0BAA0B,GAAG,0BAA0B,IACtE;IACF;;;;;;;;OAQG;IACH,OAAO,EAAE,QAAQ,GAAG,gBAAgB,CAAC,QAAQ,CAAC,GAAG;QAAE,IAAI,CAAC,EAAE,KAAK,CAAC,qBAAqB,EAAE,KAAK,CAAC,CAAA;KAAE,CAAC;IAChG,4DAA4D;IAC5D,mBAAmB,CAAC,EAAE,uBAAuB,EAAE,CAAC;IAChD;;;;;;;;OAQG;IACH,UAAU,CAAC,EAAE,OAAO,GAAG,uBAAuB,CAAC;IAC/C;;;;;;;;;;;OAWG;IACH,WAAW,CAAC,EAAE,qBAAqB,CAAC;IACpC,sBAAsB;IACtB,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAC;CAC3B,CAAC;AASF;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,SAAS,qBAAqB,GAAG,qBAAqB,EAC3D,QAAQ,SAAS,0BAA0B,GAAG,0BAA0B,EACxE,EACA,OAAO,EACP,mBAAmB,EACnB,UAAU,EACV,WAAsB,EACtB,QAAQ,GACT,EAAE,uBAAuB,CAAC,KAAK,EAAE,QAAQ,CAAC,qBAkR1C"}

package/dist/types/web-sdk/react/index.d.ts

@@ -1,5 +1,7 @@
 export * from './RevTurbineProvider';
 export { useRevTurbine } from './useRevTurbine';
+export { INIT_STATUS_OK, initStatusForError, remediationFor, type RevTurbineInitPhase, type RevTurbineInitStatus, } from './init-status';
+export { InitFailureDiagnostic, type InitFailureDiagnosticProps, } from './InitFailureDiagnostic';
 export * from './usePlacement';
 export * from './Placement';
 export * from './SurfaceTypes';

package/dist/types/web-sdk/react/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../react/index.ts"],"names":[],"mappings":"AAAA,cAAc,sBAAsB,CAAC;AACrC,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAChD,cAAc,gBAAgB,CAAC;AAC/B,cAAc,aAAa,CAAC;AAC5B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,8BAA8B,CAAC;AAC7C,cAAc,eAAe,CAAC;AAC9B,cAAc,kBAAkB,CAAC;AACjC,cAAc,kBAAkB,CAAC;AACjC,cAAc,YAAY,CAAC;AAC3B,cAAc,eAAe,CAAC;AAC9B,cAAc,kBAAkB,CAAC;AACjC,cAAc,oBAAoB,CAAC;AACnC,cAAc,kBAAkB,CAAC;AACjC,cAAc,SAAS,CAAC;AACxB,cAAc,UAAU,CAAC;AACzB,cAAc,oBAAoB,CAAC;AACnC,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAC5B,OAAO,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../react/index.ts"],"names":[],"mappings":"AAAA,cAAc,sBAAsB,CAAC;AACrC,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAGhD,OAAO,EACL,cAAc,EACd,kBAAkB,EAClB,cAAc,EACd,KAAK,mBAAmB,EACxB,KAAK,oBAAoB,GAC1B,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,qBAAqB,EACrB,KAAK,0BAA0B,GAChC,MAAM,yBAAyB,CAAC;AACjC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,aAAa,CAAC;AAC5B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,8BAA8B,CAAC;AAC7C,cAAc,eAAe,CAAC;AAC9B,cAAc,kBAAkB,CAAC;AACjC,cAAc,kBAAkB,CAAC;AACjC,cAAc,YAAY,CAAC;AAC3B,cAAc,eAAe,CAAC;AAC9B,cAAc,kBAAkB,CAAC;AACjC,cAAc,oBAAoB,CAAC;AACnC,cAAc,kBAAkB,CAAC;AACjC,cAAc,SAAS,CAAC;AACxB,cAAc,UAAU,CAAC;AACzB,cAAc,oBAAoB,CAAC;AACnC,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAC5B,OAAO,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC"}

package/dist/types/web-sdk/react/init-status.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Init status — the one surface that is reachable when the SDK is not.
+ *
+ * Plan 233 TASK-2. Every diagnostic the SDK ships (`getPolicy()`,
+ * `getExportedConfig()`, `getTargeting()`, `getTelemetryCounters()`,
+ * `validateUiPathResolvers()`, `explainPlacementDecision()`) is an instance
+ * method, so all of them are unreachable in precisely the failure mode that
+ * matters most: the one where the instance was never created. When init throws,
+ * `useRevTurbine().sdk` is `null` and there is nothing left to ask.
+ *
+ * The provider already caught the error and logged it, but a `console.error` in
+ * an app that renders correctly without us is indistinguishable from silence —
+ * a customer ran dead for 36 hours and found it only by pasting a raw browser
+ * console log. So the status lives on the context value, beside `sdk`, and is
+ * populated exactly when `sdk` is not.
+ */
+/**
+ * Where initialization was when it failed. Useful because the phases fail for
+ * different reasons: `construct` is almost always malformed options, `theme`
+ * a branding/network problem, `bootstrap` a placement that does not resolve.
+ *
+ * @public
+ */
+export type RevTurbineInitPhase = 'construct' | 'identify' | 'theme' | 'placements' | 'bootstrap';
+/**
+ * The provider's initialization outcome, readable with no SDK instance.
+ *
+ * `ok: true` with no other fields is the healthy state. On failure every field
+ * is populated — `remediation` is never empty, because a diagnostic that only
+ * restates the error leaves the reader exactly where they started.
+ *
+ * @public
+ */
+export interface RevTurbineInitStatus {
+    /** `false` once initialization has thrown; `true` while healthy. */
+    readonly ok: boolean;
+    /** Which phase threw. Absent while healthy. */
+    readonly phase?: RevTurbineInitPhase;
+    /** The underlying error message, unmodified. Absent while healthy. */
+    readonly message?: string;
+    /** What to actually change, in the caller's own code. Absent while healthy. */
+    readonly remediation?: string;
+}
+/** The healthy status. Frozen so a consumer cannot mutate the shared default. */
+export declare const INIT_STATUS_OK: RevTurbineInitStatus;
+/**
+ * Resolve the remediation for a thrown init error.
+ *
+ * @param message - The error message as thrown.
+ * @returns Actionable guidance. Never empty.
+ * @public
+ */
+export declare function remediationFor(message: string): string;
+/**
+ * Build the failure status for a thrown init error.
+ *
+ * @param phase - The phase that was running when the error was thrown.
+ * @param error - The thrown value; non-Errors are stringified.
+ * @returns A fully-populated failure status.
+ * @public
+ */
+export declare function initStatusForError(phase: RevTurbineInitPhase, error: unknown): RevTurbineInitStatus;
+//# sourceMappingURL=init-status.d.ts.map

package/dist/types/web-sdk/react/init-status.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"init-status.d.ts","sourceRoot":"","sources":["../../../../react/init-status.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;GAeG;AAEH;;;;;;GAMG;AACH,MAAM,MAAM,mBAAmB,GAC3B,WAAW,GACX,UAAU,GACV,OAAO,GACP,YAAY,GACZ,WAAW,CAAC;AAEhB;;;;;;;;GAQG;AACH,MAAM,WAAW,oBAAoB;IACnC,oEAAoE;IACpE,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAC;IACrB,+CAA+C;IAC/C,QAAQ,CAAC,KAAK,CAAC,EAAE,mBAAmB,CAAC;IACrC,sEAAsE;IACtE,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,+EAA+E;IAC/E,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED,iFAAiF;AACjF,eAAO,MAAM,cAAc,EAAE,oBAAkD,CAAC;AAoDhF;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAKtD;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,mBAAmB,EAC1B,KAAK,EAAE,OAAO,GACb,oBAAoB,CAQtB"}

package/dist/types/web-sdk/react/useRevTurbine.d.ts

@@ -1,8 +1,26 @@
 import type { RevTurbineUserContext } from '../customer-side';
+import { type RevTurbineInitStatus } from './init-status';
 type RevTurbineContextValue = {
     sdk: import('../customer-side').RevTurbineCustomerSdk | null;
     isReady: boolean;
     error: string;
+    /**
+     * Initialization outcome, readable even when {@link sdk} is `null`.
+     *
+     * Every other diagnostic the SDK exposes is an instance method, so all of
+     * them are unreachable when init failed — which is the failure that matters
+     * most (plan 233 TASK-2). On failure this carries the phase, the underlying
+     * message, and a non-empty `remediation` naming what to change.
+     */
+    initStatus: RevTurbineInitStatus;
+    /**
+     * The colour scheme currently painting placements — `'light'` or `'dark'`,
+     * with `'system'` already resolved against `prefers-color-scheme`.
+     *
+     * Read-only: set it with the provider's `colorScheme` prop. Changing it
+     * re-renders placements without re-initializing the SDK (plan 233 TASK-6).
+     */
+    colorScheme: 'light' | 'dark';
     /**
      * Update the SDK's user context. Merges the provided fields into the
      * existing context and triggers segment re-evaluation.

package/dist/types/web-sdk/react/useRevTurbine.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useRevTurbine.d.ts","sourceRoot":"","sources":["../../../../react/useRevTurbine.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,kBAAkB,CAAC;AAE9D,KAAK,sBAAsB,GAAG;IAC5B,GAAG,EAAE,OAAO,kBAAkB,EAAE,qBAAqB,GAAG,IAAI,CAAC;IAC7D,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd;;;;;OAKG;IACH,UAAU,EAAE,CAAC,OAAO,EAAE,qBAAqB,KAAK,IAAI,CAAC;CACtD,CAAC;AAEF,eAAO,MAAM,iBAAiB,iDAK5B,CAAC;AAEH,wBAAgB,aAAa,2BAE5B"}
+{"version":3,"file":"useRevTurbine.d.ts","sourceRoot":"","sources":["../../../../react/useRevTurbine.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,kBAAkB,CAAC;AAC9D,OAAO,EAAkB,KAAK,oBAAoB,EAAE,MAAM,eAAe,CAAC;AAE1E,KAAK,sBAAsB,GAAG;IAC5B,GAAG,EAAE,OAAO,kBAAkB,EAAE,qBAAqB,GAAG,IAAI,CAAC;IAC7D,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd;;;;;;;OAOG;IACH,UAAU,EAAE,oBAAoB,CAAC;IACjC;;;;;;OAMG;IACH,WAAW,EAAE,OAAO,GAAG,MAAM,CAAC;IAC9B;;;;;OAKG;IACH,UAAU,EAAE,CAAC,OAAO,EAAE,qBAAqB,KAAK,IAAI,CAAC;CACtD,CAAC;AAEF,eAAO,MAAM,iBAAiB,iDAO5B,CAAC;AAEH,wBAAgB,aAAa,2BAE5B"}

package/dist/types/web-sdk/theme/ThemeContext.d.ts

@@ -1,13 +1,39 @@
 import React from 'react';
-import type { RevTurbineTheme } from './types';
+import type { RevTurbineTheme, RevTurbineThemeInput } from './types';
+/**
+ * Whether a {@link RevTurbineThemeProvider} is already mounted above the caller.
+ *
+ * Used by {@link RevTurbineProvider} to decide whether to mount its own. Exposed
+ * so an app can make the same check — e.g. a design-system wrapper that only
+ * supplies a theme when nothing upstream has.
+ *
+ * @returns `true` when an ancestor mounted a theme provider.
+ * @public
+ */
+export declare function useRevTurbineThemeProviderPresent(): boolean;
 export interface RevTurbineThemeProviderProps {
-    theme: RevTurbineTheme;
+    /**
+     * Theme tokens. A **partial** theme is fine — every token you omit falls back
+     * to {@link DEFAULT_THEME}, so `{ colors: { primary: '#f00' } }` is a complete,
+     * valid value (plan 233 TASK-4).
+     */
+    theme: RevTurbineThemeInput;
     children: React.ReactNode;
 }
 /**
  * Provides the active {@link RevTurbineTheme} to all child SDK components.
  * Typically rendered internally by {@link RevTurbineProvider} — consumers
  * don't need to add this manually.
+ *
+ * The theme is merged over {@link DEFAULT_THEME} here, so
+ * {@link useRevTurbineTheme} always returns a complete theme.
+ *
+ * That merge used to be the caller's job while the prop was typed as a complete
+ * `RevTurbineTheme`, which made a partial theme a runtime crash rather than a
+ * type error: components read `theme.typography.fontSize` and got `undefined`
+ * on a theme that only set colors. `RevTurbineThemeInput` has always documented
+ * itself as "all values are optional — the SDK deep-merges with defaults"; this
+ * is the component honouring that.
  */
 export declare function RevTurbineThemeProvider({ theme, children }: RevTurbineThemeProviderProps): React.JSX.Element;
 /**

package/dist/types/web-sdk/theme/ThemeContext.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ThemeContext.d.ts","sourceRoot":"","sources":["../../../../theme/ThemeContext.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAoC,MAAM,OAAO,CAAC;AACzD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAK/C,MAAM,WAAW,4BAA4B;IAC3C,KAAK,EAAE,eAAe,CAAC;IACvB,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAC;CAC3B;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,EAAE,KAAK,EAAE,QAAQ,EAAE,EAAE,4BAA4B,qBAExF;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,IAAI,eAAe,CAEpD"}
+{"version":3,"file":"ThemeContext.d.ts","sourceRoot":"","sources":["../../../../theme/ThemeContext.tsx"],"names":[],"mappings":"AAAA,OAAO,KAA6C,MAAM,OAAO,CAAC;AAClE,OAAO,KAAK,EAAE,eAAe,EAAE,oBAAoB,EAAE,MAAM,SAAS,CAAC;AAgBrE;;;;;;;;;GASG;AACH,wBAAgB,iCAAiC,IAAI,OAAO,CAE3D;AAED,MAAM,WAAW,4BAA4B;IAC3C;;;;OAIG;IACH,KAAK,EAAE,oBAAoB,CAAC;IAC5B,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAC;CAC3B;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,uBAAuB,CAAC,EAAE,KAAK,EAAE,QAAQ,EAAE,EAAE,4BAA4B,qBASxF;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,IAAI,eAAe,CAEpD"}

package/dist/types/web-sdk/theme/defaults.d.ts

@@ -6,8 +6,49 @@ import type { RevTurbineTheme, RevTurbineThemeInput } from './types';
  */
 export declare const DEFAULT_THEME: Readonly<RevTurbineTheme>;
 /**
- * Deep-merge a partial theme input with the default theme, producing a
- * complete {@link RevTurbineTheme}.
+ * Dark counterpart to {@link DEFAULT_THEME}.
+ *
+ * Plan 233 TASK-6. The SDK had no sanctioned dark story at all, so a customer
+ * running a dark app either lived with white modals or — as the escalated one
+ * did — injected a palette into the Playbook object and re-initialized the SDK
+ * on every toggle. Shipping the palette is what makes `colorScheme` a swap
+ * rather than a rebuild.
+ *
+ * Only the colors differ. Typography, shape and shadows are scheme-independent,
+ * so they are inherited from {@link DEFAULT_THEME} rather than duplicated —
+ * a second copy would drift the moment either is edited.
+ *
+ * Contrast: every text-on-surface pair here clears WCAG AA at body size against
+ * its intended background.
+ *
+ * @public
  */
-export declare function mergeTheme(input?: RevTurbineThemeInput | null): RevTurbineTheme;
+export declare const DARK_THEME: Readonly<RevTurbineTheme>;
+/**
+ * The colour scheme a theme resolves against.
+ *
+ * `'system'` follows the OS/browser `prefers-color-scheme` and keeps following
+ * it as the user changes it.
+ *
+ * @public
+ */
+export type RevTurbineColorScheme = 'light' | 'dark' | 'system';
+/**
+ * The base palette for a resolved scheme.
+ *
+ * @param scheme - `'light'` or `'dark'`. Resolve `'system'` before calling.
+ * @returns The matching base theme.
+ * @public
+ */
+export declare function baseThemeForScheme(scheme: 'light' | 'dark'): Readonly<RevTurbineTheme>;
+/**
+ * Deep-merge a partial theme input with a base theme, producing a complete
+ * {@link RevTurbineTheme}.
+ *
+ * @param input - Partial tokens. Every omitted token falls back to `base`.
+ * @param base - The palette to merge over. Defaults to {@link DEFAULT_THEME};
+ *   pass {@link DARK_THEME} (or use {@link baseThemeForScheme}) to resolve a
+ *   partial brand theme against the dark palette instead.
+ */
+export declare function mergeTheme(input?: RevTurbineThemeInput | null, base?: Readonly<RevTurbineTheme>): RevTurbineTheme;
 //# sourceMappingURL=defaults.d.ts.map

package/dist/types/web-sdk/theme/defaults.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"defaults.d.ts","sourceRoot":"","sources":["../../../../theme/defaults.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,oBAAoB,EAAE,MAAM,SAAS,CAAC;AAErE;;;;GAIG;AACH,eAAO,MAAM,aAAa,EAAE,QAAQ,CAAC,eAAe,CA2ClD,CAAC;AAEH;;;GAGG;AACH,wBAAgB,UAAU,CAAC,KAAK,CAAC,EAAE,oBAAoB,GAAG,IAAI,GAAG,eAAe,CAY/E"}
+{"version":3,"file":"defaults.d.ts","sourceRoot":"","sources":["../../../../theme/defaults.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,oBAAoB,EAAE,MAAM,SAAS,CAAC;AAErE;;;;GAIG;AACH,eAAO,MAAM,aAAa,EAAE,QAAQ,CAAC,eAAe,CA2ClD,CAAC;AAGH;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,UAAU,EAAE,QAAQ,CAAC,eAAe,CA2B/C,CAAC;AAEH;;;;;;;GAOG;AACH,MAAM,MAAM,qBAAqB,GAAG,OAAO,GAAG,MAAM,GAAG,QAAQ,CAAC;AAEhE;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,GAAG,QAAQ,CAAC,eAAe,CAAC,CAEtF;AAED;;;;;;;;GAQG;AACH,wBAAgB,UAAU,CACxB,KAAK,CAAC,EAAE,oBAAoB,GAAG,IAAI,EACnC,IAAI,GAAE,QAAQ,CAAC,eAAe,CAAiB,GAC9C,eAAe,CAYjB"}

package/dist/types/web-sdk/theme/index.d.ts

@@ -1,6 +1,8 @@
 export type { RevTurbineTheme, RevTurbineThemeInput, RevTurbineThemeColors, RevTurbineThemeTypography, RevTurbineThemeShape, RevTurbineThemeShadows, } from './types';
-export { DEFAULT_THEME, mergeTheme } from './defaults';
+export { DEFAULT_THEME, DARK_THEME, baseThemeForScheme, mergeTheme, } from './defaults';
+export type { RevTurbineColorScheme } from './defaults';
+export { useResolvedColorScheme } from './useColorScheme';
 export { loadTheme, clearPersistedTheme } from './theme-loader';
 export type { ThemeLoaderOptions } from './theme-loader';
-export { RevTurbineThemeProvider, useRevTurbineTheme } from './ThemeContext';
+export { RevTurbineThemeProvider, useRevTurbineTheme, useRevTurbineThemeProviderPresent, } from './ThemeContext';
 //# sourceMappingURL=index.d.ts.map

package/dist/types/web-sdk/theme/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../theme/index.ts"],"names":[],"mappings":"AACA,YAAY,EACV,eAAe,EACf,oBAAoB,EACpB,qBAAqB,EACrB,yBAAyB,EACzB,oBAAoB,EACpB,sBAAsB,GACvB,MAAM,SAAS,CAAC;AAEjB,OAAO,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AACvD,OAAO,EAAE,SAAS,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAChE,YAAY,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AACzD,OAAO,EAAE,uBAAuB,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../theme/index.ts"],"names":[],"mappings":"AACA,YAAY,EACV,eAAe,EACf,oBAAoB,EACpB,qBAAqB,EACrB,yBAAyB,EACzB,oBAAoB,EACpB,sBAAsB,GACvB,MAAM,SAAS,CAAC;AAEjB,OAAO,EACL,aAAa,EACb,UAAU,EACV,kBAAkB,EAClB,UAAU,GACX,MAAM,YAAY,CAAC;AACpB,YAAY,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AACxD,OAAO,EAAE,sBAAsB,EAAE,MAAM,kBAAkB,CAAC;AAC1D,OAAO,EAAE,SAAS,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAChE,YAAY,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AACzD,OAAO,EACL,uBAAuB,EACvB,kBAAkB,EAClB,iCAAiC,GAClC,MAAM,gBAAgB,CAAC"}

package/dist/types/web-sdk/theme/useColorScheme.d.ts

@@ -0,0 +1,14 @@
+import type { RevTurbineColorScheme } from './defaults';
+/**
+ * Resolve a {@link RevTurbineColorScheme} to the concrete scheme to paint.
+ *
+ * `'system'` tracks `prefers-color-scheme` and keeps tracking it: a user
+ * flipping their OS theme updates the resolved value without a remount, which
+ * is the difference between following the system and sampling it once at init.
+ *
+ * @param preference - The requested scheme. `'system'` follows the OS.
+ * @returns `'light'` or `'dark'`.
+ * @public
+ */
+export declare function useResolvedColorScheme(preference: RevTurbineColorScheme): 'light' | 'dark';
+//# sourceMappingURL=useColorScheme.d.ts.map

package/dist/types/web-sdk/theme/useColorScheme.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useColorScheme.d.ts","sourceRoot":"","sources":["../../../../theme/useColorScheme.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAoBxD;;;;;;;;;;GAUG;AACH,wBAAgB,sBAAsB,CAAC,UAAU,EAAE,qBAAqB,GAAG,OAAO,GAAG,MAAM,CAuC1F"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@revturbine/sdk",
-  "version": "0.7.13",
+  "version": "0.8.0",
   "description": "RevTurbine customer-facing SDK — placement decisioning, entitlement checks, and usage tracking.",
   "type": "module",
   "packageManager": "pnpm@11.12.0",
@@ -55,9 +55,9 @@
   "devDependencies": {
     "@growthbook/growthbook": "^1.7.0",
     "@optimizely/optimizely-sdk": "^6.5.0",
-    "@revt-eng/core": "0.1.302",
-    "@revt-eng/schema": "0.1.302",
-    "@revt-eng/schema-external": "0.1.302",
+    "@revt-eng/core": "0.1.306",
+    "@revt-eng/schema": "0.1.306",
+    "@revt-eng/schema-external": "0.1.306",
     "@types/react": "^19.2.17",
     "@types/react-dom": "^19.2.3",
     "openapi-fetch": "^0.17.0",