@papermap/papermap 1.0.4 → 1.1.0

package/dist/index.d.mts

@@ -1,12 +1,15 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
+import { Layout } from 'react-grid-layout';
+import { LucideIcon } from 'lucide-react';
 import * as React$1 from 'react';
 import React__default, { RefObject } from 'react';
 import * as class_variance_authority_types from 'class-variance-authority/types';
 import { VariantProps } from 'class-variance-authority';
 import * as zustand from 'zustand';
+import { QueryClient } from '@tanstack/react-query';
 import * as axios from 'axios';
 import { AxiosInstance } from 'axios';
-import { Layout } from 'react-grid-layout';
+import { DriveStep } from 'driver.js';
 
 interface PaperChatProps {
     token?: string;
@@ -29,9 +32,15 @@ interface PaperChatProps {
      * Defaults to `true`.
      */
     showToolbar?: boolean;
+    /**
+     * Called after the floating assistant panel is closed (e.g. to refetch dashboard charts).
+     */
+    onAssistantClose?: () => void;
 }
-declare function PaperChat({ token, workspaceId, dashboardId, apiUrl, onToolbarHeightChange, showToolbar, ...uiProps }: PaperChatProps): react_jsx_runtime.JSX.Element;
+declare function PaperChat({ token, workspaceId, dashboardId, apiUrl, onToolbarHeightChange, onAssistantClose, showToolbar, ...uiProps }: PaperChatProps): react_jsx_runtime.JSX.Element;
 
+/** One row of tabular chart data (column keys depend on the query). */
+type ChartDataRow = Record<string, unknown>;
 type TChartMeta$1 = {
     title?: string;
     subtitle?: string;
@@ -39,7 +48,14 @@ type TChartMeta$1 = {
     footer?: string;
     showLegend?: boolean;
     variant?: string;
-    [key: string]: any;
+    [key: string]: unknown;
+};
+type ChartVisualizationConfig = {
+    colors: string[];
+    width: number;
+    height: number;
+    title?: string;
+    [key: string]: unknown;
 };
 type TChartResponse = {
     llm_data_chat_id: string;
@@ -48,7 +64,7 @@ type TChartResponse = {
     chart_response?: {
         chart_type: string;
         error?: boolean;
-        data: any[];
+        data: ChartDataRow[];
         response_type: string;
         text_response?: string;
         schema_hints: {
@@ -56,13 +72,7 @@ type TChartResponse = {
             y_key: string;
             label_key: string;
         };
-        visualization_config: {
-            colors: string[];
-            width: number;
-            height: number;
-            title?: string;
-            [key: string]: any;
-        };
+        visualization_config: ChartVisualizationConfig;
     };
     meta: TChartMeta$1;
     pin: boolean;
@@ -83,8 +93,8 @@ interface VisualizationConfig {
     colors: string[];
     width: number;
     height: number;
-    title: string;
-    [key: string]: any;
+    title?: string;
+    [key: string]: unknown;
 }
 interface ChartResponse {
     response_type: string;
@@ -101,6 +111,34 @@ type ConversationHistory = Omit<TChartResponse, 'chart_response'> & {
     latest_user_name?: string | null;
 };
 
+type ResizeHandle = 'n' | 's' | 'e' | 'w' | 'ne' | 'nw' | 'se' | 'sw';
+type TLayout = Layout & {
+    resizeHandles?: ResizeHandle[];
+};
+type PaperBoardLayouts = {
+    [key: string]: TLayout[];
+};
+interface DashboardTheme {
+    primary: string;
+    secondary: string;
+    interactive: string;
+    container: string;
+    module: string;
+    accent: string;
+    outline: string;
+    dialog: string;
+    fontFamily: string;
+    borderRadius: number;
+    cardBg?: string;
+    dashboardBg?: string;
+    cardIcons?: string;
+    cardText?: string;
+    cardTitle?: string;
+    buttonPrimary?: string;
+    buttonSecondary?: string;
+    buttonText?: string;
+}
+
 interface PaperCardProps {
     /**
      * Connection details for API calls. Optional when the card is rendered inside
@@ -122,6 +160,16 @@ interface PaperCardProps {
      * and logged only.
      */
     onSave?: (chart: TChartResponse) => void;
+    /**
+     * Called after the user successfully pins/saves a chart to the dashboard (streaming dialog
+     * or built-in ChartView save). Use this to refetch dashboard data from the host.
+     */
+    onPinnedToDashboard?: (chart: TChartResponse) => void;
+    /**
+     * Called after the streaming chart assistant dialog closes. Use with `onPinnedToDashboard`
+     * to refetch dashboard data so tiles reflect edits made in the assistant.
+     */
+    onAssistantClosed?: () => void;
     /**
      * The chat ID to load a chart for. When provided, the component will
      * fetch the latest chart for this chat on mount (overrides `id` → localStorage map).
@@ -167,7 +215,7 @@ interface PaperCardProps {
     /** When true, chart toolbar actions are visually disabled during layout editing. */
     isEditMode?: boolean;
     /** When true, show resize affordance and disable toolbar actions. */
-    /** Optional stable identifier for standalone resize handle instrumentation. */
+    /** Optional stable identifier for standalone resize handle / host linking (when used). */
     className?: string;
     /**
      * Card variant. When `"streaming"`, clicking the edit icon opens an
@@ -175,8 +223,16 @@ interface PaperCardProps {
      * just calling onEditClick or opening the toolbar chat.
      */
     variant?: 'default' | 'streaming';
+    /**
+     * When true with `variant="streaming"` and no chart yet, omits the extra
+     * chat-bar hint row (“Ask anything about your data”). Used by `PaperBoard`
+     * so grid tiles are not redundant with board-level empty copy.
+     */
+    hideStreamingEmptySubtext?: boolean;
+    /** Passed into maximize `ChartDialog` / streaming dialog for themed dashboards (e.g. from `PaperBoard`). */
+    dashboardTheme?: DashboardTheme;
 }
-declare function PaperCard({ token: tokenProp, workspaceId: workspaceIdProp, dashboardId: dashboardIdProp, apiUrl: apiUrlProp, id, onSave, chartId, chart: chartProp, theme, onEditClick, onDelete, isViewer, wide, hideVariants, showToolbar, isEditMode, className, variant, }: PaperCardProps): react_jsx_runtime.JSX.Element;
+declare function PaperCard({ token: tokenProp, workspaceId: workspaceIdProp, dashboardId: dashboardIdProp, apiUrl: apiUrlProp, id, onSave, onPinnedToDashboard, onAssistantClosed, chartId, chart: chartProp, theme, onEditClick, onDelete, isViewer, wide, hideVariants, showToolbar, isEditMode, className, variant, hideStreamingEmptySubtext, dashboardTheme, }: PaperCardProps): react_jsx_runtime.JSX.Element;
 
 declare function ChatAssistant(): react_jsx_runtime.JSX.Element;
 
@@ -193,10 +249,10 @@ interface FinalResponse {
         response_type: string;
         generated_text: string;
         chart_type?: string;
-        data?: any[];
+        data?: unknown[];
         pandas_code?: string;
         thoughts?: string;
-        [key: string]: any;
+        [key: string]: unknown;
     };
     llm_data_id: string;
     total_iterations: number;
@@ -236,7 +292,7 @@ interface StreamState {
     timeline: TimelineEvent[];
     currentPhase: string;
     error: string | null;
-    finalResponse: any | null;
+    finalResponse: unknown | null;
     isComplete: boolean;
     isConnected: boolean;
     isStreaming: boolean;
@@ -270,6 +326,43 @@ declare function ChartHistory(): react_jsx_runtime.JSX.Element;
 
 declare function SavedMemory(): react_jsx_runtime.JSX.Element;
 
+interface PaperDashboardSelectProps {
+    workspaceId: string;
+    dashboardId: string;
+    onChange: (dashboardId: string) => void;
+    dashboardTheme?: DashboardTheme;
+    disabled?: boolean;
+    className?: string;
+    /**
+     * When true, sets `dashboardId` on the current URL search params via `replaceState`
+     * (same idea as the main app embedded dashboard).
+     */
+    syncDashboardIdToUrl?: boolean;
+}
+/**
+ * Dashboard picker for the current workspace only (matches main app `DashboardSelect` / embedded UX).
+ */
+declare function PaperDashboardSelect({ workspaceId, dashboardId, onChange, dashboardTheme, disabled, className, syncDashboardIdToUrl, }: PaperDashboardSelectProps): react_jsx_runtime.JSX.Element;
+
+type DashboardNavbarItem = {
+    title: string;
+    /** Absolute or relative URL; pathname (before `?`) is used for the active state. */
+    href: string;
+    disabled?: boolean;
+    icon?: LucideIcon;
+};
+interface DashboardTabNavigationProps {
+    className?: string;
+    items: DashboardNavbarItem[];
+    dashboardTheme?: DashboardTheme;
+    /** Renders on the right (e.g. `PaperDashboardSelect`). */
+    rightSlot?: React.ReactNode;
+}
+/**
+ * Top tab bar styled like the main app `TabNavigation` (embedded layout navbar), without Next.js `Link`.
+ */
+declare function DashboardTabNavigation({ className, items, dashboardTheme, rightSlot, }: DashboardTabNavigationProps): react_jsx_runtime.JSX.Element;
+
 interface TChartMeta {
     title?: string;
     subtitle?: string;
@@ -278,14 +371,14 @@ interface TChartMeta {
     showLegend?: boolean;
 }
 interface ChartViewProps {
-    data: any[];
+    data: ChartDataRow[];
     chartMeta: TChartMeta;
     error?: boolean;
     chartType: string;
     variant?: string;
     className?: string;
     containerClassName?: string;
-    visualizationConfig?: Record<string, any>;
+    visualizationConfig?: Record<string, unknown>;
     previewMode?: boolean;
     onMetaChange?: (key: 'title' | 'description' | 'footer' | 'subtitle', value: string) => void;
     chartId?: string;
@@ -308,6 +401,15 @@ interface ChartViewProps {
      * of the default bottom-left outline button. Used in streaming layouts.
      */
     compactSave?: boolean;
+    /**
+     * Called after a successful pin/save to the dashboard via the built-in save action.
+     * Not invoked when `onSaveToDashboard` overrides the handler.
+     */
+    onAfterPinToDashboard?: () => void;
+    /** When set (and not skipped), header and controls use dashboard theme tokens. */
+    dashboardTheme?: DashboardTheme;
+    /** When true, ignore `dashboardTheme` (e.g. dialog with `skipDashboardTheme`). */
+    skipDashboardTheme?: boolean;
 }
 declare function ChartView(props: ChartViewProps): react_jsx_runtime.JSX.Element;
 
@@ -326,7 +428,25 @@ interface ChartDialogProps {
     visualizationConfig: Record<string, any>;
     onMetaChange: (key: 'title' | 'description' | 'footer' | 'subtitle', value: string) => void;
     variant?: string;
+    /**
+     * Optional hook for the **minimize** control only: invoked immediately before `onOpenChange(false)`.
+     * Backdrop click and Escape call **only** `onOpenChange(false)` (Radix default).
+     */
     onClose?: () => void;
+    /**
+     * When true, hides the chart variation selector in the dialog (embedded edge cases).
+     * Default false — matches main-app maximize dialog (variant switching allowed).
+     */
+    hideVariantControls?: boolean;
+    /**
+     * Workspace dashboard theme: injects scoped CSS and `dashboard-theme` on the dialog surface (main-app parity).
+     * Omit when no custom theme; combine with `skipDashboardTheme` for chat-embedded dialogs.
+     */
+    dashboardTheme?: DashboardTheme;
+    /**
+     * When true, do not apply `dashboardTheme` to the dialog shell or inner `ChartView` (e.g. `ChatAssistant`).
+     */
+    skipDashboardTheme?: boolean;
 }
 declare function ChartDialog(props: ChartDialogProps): react_jsx_runtime.JSX.Element;
 
@@ -337,8 +457,10 @@ interface StreamingChartDialogProps {
     onClose?: () => void;
     /** After a successful Save-to-dashboard (pin) from this dialog; errors from the host are caught and logged. */
     onSave?: (chart: TChartResponse) => void;
+    /** Optional workspace theme for inline chart and maximize `ChartDialog` (from `PaperCard` / `PaperBoard`). */
+    dashboardTheme?: DashboardTheme;
 }
-declare function StreamingChartDialog({ isOpen, onOpenChange, chartId, onClose, onSave, }: StreamingChartDialogProps): React$1.ReactPortal;
+declare function StreamingChartDialog({ isOpen, onOpenChange, chartId, onClose, onSave, dashboardTheme, }: StreamingChartDialogProps): React$1.ReactPortal;
 
 interface DataTableProps {
     data: any[];
@@ -395,12 +517,17 @@ interface StreamingChatPanelProps {
      * dialog when the chart column is hidden so chat isn’t artificially narrow.
      */
     expandMessageColumnOnMobile?: boolean;
+    /**
+     * Horizontal padding for the scrollable message list (main `ChatAssistant` uses wide gutters
+     * when expanded without the chart split: `px-32 md:px-48 lg:px-[320px] xl:px-[448px]`).
+     */
+    messagesPaddingClassName?: string;
     /** Auto-focuses the prompt input when this panel mounts (used by dialog hosts). */
     autoFocusInput?: boolean;
     /** Optional action rendered beside submit button in the input row. */
     inputAction?: React__default.ReactNode;
 }
-declare function StreamingChatPanel({ className, expandMessageColumnOnMobile, autoFocusInput, inputAction, }: StreamingChatPanelProps): react_jsx_runtime.JSX.Element;
+declare function StreamingChatPanel({ className, expandMessageColumnOnMobile, messagesPaddingClassName, autoFocusInput, inputAction, }: StreamingChatPanelProps): react_jsx_runtime.JSX.Element;
 
 interface LogoStandAloneProps {
     className?: string;
@@ -430,38 +557,11 @@ declare function createStreamingService(client: AxiosInstance): {
     cancelChartRequest: (request_id: string, reason?: string) => Promise<any>;
 };
 
-type ResizeHandle = 'n' | 's' | 'e' | 'w' | 'ne' | 'nw' | 'se' | 'sw';
-type TLayout = Layout & {
-    resizeHandles?: ResizeHandle[];
-};
-type PaperBoardLayouts = {
-    [key: string]: TLayout[];
-};
-interface DashboardTheme {
-    primary: string;
-    secondary: string;
-    interactive: string;
-    container: string;
-    module: string;
-    accent: string;
-    outline: string;
-    dialog: string;
-    fontFamily: string;
-    borderRadius: number;
-    cardBg?: string;
-    dashboardBg?: string;
-    cardIcons?: string;
-    cardText?: string;
-    cardTitle?: string;
-    buttonPrimary?: string;
-    buttonSecondary?: string;
-    buttonText?: string;
-}
-
 declare function createChartService(client: AxiosInstance): {
     getDashboards: (params: {
         workspace_id: string;
     }) => Promise<any>;
+    getDashboardById: (dashboardId: string) => Promise<any>;
     updateDashboardLayout: (dashboardId: string, layout: TLayout[]) => Promise<any>;
     createChat: (data: {
         name: string;
@@ -491,7 +591,7 @@ declare function createChartService(client: AxiosInstance): {
         page?: number;
     }) => Promise<any>;
     getChartById: (chartId: string) => Promise<any>;
-    updateChartMeta: (chatId: string, meta: Record<string, any>) => Promise<any>;
+    updateChartMeta: (chatId: string, meta: TChartMeta$1) => Promise<any>;
     updateChartPin: (chatId: string, pin: boolean) => Promise<any>;
     bookmarkConversation: (data: {
         llm_data_id: string;
@@ -508,9 +608,44 @@ declare function createChartService(client: AxiosInstance): {
     }) => Promise<any>;
 };
 
+/** Plain JSON object (not array, not null). */
+type JsonObject = Record<string, unknown>;
+/** Workspace `meta` fields used for dashboard theming (matches main app). */
+interface WorkspaceMeta {
+    apply_theme_to_all_dashboards?: boolean;
+    default_theme?: DashboardTheme;
+    theme?: Record<string, DashboardTheme | undefined>;
+    [key: string]: unknown;
+}
+/**
+ * Minimal workspace/dashboard document shape returned by workspace and dashboard APIs.
+ * Extra fields are preserved via the index signature.
+ */
+interface WorkspaceEntity {
+    id?: string;
+    name?: string;
+    workspace_type?: string;
+    default_dashboard?: string;
+    meta?: WorkspaceMeta;
+    /** Present on some dashboard GET payloads */
+    title?: string;
+    [key: string]: unknown;
+}
+/**
+ * Normalizes workspace or dashboard API responses that may be either the entity or `{ data: entity }`.
+ * Returns `null` when the payload is not a non-null object (e.g. raw array or primitive).
+ */
+declare function unwrapWorkspacePayload(res: unknown): WorkspaceEntity | null;
+
 declare function createWorkspaceService(client: AxiosInstance): {
+    listWorkspaces: (params?: {
+        page?: number;
+        per_page?: number;
+        search_term?: string;
+    }) => Promise<any>;
     getWorkspace: (workspaceId: string) => Promise<any>;
-    updateWorkspace: (workspaceId: string, workspace: Record<string, any>) => Promise<any>;
+    updateWorkspace: (workspaceId: string, workspace: JsonObject) => Promise<any>;
+    verifyDatabaseConnection: (workspaceId: string) => Promise<any>;
 };
 
 type PapermapHttpServices = {
@@ -525,6 +660,10 @@ declare function createPapermapServices(config: {
     apiUrl?: string;
 }): PapermapHttpServices;
 
+type MessageProgressEvent = {
+    event_type?: string;
+    data?: JsonObject;
+};
 interface Message {
     id?: string;
     llm_data_id?: string;
@@ -541,14 +680,41 @@ interface Message {
     rundown_turn_label?: string;
     noIcons?: boolean;
     feedback?: 'positive' | 'negative' | null;
-    progress_events?: {
-        event_type?: string;
-        data?: Record<string, any>;
-    }[];
+    progress_events?: MessageProgressEvent[];
     originalContent?: string;
-    [key: string]: any;
+    [key: string]: unknown;
 }
 
+type PapermapTelemetryLevel = 'debug' | 'info' | 'warn' | 'error';
+interface PapermapTelemetryEvent {
+    level: PapermapTelemetryLevel;
+    category: 'store' | 'sse' | 'network' | 'plugin' | 'ui' | 'runtime' | string;
+    message: string;
+    data?: Record<string, unknown>;
+    /** Original error or value; hosts should treat as opaque if serialized. */
+    cause?: unknown;
+}
+interface PapermapObservability {
+    emit: (event: PapermapTelemetryEvent) => void;
+    reportError: (error: unknown, context?: Record<string, unknown>) => void;
+}
+interface PapermapObservabilityOptions {
+    /** Receives every structured event (debug–error). */
+    onTelemetry?: (event: PapermapTelemetryEvent) => void;
+    /** Shortcut for failures; also receives a normalized telemetry event via `onTelemetry` when both are set. */
+    onError?: (error: unknown, context?: Record<string, unknown>) => void;
+    /**
+     * When true (default), mirror `warn`/`error` telemetry to the console in non-production runtimes.
+     * Set false in tests or strict hosts. Production never mirrors unless you log inside `onTelemetry`.
+     */
+    mirrorToConsoleInDev?: boolean;
+}
+/**
+ * Builds the observability facade used by `PapermapProvider` / `createPapermapStore`.
+ * With no options, production is silent; dev (non-test) mirrors warn/error to `console`.
+ */
+declare function createPapermapObservability(options?: PapermapObservabilityOptions): PapermapObservability;
+
 declare const CHAT_MODAL_TAB: {
     readonly CHAT: "CHAT";
     readonly SAVED_MEMORY: "SAVED_MEMORY";
@@ -561,6 +727,11 @@ interface PapermapStoreConfig {
     workspaceId: string;
     dashboardId: string;
     apiUrl?: string;
+    /**
+     * React Query client used when the store invalidates queries (e.g. after creating a chat).
+     * `PapermapProvider` supplies a per-identity instance so cache cannot leak across tenant/workspace switches.
+     */
+    queryClient?: QueryClient;
     /**
      * Optional: use your own state (e.g. Redux) to control the selected model.
      * When provided, this value is used as the initial model instead of sessionStorage.
@@ -571,6 +742,11 @@ interface PapermapStoreConfig {
      * Ideal place to dispatch a Redux action in the host app.
      */
     onModelChange?: (model: string | null) => void;
+    /**
+     * Structured telemetry for hosts. Defaults to a quiet implementation (no production console noise).
+     * `PapermapProvider` supplies a shared instance when `observability` options are passed.
+     */
+    observability?: PapermapObservability;
 }
 type Services = PapermapHttpServices;
 interface Refs {
@@ -608,10 +784,10 @@ interface PapermapState {
     browserUse: boolean;
     selectedModel: string | null;
     viewExecution: boolean;
-    chartData: any[];
+    chartData: ChartDataRow[];
     allMeta: TChartMeta$1;
     selectedChartType: string;
-    chartVisuals: Record<string, any>;
+    chartVisuals: Record<string, unknown>;
     totalPages: number;
     currentPage: number;
     isLoadingMore: boolean;
@@ -643,11 +819,11 @@ interface PapermapActions {
     updateBrowserUse: (v: boolean) => void;
     setSelectedModel: (v: string | null) => void;
     setViewExecution: (v: boolean) => void;
-    updateChartData: (data: any[]) => void;
+    updateChartData: (data: ChartDataRow[]) => void;
     updateAllMeta: (meta: TChartMeta$1) => void;
     updateChartType: (v: string) => void;
-    updateChartVisuals: (v: Record<string, any>) => void;
-    updateLatestChart: (result: any) => void;
+    updateChartVisuals: (v: Record<string, unknown>) => void;
+    updateLatestChart: (result: unknown) => void;
     clearLatestChart: () => void;
     setUseSSEStreaming: (v: boolean) => void;
     setSseRequestId: (v: string | null) => void;
@@ -707,6 +883,55 @@ interface OpenPapermapChatAssistantOptions {
  */
 declare function openPapermapChatAssistant(storeApi: PapermapStoreApi, options?: OpenPapermapChatAssistantOptions): void;
 
+/** Mirrors `package.json` version; run `npm run sync:sdk-version` or `npm run build` to refresh. */
+declare const PAPERMAP_SDK_VERSION: "1.1.0";
+/** Contract revision for hosts that gate advanced features; bump only for breaking contract changes. */
+declare const PAPERMAP_PLUGIN_CONTRACT_VERSION: 1;
+type PapermapCapability = 'chat' | 'charts' | 'dashboard' | 'streaming' | 'workspace' | (string & {});
+interface PapermapPluginManifest {
+    id: string;
+    name?: string;
+    /** Plugin’s own semver. */
+    version: string;
+    /**
+     * Required SDK range for this package, e.g. `^1.0.0`.
+     * Only caret (`^x.y.z`) and exact `x.y.z` forms are interpreted; unknown shapes are ignored (lenient).
+     */
+    peerRange?: string;
+    capabilities?: PapermapCapability[];
+}
+interface PapermapPluginContext {
+    manifest: PapermapPluginManifest;
+    workspaceId: string;
+    dashboardId: string;
+    apiUrl?: string;
+    observability: PapermapObservability;
+}
+interface PapermapPluginLifecycle {
+    onActivate?: (ctx: PapermapPluginContext) => void | Promise<void>;
+    onDeactivate?: (ctx: PapermapPluginContext) => void | Promise<void>;
+    onDispose?: (ctx: PapermapPluginContext) => void | Promise<void>;
+}
+interface PapermapPluginRegistration {
+    manifest: PapermapPluginManifest;
+    lifecycle?: PapermapPluginLifecycle;
+}
+declare function parseSemverPrefix(version: string): [number, number, number] | null;
+/**
+ * Returns whether the running SDK version satisfies the plugin’s declared range.
+ */
+declare function checkPluginPeerCompatibility(hostSdkVersion: string, pluginPeerRange?: string): {
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+};
+declare function createPluginContext(registration: PapermapPluginRegistration, identity: {
+    workspaceId: string;
+    dashboardId: string;
+    apiUrl?: string;
+}, observability: PapermapObservability): PapermapPluginContext;
+
 type PapermapConnectionValue = {
     token: string;
     workspaceId: string;
@@ -714,10 +939,26 @@ type PapermapConnectionValue = {
     apiUrl?: string;
     services: PapermapHttpServices;
 };
-interface PapermapProviderProps extends PapermapStoreConfig {
+type PapermapProviderProps = Omit<PapermapStoreConfig, 'observability'> & {
     children: React__default.ReactNode;
-}
-declare function PapermapProvider({ children, token, workspaceId, dashboardId, apiUrl, initialModel, onModelChange, }: PapermapProviderProps): react_jsx_runtime.JSX.Element;
+    /** Optional structured telemetry; forwarded to the Zustand store and SSE bridge. */
+    observability?: PapermapObservabilityOptions;
+    /** Optional plugin manifest + lifecycle (v1 contract). Safe to omit for all existing embeds. */
+    plugin?: PapermapPluginRegistration;
+};
+/**
+ * Supplies Zustand chat state, HTTP services, and React Query for one **identity boundary**.
+ *
+ * **Runtime switches:** When any of `token`, `workspaceId`, `dashboardId`, or `apiUrl` change, the
+ * provider creates a **new** Zustand store and **new** `QueryClient`. Chat UI state and TanStack Query
+ * cache from the previous boundary are not carried over, which avoids stale tenant/workspace data.
+ *
+ * **Stable props:** Changing only `initialModel`, `onModelChange`, `observability`, `plugin`, or
+ * `children` does **not** reset the store or query cache (except `observability.mirrorToConsoleInDev`,
+ * which recreates the telemetry facade). `onModelChange` / `onTelemetry` / `onError` may be inline —
+ * the latest callback is always invoked via refs.
+ */
+declare function PapermapProvider({ children, token, workspaceId, dashboardId, apiUrl, initialModel, onModelChange, observability: observabilityProp, plugin, }: PapermapProviderProps): react_jsx_runtime.JSX.Element;
 declare function usePapermapStore<T>(selector: (state: PapermapStore) => T): T;
 /**
  * Access the raw store API (for refs, services, imperative calls).
@@ -733,12 +974,25 @@ declare function usePapermapStoreApiOptional(): PapermapStoreApi | null;
 declare function usePapermapConnection(): PapermapConnectionValue;
 declare function usePapermapConnectionOptional(): PapermapConnectionValue | null;
 
-interface KeyboardShortcutHandlers {
+interface UseKeyboardShortcutsOptions {
+    shortcutKey?: string;
     onToggle?: () => void;
+    /**
+     * Legacy Escape when not using `escapeLayerActive` + `instanceId`.
+     * Prefer `onEscapeLayerClose` for multiple embeds.
+     */
     onEscape?: () => void;
-    shortcutKey?: string;
+    /** Stable id from `useId()` — enables multi-instance shortcut + Escape stacking. */
+    instanceId?: string;
+    /** Root that contains this chat surface (toolbar, overlays, portaled UI). */
+    shortcutRootRef?: RefObject<HTMLElement | null>;
+    /** When true, Escape is handled via a global stack (deepest / last-opened closes first). */
+    escapeLayerActive?: boolean;
+    onEscapeLayerClose?: () => void;
+    /** Bumps when portaled DOM attaches so `shortcutRootRef` can be bound. */
+    shortcutLayoutSyncKey?: string | number;
 }
-declare function useKeyboardShortcuts({ onToggle, onEscape, shortcutKey, }: KeyboardShortcutHandlers): void;
+declare function useKeyboardShortcuts({ onToggle, onEscape, shortcutKey, instanceId, shortcutRootRef, escapeLayerActive, onEscapeLayerClose, shortcutLayoutSyncKey, }: UseKeyboardShortcutsOptions): void;
 
 declare function useAutoResize(textareaRef: RefObject<HTMLTextAreaElement | null>, minHeight?: number, maxHeight?: number): {
     resize: () => void;
@@ -750,7 +1004,7 @@ declare function useAutoFade(enabled: boolean, delay?: number, suppressWhen?: bo
 };
 
 interface UseAnalyticsStreamOptions {
-    onComplete?: (data: any) => void;
+    onComplete?: (data: unknown) => void;
     onError?: (error: string) => void;
     onThought?: (thought: AgentThought) => void;
     onToolCall?: (toolCall: ToolCall) => void;
@@ -767,12 +1021,30 @@ declare function useAnalyticsStream(requestId: string | null, authHeaders: Recor
     timeline: TimelineEvent[];
     currentPhase: string;
     error: string | null;
-    finalResponse: any | null;
+    finalResponse: unknown | null;
     isComplete: boolean;
     isConnected: boolean;
     isStreaming: boolean;
 };
 
+interface TourStep extends DriveStep {
+    element?: string;
+    popover?: {
+        title?: string;
+        description: string;
+        side?: 'left' | 'right' | 'top' | 'bottom';
+        align?: 'start' | 'center' | 'end';
+    };
+}
+interface UseTourOptions {
+    onComplete?: () => void;
+    onSkip?: () => void;
+}
+declare function useTour(options?: UseTourOptions): {
+    startTour: (steps: TourStep[]) => void;
+    stopTour: () => void;
+};
+
 interface DecodedToken {
     api_key_id: string;
     workspace_id: string;
@@ -789,6 +1061,26 @@ declare function createApiClient(token: string, apiUrl?: string): {
     authHeaders: Record<string, string>;
 };
 
+/** Normalized API origin segment so keys differ per host when IDs collide. */
+declare function papermapApiBaseSegment(apiUrl?: string): string;
+/**
+ * Hierarchical TanStack Query keys scoped by API base + workspace + dashboard.
+ * Prevents cache bleed when the same dashboard id appears under different workspaces or APIs.
+ */
+declare const papermapQueryKeys: {
+    readonly root: readonly ["papermap"];
+    readonly scope: (params: {
+        workspaceId: string;
+        dashboardId: string;
+        apiUrl?: string;
+    }) => readonly ["papermap", string, "ws", string, "dash", string];
+    readonly conversationHistory: (workspaceId: string, dashboardId: string, apiUrl?: string) => readonly ["papermap", string, "ws", string, "dash", string, "conversationHistory"];
+    readonly chartCards: (workspaceId: string, dashboardId: string, apiUrl?: string) => readonly ["papermap", string, "ws", string, "dash", string, "chartCards"];
+    readonly dashboardsForWorkspace: (workspaceId: string, apiUrl?: string) => readonly ["papermap", string, "ws", string, "dashboards"];
+    readonly workspacesList: (apiUrl?: string) => readonly ["papermap", string, "workspaces", "list"];
+    readonly models: (apiUrl: string | undefined, token: string) => readonly ["papermap", string, "models", string];
+};
+
 interface PaperBoardProps {
     token?: string;
     workspaceId?: string;
@@ -832,8 +1124,44 @@ interface PaperBoardProps {
     enableFetch?: boolean;
     showChatAssistant?: boolean;
     variant?: 'default' | 'streaming';
+    /**
+     * When true, shows a “Tour” control in the header and enables the dashboard product tour (driver.js).
+     * Default false until the embed tour UX is finalized.
+     */
+    showDashboardTour?: boolean;
+    /**
+     * When true, starts the tour once after load if it has not been completed (localStorage).
+     * Waits until the chat bar is not open or focused. Default false for embeds.
+     */
+    autoStartDashboardTour?: boolean;
+    /** Overrides localStorage key for tour completion (`1` = done). */
+    dashboardTourStorageKey?: string;
+    /** Called when the user finishes or skips the tour (after persisting completion). */
+    onDashboardTourComplete?: () => void;
+    /**
+     * When true (default), show workspace and dashboard dropdowns in the header when `enableFetch` is on
+     * and the board is not in viewer mode. With a parent `PapermapProvider`, you must also pass
+     * `onWorkspaceDashboardChange` so the host can update provider props.
+     */
+    showWorkspaceDashboardSelect?: boolean;
+    /** Update parent state when the user picks another workspace or dashboard (required with a parent provider). */
+    onWorkspaceDashboardChange?: (ctx: {
+        workspaceId: string;
+        dashboardId: string;
+    }) => void;
 }
-declare function PaperBoard({ token, workspaceId, dashboardId, apiUrl, ...rest }: PaperBoardProps): react_jsx_runtime.JSX.Element;
+declare function PaperBoard({ token, workspaceId, dashboardId, apiUrl, showWorkspaceDashboardSelect, onWorkspaceDashboardChange, ...rest }: PaperBoardProps): react_jsx_runtime.JSX.Element;
+
+declare function readDashboardTourCompleted(key: string): boolean;
+declare function markDashboardTourCompleted(key: string): void;
+type BuildDashboardTourStepsOptions = {
+    showToolbar: boolean;
+    showChatAssistant: boolean;
+};
+/**
+ * Driver.js steps aligned with main app GridDashboard tour (workspace selector omitted in embed).
+ */
+declare function buildDashboardTourSteps({ showToolbar, showChatAssistant, }: BuildDashboardTourStepsOptions): TourStep[];
 
 type ThemePreset = 'default' | 'lime' | 'blue' | 'green' | 'purple' | 'ocean' | 'sunset' | 'dark' | 'minimal';
 
@@ -865,10 +1193,7 @@ declare const presetDisplayNames: Record<ThemePreset, string>;
  * 1. `meta.apply_theme_to_all_dashboards` + `meta.default_theme`
  * 2. `meta.theme[dashboardId]` (falls back to `default_dashboard` when `dashboardId` is empty)
  */
-declare function resolveDashboardThemeFromWorkspace(workspace: {
-    meta?: Record<string, any>;
-    default_dashboard?: string;
-} | null | undefined, dashboardId: string): DashboardTheme | undefined;
+declare function resolveDashboardThemeFromWorkspace(workspace: WorkspaceEntity | null | undefined, dashboardId: string): DashboardTheme | undefined;
 
 /**
  * Persistent link between a host-owned stable id (`id` on {@link PaperCard})
@@ -917,4 +1242,4 @@ declare function resolveChartFetchChatId(params: {
     dashboardId?: string;
 }): string | undefined;
 
-export { type AgentThought, AgentThoughtDisplay, BookmarkButton, BranchButton, ButtonWithTooltip, CHART_CARD_CHAT_MAP_KEY, CHAT_MODAL_TAB, type ChartCardIdLink, type ChartCardStorageNamespace, ChartDialog, ChartHistory, type ChartResponse, ChartView, ChatAssistant, type ChatModalTabType, type ConversationHistory, type DashboardTheme, DataTable, type DecodedToken, FeedbackButtons, type FinalResponse, LogoStandAlone, type Message, ModelSelector, MorphGradient, type OpenPapermapChatAssistantOptions, PaperBoard, type TLayout as PaperBoardLayoutItem, type PaperBoardLayouts, PaperCard, type PaperCardProps, PaperChat, type PaperChatProps, type PapermapActions, PapermapProvider as PapermapConfigProvider, type PapermapConnectionValue, type PapermapHttpServices, PapermapProvider, type PapermapState, type PapermapStore, type PapermapStoreApi, type PapermapStoreConfig, RecentConversations, SavedMemory, type StreamState, StreamingChartDialog, StreamingChatPanel, StreamingTimeline, type TChartMeta$1 as TChartMeta, type TChartResponse, ThemeCustomizationSettings, type ThemeCustomizationSettingsProps, type ThemePreset, type ThemeSaveMeta, type TimelineEvent, type ToolCall, ToolCallDisplay, buildAuthHeaders, createApiClient, createPapermapServices, createPapermapStore, decodeToken, defaultTheme, getChartCardIdLink, openPapermapChatAssistant, presetDisplayNames, removeChartCardIdLink, resolveChartFetchChatId, resolveDashboardThemeFromWorkspace, themePresetList, themePresets, upsertChartCardIdLink, useAnalyticsStream, useAutoFade, useAutoResize, useKeyboardShortcuts, usePapermapConnection, usePapermapConnectionOptional, usePapermapStore, usePapermapStoreApi, usePapermapStoreApiOptional };
+export { type AgentThought, AgentThoughtDisplay, BookmarkButton, BranchButton, ButtonWithTooltip, CHART_CARD_CHAT_MAP_KEY, CHAT_MODAL_TAB, type ChartCardIdLink, type ChartCardStorageNamespace, type ChartDataRow, ChartDialog, ChartHistory, type ChartResponse, ChartView, type ChartVisualizationConfig, ChatAssistant, type ChatModalTabType, type ConversationHistory, type DashboardNavbarItem, DashboardTabNavigation, type DashboardTabNavigationProps, type DashboardTheme, DataTable, type DecodedToken, FeedbackButtons, type FinalResponse, type JsonObject, LogoStandAlone, type Message, type MessageProgressEvent, ModelSelector, MorphGradient, type OpenPapermapChatAssistantOptions, PAPERMAP_PLUGIN_CONTRACT_VERSION, PAPERMAP_SDK_VERSION, PaperBoard, type TLayout as PaperBoardLayoutItem, type PaperBoardLayouts, PaperCard, type PaperCardProps, PaperChat, type PaperChatProps, PaperDashboardSelect, type PaperDashboardSelectProps, type PapermapActions, type PapermapCapability, PapermapProvider as PapermapConfigProvider, type PapermapConnectionValue, type PapermapHttpServices, type PapermapObservability, type PapermapObservabilityOptions, type PapermapPluginContext, type PapermapPluginLifecycle, type PapermapPluginManifest, type PapermapPluginRegistration, PapermapProvider, type PapermapState, type PapermapStore, type PapermapStoreApi, type PapermapStoreConfig, type PapermapTelemetryEvent, type PapermapTelemetryLevel, RecentConversations, SavedMemory, type StreamState, StreamingChartDialog, StreamingChatPanel, StreamingTimeline, type TChartMeta$1 as TChartMeta, type TChartResponse, ThemeCustomizationSettings, type ThemeCustomizationSettingsProps, type ThemePreset, type ThemeSaveMeta, type TimelineEvent, type ToolCall, ToolCallDisplay, type TourStep, type UseTourOptions, type WorkspaceEntity, type WorkspaceMeta, buildAuthHeaders, buildDashboardTourSteps, checkPluginPeerCompatibility, createApiClient, createPapermapObservability, createPapermapServices, createPapermapStore, createPluginContext, decodeToken, defaultTheme, getChartCardIdLink, markDashboardTourCompleted, openPapermapChatAssistant, papermapApiBaseSegment, papermapQueryKeys, parseSemverPrefix, presetDisplayNames, readDashboardTourCompleted, removeChartCardIdLink, resolveChartFetchChatId, resolveDashboardThemeFromWorkspace, themePresetList, themePresets, unwrapWorkspacePayload, upsertChartCardIdLink, useAnalyticsStream, useAutoFade, useAutoResize, useKeyboardShortcuts, usePapermapConnection, usePapermapConnectionOptional, usePapermapStore, usePapermapStoreApi, usePapermapStoreApiOptional, useTour };