guideai-app 0.5.1 → 0.5.4-1

package/dist/devtools/visualContextInspector/inspectorStore.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Tiny event bus + in-memory log that the Visual Context Inspector dev-tool uses.
+ *
+ * Listens to the two `window` events dispatched by the visual-context module:
+ *   - `guideai:screenshot` — a frame was captured and dispatched to the hook.
+ *   - `guideai:vc:send`    — a send decision was made (sent OR skipped with a gate).
+ *
+ * Matches captures to send-decisions by `frame.timestamp` (unique per capture) and
+ * notifies subscribers. Ring-buffers to `MAX_ENTRIES` so long sessions don't leak.
+ *
+ * This file is Inspector-only. `VisualContextInspector` calls `start()` on mount and
+ * `stop()` on unmount so window listeners are not left attached after the panel closes.
+ * Main VC code still dispatches the events unconditionally (cheap when nothing listens).
+ */
+import type { CaptureLogEntry } from './types';
+type Listener = () => void;
+declare class InspectorStore {
+    private entries;
+    private listeners;
+    private nextId;
+    private started;
+    private onScreenshotBound;
+    private onSendBound;
+    start(): void;
+    stop(): void;
+    clear(): void;
+    getEntries(): CaptureLogEntry[];
+    subscribe(listener: Listener): () => void;
+    private appendCapture;
+    private applySendDecision;
+    private trim;
+    private notify;
+}
+export declare const inspectorStore: InspectorStore;
+export {};

package/dist/devtools/visualContextInspector/inspectorStyles.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Inspector-only CSS. Concatenated into the main package stylesheet by
+ * `src/styles/GuideAI.styles.ts`, so the rules are visible both in the light DOM
+ * and (via the Chrome extension's `syncGuideAIStylesToShadow`) inside Shadow DOM.
+ *
+ * All class names are `guideai-vci-*` so the dev-tool does NOT share stylesheet
+ * naming with the rest of the package. Visuals intentionally resemble the Audio
+ * Configuration dialog, but the rules are independent.
+ *
+ * Deleting `devtools/visualContextInspector/` also requires removing the one-liner
+ * append in `GuideAI.styles.ts` that pulls this in.
+ */
+export declare const visualContextInspectorStyles: () => string;

package/dist/devtools/visualContextInspector/types.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Types used by the Visual Context Inspector dev-tool.
+ *
+ * This folder is intentionally self-contained — it can be deleted without breaking
+ * anything outside of `GuideAI.tsx` (which mounts the panel conditionally on
+ * `visualContext.inspector === true`). See `./VisualContextInspector.tsx`.
+ */
+import type { ScreenshotFrame, ScreenshotReason } from '../../visualContext/types';
+/** One row in the Inspector's capture/send log. */
+export interface CaptureLogEntry {
+    /** Monotonic id for list keys. */
+    id: number;
+    /** Frame as dispatched by the scheduler. */
+    frame: ScreenshotFrame;
+    /** `guideai:screenshot` event time. */
+    capturedAt: number;
+    /** `guideai:vc:send` event info; undefined until the hook decides. */
+    send?: {
+        sent: boolean;
+        gate?: string;
+        at: number;
+    };
+}
+export interface InspectorSnapshot {
+    entries: CaptureLogEntry[];
+}
+export type CaptureReason = ScreenshotReason;

package/dist/hooks/index.d.ts

@@ -1,3 +1,9 @@
 export { useGuideAIAPI } from './useGuideAIAPI';
+export { useGuideAILayout } from './useGuideAILayout';
+export type { GuideAILayout, UseGuideAILayoutParams } from './useGuideAILayout';
+export { useMicPromptHook } from './useMicPromptHook';
+export type { MicPromptHookResult, UseMicPromptHookParams } from './useMicPromptHook';
 export { useTranscriptState } from './useTranscriptState';
 export { useWebRTC } from './useWebRTC';
+export { useDocToFormDropFlow } from './useDocToFormDropFlow';
+export type { DocFormProgress, UseDocToFormDropFlowParams, UseDocToFormDropFlowResult, } from './useDocToFormDropFlow';

package/dist/hooks/useAssistantPlaybackMute.d.ts

@@ -0,0 +1,16 @@
+import type { MutableRefObject } from 'react';
+import type { ReactHooks } from '../utils/reactHooks';
+export interface UseAssistantPlaybackMuteParams {
+    hooks: ReactHooks;
+    audioElementRef: MutableRefObject<HTMLAudioElement | null>;
+    isDataChannelOpen: boolean;
+}
+/**
+ * Mute **assistant** (TTS / remote) playback via the WebRTC `<audio>` element.
+ * Separate from mic mute (`guideAI_isMuted`).
+ */
+export declare function useAssistantPlaybackMute({ hooks, audioElementRef, isDataChannelOpen, }: UseAssistantPlaybackMuteParams): {
+    isAssistantPlaybackMuted: boolean;
+    handleToggleAssistantPlaybackMute: () => void;
+    clearAssistantPlaybackMuteOnSessionEnd: () => void;
+};

package/dist/hooks/useAudioConfigSurface.d.ts

@@ -0,0 +1,20 @@
+import type { DataChannelManager } from '../utils/dataChannel';
+import type { ReactHooks } from '../utils/reactHooks';
+import type { AudioConfig, StoredAudioConfig } from '../types/audioConfig.types';
+export interface UseAudioConfigSurfaceParams {
+    hooks: ReactHooks;
+    hasMic: boolean;
+    getDataChannel: () => DataChannelManager | null;
+}
+/**
+ * Audio settings dialog: open/close, default mic label for the dialog,
+ * and apply → storage + realtime session.update.
+ * Entry UI: transcript ⋯ menu → Debug → “Audio settings” (when debug more menu is on).
+ */
+export declare function useAudioConfigSurface({ hooks, hasMic, getDataChannel, }: UseAudioConfigSurfaceParams): {
+    showConfigDialog: boolean;
+    handleOpenConfigDialog: () => void;
+    handleCloseConfigDialog: () => void;
+    handleApplyAudioConfig: (config: AudioConfig, stored: StoredAudioConfig) => void;
+    defaultMicLabel: string | null;
+};

package/dist/hooks/useConversationSession.d.ts

@@ -0,0 +1,69 @@
+import type { Dispatch, MutableRefObject, SetStateAction } from 'react';
+import type { GuideAIProps, RecordingStatus } from '../types/GuideAI.types';
+import type { ReactHooks } from '../utils/reactHooks';
+import type { ConversationManager } from '../utils/conversationManager';
+import type { DataChannelManager } from '../utils/dataChannel';
+import type { UseVisualContextReturn } from '../visualContext/useVisualContext';
+import type { StoredMessage } from '../utils/messageStorage';
+import type { InitializeWebRTCCallOptions } from './useWebRTC';
+export type UseConversationSessionParams = {
+    hooks: ReactHooks;
+    conversationKey: string;
+    keyTrim: string;
+    hasPortalAuth: boolean;
+    workspaceDataSource: 'api' | 'stub';
+    widgetAuthWorkspace: string | undefined;
+    transcriptOptions: GuideAIProps['transcript'];
+    inputOptions: GuideAIProps['input'];
+    hasInteracted: boolean;
+    setHasInteractedState: Dispatch<SetStateAction<boolean>>;
+    setShowOnboarding: Dispatch<SetStateAction<boolean>>;
+    isConversationActive: boolean;
+    setIsConversationActive: Dispatch<SetStateAction<boolean>>;
+    setStatus: Dispatch<SetStateAction<RecordingStatus>>;
+    setIsResponseActive: Dispatch<SetStateAction<boolean>>;
+    setIsConnecting: Dispatch<SetStateAction<boolean>>;
+    setShowTranscript: Dispatch<SetStateAction<boolean>>;
+    setShowTextInput: Dispatch<SetStateAction<boolean>>;
+    setInputMode: Dispatch<SetStateAction<'voice' | 'text'>>;
+    setHasMic: Dispatch<SetStateAction<boolean>>;
+    setAllMessages: Dispatch<SetStateAction<StoredMessage[]>>;
+    /** Close workflow drawer when ending session (`useTranscriptChrome` owns dock/float panel mode). */
+    setWorkflowDrawerOpen: Dispatch<SetStateAction<boolean>>;
+    hasInitializedRef: MutableRefObject<boolean>;
+    isConversationActiveRef: MutableRefObject<boolean>;
+    peerConnectionRef: MutableRefObject<RTCPeerConnection | null>;
+    dataChannelManagerRef: MutableRefObject<DataChannelManager | null>;
+    mediaStreamRef: MutableRefObject<MediaStream | null>;
+    conversationManagerRef: MutableRefObject<ConversationManager | null>;
+    cleanupWebRTC: () => void;
+    initializeWebRTC: (audioStream: MediaStream | null, callOptions?: InitializeWebRTCCallOptions) => Promise<boolean>;
+    applyMuteStateToMediaStreamTracks: () => void;
+    visualContext: Pick<UseVisualContextReturn, 'cleanupOnConversationEnd'>;
+    protectedPlayback: {
+        resetProtectedPlayback: () => void;
+    };
+    errorHandlingTimeoutRefs: MutableRefObject<Set<NodeJS.Timeout>>;
+    hasAttemptedAutoStartRef: MutableRefObject<boolean>;
+    flushPendingWorkspaceCatalogOnEndSession: () => void;
+    clearWorkspaceCatalogCacheForReset: () => void;
+    pendingWorkspaceGreetingRef: MutableRefObject<string | null>;
+    workspaceGreetingRef: MutableRefObject<string | null>;
+    clearPendingWorkflowSteerTitle: () => void;
+    reestablishRealtimeSessionRef: MutableRefObject<((callOptions?: InitializeWebRTCCallOptions) => Promise<boolean>) | null>;
+    endConversationSessionRef: MutableRefObject<() => void>;
+    handleResetChatRef: MutableRefObject<() => Promise<void>>;
+    scheduleWorkspaceCatalogFetch: () => Promise<void>;
+    resetNoisySuggestForChatReset: () => void;
+    /** Runs at the start of `endConversationSession` (toolbar X, errors, reset chat, etc.). */
+    onBeforeEndConversationSession?: () => void;
+};
+export declare function useConversationSession(params: UseConversationSessionParams): {
+    startConversationSession: () => Promise<boolean>;
+    reestablishActiveRealtimeSession: (callOptions?: InitializeWebRTCCallOptions) => Promise<boolean>;
+    endConversationSession: () => void;
+    toggleConversation: (force?: boolean) => Promise<void>;
+    handleToggleConversation: () => Promise<void>;
+    handleResetChat: () => Promise<void>;
+    handleOnboardingComplete: () => Promise<void>;
+};

package/dist/hooks/useDocToFormDropFlow.d.ts

@@ -0,0 +1,31 @@
+import type { MutableRefObject } from 'react';
+import type { ReactHooks } from '../utils/reactHooks';
+import type { ConversationManager } from '../utils/conversationManager';
+import type { DataChannelManager } from '../utils/dataChannel';
+export type DocFormProgress = 'off' | 'extracting' | 'filling';
+export interface UseDocToFormDropFlowParams {
+    hooks: ReactHooks;
+    isConversationActive: boolean;
+    isDataChannelOpen: boolean;
+    isResponseActive: boolean;
+    showTranscript: boolean;
+    dataChannelManagerRef: MutableRefObject<DataChannelManager | null>;
+    conversationManagerRef: {
+        current: ConversationManager | null;
+    };
+}
+export interface UseDocToFormDropFlowResult {
+    docFormProgress: DocFormProgress;
+    fileDragOverDocument: boolean;
+    transcriptFileDropAllowed: boolean;
+    handleTranscriptFileDrop: (file: File) => void;
+}
+/**
+ * Owns the docToForm / fillForm drag-and-drop transcript flow:
+ * - tracks extraction/filling progress (`docFormProgress`),
+ * - tracks document-wide OS file-drag state (`fileDragOverDocument`),
+ * - gates drop acceptance (`transcriptFileDropAllowed`), and
+ * - runs Gemini extraction + posts the extracted text to the realtime data channel
+ *   when a file is dropped on the transcript card.
+ */
+export declare function useDocToFormDropFlow({ hooks, isConversationActive, isDataChannelOpen, isResponseActive, showTranscript, dataChannelManagerRef, conversationManagerRef, }: UseDocToFormDropFlowParams): UseDocToFormDropFlowResult;

package/dist/hooks/useGuideAIAPI.d.ts

@@ -4,18 +4,15 @@
 import type { UseEffectHook } from '../types/GuideAI.types';
 export interface UseGuideAIAPIParams {
     useEffect: UseEffectHook;
-    organizationKey: string;
-    setShowTranscript: (value: React.SetStateAction<boolean>) => void;
-    showTranscript: boolean;
+    conversationKey: string;
     setInputMode: (mode: 'voice' | 'text') => void;
-    setShowTextInput: (value: React.SetStateAction<boolean>) => void;
+    setShowTextInput: (value: boolean | ((prev: boolean) => boolean)) => void;
     inputMode: 'voice' | 'text';
-    setTextInput: (value: React.SetStateAction<string>) => void;
+    setTextInput: (value: string) => void;
     inputOptions?: {
         enableTextInput?: boolean;
     };
     isConversationActive: boolean;
-    handleToggleInputMode: () => void;
     handleTextSubmit: (text?: string) => Promise<void>;
     visualContextWindowAPI: any;
 }

package/dist/hooks/useGuideAILayout.d.ts

@@ -0,0 +1,38 @@
+import type { CSSProperties } from 'react';
+import type { ZIndexConfig } from '../styles/GuideAI.styles.types';
+import type { GuideAIProps, GuideAIPosition, PopupPosition, TranscriptPanelMode, TranscriptPosition } from '../types/GuideAI.types';
+type LayoutHooks = {
+    useState: <T>(initial: T | (() => T)) => [T, (value: T | ((prev: T) => T)) => void];
+    useMemo: <T>(factory: () => T, deps: any[]) => T;
+    useCallback: <T extends (...args: any[]) => any>(callback: T, deps: any[]) => T;
+    useEffect: (effect: () => void | (() => void), deps?: any[]) => void;
+};
+export interface UseGuideAILayoutParams {
+    hooks: LayoutHooks;
+    position?: GuideAIPosition;
+    transcriptOptions?: GuideAIProps['transcript'];
+    zIndexConfig: ZIndexConfig;
+    /** Key for transcript drawer width pref in localStorage. */
+    layoutPrefsKey: string;
+    showTranscript: boolean;
+    /**
+     * `docked` = full-height transcript side panel (toolbar float/dock toggle).
+     * Not the workflow checklist drawer (`workflowDrawerOpen` in TranscriptBox).
+     */
+    transcriptPanelMode: TranscriptPanelMode;
+}
+export interface GuideAILayout {
+    /** Mic / floating UI position (may shift when the transcript docked panel is open). */
+    layoutPosition: GuideAIPosition;
+    transcriptPosition: TranscriptPosition;
+    popupPosition: PopupPosition;
+    baseStyles: CSSProperties;
+    drawerWidthPx: number;
+    onDrawerWidthChange: (nextWidthPx: number) => void;
+}
+/**
+ * Transcript docked-panel width persistence, mic position offset when the docked panel is visible,
+ * welcome-bubble / onboarding popup placement from mic geometry, fixed mic shell styles, and document `padding-right` while docked.
+ */
+export declare function useGuideAILayout({ hooks, position, transcriptOptions, zIndexConfig, layoutPrefsKey, showTranscript, transcriptPanelMode, }: UseGuideAILayoutParams): GuideAILayout;
+export {};

package/dist/hooks/useGuideAILocalStorageSync.d.ts

@@ -0,0 +1,17 @@
+import type { Dispatch, SetStateAction } from 'react';
+import type { ReactHooks } from '../utils/reactHooks';
+import { getWorkspaceDataSource } from '../utils/localStorageHelper';
+export type GuideAILocalStorageSyncHooks = Pick<ReactHooks, 'useState' | 'useEffect'>;
+export type UseGuideAILocalStorageSyncParams = {
+    hooks: GuideAILocalStorageSyncHooks;
+};
+export type GuideAILocalStorageSync = {
+    debugMoreMenu: boolean;
+    workspaceDataSource: ReturnType<typeof getWorkspaceDataSource>;
+    setWorkspaceDataSourceState: Dispatch<SetStateAction<ReturnType<typeof getWorkspaceDataSource>>>;
+};
+/**
+ * Cross-tab localStorage sync for debug menu visibility and workspace data source (stub vs API).
+ * Keeps `GuideAI.tsx` free of raw `window.addEventListener` for these keys.
+ */
+export declare function useGuideAILocalStorageSync({ hooks, }: UseGuideAILocalStorageSyncParams): GuideAILocalStorageSync;

package/dist/hooks/useHiddenRealtimeSteers.d.ts

@@ -0,0 +1,22 @@
+import type { MutableRefObject } from 'react';
+import type { ConversationManager } from '../utils/conversationManager';
+import type { DataChannelManager } from '../utils/dataChannel';
+import type { ReactHooks } from '../utils/reactHooks';
+export interface UseHiddenRealtimeSteersParams {
+    hooks: ReactHooks;
+    isDataChannelOpen: boolean;
+    isConversationActive: boolean;
+    pendingWorkspaceGreetingRef: MutableRefObject<string | null>;
+    pendingWorkflowSteerTitle: string | null;
+    clearPendingWorkflowSteerTitle: () => void;
+    dataChannelManagerRef: MutableRefObject<DataChannelManager | null>;
+    conversationManagerRef: {
+        current: ConversationManager | null;
+    };
+    scheduleInterruptLockThenSend: (dcm: DataChannelManager, send: () => void, reason: string) => void;
+}
+/**
+ * Hidden `conversation.item.create` + `response.create` for workspace greeting and workflow steer,
+ * with Noisy-preset interrupt lock sequencing via `scheduleInterruptLockThenSend`.
+ */
+export declare function useHiddenRealtimeSteers({ hooks, isDataChannelOpen, isConversationActive, pendingWorkspaceGreetingRef, pendingWorkflowSteerTitle, clearPendingWorkflowSteerTitle, dataChannelManagerRef, conversationManagerRef, scheduleInterruptLockThenSend, }: UseHiddenRealtimeSteersParams): void;

package/dist/hooks/useMicMute.d.ts

@@ -0,0 +1,20 @@
+import type { MutableRefObject } from 'react';
+import type { ConversationManager } from '../utils/conversationManager';
+import type { ReactHooks } from '../utils/reactHooks';
+export interface UseMicMuteParams {
+    hooks: ReactHooks;
+    mediaStreamRef: MutableRefObject<MediaStream | null>;
+    conversationManagerRef: {
+        current: ConversationManager | null;
+    };
+    hasMic: boolean;
+    isConversationActive: boolean;
+}
+/**
+ * Mute preference (localStorage), toggle + server log, and `MediaStream` track `enabled` sync.
+ */
+export declare function useMicMute({ hooks, mediaStreamRef, conversationManagerRef, hasMic, isConversationActive, }: UseMicMuteParams): {
+    isMuted: boolean;
+    handleToggleMute: () => void;
+    applyMuteStateToMediaStreamTracks: () => void;
+};

package/dist/hooks/useMicPreset.d.ts

@@ -0,0 +1,19 @@
+import type { ConversationManager } from '../utils/conversationManager';
+import type { DataChannelManager } from '../utils/dataChannel';
+import type { ReactHooks } from '../utils/reactHooks';
+import type { MicPresetId } from '../types/audioConfig.types';
+export interface UseMicPresetParams {
+    hooks: ReactHooks;
+    conversationManagerRef: {
+        current: ConversationManager | null;
+    };
+    getDataChannel: () => DataChannelManager | null;
+}
+/**
+ * Mic preset UI state, localStorage sync, apply + session.update, and debug logging to the server.
+ */
+export declare function useMicPreset({ hooks, conversationManagerRef, getDataChannel, }: UseMicPresetParams): {
+    micPreset: MicPresetId;
+    handleApplyMicPreset: (preset: MicPresetId) => void;
+    logMicPresetToServer: (preset: MicPresetId) => void;
+};

package/dist/hooks/useMicPromptHook.d.ts

@@ -0,0 +1,28 @@
+import type { MicPromptAnimationId } from '../types/GuideAI.types';
+export interface MicPromptHookResult {
+    animation: MicPromptAnimationId | null;
+    message: string | null;
+    /** Pre-interaction presentation (pill-expand inside the mic shell). */
+    isPill: boolean;
+    /** Visible in any form (reveal or closing animation). */
+    onSurface: boolean;
+    /** Reveal-complete; closing has not started yet. */
+    revealed: boolean;
+    /** Closing animation (pill collapse or simple bubble exit) is running. */
+    closing: boolean;
+    reduceMotion: boolean;
+}
+export interface UseMicPromptHookParams {
+    /** All gate conditions pre-combined: idle && !transcript && !onboarding && !connecting. */
+    eligible: boolean;
+    /** Source of truth for pre (`false`) vs post (`true`) presentation. */
+    hasInteracted: boolean;
+}
+/**
+ * "The hook" — idle mic call-to-action lifecycle (see `docs/THE_HOOK.md`).
+ *
+ * State machine: `hidden → waiting → visible → closing → hidden`. One timer at a time.
+ * `isPill` is cached at pick time (`!hasInteracted`); if `hasInteracted` flips mid-lifecycle the
+ * active pick is discarded and the cycle resets.
+ */
+export declare function useMicPromptHook(React: typeof import('react'), { eligible, hasInteracted }: UseMicPromptHookParams): MicPromptHookResult;

package/dist/hooks/useNoisyPresetSuggest.d.ts

@@ -0,0 +1,19 @@
+import type { MicPresetId } from '../types/audioConfig.types';
+export interface UseNoisyPresetSuggestParams {
+    micPreset: MicPresetId;
+    isDataChannelOpen: boolean;
+    onApplyMicPreset?: (preset: MicPresetId) => void;
+}
+/**
+ * Precise-only barge-in hint to switch to Noisy preset. Lives in GuideAI; transcript stays presentational via props.
+ */
+export declare function useNoisyPresetSuggest({ micPreset, isDataChannelOpen, onApplyMicPreset, }: UseNoisyPresetSuggestParams): {
+    noisyPresetSuggestVisible: boolean;
+    onNoisyPresetSuggestYes: () => void;
+    onNoisyPresetSuggestNo: () => void;
+    onNoisyPresetSuggestAutoDismiss: () => void;
+    /** Call from `handlePlaybackInterruptedByUser` (stable ref for current Precise / dismissed state). */
+    notifyPlaybackInterrupted: () => void;
+    /** Call from chat reset (clears “don’t ask again” for this conversation). */
+    resetNoisySuggestForChatReset: () => void;
+};

package/dist/hooks/usePlaybackLockDebugOverlay.d.ts

@@ -0,0 +1,12 @@
+import type { ReactHooks } from '../utils/reactHooks';
+export interface UsePlaybackLockDebugOverlayParams {
+    hooks: ReactHooks;
+}
+/**
+ * Transcript ⋯ → Debug → playback lock panel: visibility (localStorage + cross-tab sync), close, toggle.
+ */
+export declare function usePlaybackLockDebugOverlay({ hooks }: UsePlaybackLockDebugOverlayParams): {
+    visible: boolean;
+    close: () => void;
+    toggle: () => void;
+};

package/dist/hooks/useProtectedPlayback.d.ts

@@ -0,0 +1,36 @@
+import type { MutableRefObject } from 'react';
+import type { ConversationManager } from '../utils/conversationManager';
+import type { DataChannelManager } from '../utils/dataChannel';
+import type { ReactHooks } from '../utils/reactHooks';
+import type { MicPresetId } from '../types/audioConfig.types';
+export interface UseProtectedPlaybackParams {
+    hooks: ReactHooks;
+    conversationManagerRef: {
+        current: ConversationManager | null;
+    };
+    getDataChannel: () => DataChannelManager | null;
+    playbackInterruptNoisyRef: MutableRefObject<() => void>;
+    micPreset: MicPresetId;
+    isDataChannelOpen: boolean;
+}
+export interface InterruptLockOverlayConfig {
+    lockMode: 'system_interrupt_lock' | 'none';
+    vadType: 'server_vad' | 'off' | 'semantic_vad';
+    threshold: number | undefined;
+    interruptResponse: boolean | undefined;
+}
+/**
+ * System "interrupt lock" for Noisy preset: VAD config during protected assistant playback,
+ * restore on output end, barge-in debug + noisy preset nudge wiring.
+ */
+export declare function useProtectedPlayback({ hooks, conversationManagerRef, getDataChannel, playbackInterruptNoisyRef, micPreset, isDataChannelOpen, }: UseProtectedPlaybackParams): {
+    protectedPlaybackActiveRef: MutableRefObject<boolean>;
+    protectedPlaybackActive: boolean;
+    playbackInterruptDebug: boolean;
+    handlePlaybackInterruptedByUser: () => void;
+    handleAudioOutputStopped: () => void;
+    handleAudioOutputStartedClearInterrupt: () => void;
+    resetProtectedPlayback: () => void;
+    scheduleInterruptLockThenSend: (dcm: DataChannelManager, send: () => void, reason: string) => void;
+    overlayConfig: InterruptLockOverlayConfig;
+};

package/dist/hooks/useTranscriptChrome.d.ts

@@ -0,0 +1,39 @@
+import type { Dispatch, MutableRefObject, SetStateAction } from 'react';
+import type { TranscriptPanelMode, TranscriptSessionMode } from '../types/GuideAI.types';
+import type { StubWorkflowItem, StubWorkspaceOption } from '../stubs/workspaces';
+import type { ConversationManager } from '../utils/conversationManager';
+import type { ReactHooks } from '../utils/reactHooks';
+import type { InitializeWebRTCCallOptions } from './useWebRTC';
+export type UseTranscriptChromeHooks = Pick<ReactHooks, 'useState' | 'useEffect' | 'useCallback' | 'useRef'>;
+export type UseTranscriptChromeParams = {
+    hooks: UseTranscriptChromeHooks;
+    /** Key for transcript panel dock/float prefs in localStorage (per embed / conversation namespace). */
+    layoutPrefsKey: string;
+    showTranscript: boolean;
+    workspaceOptions: StubWorkspaceOption[];
+    workspaceDataSource: 'stub' | 'api';
+    apiWorkflowsByWorkspaceId: Record<string, StubWorkflowItem[]> | null;
+    keyTrim: string;
+    hasPortalAuth: boolean;
+    reestablishRealtimeSessionRef: MutableRefObject<((callOptions?: InitializeWebRTCCallOptions) => Promise<boolean>) | null>;
+    queueWorkflowSteerTitle: (title: string) => void;
+    clearPendingWorkflowSteerTitle: () => void;
+    conversationManagerRef: MutableRefObject<ConversationManager | null>;
+    /** When set (e.g. shared with `useWorkspaceCatalog`), used instead of an internal ref. */
+    sessionWorkflowIdForInitRef?: MutableRefObject<string | null>;
+};
+export type TranscriptChrome = {
+    sessionWorkflowIdForInitRef: MutableRefObject<string | null>;
+    transcriptPanelMode: TranscriptPanelMode;
+    workflowDrawerOpen: boolean;
+    transcriptSessionMode: TranscriptSessionMode;
+    setTranscriptSessionMode: Dispatch<SetStateAction<TranscriptSessionMode>>;
+    setWorkflowDrawerOpen: Dispatch<SetStateAction<boolean>>;
+    handleToggleTranscriptPanelMode: () => void;
+    handleTranscriptSessionModeChange: (mode: TranscriptSessionMode) => void;
+};
+/**
+ * Transcript dock/float preference, workflow drawer visibility, and workspace session mode
+ * (including reconnect + first workflow steer after mode change).
+ */
+export declare function useTranscriptChrome({ hooks, layoutPrefsKey, showTranscript, workspaceOptions, workspaceDataSource, apiWorkflowsByWorkspaceId, keyTrim, hasPortalAuth, reestablishRealtimeSessionRef, queueWorkflowSteerTitle, clearPendingWorkflowSteerTitle, conversationManagerRef, sessionWorkflowIdForInitRef: sessionWorkflowIdForInitRefProp, }: UseTranscriptChromeParams): TranscriptChrome;

package/dist/hooks/useTranscriptState.d.ts

@@ -10,7 +10,7 @@ export interface UseTranscriptStateParams {
         };
         useCallback: <T extends (...args: any[]) => any>(callback: T, deps: any[]) => T;
     };
-    organizationKey: string;
+    conversationKey: string;
     setAllMessages: React.Dispatch<React.SetStateAction<StoredMessage[]>>;
     setStatus: (status: RecordingStatus) => void;
 }

package/dist/hooks/useWebRTC.d.ts

@@ -20,16 +20,22 @@ export interface UseWebRTCParams {
         };
         useCallback: <T extends (...args: any[]) => any>(callback: T, deps: any[]) => T;
     };
-    organizationKey: string;
+    /** Namespace for local conversation / transcript storage (`guideAI_conversation`). */
+    conversationKey: string;
+    /** Sent to /initialize when not using Bearer (access key + workspace only on session exchange otherwise). */
+    widgetAuth?: {
+        authKey?: string;
+        workspace?: string;
+    };
+    /** Pre-issued widget Bearer JWT (portal / extension); skips ensureWidgetSession. */
+    widgetSessionToken?: string;
+    /** Sent as `user` on /initialize when using widget Bearer (e.g. portal AuthUser id). */
+    initializeUserId?: string;
     environment: GuideAIEnvironment;
     setIsDataChannelOpen: (open: boolean) => void;
     setIsResponseActive: (active: boolean) => void;
     setIsConnecting: (connecting: boolean) => void;
     setStatus: (status: RecordingStatus) => void;
-    handleHighlightThenClick: (out: any) => Promise<boolean>;
-    handleHoverThenClick: (out: any) => Promise<boolean>;
-    handleHover: (out: any) => Promise<boolean>;
-    handleGoToAElmLink: (linkText: string, delay?: number) => Promise<boolean>;
     handleResetChatRef: {
         current: () => Promise<void>;
     };
@@ -46,7 +52,36 @@ export interface UseWebRTCParams {
     onMessageLogged: () => void;
     /** Optional tools from component prop: Record<functionName, { description, parameters, execute }> */
     tools?: PropTools;
+    onSessionUpdated?: (session: any) => void;
+    onAudioOutputStarted?: () => void;
+    onAudioOutputStopped?: () => void;
+    /** Fired when user speech starts during assistant `output_audio_buffer` playback. */
+    onPlaybackInterruptedByUser?: () => void;
+    /** Set connection message (e.g. "Retrying...") during init retries */
+    setConnectionMessage: (msg: string | null) => void;
+    /** Called when initialize fails after all retries */
+    onInitializeError?: (error: {
+        message: string;
+    }) => void;
+    /** Latest workspace `greeting` from initialize (access-key); cleared when absent. */
+    workspaceGreetingRef?: {
+        current: string | null;
+    };
+    /** Fire-and-forget workspace catalog fetch in parallel with initialize (after access-key session if any). */
+    onWorkspaceCatalogPrefetch?: () => void;
+    /** Read at connect — published workflow id for /initialize (null = server default). */
+    sessionWorkflowIdForInitRef?: {
+        current: string | null;
+    };
+    /** When true, omit sessionWorkflowId so the server uses full rollup instructions. */
+    rollupWorkflowsForInitRef?: {
+        current: boolean;
+    };
 }
+/** One-shot options for a single `initializeWebRTC` call (e.g. reconnect before React commits new workspace). */
+export type InitializeWebRTCCallOptions = {
+    workspaceForInit?: string;
+};
 export declare function useWebRTC(params: UseWebRTCParams): {
     peerConnectionRef: {
         current: RTCPeerConnection | null;
@@ -67,5 +102,5 @@ export declare function useWebRTC(params: UseWebRTCParams): {
         current: string | null;
     };
     cleanupWebRTC: () => void;
-    initializeWebRTC: (audioStream: MediaStream | null) => Promise<boolean>;
+    initializeWebRTC: (audioStream: MediaStream | null, callOptions?: InitializeWebRTCCallOptions) => Promise<boolean>;
 };

package/dist/hooks/useWidgetWorkflowSession.d.ts

@@ -0,0 +1,35 @@
+import type { MutableRefObject } from 'react';
+import type { TranscriptSessionMode } from '../types/GuideAI.types';
+import type { StubWorkspaceOption } from '../stubs/workspaces';
+import type { ReactHooks } from '../utils/reactHooks';
+import type { InitializeWebRTCCallOptions } from './useWebRTC';
+export type UseWidgetWorkflowSessionParams = {
+    hooks: ReactHooks;
+    workspaceOptions: StubWorkspaceOption[];
+    transcriptSessionMode: TranscriptSessionMode;
+    /**
+     * Optional shared ref (e.g. with `useWorkspaceCatalog` apply) so clearing workflow id stays in
+     * sync. If omitted, an internal ref is used unless `sessionWorkflowIdForInitRefOverride` is set.
+     */
+    sessionWorkflowIdForInitRef?: MutableRefObject<string | null>;
+    /** Filled after `reestablishActiveRealtimeSession` is defined; read at call time. */
+    reestablishRef: MutableRefObject<((callOptions?: InitializeWebRTCCallOptions) => Promise<boolean>) | null>;
+    /**
+     * Optional shared ref (e.g. with `useTranscriptChrome`) so clearing workflow id on session mode
+     * change stays in sync. Takes precedence over `sessionWorkflowIdForInitRef` when both are set.
+     */
+    sessionWorkflowIdForInitRefOverride?: MutableRefObject<string | null>;
+};
+/**
+ * Access-key workflow focus for /initialize (sessionWorkflowId vs rollup) and pending hidden
+ * workflow steer after reconnect (non-rollup) or immediately (rollup).
+ */
+export declare function useWidgetWorkflowSession(params: UseWidgetWorkflowSessionParams): {
+    sessionWorkflowIdForInitRef: MutableRefObject<string | null>;
+    rollupWorkflowsForInitRef: MutableRefObject<boolean>;
+    pendingWorkflowSteerTitle: string | null;
+    clearPendingWorkflowSteerTitle: () => void;
+    /** Queue hidden `Start the … Workflow` steer once the data channel is ready. */
+    queueWorkflowSteerTitle: import("react").Dispatch<import("react").SetStateAction<string | null>>;
+    onSessionWorkflowForRealtimeInit: (workflowId: string | null, workflowLabel?: string) => void;
+};