@belonguniverseai/react-sdk 0.6.28 → 0.6.29

package/dist/routes/chat/use-catch-up-on-return.d.ts

@@ -0,0 +1,70 @@
+import { BelongUIMessage } from '../../stream/belong-data-parts.ts';
+import { HistoryPageResult, LoadedHistoryPage } from './history-cache.ts';
+import { useReturnToPage } from './use-return-to-page.ts';
+/** The chat as the catch-up reads it: `@ai-sdk/react`'s `Chat`, live. Its
+ * `messages` array is replaced on every change, so identity says "changed". */
+export type CatchUpChat = {
+    readonly status: "submitted" | "streaming" | "ready" | "error";
+    readonly messages: readonly BelongUIMessage[];
+};
+/** The server's answer about the session's active run. `failed` (network,
+ * non-2xx, a drifted body) is not `none`: only a confirmed `none` is
+ * remembered. */
+export type ActiveRunLookup = {
+    readonly kind: "none";
+} | {
+    readonly kind: "run";
+    readonly runId: string;
+} | {
+    readonly kind: "failed";
+};
+/** The transport as the catch-up reads it. */
+export type CatchUpTransport = {
+    readonly sessionId: string | null;
+    /** A stream, its handshake or its retry loop owns this session. */
+    readonly hasLiveStream: boolean;
+};
+/** What else may own the transcript right now; any of them blocks a step. */
+export type CatchUpBlockers = {
+    /** The workspace does not resolve. */
+    readonly workspaceMissing: boolean;
+    /** The mount's first history read is out. */
+    readonly historyLoading: boolean;
+    /** A resume handshake is under way. */
+    readonly restoringLiveRun: boolean;
+    /** A queued-reply reconciliation is pending. It starts without a render,
+     * so it is asked for when needed rather than passed as a value. */
+    readonly queuedReconciliationPending: () => boolean;
+};
+export declare const useCatchUpOnReturn: (input: {
+    readonly chat: CatchUpChat;
+    readonly transport: CatchUpTransport;
+    /** Checked when a step starts and again after every await, against the
+     * latest render's values, never those of the render that started it. */
+    readonly blockers: CatchUpBlockers;
+    /** Read the newest page from the server now. */
+    readonly readNewestPage: (sessionId: string) => Promise<HistoryPageResult>;
+    /** The read landed after the transcript changed: the page it cached may
+     * predate the change (a clear), so no chat may be painted from it. */
+    readonly onReadOutdated: (sessionId: string) => void;
+    /** Show `caughtUp`, the conversation `page` brought the screen up to. */
+    readonly onCaughtUp: (caughtUp: BelongUIMessage[], page: LoadedHistoryPage) => void;
+    /** Ask the server for the session's active run. */
+    readonly findActiveRun: (sessionId: string) => Promise<ActiveRunLookup>;
+    /** Follow `runId`, the reply to the turn `page` ends on, from its first event. */
+    readonly onFollowRun: (sessionId: string, runId: string, page: LoadedHistoryPage) => void;
+    /** The session this tab has selected now (the stream-state pointer). */
+    readonly selectedSessionId: () => string | null;
+    /** Bumped when the transcript's work loses its owner (leaving the chat, a
+     * clear, a stop): a step started under an older value drops itself. A
+     * clear's POST runs before it empties the screen, so the transcript alone
+     * cannot tell a lookup that the clear is under way. */
+    readonly ownerGeneration: () => number;
+    /** A newly controlling tab catches up even when the page stayed visible. */
+    readonly controlRole?: "leader" | "follower";
+    /** Explicit retries of a control request, including a failed catch-up. */
+    readonly controlRequestId?: number;
+    readonly prepareControl?: (sessionId: string) => Promise<void>;
+    readonly onControlReady?: (ready: boolean) => void;
+    readonly returnOptions?: Parameters<typeof useReturnToPage>[1];
+}) => void;

package/dist/routes/chat/use-return-to-page.d.ts

@@ -0,0 +1,7 @@
+/** Two return signals closer together than this are one return. */
+export declare const RETURN_MIN_GAP_MS = 2000;
+export declare const useReturnToPage: (onReturn: () => void, options?: {
+    readonly minGapMs?: number;
+    /** Clock seam (§25). */
+    readonly nowMs?: () => number;
+}) => void;

package/dist/stream/belong-chat-transport.d.ts

@@ -1,6 +1,7 @@
 import { z } from 'zod';
 import { ChatTransport, UIMessageChunk } from 'ai';
 import { FirstResponseObservation, FirstResponseSample } from '../infrastructure/telemetry/first-response-timing.ts';
+import { AUTH_EXPIRED_ERROR_PREFIX } from '../api/auth-errors.ts';
 import { BelongUIMessage, WireStreamPart } from './belong-data-parts.ts';
 declare const cancelRunResponseSchema: z.ZodObject<{
     recalledMessages: z.ZodDefault<z.ZodArray<z.ZodObject<{
@@ -364,9 +365,9 @@ export declare const wireStreamPartSchema: z.ZodDiscriminatedUnion<[z.ZodObject<
             at: z.ZodString;
         }, z.core.$strip>>>;
         runway: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+            long: "long";
             quick: "quick";
             normal: "normal";
-            long: "long";
         }>>>;
     }, z.core.$strip>;
 }, z.core.$strip>, z.ZodObject<{
@@ -377,15 +378,17 @@ export declare const wireStreamPartSchema: z.ZodDiscriminatedUnion<[z.ZodObject<
         why: z.ZodString;
         criteria: z.ZodOptional<z.ZodArray<z.ZodString>>;
         runway: z.ZodOptional<z.ZodEnum<{
+            long: "long";
             quick: "quick";
             normal: "normal";
-            long: "long";
         }>>;
     }, z.core.$strip>;
 }, z.core.$strip>], "type">;
-/** A request was 401'd twice (once with a freshly re-read token): the host
- * session is expired — the dock must surface re-auth, not retry forever. */
-export declare const AUTH_EXPIRED_ERROR_PREFIX = "auth_expired:";
+/** A request was 401'd twice (once with a freshly re-read token), or no usable
+ * token could be had at all (`BelongAuthUnavailableError`): the host session is
+ * expired — the dock must surface re-auth, not retry forever. Defined by the
+ * request layer, which raises it too; re-exported here for chat.tsx. */
+export { AUTH_EXPIRED_ERROR_PREFIX };
 /** The SSE reconnect loop exhausted its attempt budget without the backend
  * delivering a single event — the service is unreachable. */
 export declare const BACKEND_UNAVAILABLE_ERROR_PREFIX = "backend_unavailable:";
@@ -604,4 +607,3 @@ export declare class BelongChatTransport implements ChatTransport<BelongUIMessag
     reconnectToStream: ChatTransport<BelongUIMessage>["reconnectToStream"];
 }
 export declare const wireToUiChunks: (part: WireStreamPart, ctx: StreamContext) => readonly UIMessageChunk[];
-export {};

package/dist/stream/dispatch-once.d.ts

@@ -4,7 +4,7 @@ export declare const claimDispatch: (key: string) => boolean;
  * Run `effect` once for `key` on this page — or, without a key, once for the
  * component's lifetime (React 19 StrictMode double-invokes included).
  */
-export declare const useDispatchOnce: (key: string | undefined, effect: () => void, deps: readonly unknown[]) => void;
+export declare const useDispatchOnce: (key: string | undefined, effect: () => void, deps: readonly unknown[], canDispatch?: () => boolean) => void;
 /** Where a dispatch card's one-shot call stands. */
 export type DispatchStatus = "dispatching" | "running" | "ok" | "no_handler" | "failed" | "done";
 /** What a dispatch card shows, remembered by the same key as its guard. */

package/dist/stream/queued-message-outbox.d.ts

@@ -20,6 +20,7 @@ declare const queuedMessageOutboxEntrySchema: z.ZodObject<{
         fast: "fast";
         smart: "smart";
     }>>;
+    pageLabel: z.ZodOptional<z.ZodString>;
     workspaceExternalId: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export type QueuedMessageOutboxEntry = Readonly<z.infer<typeof queuedMessageOutboxEntrySchema>>;

package/dist/stream/session-control-context.d.ts

@@ -0,0 +1,7 @@
+export type SessionControl = {
+    readonly readOnly: boolean;
+    /** Read live ownership again at the moment a side effect starts. */
+    readonly canControl: () => boolean;
+};
+export declare const SessionControlContext: import('react').Context<SessionControl>;
+export declare const useSessionControl: () => SessionControl;

package/dist/types/public.d.ts

@@ -166,9 +166,11 @@ export type BelongInitInput = {
     };
     /**
      * What page the user is on, shown as "Looking at ‹label›" before the first
-     * message. Omit `label` to use the browser tab title (`document.title`,
+     * message and in the composer's page chip, and SENT with every message so
+     * the agent can resolve "this page" (the label only, never the page's
+     * contents). Omit `label` to use the browser tab title (`document.title`,
      * tracked live so SPA navigation updates the line); pass
-     * `fromDocumentTitle: false` to show nothing unless a label is given.
+     * `fromDocumentTitle: false` to show and send nothing unless a label is given.
      * A re-`init` replaces this config wholesale: omitting `pageContext` clears
      * a previously seeded `label` and restores the tab-title fallback.
      * `belong.setPageContext` overrides both at runtime and SURVIVES a later
@@ -182,7 +184,12 @@ export type BelongInitInput = {
     readonly theme?: PartialBelongTheme;
     /** Optional voice config (push-to-talk + read-aloud). */
     readonly voice?: {
-        /** Hold-to-talk key as a `KeyboardEvent.code`. Default `"ControlLeft"`. */
+        /**
+         * Default hold-to-talk key as a `KeyboardEvent.code`: one of
+         * `"ControlRight"`, `"ControlLeft"`, `"AltRight"`, `"AltLeft"`, `"F2"`,
+         * `"F8"`, `"F9"`; any other code is ignored. Default: none — each user
+         * picks a key (or keeps it off) in Settings → Voice, and their choice wins.
+         */
         readonly pushToTalkKey?: string;
         /** Auto-read assistant replies aloud (ElevenLabs TTS). Default `true`. */
         readonly autoplayTts?: boolean;
@@ -324,8 +331,8 @@ export type BelongGlobal = {
         readonly displayName?: string | null;
     } | null) => void;
     /**
-     * Set the page label shown before the first message (wins over
-     * `init({ pageContext })` and the tab title). `null` drops the override.
+     * Set the page label shown in the dock and sent with each message (wins
+     * over `init({ pageContext })` and the tab title). `null` drops the override.
      */
     readonly setPageContext: (label: string | null) => void;
     readonly setTheme: (theme: PartialBelongTheme) => void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@belonguniverseai/react-sdk",
-  "version": "0.6.28",
+  "version": "0.6.29",
   "description": "Belong — embeddable React AI assistant dock. Mount <BelongWidget> in your app tree with getToken dependency-injection auth.",
   "license": "UNLICENSED",
   "type": "module",