@bitbitpress/client 1.1.2 → 1.1.4

package/dist/generated/openapi.d.ts

@@ -4,6 +4,86 @@
  */
 
 export interface paths {
+    "/v1/auth/magic-link": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Auth - Send Magic Link
+         * @description **POST** `/v1/auth/magic-link`
+         *
+         *     Send a one-time sign-in link by email. The callback must be registered for the supplied client. The token in the link is exchanged through `POST /v1/auth/token`.
+         */
+        post: {
+            parameters: {
+                query?: never;
+                header?: never;
+                path?: never;
+                cookie?: never;
+            };
+            requestBody: {
+                content: {
+                    "application/json": {
+                        email: string;
+                        /** @description Public identifier of the app requesting the sign-in link */
+                        clientId: string;
+                        /** @description Registered callback URL. Optional when the client has a default callback. */
+                        redirectUri?: string;
+                    };
+                };
+            };
+            responses: {
+                /** @description Default Response */
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            /** @example true */
+                            success: boolean;
+                        };
+                    };
+                };
+                /** @description Bad request - missing or invalid parameters */
+                400: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            /** @example Bad request */
+                            error?: string;
+                        };
+                    };
+                };
+                /** @description Internal server error */
+                500: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            /** @example false */
+                            success?: boolean;
+                            /** @example Internal server error: An unknown error occurred */
+                            error?: string;
+                        };
+                    };
+                };
+            };
+        };
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/v1/auth/token": {
         parameters: {
             query?: never;
@@ -767,6 +847,122 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/v1/user/piece-events": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Synthesis - Record Piece Events
+         * @description **POST** `/v1/user/piece-events` Records behavioral events (views, clicks) for a SynthesisPiece embed, addressed by the piece's `keyName`. Batched by the SDK; powers per-piece engagement. Distinct from `/v1/user/events` (SynthesisUIs) so a keyName shared across the two entity namespaces is never misattributed.
+         */
+        post: {
+            parameters: {
+                query?: never;
+                header: {
+                    /** @description Bearer token for authentication */
+                    authorization: string;
+                };
+                path?: never;
+                cookie?: never;
+            };
+            requestBody: {
+                content: {
+                    "application/json": {
+                        /** @description Events to record. */
+                        events: {
+                            /** @description The piece's load id (`<BitBitPiece keyName>`) the event belongs to. */
+                            keyName: string;
+                            /**
+                             * @description VIEW (the piece was shown) or CLICK (a tracked interaction).
+                             * @enum {string}
+                             */
+                            type: "VIEW" | "CLICK";
+                            /** @description For CLICK: the human-readable action name. Omit for VIEW. */
+                            name?: string;
+                            /** @description Arbitrary event properties (retained for analytics drill-down). */
+                            payload?: {
+                                [key: string]: unknown;
+                            };
+                            /** @description ISO timestamp the event occurred; defaults to server time. */
+                            occurredAt?: string;
+                        }[];
+                    };
+                };
+            };
+            responses: {
+                /** @description Events recorded */
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            /** @example true */
+                            success: boolean;
+                            data: {
+                                /**
+                                 * @description Whether any event resolved to a known piece and was recorded.
+                                 * @example true
+                                 */
+                                recorded: boolean;
+                            };
+                        };
+                    };
+                };
+                /** @description Bad request - missing or invalid parameters */
+                400: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            /** @example Bad request */
+                            error?: string;
+                        };
+                    };
+                };
+                /** @description Unauthorized errors */
+                401: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            /**
+                             * @example Unauthorized: No authentication token provided
+                             * @enum {string}
+                             */
+                            error?: "Unauthorized: No authentication token provided" | "Unauthorized: Token has expired" | "Unauthorized: Invalid token" | "Unauthorized: Authentication failed";
+                        };
+                    };
+                };
+                /** @description Internal server error */
+                500: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            /** @example false */
+                            success?: boolean;
+                            /** @example Internal server error: An unknown error occurred */
+                            error?: string;
+                        };
+                    };
+                };
+            };
+        };
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/v1/user/synthesize": {
         parameters: {
             query?: never;
@@ -799,7 +995,7 @@ export interface paths {
                         items: {
                             /** @description Optional configuration key name. Loads an existing synthesis config by this name; omit for default configuration. */
                             configurationKeyName?: string;
-                            /** @description How many recent stored synthesis outputs to expose in the streamed `synthesisHistory` / `synthesisHistoryEntries` fields. Defaults to 0 (no history emitted). When > 0, the final data event includes a `synthesisHistoryEntries` array of up to N `{ synthesisOutputId, data }` (most-recent first; each row's payload paired with its output id, so submissions can attach to a specific historical output), and — DEPRECATED, for retrocompatibility — an index-aligned `synthesisHistory` array of the same bare `data` payloads. The first entry is the current synthesis itself — the same payload `data` is derived from — and the remaining entries are older stored rows. */
+                            /** @description How many recent stored synthesis outputs to expose in the streamed `synthesisHistory` / `synthesisHistoryEntries` fields. Defaults to 0 (no history emitted). When > 0, the final data event includes a `synthesisHistoryEntries` array of up to N `{ synthesisOutputId, data }` (most-recent first; each row's payload paired with its output id, so submissions can attach to a specific historical output), and — DEPRECATED, for older app builds — an index-aligned `synthesisHistory` array of the same bare `data` payloads. The first entry is the current synthesis itself — the same payload `data` is derived from — and the remaining entries are older stored rows. */
                             synthesisHistoryLimit?: number;
                             /** @description Per-request overrides for search options. */
                             searchOptionsOverrides?: {
@@ -845,7 +1041,7 @@ export interface paths {
                  *     ```
                  *     `data` is always a single synthesized object (keys match your output schema). `complete` is `false` for partial streaming updates and `true` for the final validated payload.
                  *
-                 *     When `synthesisHistoryLimit > 0`, the final event additionally includes `synthesisHistoryEntries`: an array of up to N entries (most-recent first), each `{ synthesisOutputId, data }`, so a client can attach submissions (e.g. poll votes) to a specific historical output. The first entry is the current synthesis itself — the raw payload `data` is derived from (identical to `data` when reranking isn't configured; the unreranked source when it is) — and the remaining entries are older stored rows. A DEPRECATED `synthesisHistory` field (index-aligned bare `data` payloads) is also included for retrocompatibility. The primary `data` field stays a single object — when user reranking is configured, it is built by pooling items at the reranking field across the fetched rows and scoring against the user profile.
+                 *     When `synthesisHistoryLimit > 0`, the final event additionally includes `synthesisHistoryEntries`: an array of up to N entries (most-recent first), each `{ synthesisOutputId, data }`, so a client can attach submissions (e.g. poll votes) to a specific historical output. The first entry is the current synthesis itself — the raw payload `data` is derived from (identical to `data` when reranking isn't configured; the unreranked source when it is) — and the remaining entries are older stored rows. A DEPRECATED `synthesisHistory` field (index-aligned bare `data` payloads) is also included for older app builds. The primary `data` field stays a single object — when user reranking is configured, it is built by pooling items at the reranking field across the fetched rows and scoring against the user profile.
                  *
                  *     **Data Events (error):**
                  *     ```json
@@ -926,9 +1122,9 @@ export interface paths {
          * Synthesis - Synthesize UI
          * @description **POST** `/v1/user/synthesize-ui`
          *
-         *     Resolve one or more generated UIs in a single request, each identified by its `keyName`. Streams results as Server-Sent Events so the client can load the (cacheable) code bundle immediately and render synthesis `data` as it arrives — the same streaming model as `/v1/user/synthesize`.
+         *     Resolve one or more generated UIs in a single request, each identified by its `keyName`. Works exactly like `/v1/user/synthesize` — same per-item synthesis inputs (`inputs`, `output.schema`, `searchOptionsOverrides`, `synthesisHistoryLimit`) and the same personalized, streamed `data` — except it additionally returns the UI code bundle to render that data. The synthesis runs against the config attached to each UI.
          *
-         *     The code bundle is immutable per published version and identical for every app user, so it is served from a CDN by versioned `bundleUrl` and cached once across renders and users. `data` is the per-request, per-user piece and may stream in partials before a final `complete: true` event. `theme` is deployment-level and emitted once in the `manifest`. (`bundleSource` is an inlined fallback used only while bundles are served inline, before CDN delivery.)
+         *     Streams as Server-Sent Events so the client can load the (cacheable) code bundle immediately and render synthesis `data` as it arrives. The code bundle is immutable per published version and identical for every app user, so it is served from a CDN by versioned `bundleUrl` and cached once across renders and users. `data` is the per-request, per-user piece and may stream in partials before a final `complete: true` event. `theme` is deployment-level and emitted once in the `manifest`. (`bundleSource` is an inlined fallback used only while bundles are served inline, before CDN delivery.)
          */
         post: {
             parameters: {
@@ -952,6 +1148,28 @@ export interface paths {
                         items: {
                             /** @description Stable identifier of the UI to load. Configured in the CMS. */
                             keyName: string;
+                            /** @description How many recent stored synthesis outputs to expose in the streamed `synthesisHistory` / `synthesisHistoryEntries` fields. Defaults to 0. See `/v1/user/synthesize` for the full semantics. */
+                            synthesisHistoryLimit?: number;
+                            /** @description Per-request overrides for search options. */
+                            searchOptionsOverrides?: {
+                                /** @description Override for search lookback window in minutes (e.g. 1440 for last 24 hours). */
+                                lookbackMinutes?: number;
+                            };
+                            /** @description Inputs used as context for the synthesis: externalId (article ID), or text (freeform text). */
+                            inputs?: {
+                                /**
+                                 * @description Type of input: externalId (article) or text (freeform).
+                                 * @enum {string}
+                                 */
+                                type: "externalId" | "text" | "excludeExternalIds";
+                                /** @description External ID (e.g. article) for externalId, freeform text for text, or comma-separated list of external IDs to exclude */
+                                value: string;
+                            }[];
+                            /** @description Optional output definition. Omit to use the output schema declared on the UI's attached config (`output.outputSchema`). */
+                            output?: {
+                                /** @description Output schema as a JSON string. Top-level type must be "object". See `/v1/user/synthesize` for the format. */
+                                schema: string;
+                            };
                         }[];
                     };
                 };
@@ -1043,6 +1261,230 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/v1/user/synthesis-piece": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * User - Get Synthesis Pieces
+         * @description **POST** `/v1/user/synthesis-piece`
+         *
+         *     Fetch one or more published pieces to display, each by its `keyName`. For every requested piece you receive its ready-to-render view (`uiWebCode`), its current content (`fields`), and your workspace's display theme (`theme`, the same for every piece). Render the view and give it the content as its data. Results come back in the same order as the pieces you requested; if a piece can't be found or isn't published, its result contains an `error` message in place of the content.
+         */
+        post: {
+            parameters: {
+                query?: never;
+                header: {
+                    /** @description Bearer token for authentication */
+                    authorization: string;
+                };
+                path?: never;
+                cookie?: never;
+            };
+            requestBody: {
+                content: {
+                    "application/json": {
+                        /** @description The pieces to fetch, each by its key. */
+                        items: {
+                            /** @description The piece's unique key. */
+                            keyName: string;
+                        }[];
+                    };
+                };
+            };
+            responses: {
+                /** @description Successful response */
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            /** @example true */
+                            success: boolean;
+                            data: {
+                                /** @description Your workspace's brand theme as CSS custom properties (the same for every piece). */
+                                theme: {
+                                    [key: string]: string;
+                                };
+                                /** @description One result per requested piece, in the same order. */
+                                items: ({
+                                    /** @description Position of this result in the requested list. */
+                                    index: number;
+                                    /** @description The piece's ready-to-render view. */
+                                    uiWebCode?: string;
+                                    /** @description The piece's current content, given to the view as its data (includes ready-to-play audio for audio pieces). */
+                                    fields?: {
+                                        [key: string]: unknown;
+                                    };
+                                    /** @description A message explaining why this piece couldn't be returned. */
+                                    error?: string;
+                                } & {
+                                    [key: string]: unknown;
+                                })[];
+                            };
+                        };
+                    };
+                };
+                /** @description Bad request - missing or invalid parameters */
+                400: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            /** @example Bad request */
+                            error?: string;
+                        };
+                    };
+                };
+                /** @description Unauthorized errors */
+                401: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            /**
+                             * @example Unauthorized: No authentication token provided
+                             * @enum {string}
+                             */
+                            error?: "Unauthorized: No authentication token provided" | "Unauthorized: Token has expired" | "Unauthorized: Invalid token" | "Unauthorized: Authentication failed";
+                        };
+                    };
+                };
+                /** @description Internal server error */
+                500: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            /** @example false */
+                            success?: boolean;
+                            /** @example Internal server error: An unknown error occurred */
+                            error?: string;
+                        };
+                    };
+                };
+            };
+        };
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v1/user/synthesis-piece/tts": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * User - Synthesize Piece Audio
+         * @description **POST** `/v1/user/synthesis-piece/tts`
+         *
+         *     Mint a short-lived, self-authenticating HLS URL for a published piece's spoken content. A media player calls this when the listener presses play, then plays the returned `url` (via the SDK's `ctx.playMedia`) to stream the synthesized speech on demand. The request REFERENCES the piece's content — omit `field` for the whole piece's spoken content, pass a top-level `field` to scope to it, and/or `index` for a single turn — and the server resolves the turns from the piece itself (so the URL never carries the text). The URL is gated at issue time (a few-minute expiry, and only PUBLISHED pieces), so a fresh URL can't be minted after a piece is unpublished. Note: the URL is an HLS playlist whose audio segments are content-addressed and cached long-lived — a player that already loaded a URL may keep playing that audio from cache after the URL expires or the piece is unpublished.
+         */
+        post: {
+            parameters: {
+                query?: never;
+                header: {
+                    /** @description Bearer token for authentication */
+                    authorization: string;
+                };
+                path?: never;
+                cookie?: never;
+            };
+            requestBody: {
+                content: {
+                    "application/json": {
+                        /** @description The piece's unique key. */
+                        keyName: string;
+                        /** @description Top-level field to voice. Omit for the whole piece's spoken content. */
+                        field?: string;
+                        /** @description A single turn index within the resolved content. Omit for all turns. */
+                        index?: number;
+                    };
+                };
+            };
+            responses: {
+                /** @description Successful response */
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            /** @example true */
+                            success: boolean;
+                            data: {
+                                /** @description A short-lived streaming URL to point an `<audio>` element at. */
+                                url?: string;
+                                /** @description Set instead of `url` when audio can't be produced (piece not found/published, or the text isn't part of the piece). */
+                                error?: string;
+                            };
+                        };
+                    };
+                };
+                /** @description Bad request - missing or invalid parameters */
+                400: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            /** @example Bad request */
+                            error?: string;
+                        };
+                    };
+                };
+                /** @description Unauthorized errors */
+                401: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            /**
+                             * @example Unauthorized: No authentication token provided
+                             * @enum {string}
+                             */
+                            error?: "Unauthorized: No authentication token provided" | "Unauthorized: Token has expired" | "Unauthorized: Invalid token" | "Unauthorized: Authentication failed";
+                        };
+                    };
+                };
+                /** @description Internal server error */
+                500: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            /** @example false */
+                            success?: boolean;
+                            /** @example Internal server error: An unknown error occurred */
+                            error?: string;
+                        };
+                    };
+                };
+            };
+        };
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/v1/user/interactions": {
         parameters: {
             query?: never;
@@ -1054,7 +1496,7 @@ export interface paths {
         put?: never;
         /**
          * Synthesis - Get User Interactions (DEPRECATED)
-         * @description **DEPRECATED** — use `GET /v1/user/submissions` (submission state), keyed by the poll's `synthesisOutputId`. Kept for retrocompatibility.
+         * @description **DEPRECATED** — use `GET /v1/user/submissions` (submission state), keyed by the poll's `synthesisOutputId`. Kept for older app builds.
          *
          *     **POST** `/v1/user/interactions`
          *
@@ -1168,7 +1610,7 @@ export interface paths {
         put?: never;
         /**
          * Synthesis - Create User Interaction Response (DEPRECATED)
-         * @description **DEPRECATED** — use `POST /v1/user/submissions` (submit), keyed by the poll's `synthesisOutputId`. Kept for retrocompatibility.
+         * @description **DEPRECATED** — use `POST /v1/user/submissions` (submit), keyed by the poll's `synthesisOutputId`. Kept for older app builds.
          *
          *     **POST** `/v1/user/interactions/:interactionId/responses`
          *
@@ -1534,7 +1976,7 @@ export interface paths {
                         externalIds?: string[];
                         /** @description Asset fields to return (dot or bracket notation). Allowed: assetId, title, tags, images, videos, publishedAt, externalId, externalData, assetType, sourceUrl, dataSource.name, and subfields. Empty array returns objects with only assetId. */
                         assetFields: string[];
-                    };
+                    } & (unknown | unknown);
                 };
             };
             responses: {

package/dist/react/index.d.ts

@@ -1,14 +1,20 @@
-import type { SynthesisUiPlatform, SynthesisUiStreamEvent, SynthesizeUiFetcher } from '../synthesisUi/types.js';
-export type { BitBitViewContext, GeneratedUiModule, GeneratedUiViewHandle, } from '../runtime/index.js';
+import { type BitBitTtsRef } from '../runtime/index.js';
+import type { SynthesisUiPlatform, SynthesisUiRequestInputs, SynthesisUiStreamEvent, SynthesizeUiFetcher } from '../synthesisUi/types.js';
+export type { BitBitTtsRef, BitBitViewContext, GeneratedUiModule, GeneratedUiViewHandle, } from '../runtime/index.js';
 export { type BitBitContextValue, BitBitProvider } from '../synthesisUi/context.js';
-export type { SynthesisUiPlatform, SynthesisUiStreamEvent, SynthesizeUiFetcher };
-export interface BitBitSynthesisProps {
+export type { SynthesisUiPlatform, SynthesisUiRequestInputs, SynthesisUiStreamEvent, SynthesizeUiFetcher, };
+/** `SynthesisUiRequestInputs` (`inputs`, `output`, `searchOptionsOverrides`,
+ *  `synthesisHistoryLimit`) are forwarded to the synthesis request. Non-primitive
+ *  values (e.g. `inputs`) should be stable/memoized — a new identity re-subscribes
+ *  the stream (re-synthesizes). */
+export interface BitBitViewProps extends SynthesisUiRequestInputs {
     /** Client to fetch the UI through. Optional when a `<BitBitProvider client>`
      *  is in scope. */
     client?: SynthesizeUiFetcher;
     keyName: string;
-    /** Target platform. Defaults to `web`; the studio passes `mobile` to
-     *  preview the react-native-web bundle. */
+    /** Target platform. Defaults to `web`. The CMS studio passes `mobile` to
+     *  preview the mobile bundle in a browser; a real native app renders mobile
+     *  through the `react-native-expo` entry (a WebView), not this one. */
     platform?: SynthesisUiPlatform;
     /** Brand analytics / link tracking. */
     onTrack?: (event: string, payload?: unknown) => void;
@@ -16,17 +22,90 @@ export interface BitBitSynthesisProps {
     onEvent?: (name: string, payload?: unknown) => void;
     /** Navigate a link the view requested. */
     onNavigate?: (href: string) => void;
+    /** Resolve an on-demand audio URL for a voice player (`ctx.tts`). */
+    onTts?: (ref?: BitBitTtsRef) => Promise<string>;
 }
 /**
  * Web view for a server-generated SynthesisUI. Streams the UI by `keyName`
  * through `client` (or the `<BitBitProvider client>` in scope): loads and
- * mounts the built bundle (which owns its React) on the `manifest`, then pushes
- * `data` into the mounted view as it streams in. Web mounts in a Shadow DOM;
- * the `mobile` preview (react-native-web) mounts in the light DOM so rn-web's
- * global stylesheet applies. Native delivery (React Native via Re.Pack) is a
- * separate entry.
+ * mounts the built bundle (which owns its own framework) on the `manifest`, then
+ * pushes `data` into the mounted view as it streams in. Both web and mobile
+ * bundles are plain DOM, so both mount here (web in a Shadow DOM; the studio's
+ * `mobile` preview in the light DOM). Native delivery renders the same mobile
+ * bundle in a WebView via the `react-native-expo` entry.
  */
-export declare function BitBitSynthesis({ client: clientProp, keyName, platform, onTrack, onEvent, onNavigate, }: BitBitSynthesisProps): import("react").DetailedReactHTMLElement<{
+export declare function BitBitView({ client: clientProp, keyName, platform, onTrack, onEvent, onNavigate, onTts, inputs, output, searchOptionsOverrides, synthesisHistoryLimit, }: BitBitViewProps): import("react").DetailedReactHTMLElement<{
+    ref: import("react").RefObject<HTMLDivElement>;
+    style: {
+        height: string;
+    };
+}, HTMLDivElement>;
+/** What `<BitBitPiece keyName>` needs from a client: resolve a piece for embedding.
+ *  A full `BitBitPressClient` satisfies this; the piece studio's static preview
+ *  doesn't need it (it uses `code`+`data`). */
+export interface BitBitPieceFetcher {
+    user: {
+        getSynthesisPiece(keyName: string): Promise<{
+            uiWebCode: string;
+            fields: unknown;
+            theme?: Record<string, string>;
+        }>;
+        /** Mint an on-demand audio URL for a piece's spoken turns. When present, embed mode
+         *  (`keyName`) wires it into `ctx.tts` so audio players play without host setup. */
+        synthesisPieceTtsUrl?(keyName: string, ref?: BitBitTtsRef): Promise<string>;
+    };
+}
+interface BitBitPieceCommonProps {
+    /** Brand tokens → CSS custom properties + `ctx.theme`. In `keyName` mode the
+     *  fetched deployment theme is used unless this overrides it. */
+    theme?: Record<string, string>;
+    /** Web (Shadow DOM isolation) or the studio's light-DOM mobile preview. */
+    platform?: SynthesisUiPlatform;
+    /** Force the rendered scheme (`ctx.colorScheme`). Leave unset to let a
+     *  dual-mode piece follow the browser's `prefers-color-scheme`. */
+    colorScheme?: 'light' | 'dark';
+    onTrack?: (event: string, payload?: unknown) => void;
+    onEvent?: (name: string, payload?: unknown) => void;
+    onNavigate?: (href: string) => void;
+    /** Resolve an on-demand audio URL for a voice player (`ctx.tts`). */
+    onTts?: (ref?: BitBitTtsRef) => Promise<string>;
+    /** Bump to force a clean re-mount (reusing the loaded module) — the editor uses this
+     *  to recover after a structural in-place edit that would corrupt the framework's
+     *  own reconciliation. */
+    remountToken?: number;
+}
+/** Direct mode — the bundle source + data are already in hand (editor-side
+ *  previews, e.g. the piece studio). No fetch, no client. */
+export interface BitBitPieceCodeProps extends BitBitPieceCommonProps {
+    /** The generated self-contained ESM bundle — source string or a URL. */
+    code: string;
+    /** Field values passed to the bundle as `props.data`. */
+    data: unknown;
+    keyName?: never;
+    client?: never;
+}
+/** Embed mode — resolve the piece by `keyName` through `client` (or the
+ *  `<BitBitProvider client>` in scope), exactly like `<BitBitView keyName>`. */
+export interface BitBitPieceKeyNameProps extends BitBitPieceCommonProps {
+    keyName: string;
+    /** Client to fetch through. Optional when a `<BitBitProvider client>` is in scope. */
+    client?: BitBitPieceFetcher;
+    code?: never;
+    data?: never;
+}
+export type BitBitPieceProps = BitBitPieceCodeProps | BitBitPieceKeyNameProps;
+/**
+ * Render a generated piece bundle (its `uiWebCode`). Two modes:
+ * - **Direct** (`code` + `data`): mounts the module from source in hand — editor
+ *   previews where code and data are already available (the piece studio).
+ * - **Embed** (`keyName` + `client`): resolves the piece's bundle, field values
+ *   (incl. pre-generated `audioData.url`s), and theme by `keyName` through the
+ *   client (like `<BitBitView keyName>`).
+ *
+ * Either way the module mounts on the host (web: Shadow DOM) and `data` is pushed
+ * in, re-rendering in place when it changes.
+ */
+export declare function BitBitPiece(props: BitBitPieceProps): import("react").DetailedReactHTMLElement<{
     ref: import("react").RefObject<HTMLDivElement>;
     style: {
         height: string;

package/dist/react/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/react/index.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EACV,mBAAmB,EACnB,sBAAsB,EACtB,mBAAmB,EACpB,MAAM,yBAAyB,CAAC;AAEjC,YAAY,EACV,iBAAiB,EACjB,iBAAiB,EACjB,qBAAqB,GACtB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,KAAK,kBAAkB,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AACpF,YAAY,EAAE,mBAAmB,EAAE,sBAAsB,EAAE,mBAAmB,EAAE,CAAC;AAEjF,MAAM,WAAW,oBAAoB;IACnC;uBACmB;IACnB,MAAM,CAAC,EAAE,mBAAmB,CAAC;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB;+CAC2C;IAC3C,QAAQ,CAAC,EAAE,mBAAmB,CAAC;IAC/B,uCAAuC;IACvC,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC;IACrD,+DAA+D;IAC/D,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC;IACpD,0CAA0C;IAC1C,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CACrC;AAID;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,EAC9B,MAAM,EAAE,UAAU,EAClB,OAAO,EACP,QAAgB,EAChB,OAAO,EACP,OAAO,EACP,UAAU,GACX,EAAE,oBAAoB;;;;;mBAkEtB"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/react/index.ts"],"names":[],"mappings":"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"}