@papermap/papermap 1.0.4 → 1.1.1

package/dist/index.d.ts

@@ -1,37 +1,393 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import * as React$1 from 'react';
-import React__default, { RefObject } from 'react';
+import React__default, { ReactNode, RefObject } from 'react';
+import { Layout } from 'react-grid-layout';
+import { LucideIcon } from 'lucide-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';
+
+/** Matches main-app embedded layout (`EmbeddedLayout` / `?theme=`). */
+type PapermapColorScheme = 'light' | 'dark' | 'system';
+
+/**
+ * Host-supplied avatar nodes for chat message rows.
+ *
+ * A supplied node is rendered **as-is** inside a 32px-square layout slot — the
+ * default circle background, rounding and color are NOT applied to it, so host
+ * colors, gradients, images and borders are preserved across light and dark
+ * themes. Provide a self-contained node (e.g.
+ * `<img className="h-full w-full rounded-full object-cover" />` or a styled
+ * element using `h-full w-full`). Any slot left undefined falls back to the
+ * built-in icon inside the default circle.
+ */
+interface PaperChatAvatars {
+    /** Replaces the built-in `User` avatar on user-role rows. */
+    user?: React__default.ReactNode;
+    /** Replaces the built-in `LogoStandAlone` avatar on assistant-role rows. */
+    assistant?: React__default.ReactNode;
+    /** Replaces the built-in `ThinkingLogo` loader shown while the assistant generates. */
+    thinking?: React__default.ReactNode;
+}
+declare function ChatAssistant({ hideChartArea, inline: inlineProp, showAvatars: showAvatarsProp, avatars, greetingMessage, }: {
+    hideChartArea?: boolean;
+    /** Sheet side panel: same as main app `inline={true}`; overrides store `assistantInline` when passed. */
+    inline?: boolean;
+    /**
+     * Force the user / assistant avatars to render even when `inline` (or the store's
+     * `assistantInline`) is true. Without this, inline mode hides avatars for a compact
+     * column layout. Side and dialog variants opt in so the brand/identity stays visible
+     * in those chrome-rich surfaces.
+     */
+    showAvatars?: boolean;
+    /** Override the user / assistant / thinking avatar icons. */
+    avatars?: PaperChatAvatars;
+    /**
+     * Optional welcome line rendered as the first assistant bubble before any
+     * real messages have been exchanged. Skipped automatically once the user
+     * sends a message or a chat is loaded with history.
+     */
+    greetingMessage?: string;
+}): react_jsx_runtime.JSX.Element;
 
+type PaperChatDialogLauncherPosition = 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left';
+interface PaperChatDialogInnerProps {
+    hideChartArea?: boolean;
+    /** Primary label in the dialog header (report / slash-command style). */
+    dialogTitle?: string;
+    /** Secondary line under the title. */
+    dialogSubtitle?: string;
+    /** Controlled open state. Omit to manage open state internally (floating launcher toggles). */
+    dialogOpen?: boolean;
+    onDialogOpenChange?: (open: boolean) => void;
+    /** When false, hide the floating launcher (e.g. fully controlled from the host). Default true. */
+    showDialogLauncher?: boolean;
+    /** `aria-label` / `title` on the floating launcher. */
+    dialogLauncherAriaLabel?: string;
+    /** Viewport corner for the floating launcher (`fixed` inset). Default `bottom-right`. */
+    dialogLauncherPosition?: PaperChatDialogLauncherPosition;
+    className?: string;
+    /** Optional portal target for the sheet chart overlay (same as side panel). */
+    chartOverlayPortalRef?: React__default.RefObject<HTMLDivElement | null>;
+    onAssistantClose?: () => void;
+    /** Render user / assistant avatars inside the embedded chat. Defaults to `true`. */
+    showAvatars?: boolean;
+    /** Override the user / assistant / thinking avatar icons. */
+    avatars?: PaperChatAvatars;
+    /**
+     * Custom trigger node replacing the default floating launcher button. Wrapped
+     * with a `data-paper-dialog-launcher` element that toggles the dialog on click
+     * so any node (icon, branded button, etc.) keeps the open/close UX.
+     */
+    trigger?: React__default.ReactNode;
+    /** Controlled expand/collapse state for the dialog popup. */
+    expanded?: boolean;
+    /** Uncontrolled initial expanded state. Default `false`. */
+    defaultExpanded?: boolean;
+    /** Fires when the dialog toggles between default and expanded size. */
+    onExpandedChange?: (expanded: boolean) => void;
+    /**
+     * Greeting message rendered as the first assistant bubble before the user
+     * sends anything. Plain string for now; mirrors a live-chat widget welcome.
+     */
+    greetingMessage?: string;
+}
+/**
+ * Report-style chat: floating launcher button + modal shell matching the main app’s
+ * in-editor slash chat (header chip, MessageSquare icon, full assistant + composer).
+ */
+declare function PaperChatDialogInner({ hideChartArea, dialogTitle, dialogSubtitle, dialogOpen: dialogOpenProp, onDialogOpenChange, showDialogLauncher, dialogLauncherAriaLabel, dialogLauncherPosition, className, chartOverlayPortalRef, onAssistantClose, showAvatars, avatars, trigger, expanded: expandedProp, defaultExpanded, onExpandedChange, greetingMessage, }: PaperChatDialogInnerProps): react_jsx_runtime.JSX.Element;
+
+type PaperChatVariant = 'default' | 'side' | 'floating' | 'dialog';
+/** Docking edge for `variant="side"` (viewport-anchored left/right rail). */
+type PaperChatSidePosition = 'left' | 'right';
+type PaperChatSideContentInsetMode = 'none' | 'auto';
+
+/**
+ * Controls handed to {@link PaperChatProps.renderSidePanelOpenTrigger}. The
+ * host's open state remains the source of truth — `show` and `toggle` simply
+ * forward to the `onOpenChange` callback.
+ */
+interface SidePanelTriggerControls {
+    open: boolean;
+    show: () => void;
+    toggle: () => void;
+}
 interface PaperChatProps {
+    variant?: PaperChatVariant;
     token?: string;
     workspaceId?: string;
     dashboardId?: string;
     apiUrl?: string;
-    /**
-     * Called whenever the toolbar height changes (including multiline expansion).
-     * Host apps can use this to add bottom padding/margin to their chart area,
-     * mirroring how the main app dashboard layout reacts to toolbar height.
-     */
+    hideChartArea?: boolean;
     onToolbarHeightChange?: (height: number) => void;
     placeholder?: string;
     shortcutKey?: string;
     autoFade?: boolean;
     fadeDelay?: number;
     className?: string;
+    showToolbar?: boolean;
+    onAssistantClose?: () => void;
+    initialChatScroll?: 'top' | 'bottom';
+    isViewer?: boolean;
+    assistantInline?: boolean;
     /**
-     * Controls whether the fixed bottom chat toolbar (input + quick actions) is rendered.
-     * Defaults to `true`.
+     * Whether to render user / assistant avatars (User icon and Papermap logo)
+     * in chat message rows. Defaults to visible across every variant; pass
+     * `false` to hide them.
      */
-    showToolbar?: boolean;
+    showAvatars?: boolean;
+    /**
+     * Override the user / assistant / thinking avatar icons. Each slot replaces
+     * only the icon — the surrounding circle wrapper stays. Useful for
+     * white-labeling the chat with the host product's brand.
+     */
+    avatars?: PaperChatAvatars;
+    /**
+     * Color scheme when this component creates `PapermapProvider` (main-app embedded `?theme=` parity).
+     */
+    theme?: PapermapColorScheme;
+    /**
+     * Which edge the side rail attaches to (border + shadow face the main area).
+     * - `"left"` (default): dock to the viewport left edge.
+     * - `"right"`: dock to the viewport right edge.
+     */
+    sidePosition?: PaperChatSidePosition;
+    /**
+     * Whether the side rail participates in document flow vs overlaying the page.
+     * - `"none"` (default): on `md+` the rail is viewport-fixed and overlays host content.
+     * - `"auto"`: on `md+` the rail is **in-flow** — place `PaperChat` as a flex sibling next to your
+     *   main surface (`flex` row, `min-h-0`, main `flex-1 min-w-0 overflow-auto`) so content resizes
+     *   with the panel. Below `md`, behavior matches `"none"` (slide-over sheet). Hosts should not rely
+     *   on `body` padding for insetting; the package no longer sets `--papermap-side-inset-*` for this mode.
+     */
+    sideContentInsetMode?: PaperChatSideContentInsetMode;
+    /**
+     * Whether the chat surface is open — use with **`onOpenChange`** for
+     * **`variant="side"`** (rail), **`variant="floating"`** (overlay), and
+     * **`variant="dialog"`** (modal). When omitted, each variant falls back to
+     * its own defaults (side: closed; floating: use `visible`; dialog:
+     * internal state or `dialogOpen`).
+     */
+    open?: boolean;
+    /**
+     * Fires when the surface opens or closes. Use for **`side`**, **`floating`**,
+     * and **`dialog`** instead of legacy `onClose` / `onDialogOpenChange`.
+     */
+    onOpenChange?: (open: boolean) => void;
+    onChartVisibilityChange?: (visible: boolean) => void;
+    /**
+     * Mount node for the sheet chart overlay (`createPortal`). Omit to use `document.body` (no host ref).
+     */
+    chartOverlayPortalRef?: React__default.RefObject<HTMLDivElement | null>;
+    onPendingSheetEditsChange?: (edits: {
+        edit_session_id?: string;
+    }[]) => void;
+    clearPendingSheetEditsRef?: React__default.MutableRefObject<(() => void) | null>;
+    /**
+     * Render-prop for a custom open trigger shown when `variant === 'side'` and
+     * `open === false`. The returned node mounts inside the side wrapper; if you
+     * need the trigger to escape the wrapper (e.g. as a floating action button),
+     * style it with `fixed` / `absolute` positioning.
+     *
+     * Omit to render no trigger — keep the existing pattern where the host
+     * renders its own open affordance outside `PaperChat`.
+     */
+    renderSidePanelOpenTrigger?: (controls: SidePanelTriggerControls) => React__default.ReactNode;
+    /**
+     * @deprecated Use **`open`** for `variant="floating"`. When both are set,
+     * `open` takes precedence.
+     */
+    visible?: boolean;
+    /**
+     * @deprecated Use **`onOpenChange(false)`** for `variant="floating"`. Still
+     * invoked after `onOpenChange` when the overlay requests close, if provided.
+     */
+    onClose?: () => void;
+    historyOpen?: boolean;
+    onCloseHistory?: () => void;
+    /** Header title inside the modal (default: `Chat`). Prefer `title`. */
+    title?: string;
+    /** @deprecated Use **`title`**. */
+    dialogTitle?: string;
+    /** Subtitle under the title. Prefer `subtitle`. */
+    subtitle?: string;
+    /** @deprecated Use **`subtitle`**. */
+    dialogSubtitle?: string;
+    /**
+     * @deprecated Use **`open`** for controlled dialog state. When both are set,
+     * `open` takes precedence.
+     */
+    dialogOpen?: boolean;
+    /**
+     * @deprecated Use **`onOpenChange`**. When both are set, `onOpenChange` is
+     * preferred.
+     */
+    onDialogOpenChange?: (open: boolean) => void;
+    /** Whether to show the floating launcher. Default `true`. Prefer `showLauncher`. */
+    showLauncher?: boolean;
+    /** @deprecated Use **`showLauncher`**. */
+    showDialogLauncher?: boolean;
+    /** Accessible name for the launcher. Prefer `launcherAriaLabel`. */
+    launcherAriaLabel?: string;
+    /** @deprecated Use **`launcherAriaLabel`**. */
+    dialogLauncherAriaLabel?: string;
+    /** Viewport corner for the launcher. Prefer `launcherPosition`. */
+    launcherPosition?: PaperChatDialogLauncherPosition;
+    /** @deprecated Use **`launcherPosition`**. */
+    dialogLauncherPosition?: PaperChatDialogLauncherPosition;
+    /**
+     * Custom trigger node for the `dialog` and `side` variants. The plugin
+     * wraps the node with the open/close handler so any element (icon, branded
+     * button, link, etc.) keeps the built-in toggle UX and accessibility.
+     * Ignored for `default` / `floating` variants.
+     */
+    trigger?: React__default.ReactNode;
+    /** Custom avatar node for assistant message rows. Equivalent to `avatars.assistant`. */
+    assistantAvatar?: React__default.ReactNode;
+    /** Custom avatar node for user message rows. Equivalent to `avatars.user`. */
+    userAvatar?: React__default.ReactNode;
+    /**
+     * Greeting/welcome line rendered as the first assistant bubble before any
+     * real messages have been exchanged. Applies to `side` and `dialog`
+     * variants (where the conversation surface is always mounted).
+     */
+    greetingMessage?: string;
+    /** Controlled expanded state for `side` and `dialog` variants. */
+    expanded?: boolean;
+    /** Uncontrolled initial expanded state. Default `false`. */
+    defaultExpanded?: boolean;
+    /** Fires when the side panel or dialog toggles between default and expanded size. */
+    onExpandedChange?: (expanded: boolean) => void;
+}
+declare function PaperChat({ variant, token, workspaceId, dashboardId, apiUrl, onToolbarHeightChange, onAssistantClose, initialChatScroll, isViewer, assistantInline, theme, showToolbar, showAvatars, avatars, sidePosition, sideContentInsetMode, open, onOpenChange, onChartVisibilityChange, chartOverlayPortalRef, onPendingSheetEditsChange, clearPendingSheetEditsRef, renderSidePanelOpenTrigger, visible, onClose, historyOpen, onCloseHistory, hideChartArea, title, dialogTitle, subtitle, dialogSubtitle, dialogOpen, onDialogOpenChange, showLauncher, showDialogLauncher, launcherAriaLabel, dialogLauncherAriaLabel, launcherPosition, dialogLauncherPosition, trigger, assistantAvatar, userAvatar, greetingMessage, expanded, defaultExpanded, onExpandedChange, ...uiProps }: PaperChatProps): react_jsx_runtime.JSX.Element;
+
+type PendingSheetEditLike = {
+    edit_session_id?: string;
+};
+interface PaperChatSidePanelProps {
+    token?: string;
+    workspaceId?: string;
+    dashboardId?: string;
+    apiUrl?: string;
+    initialChatScroll?: 'top' | 'bottom';
+    isViewer?: boolean;
+    assistantInline?: boolean;
+    /** Color scheme when this component creates `PapermapProvider`. */
+    theme?: PapermapColorScheme;
+    hideChartArea?: boolean;
+    open: boolean;
+    onOpenChange: (open: boolean) => void;
+    onChartVisibilityChange?: (visible: boolean) => void;
+    /**
+     * Optional mount node for the sheet chart overlay portal. When omitted, the overlay portals to
+     * `document.body` so side-panel + dialog embeds work without a host ref.
+     */
+    chartOverlayPortalRef?: React__default.RefObject<HTMLDivElement | null>;
+    onPendingSheetEditsChange?: (edits: PendingSheetEditLike[]) => void;
+    clearPendingSheetEditsRef?: React__default.MutableRefObject<(() => void) | null>;
+    /** When embedded in a modal (e.g. `PaperChat` variant `dialog`), use full width and skip rail animation. */
+    embedInDialog?: boolean;
+    /** Hide the panel title row when the host supplies chrome (e.g. report-style dialog header). */
+    hideHeader?: boolean;
+    /**
+     * Which screen edge the sheet rail attaches to (borders/shadow face the main content).
+     * Ignored when `embedInDialog` is true.
+     */
+    sidePosition?: 'left' | 'right';
+    /**
+     * When true (e.g. `PaperChat` `sideContentInsetMode="auto"`), the desktop rail is laid out in-flow
+     * inside a flex host; width clamps use the smaller of viewport and the host column width, and the
+     * chart overlay reserves the live rail width instead of a fixed constant.
+     */
+    layoutFlowRail?: boolean;
+    /**
+     * Dialog embed only: whether chat chrome or the portaled chart overlay stacks above (focus-driven).
+     */
+    embedDialogStackLeader?: 'chat' | 'chart';
+    /** Ref to the floating chart dock root for embed stacking hit-testing. */
+    embedChartDockRef?: React__default.MutableRefObject<HTMLDivElement | null>;
+    /** Dialog embed: sync expanded/history fullscreen overlay foreground for Radix stack tiers. */
+    onEmbedChartForegroundChange?: (foreground: boolean) => void;
+    /**
+     * Whether to render user / assistant avatars (User icon and Papermap logo)
+     * in message bubbles. Defaults to `true` for this surface — the side rail
+     * and dialog modal are chrome-rich and benefit from identity affordances.
+     * Set `false` to hide them.
+     */
+    showAvatars?: boolean;
+    /** Override the user / assistant / thinking avatar icons. */
+    avatars?: PaperChatAvatars;
+    /**
+     * Greeting / welcome message rendered as the first assistant bubble before
+     * the user sends anything. Mirrors a live-chat widget welcome line.
+     */
+    greetingMessage?: string;
+    /** Controlled expanded state — when true, the panel grows beyond default width. */
+    expanded?: boolean;
+    /** Uncontrolled initial expanded state. Default `false`. */
+    defaultExpanded?: boolean;
+    /** Fires when the panel toggles between default and expanded width. */
+    onExpandedChange?: (expanded: boolean) => void;
+    /** Hide the built-in expand/collapse toggle in the header. Default `false`. */
+    hideExpandToggle?: boolean;
+}
+declare function PaperChatSidePanel({ token, workspaceId, dashboardId, apiUrl, initialChatScroll, isViewer, assistantInline, theme, ...panelProps }: PaperChatSidePanelProps): react_jsx_runtime.JSX.Element;
+/** Backward-compatible alias. Prefer `PaperChatSidePanel`. */
+declare function ChatSidePanel(props: PaperChatSidePanelProps): react_jsx_runtime.JSX.Element;
+
+interface PaperChatFloatingChartOverlayProps {
+    token?: string;
+    workspaceId?: string;
+    dashboardId?: string;
+    apiUrl?: string;
+    initialChatScroll?: 'top' | 'bottom';
+    isViewer?: boolean;
+    assistantInline?: boolean;
+    /** Color scheme when this component creates `PapermapProvider`. */
+    theme?: PapermapColorScheme;
+    visible: boolean;
+    onClose: () => void;
+    /** Sheet page: charts history list in this overlay instead of the chat column */
+    historyOpen?: boolean;
+    onCloseHistory?: () => void;
+    /**
+     * When true (e.g. `PaperChat` variant `dialog`), use the same z-index layer as {@link ChartDialog}
+     * (`PAPERMAP_CHAT_DIALOG_Z`) with `fixed` positioning. Prefer portaling to `document.body` in the host.
+     */
+    stackWithChartDialog?: boolean;
+    /**
+     * When portaling to `document.body` next to {@link ChatSidePanel}, inset the overlay so it only
+     * covers the main area — not the chat rail (`CHAT_SIDE_PANEL_WIDTH_PX`).
+     */
+    besideRail?: boolean;
+    /**
+     * When set with `besideRail`, padding matches this width (e.g. in-flow rail after drag/expand)
+     * instead of the default `CHAT_SIDE_PANEL_WIDTH_PX`.
+     */
+    besideRailReservedWidthPx?: number;
+    /** Which edge the side panel is on — must match `ChatSidePanel` `sidePosition`. */
+    sidePosition?: 'left' | 'right';
+    /** When false and `besideRail`, do not reserve rail width (panel collapsed). */
+    sideRailOpen?: boolean;
+    /** Merged onto the chart overlay card shell (rounded panel). */
+    className?: string;
+    /** Dialog embed: z-index tier vs chat (from `PaperChatDialogInner`). */
+    embedDialogStackLeader?: 'chat' | 'chart';
+    embedChartDockRef?: React__default.MutableRefObject<HTMLDivElement | null>;
+    /** Dialog embed: expanded or history fullscreen should stack above chat and lower dialog chrome. */
+    onEmbedChartForegroundChange?: (foreground: boolean) => void;
 }
-declare function PaperChat({ token, workspaceId, dashboardId, apiUrl, onToolbarHeightChange, showToolbar, ...uiProps }: PaperChatProps): react_jsx_runtime.JSX.Element;
+declare function PaperChatFloatingChartOverlay({ token, workspaceId, dashboardId, apiUrl, initialChatScroll, isViewer, assistantInline, theme, ...overlayProps }: PaperChatFloatingChartOverlayProps): react_jsx_runtime.JSX.Element;
+/** Backward-compatible alias. Prefer `PaperChatFloatingChartOverlay`. */
+declare function FloatingChartOverlay(props: PaperChatFloatingChartOverlayProps): 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 +395,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 +411,7 @@ type TChartResponse = {
     chart_response?: {
         chart_type: string;
         error?: boolean;
-        data: any[];
+        data: ChartDataRow[];
         response_type: string;
         text_response?: string;
         schema_hints: {
@@ -56,13 +419,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 +440,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 +458,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 +507,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).
@@ -135,8 +530,9 @@ interface PaperCardProps {
     /**
      * Visual theme for the chart card. When set, renders in the specified
      * mode independent of the host app. Omit to inherit the host page's theme.
+     * When the card creates its own `PapermapProvider`, this also sets the provider color scheme.
      */
-    theme?: 'light' | 'dark';
+    theme?: 'light' | 'dark' | 'system';
     /**
      * Called when the user clicks the edit button on the chart card.
      * In streaming variant, if not provided, the built-in StreamingChartDialog opens.
@@ -162,12 +558,12 @@ interface PaperCardProps {
     wide?: boolean;
     /** Hide the chart variation selector. Defaults to true. */
     hideVariants?: boolean;
-    /** Show the toolbar with edit/delete/maximize buttons. Defaults to true. */
+    /** Show the card chrome toolbar (maximize, edit, delete). Main app `ChartCard` uses `showChatToolbar`. Default true. */
     showToolbar?: boolean;
     /** 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,10 +571,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 ChatAssistant(): 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;
 
 interface AgentThought {
     type: 'agent_thought';
@@ -187,16 +589,34 @@ interface AgentThought {
     iteration: number;
     timestamp: string;
 }
+/** Native model reasoning (OpenAI summaries, Claude extended thinking) */
+interface Reasoning {
+    type: 'reasoning';
+    content: string;
+    is_complete: boolean;
+    iteration: number;
+    timestamp: string;
+}
+/** SSE payload when the agent requires user confirmation before executing a tool */
+interface ConfirmationRequired {
+    type: 'confirmation_required';
+    confirmation_id: string;
+    tool_display_name: string;
+    message: string;
+    action_description: string;
+    timeout_seconds: number;
+    timestamp: string;
+}
 interface FinalResponse {
     type: 'final_response';
     response_data: {
         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;
@@ -212,7 +632,7 @@ interface ToolCall {
     tool_name: string;
     tool_display_name: string;
     args_preview: string;
-    status: 'announced' | 'streaming' | 'ready' | 'executing' | 'success' | 'error';
+    status: 'announced' | 'streaming' | 'ready' | 'confirmation_pending' | 'executing' | 'success' | 'error' | 'denied';
     output?: string;
     code?: string;
     isStreamingArgs?: boolean;
@@ -221,13 +641,17 @@ interface ToolCall {
     duration_ms?: number;
     error_message?: string;
     tool_call_id?: string;
+    /** Present while status is `confirmation_pending` */
+    confirmationData?: ConfirmationRequired;
     timestamp: string;
 }
 interface TimelineEvent {
-    type: 'thought' | 'tool';
+    type: 'thought' | 'reasoning' | 'tool';
     timestamp: string;
     iteration?: number;
     thoughtData?: AgentThought;
+    /** For native model reasoning */
+    reasoningData?: Reasoning;
     toolData?: ToolCall;
 }
 interface StreamState {
@@ -236,16 +660,17 @@ interface StreamState {
     timeline: TimelineEvent[];
     currentPhase: string;
     error: string | null;
-    finalResponse: any | null;
+    finalResponse: unknown | null;
     isComplete: boolean;
     isConnected: boolean;
     isStreaming: boolean;
 }
 
-declare function StreamingTimeline({ timeline, collapseThreshold, recentFullCount, }: {
+declare function StreamingTimeline({ timeline, collapseThreshold, recentFullCount, onConfirmationResponse, }: {
     timeline: TimelineEvent[];
     collapseThreshold?: number;
     recentFullCount?: number;
+    onConfirmationResponse?: (confirmationId: string, confirmed: boolean, message?: string) => Promise<void>;
 }): react_jsx_runtime.JSX.Element | null;
 
 interface AgentThoughtDisplayProps {
@@ -261,31 +686,178 @@ interface ToolCallDisplayProps {
     className?: string;
     showAll?: boolean;
     isLatest?: boolean;
+    onConfirmationResponse?: (confirmationId: string, confirmed: boolean, message?: string) => Promise<void>;
 }
-declare function ToolCallDisplay({ toolCalls, className, showAll, isLatest, }: ToolCallDisplayProps): react_jsx_runtime.JSX.Element | null;
+declare function ToolCallDisplay({ toolCalls, className, showAll, isLatest, onConfirmationResponse, }: ToolCallDisplayProps): react_jsx_runtime.JSX.Element | null;
 
-declare function RecentConversations(): react_jsx_runtime.JSX.Element;
+declare function RecentConversations({ embedInPanel }?: {
+    embedInPanel?: boolean;
+}): react_jsx_runtime.JSX.Element;
 
 declare function ChartHistory(): react_jsx_runtime.JSX.Element;
 
 declare function SavedMemory(): react_jsx_runtime.JSX.Element;
 
+/**
+ * In the main app, workspace/dashboard selection lives in Redux. The plugin
+ * provides the same `WorkspaceSelector` API (`dashboardTheme` only) and
+ * supplies selection state and callbacks through this context (see PaperBoard).
+ */
+type WorkspaceSelectorControl = {
+    workspaceId: string;
+    dashboardId: string;
+    onSelect: (next: {
+        workspaceId: string;
+        dashboardId: string;
+    }) => void;
+    isViewer?: boolean;
+};
+declare function WorkspaceSelectorProvider({ value, children, }: {
+    value: WorkspaceSelectorControl;
+    children: ReactNode;
+}): react_jsx_runtime.JSX.Element;
+
+declare function DashboardAppHeader({ dashboardTheme, showWorkspaceSelector, workspaceSelectorValue, user, onLogout, billingHref, settingsHref, logoutUrl, appHeaderRightSlot, className, 
+/**
+ * When false, the header does not use `position: sticky` — use with a parent flex column where
+ * the scroll region is a sibling below the header (main-app `AuthenticatedLayout` pattern).
+ */
+sticky, }: {
+    dashboardTheme?: DashboardTheme | null;
+    showWorkspaceSelector: boolean;
+    workspaceSelectorValue: WorkspaceSelectorControl;
+    user?: {
+        name?: string | null;
+        email?: string | null;
+    } | null;
+    onLogout?: () => void;
+    billingHref?: string;
+    settingsHref?: string;
+    logoutUrl?: string;
+    appHeaderRightSlot?: ReactNode;
+    className?: string;
+    sticky?: boolean;
+}): react_jsx_runtime.JSX.Element;
+
+declare function UserNav({ dashboardTheme, user: userProp, onLogout, billingHref, settingsHref, logoutUrl, }: {
+    dashboardTheme?: DashboardTheme | null;
+    user?: {
+        name?: string | null;
+        email?: string | null;
+    } | null;
+    /** Called when user picks Log out; if omitted, navigates to `logoutUrl` or Papermap home. */
+    onLogout?: () => void;
+    /** Defaults: `/billing` and `/settings` on the hosted web app. */
+    billingHref?: string;
+    settingsHref?: string;
+    logoutUrl?: string;
+}): react_jsx_runtime.JSX.Element;
+
+/**
+ * Main app: [IntegrationsBar](papermap/src/components/IntegrationsBar.tsx) — Slack in the package;
+ * WhatsApp is main-app-only (omitted to avoid a large second port).
+ */
+declare function IntegrationsBar({ dashboardTheme, }: Readonly<{
+    dashboardTheme?: DashboardTheme | null;
+}>): react_jsx_runtime.JSX.Element;
+
+/**
+ * Same surface API as the main app `src/components/dashboard/workspace-selector.tsx`:
+ * `dashboardTheme` for scoped styling. Selection state and `onSelect` are provided by
+ * {@link WorkspaceSelectorProvider} (wired from PaperBoard).
+ */
+declare function WorkspaceSelector({ dashboardTheme }: {
+    dashboardTheme?: DashboardTheme;
+}): 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;
+    /** Sticky offset below the app header. Main app uses `top-14` (3.5rem) under a 14 (`h-14`) top bar. */
+    stickyTopClassName?: string;
+    /** When false, tabs are not `position: sticky` (stack below the header; scroll is a sibling below). */
+    sticky?: boolean;
+    rightSlot?: ReactNode;
+}
+/**
+ * Top tab bar styled like the main app `TabNavigation` (embedded layout navbar), without Next.js `Link`.
+ *
+ * **Active tab:** each item’s `href` pathname is compared to `window.location.pathname`. In a single-page
+ * embed where every tab would share the same path, no tab may appear active unless the host uses distinct
+ * paths or supplies custom `items` / a future `activeNavId`-style override.
+ */
+declare function DashboardTabNavigation({ className, items, dashboardTheme, stickyTopClassName, 
+/** When false, tabs are not `position: sticky` (stack below a fixed top bar; scroll is a sibling below). */
+sticky, rightSlot, }: DashboardTabNavigationProps): react_jsx_runtime.JSX.Element;
+
+type CreatedDashboard = {
+    dashboard_id: string;
+    title: string;
+};
+type CreateDashboardDialogProps = {
+    open: boolean;
+    onOpenChange: (open: boolean) => void;
+    workspaceId: string;
+    onSuccess: (dashboard: CreatedDashboard) => void;
+};
+declare function CreateDashboardDialog({ open, onOpenChange, workspaceId, onSuccess, }: CreateDashboardDialogProps): react_jsx_runtime.JSX.Element;
+
+type CreatedUnifiedWorkspace = {
+    workspace_id: string;
+    name: string;
+    default_dashboard: string;
+};
+type CreateUnifiedWorkspaceDialogProps = {
+    open: boolean;
+    onOpenChange: (open: boolean) => void;
+    /** Called after API success with IDs so the host can navigate / invalidate queries. */
+    onSuccess: (workspace: CreatedUnifiedWorkspace) => void;
+};
+declare function CreateUnifiedWorkspaceDialog({ open, onOpenChange, onSuccess, }: CreateUnifiedWorkspaceDialogProps): react_jsx_runtime.JSX.Element;
+
 interface TChartMeta {
     title?: string;
     subtitle?: string;
+    description?: string;
     footer?: string;
     variant?: string;
     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 +880,18 @@ 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;
+    /** When provided, renders a camera/screenshot control next to chart variations (main-app parity). */
+    onScreenshot?: () => void;
+    isScreenshotting?: boolean;
 }
 declare function ChartView(props: ChartViewProps): react_jsx_runtime.JSX.Element;
 
@@ -326,7 +910,38 @@ interface ChartDialogProps {
     visualizationConfig: Record<string, any>;
     onMetaChange: (key: 'title' | 'description' | 'footer' | 'subtitle', value: string) => void;
     variant?: string;
+    hideChartArea?: boolean;
+    /**
+     * Optional callback (main app passes it from chat but does not invoke it from the dialog minimize control).
+     * Minimize calls `onOpenChange(false)` only, matching the main Papermap `ChartDialog`.
+     */
     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;
+    /**
+     * Package-only: near-full viewport sizing for expanded `ChatAssistant` / streaming hosts.
+     * The main app `ChartDialog` has no equivalent prop; default `false` matches main-app layout.
+     */
+    fullBleed?: boolean;
+    /** Color scheme when this component creates `PapermapProvider`. */
+    theme?: PapermapColorScheme;
+    /**
+     * Hide the floating screenshot control (main app keeps it on maximize dialogs from grid/chat paths).
+     * `FloatingChartOverlay` omits chart screenshots in the embed package.
+     */
+    hideScreenshotButton?: boolean;
 }
 declare function ChartDialog(props: ChartDialogProps): react_jsx_runtime.JSX.Element;
 
@@ -337,17 +952,19 @@ 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[];
-    dashboardTheme?: any;
+    dashboardTheme?: DashboardTheme | null;
 }
 declare function DataTable({ data, dashboardTheme }: DataTableProps): react_jsx_runtime.JSX.Element;
 
 declare const buttonVariants: (props?: ({
-    variant?: "default" | "link" | "destructive" | "outline" | "secondary" | "ghost" | null | undefined;
+    variant?: "link" | "default" | "destructive" | "outline" | "secondary" | "ghost" | null | undefined;
     size?: "default" | "sm" | "lg" | "icon" | null | undefined;
 } & class_variance_authority_types.ClassProp) | undefined) => string;
 interface ButtonProps extends React$1.ButtonHTMLAttributes<HTMLButtonElement>, VariantProps<typeof buttonVariants> {
@@ -386,7 +1003,11 @@ interface FeedbackButtonsProps {
 }
 declare function FeedbackButtons({ onFeedback, className, isLoading, selectedFeedback, loadingType, }: FeedbackButtonsProps): react_jsx_runtime.JSX.Element;
 
-declare function ModelSelector(): react_jsx_runtime.JSX.Element;
+interface ModelSelectorProps {
+    /** `icon` = sparkles only; `compact` = sparkles + current model label (main toolbar when expanded / multiline). */
+    variant?: 'icon' | 'compact';
+}
+declare function ModelSelector({ variant }: ModelSelectorProps): react_jsx_runtime.JSX.Element;
 
 interface StreamingChatPanelProps {
     className?: string;
@@ -395,12 +1016,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,39 +1056,23 @@ 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>;
+    getDashboardsPaginated: (params: {
+        workspace_id: string;
+        page?: number;
+        per_page?: number;
+        search_term?: string;
+    }) => Promise<any>;
+    getDashboardById: (dashboardId: string) => Promise<any>;
     updateDashboardLayout: (dashboardId: string, layout: TLayout[]) => Promise<any>;
+    createDashboard: (payload: {
+        title: string;
+        description?: string;
+        workspace_id: string;
+    }) => Promise<any>;
     createChat: (data: {
         name: string;
         dashboard_id: string;
@@ -491,7 +1101,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;
@@ -500,6 +1110,12 @@ declare function createChartService(client: AxiosInstance): {
     removeBookmark: (bookmarkId: string) => Promise<any>;
     updateResponseLabel: (llm_data_id: string, label: "positive" | "negative") => Promise<any>;
     branchConversation: (dashboard_id: string, llm_data_id: string) => Promise<any>;
+    submitToolConfirmation: (data: {
+        request_id: string;
+        confirmation_id: string;
+        confirmed: boolean;
+        message?: string;
+    }) => Promise<any>;
     getModels: () => Promise<any>;
     generateProactiveDashboard: (payload: {
         workspace_id: string;
@@ -508,9 +1124,105 @@ declare function createChartService(client: AxiosInstance): {
     }) => Promise<any>;
 };
 
+interface SlackIntegrationStatus {
+    connected: boolean;
+    team_name?: string;
+    team_id?: string;
+    connected_at?: string;
+    scopes?: string[];
+    requires_reauth?: boolean;
+    error_code?: string;
+    error_message?: string;
+    error_timestamp?: string;
+    can_reactivate?: boolean;
+}
+interface SlackDisconnectResponse {
+    success: boolean;
+    message: string;
+    count: number;
+}
+interface SlackReactivateResponse {
+    success: boolean;
+    message: string;
+    status: {
+        status: string;
+        team_name?: string;
+        team_id?: string;
+        requires_reauth?: boolean;
+        error_code?: string;
+    };
+}
+interface WorkspaceAccess {
+    workspace_id: string;
+    name: string;
+    workspace_type: string;
+    allowed: boolean;
+}
+interface WorkspaceAccessSettings {
+    team_id: string;
+    team_name: string;
+    total_workspaces: number;
+    allowed_workspaces: number;
+    updated_at: string | null;
+    updated_by_user_id: string | null;
+}
+interface WorkspaceAccessResponse {
+    success: boolean;
+    workspaces: WorkspaceAccess[];
+    settings: WorkspaceAccessSettings;
+}
+
+/**
+ * Slack API (matches [slack.service](papermap/src/services/slack.service.ts)); uses the Papermap API client and embed token.
+ */
+declare function createSlackService(client: AxiosInstance, baseUrl: string): {
+    getStatus(): Promise<SlackIntegrationStatus>;
+    initiateOAuth(rawToken: string): Promise<void>;
+    disconnect(): Promise<SlackDisconnectResponse>;
+    reactivate(): Promise<SlackReactivateResponse>;
+    getWorkspaceAccess(teamId: string): Promise<WorkspaceAccessResponse>;
+    updateWorkspaceAccess(teamId: string, allowedWorkspaceIds: string[]): Promise<WorkspaceAccessResponse>;
+};
+
+/** 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>;
+    createUnifiedWorkspace: (name?: string) => Promise<any>;
 };
 
 type PapermapHttpServices = {
@@ -518,6 +1230,9 @@ type PapermapHttpServices = {
     streamingSvc: ReturnType<typeof createStreamingService>;
     chartSvc: ReturnType<typeof createChartService>;
     workspaceSvc: ReturnType<typeof createWorkspaceService>;
+    slackSvc: ReturnType<typeof createSlackService>;
+    /** Raw embed token (used for Slack OAuth redirect). */
+    token: string;
     baseUrl: string;
 };
 declare function createPapermapServices(config: {
@@ -525,8 +1240,13 @@ declare function createPapermapServices(config: {
     apiUrl?: string;
 }): PapermapHttpServices;
 
+type MessageProgressEvent = {
+    event_type?: string;
+    data?: JsonObject;
+};
 interface Message {
     id?: string;
+    /** Preferred id for bookmark / feedback / branch APIs when both are present (matches main app). */
     llm_data_id?: string;
     content: string;
     role: 'user' | 'assistant' | 'error' | 'branch';
@@ -541,13 +1261,40 @@ 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";
@@ -561,6 +1308,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 +1323,26 @@ 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;
+    /**
+     * ChatAssistant scroll: `top` mimics main-app onboarding (open at top, less aggressive bottom follow).
+     * Omit or `bottom` for default bottom-anchored chat scrolling.
+     */
+    initialChatScroll?: 'top' | 'bottom';
+    /**
+     * When true, bookmark actions in chat are hidden (mirrors main app viewer role).
+     * `PapermapProvider` / `PaperChat` forward this; hosts using only metadata can pass without an API role fetch.
+     */
+    isViewer?: boolean;
+    /**
+     * When true, `ChatAssistant` uses column-friendly layout (no floating card chrome). Hosts embed via
+     * `PapermapProvider` + a sized parent, or pass from `PaperChat` when it creates the provider.
+     */
+    assistantInline?: boolean;
 }
 type Services = PapermapHttpServices;
 interface Refs {
@@ -608,10 +1380,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;
@@ -626,6 +1398,30 @@ interface PapermapState {
     sseIsStreaming: boolean;
     sseIsComplete: boolean;
     sseError: string | null;
+    /**
+     * Bound to `useAnalyticsStream().submitConfirmation` while an SSE request is active.
+     * Used by `StreamingTimeline` / tool confirmation UI.
+     */
+    sseSubmitConfirmation: ((confirmationId: string, confirmed: boolean, message?: string) => Promise<void>) | null;
+    /** Workspace role: hide bookmark affordances when true. Synced from `PapermapStoreConfig.isViewer`. */
+    isViewer: boolean;
+    /** Column / side-panel layout for `ChatAssistant` (see `PapermapStoreConfig.assistantInline`). */
+    assistantInline: boolean;
+    /**
+     * Bottom toolbar height (PaperChat input strip), measured via ResizeObserver.
+     * Feeds `getAssistantDimensions` expanded height like main app `useChartStore().toolbarHeight`.
+     */
+    toolbarHeight: number;
+    /**
+     * Sheet / floating chart overlay open — mirrors main `sheetChartUiOpen` on `ChatAssistant`
+     * so the inline “Show Chart” chip hides when the overlay is already up.
+     */
+    sheetChartUiOpen: boolean;
+    /**
+     * Registered by `ChatSidePanelInner` so inline `ChatAssistant` can open `FloatingChartOverlay`
+     * instead of only toggling the split chart column.
+     */
+    externalShowChartHandler: ((visible: boolean) => void) | null;
 }
 interface PapermapActions {
     setMessages: (messages: Message[] | ((prev: Message[]) => Message[])) => void;
@@ -643,16 +1439,27 @@ 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;
+    /**
+     * Merge one chart meta field into `allMeta` (dialog title edits, etc.). Matches main `updateChartMeta` field-wise merge.
+     */
+    patchChartMeta: (key: 'title' | 'description' | 'footer' | 'subtitle', value: string) => void;
     setUseSSEStreaming: (v: boolean) => void;
     setSseRequestId: (v: string | null) => void;
     setSseChatId: (v: string | null) => void;
     clearStreamingState: () => void;
+    /** Called from `SSESync` to wire tool Allow/Deny into the analytics stream hook */
+    setSseSubmitConfirmation: (fn: ((confirmationId: string, confirmed: boolean, message?: string) => Promise<void>) | null) => void;
+    setIsViewer: (v: boolean) => void;
+    setAssistantInline: (v: boolean) => void;
+    setToolbarHeight: (v: number) => void;
+    setSheetChartUiOpen: (v: boolean) => void;
+    setExternalShowChartHandler: (fn: ((visible: boolean) => void) | null) => void;
     syncSseDisplay: (data: {
         thoughts: AgentThought[];
         toolCalls: ToolCall[];
@@ -675,6 +1482,8 @@ interface PapermapActions {
     getConfig: () => PapermapStoreConfig;
 }
 type PapermapStore = PapermapState & PapermapActions;
+/** Default assistant bubble when a thread has no messages yet (API empty or before load). */
+declare const PAPERMAP_CHAT_GREETING_MESSAGE: Message;
 declare function createPapermapStore(config: PapermapStoreConfig, injectedServices?: PapermapHttpServices): zustand.StoreApi<PapermapStore>;
 type PapermapStoreApi = ReturnType<typeof createPapermapStore>;
 interface OpenPapermapChatAssistantOptions {
@@ -700,13 +1509,62 @@ interface OpenPapermapChatAssistantOptions {
  * open in edit mode for that chart.
  *
  * When chart is provided (e.g. from ChartCard), primes the store like the main
- * app openEditChartModal: setMessages([]), updateAllMeta(chart.meta),
+ * app openEditChartModal: setMessages([greeting]), updateAllMeta(chart.meta),
  * updateChartData/Type/Visuals(chart.chart_response), then set editChatId and open.
  * ConversationLoader still runs loadConversations() for messages; variant shows
  * immediately from chart.meta.
  */
 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.1";
+/** 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 +1572,32 @@ 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;
+    /**
+     * Color scheme for the plugin UI (`light` / `dark` / `system`), matching main-app embedded
+     * `?theme=` and `EmbeddedThemeProvider` (`next-themes` + `document.documentElement` class sync).
+     * Default `light`.
+     */
+    theme?: PapermapColorScheme;
+    /** 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`, `initialChatScroll`, `isViewer`, `assistantInline`, `theme`, `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, initialChatScroll, isViewer, assistantInline, onModelChange, observability: observabilityProp, plugin, theme, }: 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 +1613,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,10 +1643,17 @@ 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;
+    /** HTTP implementation — typically `chartSvc.submitToolConfirmation` from the store */
+    submitToolConfirmationRequest?: (data: {
+        request_id: string;
+        confirmation_id: string;
+        confirmed: boolean;
+        message?: string;
+    }) => Promise<unknown>;
 }
 /**
  * Adapted from papermap's useAnalyticsStream.
@@ -762,17 +1662,36 @@ interface UseAnalyticsStreamOptions {
 declare function useAnalyticsStream(requestId: string | null, authHeaders: Record<string, string>, apiUrl: string, options?: UseAnalyticsStreamOptions): {
     disconnect: () => void;
     markRequestAsCompleted: (reqId: string) => void;
+    submitConfirmation: (confirmationId: string, confirmed: boolean, message?: string) => Promise<void>;
     thoughts: AgentThought[];
     toolCalls: ToolCall[];
     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 +1708,35 @@ 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"];
+    /** Infinite workspace list with optional search (matches main app workspace selector). */
+    readonly workspacesInfinite: (apiUrl: string | undefined, searchTerm: string | undefined) => readonly ["papermap", string, "workspaces", "infinite", string];
+    /** Paginated dashboards for a workspace with optional search. */
+    readonly dashboardsPaginated: (workspaceId: string | undefined, apiUrl: string | undefined, page: number, perPage: number, searchTerm: string | undefined) => readonly ["papermap", string, "ws", string, "dashboardsPaginated", number, number, string];
+    readonly models: (apiUrl: string | undefined, token: string) => readonly ["papermap", string, "models", string];
+    readonly slack: {
+        readonly all: (apiUrl: string | undefined) => readonly ["papermap", string, "slack"];
+        readonly status: (apiUrl: string | undefined) => readonly ["papermap", string, "slack", "status"];
+        readonly workspaceAccess: (apiUrl: string | undefined, teamId: string) => readonly ["papermap", string, "slack", "workspace-access", string];
+    };
+};
+
 interface PaperBoardProps {
     token?: string;
     workspaceId?: string;
@@ -798,7 +1746,17 @@ interface PaperBoardProps {
     layouts?: PaperBoardLayouts;
     onLayoutsChange?: (layouts: PaperBoardLayouts) => void;
     isEditMode?: boolean;
+    /**
+     * Show the **dashboard** toolbar (generate, screenshot, edit layout, theme, etc.) in the page header.
+     * Main app `TGridDashboard.showToolbar`. Default `true`.
+     */
     showToolbar?: boolean;
+    /**
+     * Show **per-chart** controls (maximize, edit, delete) on each `PaperCard`. Independent of `showToolbar`.
+     * Main app `TGridDashboard.showChatToolbar` on `ChartCard`. When omitted, matches `showToolbar` so
+     * `showToolbar={false}` still hides both toolbars.
+     */
+    showChatToolbar?: boolean;
     showScreenshot?: boolean;
     showGenerateDashboard?: boolean;
     editLayout?: boolean;
@@ -832,8 +1790,84 @@ 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;
+    /** Color scheme when this component creates `PapermapProvider` (embedded `?theme=` parity). */
+    theme?: PapermapColorScheme;
+    /**
+     * When true, render main-app-style top bar (logo, workspace selector, integrations, user)
+     * and tab navigation above the `PageHeader` and grid. Default `false` for embeds; set `true` for full-app chrome.
+     */
+    showAppChrome?: boolean;
+    /**
+     * Override default tab items (Papermap web app deep links with workspace/dashboard query params).
+     * When omitted, items are built from the workspace API entity (see `buildDashboardNavItems`).
+     */
+    navItems?: DashboardNavbarItem[];
+    /** Shown in the user menu; optional when using embed tokens without a user profile. */
+    user?: {
+        name?: string | null;
+        email?: string | null;
+    } | null;
+    onLogout?: () => void;
+    billingHref?: string;
+    settingsHref?: string;
+    /** Default: Papermap web app origin. */
+    logoutUrl?: string;
+    appHeaderRightSlot?: ReactNode;
 }
-declare function PaperBoard({ token, workspaceId, dashboardId, apiUrl, ...rest }: PaperBoardProps): react_jsx_runtime.JSX.Element;
+declare function PaperBoard({ token, workspaceId, dashboardId, apiUrl, theme, showWorkspaceDashboardSelect, onWorkspaceDashboardChange, showAppChrome, navItems: navItemsProp, user: userProp, onLogout, billingHref, settingsHref, logoutUrl, appHeaderRightSlot, ...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 BuildDashboardNavItemsParams = {
+    workspaceId: string;
+    dashboardId: string;
+    /** From workspace entity */
+    workspaceType?: string;
+    /** Present when Google Sheet source exists */
+    sheet?: string;
+    isAdmin?: boolean;
+    /** When true, user is read-only; hides editor-only tabs (matches main app viewer gating). */
+    isViewer: boolean;
+};
+/**
+ * Main app: [src/navigation/sidebar/sidebarItems.tsx](papermap/src/navigation/sidebar/sidebarItems.tsx).
+ * Links open the hosted Papermap web app with `workspace_id` / `dashboard_id` query params.
+ */
+declare function buildDashboardNavItems(params: BuildDashboardNavItemsParams): DashboardNavbarItem[];
 
 type ThemePreset = 'default' | 'lime' | 'blue' | 'green' | 'purple' | 'ocean' | 'sunset' | 'dark' | 'minimal';
 
@@ -865,10 +1899,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 +1948,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, type BuildDashboardNavItemsParams, 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, ChatSidePanel, type ConversationHistory, CreateDashboardDialog, type CreateDashboardDialogProps, CreateUnifiedWorkspaceDialog, type CreateUnifiedWorkspaceDialogProps, type CreatedDashboard, type CreatedUnifiedWorkspace, DashboardAppHeader, type DashboardNavbarItem, DashboardTabNavigation, type DashboardTabNavigationProps, type DashboardTheme, DataTable, type DecodedToken, FeedbackButtons, type FinalResponse, FloatingChartOverlay, IntegrationsBar, type JsonObject, LogoStandAlone, type Message, type MessageProgressEvent, ModelSelector, MorphGradient, type OpenPapermapChatAssistantOptions, PAPERMAP_CHAT_GREETING_MESSAGE, PAPERMAP_PLUGIN_CONTRACT_VERSION, PAPERMAP_SDK_VERSION, PaperBoard, type TLayout as PaperBoardLayoutItem, type PaperBoardLayouts, PaperCard, type PaperCardProps, PaperChat, type PaperChatAvatars, PaperChatDialogInner, type PaperChatDialogInnerProps, type PaperChatDialogLauncherPosition, PaperChatFloatingChartOverlay, type PaperChatFloatingChartOverlayProps, type PaperChatProps, PaperChatSidePanel, type PaperChatSidePanelProps, type PaperChatSidePosition, type PaperChatVariant, PaperDashboardSelect, type PaperDashboardSelectProps, type PapermapActions, type PapermapCapability, type PapermapColorScheme, 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, UserNav, type WorkspaceEntity, type WorkspaceMeta, WorkspaceSelector, type WorkspaceSelectorControl, WorkspaceSelectorProvider, buildAuthHeaders, buildDashboardNavItems, 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 };