guideai-app 0.5.1 → 0.5.4-1

package/dist/staticContext/collectContext.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Pure DOM collectors for the Static Context blob. No DOM mutation, no
+ * network, no React. Exists in its own module so the hook can dedup against
+ * a stable hash of the result.
+ */
+import { SpaRouteSnapshot, StaticContextIncludeFlags, StaticContextPayload, StaticContextTrigger } from './types';
+export interface CollectStaticContextOptions {
+    trigger: StaticContextTrigger;
+    rebuild: boolean;
+    include?: StaticContextIncludeFlags;
+    scrollBucketPx?: number;
+    spaRoute?: SpaRouteSnapshot;
+    includeRouterState?: boolean;
+}
+/**
+ * Collect a fresh static-context payload from the live DOM. Cheap enough to
+ * call on every heartbeat / activity tick — the dedup hash is computed by
+ * the caller after this returns.
+ */
+export declare function collectStaticPageContext(opts: CollectStaticContextOptions): StaticContextPayload;
+/**
+ * Stable hash of the fields whose change should trigger a fresh send.
+ * Operational metadata (`trigger`, `rebuild`, `capturedAt`) is excluded so the
+ * heartbeat cannot send the same blob over and over.
+ */
+export declare function hashStaticContextPayload(payload: StaticContextPayload): string;
+/** Format a payload for the realtime model — short tag + JSON body. */
+export declare function formatStaticContextForModel(payload: StaticContextPayload): string;

package/dist/staticContext/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Static Context module — pushes a structured page-metadata blob to the
+ * realtime model alongside Visual Context's screenshot pipeline.
+ */
+export { useStaticContext } from './useStaticContext';
+export { collectStaticPageContext, formatStaticContextForModel, hashStaticContextPayload, } from './collectContext';
+export type { StaticContextConfig, StaticContextPayload, StaticContextTrigger, StaticContextLocation, StaticContextIncludeFlags, StaticDialogContext, StaticFocusedControl, SpaRouteSnapshot, PageActivityDetail, PageActivityKind, } from './types';
+export { PAGE_ACTIVITY_EVENT, STATIC_CONTEXT_SCHEMA_VERSION } from './types';

package/dist/staticContext/types.d.ts

@@ -0,0 +1,176 @@
+/**
+ * Type definitions for the Static Context module.
+ *
+ * Static Context sends a structured page-metadata blob to the realtime model
+ * alongside the Visual Context screenshot pipeline. See `docs/STATIC_CONTEXT.md`
+ * (or the inline header in `useStaticContext.ts`) for the full design.
+ */
+export declare const STATIC_CONTEXT_SCHEMA_VERSION = 1;
+/** Why a static-context send was triggered. Aligned with the VC trigger taxonomy. */
+export type StaticContextTrigger = 'initial' | 'heartbeat' | 'navigation' | 'dom_update' | 'tool_batch' | 'pointer';
+/**
+ * Optional declarative SPA route snapshot the embedder fills from React Router
+ * (or any other router) — the package does **not** depend on `react-router`.
+ *
+ * Keep all values plain JSON-serializable; the package merges this object into
+ * the static-context blob under the fixed key `spaRoute`.
+ */
+export interface SpaRouteSnapshot {
+    pathname?: string;
+    search?: string;
+    hash?: string;
+    key?: string;
+    params?: Record<string, string>;
+    /** Matched pattern string when the host wants to pass it (e.g. `/users/:id`). */
+    pathnamePattern?: string;
+    /**
+     * `location.state` from React Router. Surfaced in the blob only when
+     * `staticContext.includeRouterState === true` and only if shallow + JSON-safe
+     * within the size cap (see `useStaticContext`).
+     */
+    state?: unknown;
+}
+/**
+ * Bucketed opt-ins for fields the host can include in the blob. v1 ships
+ * conservative defaults; richer presets can be layered in later.
+ */
+export interface StaticContextIncludeFlags {
+    /** First 1–3 visible headings (h1–h3) inside main content. Default `true`. */
+    headings?: boolean;
+    /** Landmark roles in document order (`main`, `nav`, etc.). Default `false`. */
+    landmarks?: boolean;
+    /** Viewport size + document scroll height. Default `false`. */
+    viewport?: boolean;
+    /** Scroll band (bucketed per `scrollBucketPx`). Default `false`. */
+    scrollPosition?: boolean;
+    /** Currently-focused form control metadata (no values). Default `true`. */
+    focusedControl?: boolean;
+    /** Open dialog / `aria-modal` snippet. Default `true`. */
+    dialog?: boolean;
+    /** `og:title` / `og:type` / `twitter:title`. Default `false`. */
+    media?: boolean;
+    /** `lang`, `timezone`, `colorScheme`. Default `false`. */
+    tech?: boolean;
+    /** `utm_*` keys parsed from `location.search`. Default `false`. */
+    utm?: boolean;
+}
+export interface StaticContextConfig {
+    /** Master switch. Default `true` — runs whenever a conversation is active. */
+    enabled?: boolean;
+    /**
+     * Heartbeat send interval. Static text is small but still costs tokens, so the
+     * default heartbeat is meaningfully longer than VC's screenshot heartbeat.
+     * Default 12 000 ms (per plan's 8–15s range).
+     */
+    heartbeatMs?: number;
+    /**
+     * Minimum elapsed time between non-urgent sends (ms). Default 8000 — keeps
+     * static off the same tick as VC heartbeats so we do not double up.
+     */
+    minIntervalMs?: number;
+    /**
+     * Minimum elapsed time between urgent sends (ms). Aligns with VC's default
+     * (1200) so navigation / pointer / tool_batch share the same floor.
+     */
+    urgentMinIntervalMs?: number;
+    /** Send a `static_context` immediately on conversation start. Default `true`. */
+    captureOnLoad?: boolean;
+    /** Send a `static_context` after each assistant tool batch completes. Default `true`. */
+    captureAfterTools?: boolean;
+    /** Listen for debounced pointer/click and treat as urgent. Default `true`. */
+    pointerTriggersStaticContext?: boolean;
+    /** Pointer debounce window (ms). Default 300. */
+    pointerDebounceMs?: number;
+    /** Per-bucket toggles for richer DOM fields. */
+    include?: StaticContextIncludeFlags;
+    /** Width of scroll-position buckets in pixels (only used when `include.scrollPosition === true`). Default 200. */
+    scrollBucketPx?: number;
+    /**
+     * Optional declarative SPA route snapshot. The package never imports
+     * `react-router`; the host passes this in from `useLocation()` etc.
+     */
+    spaRoute?: SpaRouteSnapshot;
+    /**
+     * Surface `spaRoute.state` on the blob when present. Default `false` —
+     * router state can carry app-level data we have not vetted; keep it opt-in.
+     */
+    includeRouterState?: boolean;
+}
+/**
+ * Lightweight focused-control snapshot — no values, only structural identifiers.
+ * Excludes `<input value>`, selected option text, contenteditable text, password
+ * inputs, and inputs whose `autocomplete` looks like a card / sensitive field.
+ */
+export interface StaticFocusedControl {
+    tag: string;
+    type?: string;
+    id?: string;
+    name?: string;
+    role?: string;
+    ariaLabel?: string;
+    placeholder?: string;
+    autocomplete?: string;
+}
+export interface StaticDialogContext {
+    role: string;
+    heading?: string;
+    ariaLabel?: string;
+}
+export interface StaticContextLocation {
+    href: string;
+    pathname?: string;
+    search?: string;
+    hash?: string;
+    host?: string;
+    origin?: string;
+}
+export interface StaticContextPayload {
+    schemaVersion: number;
+    trigger: StaticContextTrigger;
+    rebuild: boolean;
+    capturedAt: string;
+    location: StaticContextLocation;
+    title?: string;
+    description?: string;
+    lang?: string;
+    canonical?: string;
+    headings?: string[];
+    landmarks?: string[];
+    viewport?: {
+        w: number;
+        h: number;
+        scrollHeight?: number;
+    };
+    scroll?: {
+        yBucket: number;
+        bucketSize: number;
+    };
+    focusedControl?: StaticFocusedControl;
+    dialog?: StaticDialogContext;
+    media?: {
+        ogTitle?: string;
+        ogType?: string;
+        twitterTitle?: string;
+    };
+    tech?: {
+        lang?: string;
+        timezone?: string;
+        locale?: string;
+        colorScheme?: string;
+    };
+    utm?: Record<string, string>;
+    spaRoute?: SpaRouteSnapshot;
+}
+/**
+ * Window-level CustomEvent dispatched by Visual Context's `domChangeTracker`
+ * (or by `useStaticContext`'s fallback tracker when VC is disabled). Listeners
+ * inside the package consume it to drive non-VC pipelines (currently just
+ * static context). Keeps us at one MutationObserver / scroll / nav listener
+ * stack across both subsystems.
+ */
+export type PageActivityKind = 'navigation' | 'scroll' | 'dom_burst';
+export interface PageActivityDetail {
+    kind: PageActivityKind;
+    timestamp: number;
+}
+export declare const PAGE_ACTIVITY_EVENT = "guideai:page-activity";

package/dist/staticContext/useStaticContext.d.ts

@@ -0,0 +1,32 @@
+/**
+ * useStaticContext — companion to `useVisualContext` that pushes a structured
+ * page-metadata blob (URL / title / description / DOM signals) to the realtime
+ * model and logs each send through the conversation messages API.
+ *
+ * Design highlights:
+ *   - **No `response.create`**: items are sent as `conversation.item.create`
+ *     only, identical to how VC delivers screenshots. The model uses them as
+ *     background context on the next natural turn — no surprise TTS reply,
+ *     no separate transcript line.
+ *   - **Single observer**: when Visual Context is enabled it owns the only
+ *     `domChangeTracker`; this hook just listens for the
+ *     `guideai:page-activity` events VC re-broadcasts. When VC is disabled
+ *     this hook spins up its own minimal tracker so we never run two.
+ *   - **Looser send gate than VC**: any active conversation may send static
+ *     context, including `idle` / `playing` statuses. VC rules are unchanged.
+ */
+import { StaticContextConfig, StaticContextPayload } from './types';
+export type StaticContextRecordingStatus = 'idle' | 'recording' | 'active' | 'processing' | 'playing';
+export interface UseStaticContextParams {
+    options?: StaticContextConfig;
+    /** Whether Visual Context is also enabled. When `true`, VC owns the
+     * `domChangeTracker`; this hook listens to its `guideai:page-activity`
+     * events instead of starting its own. */
+    visualContextEnabled: boolean;
+    sendMessage: (msg: any) => void;
+    isDataChannelOpen: () => boolean;
+    isConversationActive: boolean;
+    getContainer: () => HTMLElement | null;
+    onLogStaticContext: (content: string, payload: StaticContextPayload) => void;
+}
+export declare function useStaticContext(React: typeof import('react'), params: UseStaticContextParams): void;

package/dist/stubs/workspaces.d.ts

@@ -0,0 +1,36 @@
+/** Icon id: same set as admin embed config (`lib/workspaceEmbedIcons`). */
+export type WorkspaceIconId = string;
+export interface StubWorkspaceOption {
+    /** Workspace slug (stub modes use onboarding | training | doIt). */
+    id: string;
+    label: string;
+    icon: WorkspaceIconId;
+    /** Shown under the selector pill and in the workflow drawer header (stub until server-driven). */
+    description: string;
+    /**
+     * When true, the workflow drawer shows per-step checkboxes and the transcript toolbar shows
+     * completion progress (e.g. 4/16). Other workspaces list steps as links only.
+     * Future: drive from API / workspace config.
+     */
+    workflowChecklistEnabled?: boolean;
+    /**
+     * When false, checklist completion does not trigger confetti. Omitted defaults to true (stub only).
+     * Future: API workspace config.
+     */
+    workflowConfettiEnabled?: boolean;
+    /** API: when true, initialize always sends full rollup instructions (ignore per-workflow session selection). */
+    rollupWorkflows?: boolean;
+}
+/**
+ * Sentinel until `/widget/workspaces` returns. Must not match a real workspace slug or stub ids
+ * (`onboarding`, `training`, `doIt`).
+ */
+export declare const API_WORKSPACE_LOADING_ID = "__guideai_workspace_loading__";
+/** Placeholder row while the workspace catalog request is in flight (API data source). */
+export declare function getApiPlaceholderWorkspaceOptions(): StubWorkspaceOption[];
+export interface StubWorkflowItem {
+    id: string;
+    label: string;
+}
+export declare function getStubWorkspaceOptions(): StubWorkspaceOption[];
+export declare function getStubWorkflowsForWorkspace(workspaceId: string): StubWorkflowItem[];

package/dist/styles/GuideAI.styles.d.ts

@@ -1,7 +1,3 @@
-export interface ZIndexConfig {
-    main: number;
-    transcript: number;
-    microphone: number;
-    onboarding: number;
-}
+export type { ZIndexConfig } from './GuideAI.styles.types';
+import type { ZIndexConfig } from './GuideAI.styles.types';
 export declare const guideAIStyles: (zIndexConfig: ZIndexConfig) => string;

package/dist/styles/GuideAI.styles.types.d.ts

@@ -0,0 +1,6 @@
+export interface ZIndexConfig {
+    main: number;
+    transcript: number;
+    microphone: number;
+    onboarding: number;
+}

package/dist/styles/guideAIStylesCore.d.ts

@@ -0,0 +1,2 @@
+import type { ZIndexConfig } from './GuideAI.styles.types';
+export declare const guideAIStylesCore: (zIndexConfig: ZIndexConfig) => string;

package/dist/styles/guideAIStylesDialogs.d.ts

@@ -0,0 +1,2 @@
+import type { ZIndexConfig } from './GuideAI.styles.types';
+export declare const guideAIStylesDialogs: (zIndexConfig: ZIndexConfig) => string;

package/dist/styles/guideAIStylesMicPrompt.d.ts

@@ -0,0 +1,2 @@
+/** Mic prompt idle CTA: tooltip enter/exit, elongate pill, bubble + icon attention variants, reduced-motion overrides. */
+export declare const guideAIStylesMicPrompt: () => string;

package/dist/styles/guideAIStylesTranscript.d.ts

@@ -0,0 +1,2 @@
+import type { ZIndexConfig } from './GuideAI.styles.types';
+export declare const guideAIStylesTranscript: (zIndexConfig: ZIndexConfig) => string;

package/dist/types/GuideAI.types.d.ts

@@ -1,4 +1,5 @@
 import { VisualContextConfig } from '../visualContext/types';
+import { StaticContextConfig } from '../staticContext/types';
 export type RecordingStatus = 'idle' | 'recording' | 'active' | 'processing' | 'playing';
 export type UseStateHook = <T>(initialState: T | (() => T)) => [T, (value: T | ((prev: T) => T)) => void];
 export type UseEffectHook = (effect: () => void | (() => void), deps?: any[]) => void;
@@ -7,6 +8,19 @@ export type UseRefHook = <T>(initialValue: T) => {
 };
 export type UseCallbackHook = <T extends (...args: any[]) => any>(callback: T, deps: any[]) => T;
 export type GuideAIEnvironment = 'development' | 'production' | 'local';
+/** CSS-driven mic CTA animation ids. Keyframes live in `styles/guideAIStylesMicPrompt.ts`. */
+export declare const MIC_PROMPT_ANIMATION_IDS: readonly ["pulseRing", "bounceNudge", "shimmerGlow", "ribbonPeel", "softWobble", "glowHalo", "stampDrop", "orbitDot", "slideStack", "driftLift", "rippleEcho", "twinklePulse", "sidestepNudge", "magnetPulse", "cornerGlow", "flutterTilt", "depthTap", "auroraSheen", "tickRock", "elongateExpand", "elongateBurst", "elongateSlideReveal", "elongateShadowStack"];
+export type MicPromptAnimationId = (typeof MIC_PROMPT_ANIMATION_IDS)[number];
+/** Pill-style prompts: message inside expanding mic shell (see elongate CSS variants). */
+export declare const MIC_PROMPT_PILL_EXPAND_IDS: readonly ["elongateExpand", "elongateBurst", "elongateSlideReveal", "elongateShadowStack"];
+export type MicPromptPillExpandId = (typeof MIC_PROMPT_PILL_EXPAND_IDS)[number];
+export declare function isMicPromptPillExpand(id: MicPromptAnimationId): id is MicPromptPillExpandId;
+/**
+ * CSS modifier class applied alongside `guideai-mic-elongate` for each pill-expand variant.
+ * Empty string = base elongate class only. Declaring every variant here keeps new pill ids from
+ * silently falling back to the base look.
+ */
+export declare const MIC_PROMPT_PILL_EXPAND_MODIFIERS: Record<MicPromptPillExpandId, string>;
 export type GuideAIPosition = {
     top?: string;
     right?: string;
@@ -21,8 +35,32 @@ export type GuideAIPosition = {
 };
 export type MicButtonPosition = GuideAIPosition;
 export interface GuideAIProps {
-    organizationKey: string;
-    workflowKey?: string;
+    /**
+     * Access key for widget auth (memory only; sent only on `POST /widget/session`). Use with optional `workspace`.
+     * Requires `authKey`, or `widgetSessionToken` with `adminConversationPersistenceKey`.
+     */
+    authKey?: string;
+    /** Workspace slug when using `authKey` (access-key) auth. */
+    workspace?: string;
+    /**
+     * Pre-issued widget Bearer JWT (internal admin / portal tooling). Requires `adminConversationPersistenceKey`.
+     * Written to `guideai_widget_bearer_token` in localStorage; not used for the normal embed flow.
+     */
+    widgetSessionToken?: string;
+    /**
+     * Stable namespace for `guideAI_conversation` in localStorage. Required with `widgetSessionToken`.
+     * Must never be the raw access key. Optional on embeds: when omitted, a non-secret key is derived from
+     * `location.origin` only (so SPA navigations keep the same transcript partition). Pass an explicit value
+     * when multiple widget instances on one page need isolated transcripts.
+     */
+    adminConversationPersistenceKey?: string;
+    /** Value sent as `user` on `/initialize` when using portal/widget Bearer (e.g. portal AuthUser id). */
+    initializeUserId?: string;
+    /**
+     * Optional allowlist of workspace slugs for the catalog request; omit to load all workspaces
+     * for the authenticated customer.
+     */
+    workspaces?: string | string[];
     environment?: GuideAIEnvironment;
     React: typeof import('react');
     ReactDOM: any;
@@ -38,12 +76,35 @@ export interface GuideAIProps {
         placeholder?: string;
     };
     visualContext?: VisualContextConfig;
+    /**
+     * Static context configuration — periodic structured page-metadata blob
+     * (URL, title, description, DOM signals) sent alongside Visual Context.
+     * On by default whenever a conversation is active; pass
+     * `staticContext: { enabled: false }` to disable.
+     */
+    staticContext?: StaticContextConfig;
     /** Custom tools: Record<functionName, { description, parameters, execute }> - always custom handler */
     tools?: Record<string, {
         description: string;
         parameters: object;
         execute: (args: Record<string, unknown>) => Promise<unknown>;
     }>;
+    /** Called when initialize fails after all retries. Host can show toast. */
+    onInitializeError?: (error: {
+        message: string;
+    }) => void;
+    /**
+     * When false (default), the widget does not render on mobile/tablet browsers.
+     * Set to true to allow the widget on those devices.
+     */
+    mobileEnabled?: boolean;
 }
 export type TranscriptPosition = 'right' | 'left';
+/**
+ * Transcript chrome: **FloatPanel** (`float`) = card near the mic; **DockedPanel** (`docked`) = full-height
+ * side panel. Distinct from the workflow checklist drawer.
+ */
+export type TranscriptPanelMode = 'float' | 'docked';
+/** Session focus: stub slugs `onboarding` | `training` | `doIt`, or a server workspace slug. */
+export type TranscriptSessionMode = string;
 export type PopupPosition = 'above' | 'below' | 'above-left' | 'above-right' | 'above-center' | 'below-left' | 'below-right' | 'below-center';

package/dist/types/audioConfig.types.d.ts

@@ -0,0 +1,78 @@
+export interface ServerVadConfig {
+    type: 'server_vad';
+    create_response?: boolean;
+    interrupt_response?: boolean;
+    threshold?: number;
+    silence_duration_ms?: number | undefined;
+    prefix_padding_ms?: number | undefined;
+    idle_timeout_ms?: number | null;
+}
+export interface SemanticVadConfig {
+    type: 'semantic_vad';
+    create_response?: boolean;
+    interrupt_response?: boolean;
+    eagerness?: 'low' | 'medium' | 'high' | 'auto';
+}
+export type TurnDetectionConfig = ServerVadConfig | SemanticVadConfig;
+export type NoiseReductionType = 'near_field' | 'far_field';
+export interface NoiseReductionConfig {
+    type: NoiseReductionType;
+}
+export interface AudioConfigInput {
+    noise_reduction?: NoiseReductionConfig | null;
+    turn_detection?: TurnDetectionConfig | null;
+}
+export interface AudioConfigOutput {
+    speed?: number;
+    voice?: string;
+}
+export interface AudioConfig {
+    input?: AudioConfigInput;
+    output?: AudioConfigOutput;
+}
+/**
+ * Tracks which fields the user has customized (unchecked "Default").
+ * If a key is absent or true, that field uses the hardcoded default.
+ */
+export interface AudioConfigDefaults {
+    noise_reduction?: boolean;
+    vad_type?: boolean;
+    create_response?: boolean;
+    interrupt_response?: boolean;
+    threshold?: boolean;
+    silence_duration_ms?: boolean;
+    prefix_padding_ms?: boolean;
+    idle_timeout_ms?: boolean;
+    eagerness?: boolean;
+    speed?: boolean;
+    voice?: boolean;
+}
+export interface StoredAudioConfig {
+    config: AudioConfig;
+    useDefaults: AudioConfigDefaults;
+}
+export type MicPresetId = 'precise' | 'noisy';
+export declare const MIC_PRESETS: readonly MicPresetId[];
+export declare const VOICES: readonly ["alloy", "ash", "ballad", "coral", "echo", "sage", "shimmer", "verse", "marin", "cedar"];
+export type VoiceName = (typeof VOICES)[number];
+export declare const DEFAULT_AUDIO_CONFIG: AudioConfig;
+export declare const DEFAULT_SERVER_VAD: ServerVadConfig;
+/** User preset: Noisy environment defaults (server VAD, lower threshold). */
+export declare const PRESET_NOISY_SERVER_VAD: ServerVadConfig;
+/** System-only preset: used during protected playback when Noisy preset is active. */
+export declare const SYSTEM_INTERRUPT_LOCK_VAD: ServerVadConfig;
+export declare function getPresetBaseAudioConfig(preset: MicPresetId): AudioConfig;
+export declare const DEFAULT_SEMANTIC_VAD: SemanticVadConfig;
+export declare const ALL_DEFAULTS_TRUE: AudioConfigDefaults;
+export declare const FIELD_INFO: Record<string, string>;
+export declare function mergeWithDefaults(stored: StoredAudioConfig | null, preset?: MicPresetId): AudioConfig;
+/**
+ * Builds the audio payload for session.update from an AudioConfig.
+ * All types match the API shape directly -- no conversion needed.
+ */
+export declare function buildAudioSessionPayload(config: AudioConfig): Record<string, any>;
+export interface ValidationError {
+    field: string;
+    message: string;
+}
+export declare function validateAudioConfig(config: AudioConfig): ValidationError[];

package/dist/utils/api.d.ts

@@ -1,16 +1,17 @@
 import { GuideAIEnvironment } from '../types/GuideAI.types';
+import type { StubWorkflowItem } from '../stubs/workspaces';
 import { MessageData } from './conversationManager';
-export declare function getApiHeaders(): Record<string, string>;
-export interface Workflow {
-    id: string;
-    name: string;
-    triggers: string[];
-    organizationKey: string;
-    prompt: string;
-    archived?: boolean;
-    createdAt?: string;
-    updatedAt?: string;
+/** Thrown when `POST /initialize` rejects the widget Bearer JWT (typically HTTP 401). */
+export declare class InitializeUnauthorizedError extends Error {
+    readonly status: number;
+    constructor(status: number, message: string);
 }
+export interface ApiHeadersOptions {
+    authorizationBearer?: string;
+    /** Server treats request as Chrome extension (domain allowlist bypass for session). */
+    extensionContext?: boolean;
+}
+export declare function getApiHeaders(options?: ApiHeadersOptions): Record<string, string>;
 export interface PropToolDefinition {
     name: string;
     description: string;
@@ -18,11 +19,12 @@ export interface PropToolDefinition {
 }
 export interface InitializeWebRTCPayload {
     sdp: string;
-    organizationKey: string;
+    /** Workspace slug: forwarded on the body so the server can pick a non-default workspace per request. */
+    workspace?: string;
     user?: string;
     conversationId?: string;
-    /** Prop tools to sync to library (server creates if not exist, unpublished) */
-    propTools?: PropToolDefinition[];
+    /** Access-key: linked published workflow id for session instructions (omit = first linked). */
+    sessionWorkflowId?: string;
 }
 export interface ToolFromServer {
     toolConfig: object;
@@ -32,6 +34,50 @@ export interface InitializeWebRTCResponse {
     answerSdp: string;
     id: string;
     tools?: ToolFromServer[];
+    contextKey?: string;
+    transcriptionModel?: string;
+    greeting?: string | null;
+}
+export interface InitializeWebRTCOptions {
+    /** Required widget Bearer JWT; the server is JWT-only on `/initialize`. */
+    authorizationBearer?: string;
+    extensionContext?: boolean;
+}
+export declare const initializeWebRTC: (endpoint: string, payload: InitializeWebRTCPayload, options?: InitializeWebRTCOptions) => Promise<InitializeWebRTCResponse>;
+/** Fire-and-forget: register missing prop tools (customer-scoped). Does not await. */
+export declare const registerTools: (endpoint: string, payload: {
+    propTools?: PropToolDefinition[];
+}, options?: InitializeWebRTCOptions) => void;
+/** Built-in tool definition for server registration */
+export interface BuiltInToolDefinition {
+    toolConfig: object;
+    functionConfig: object;
+}
+export declare const logMessage: (messageData: MessageData, conversationId: string | null, _conversationKey: string, user?: string, environment?: GuideAIEnvironment) => Promise<void>;
+/** One workspace row from `POST /widget/workspaces` (normalized). */
+export interface WidgetWorkspaceRow {
+    id: string;
+    label: string;
+    description: string;
+    icon: string;
+    /** When true, realtime session uses full workspace prompt + rolled-up linked workflow prompts (not a single workflow). */
+    rollupWorkflows: boolean;
+    workflowChecklistEnabled: boolean;
+    workflowConfettiEnabled: boolean;
+    workflows: StubWorkflowItem[];
+}
+export interface WidgetWorkspacesResponse {
+    workspaces: WidgetWorkspaceRow[];
+}
+export interface FetchWidgetWorkspacesParams {
+    apiBase: string;
+    /** Omit to request all workspaces for the customer; empty array requests none. */
+    workspacesFilter?: string[];
+    authorizationBearer?: string;
+    extensionContext?: boolean;
 }
-export declare const initializeWebRTC: (endpoint: string, payload: InitializeWebRTCPayload) => Promise<InitializeWebRTCResponse>;
-export declare const logMessage: (messageData: MessageData, conversationId: string | null, organizationKey: string, user?: string, environment?: GuideAIEnvironment) => Promise<void>;
+/**
+ * POST `/widget/workspaces` — widget workspace list + embedded workflow steps.
+ * Keep HTTP here; map to transcript types in `widgetWorkspaces.ts` / `workspaceCatalog.ts`.
+ */
+export declare function fetchWidgetWorkspaces(params: FetchWidgetWorkspacesParams): Promise<WidgetWorkspacesResponse | null>;

package/dist/utils/confettiBurst.d.ts

@@ -0,0 +1,6 @@
+/** One-shot confetti burst; DOM-only, no extra deps. Safe to call from event handlers. */
+/**
+ * @param clientX - burst origin X (defaults to viewport center)
+ * @param clientY - burst origin Y (defaults to upper third)
+ */
+export declare function burstConfetti(clientX?: number, clientY?: number, particleCount?: number): void;

package/dist/utils/constants.d.ts

@@ -5,7 +5,8 @@ export declare const GUIDE_AI_API_BASE_LOCAL = "http://localhost:3000/api";
 export declare const getApiBaseUrl: (environment?: "development" | "production" | "local") => string;
 export declare const GUIDE_AI_API_BASE = "https://app.getguide.ai/api";
 export declare const OPENAI_REALTIME_BASE = "https://api.openai.com/v1/realtime/calls";
-export type ElementInteractionType = 'HIGHLIGHT' | 'HOVERANDCLICK';
+/** Must match guideaisite `WIDGET_EXTENSION_HEADER` — server bypasses session hostname allowlist for extension builds. */
+export declare const WIDGET_EXTENSION_HEADER = "x-guideai-extension";
 export declare const UI_LAYOUT: {
     /** Mic/icon wrapper size - matches .guideai-icon-wrapper */
     readonly micButtonSize: 50;
@@ -19,4 +20,9 @@ export declare const UI_LAYOUT: {
     readonly defaultBottom: 20;
     /** Default horizontal offset when position is not provided */
     readonly defaultHorizontalOffset: 40;
+    /**
+     * Floating transcript card (`guideai-transcript-box`) inset from the viewport right and bottom.
+     * Kept separate from mic `position` so the card can sit closer to the corner (e.g. 20px vs 40px).
+     */
+    readonly transcriptFloatEdgeInset: 20;
 };