@papermap/papermap 1.1.0 → 1.1.2

package/dist/index.d.mts

@@ -1,8 +1,8 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
+import * as React$1 from 'react';
+import React__default, { CSSProperties, ReactNode, RefObject } from 'react';
 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';
@@ -11,33 +11,400 @@ import * as axios from 'axios';
 import { AxiosInstance } from 'axios';
 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;
     /**
-     * Called after the floating assistant panel is closed (e.g. to refetch dashboard charts).
+     * 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.
      */
-    onAssistantClose?: () => void;
+    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({ token, workspaceId, dashboardId, apiUrl, onToolbarHeightChange, onAssistantClose, showToolbar, ...uiProps }: PaperChatProps): react_jsx_runtime.JSX.Element;
+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;
+    /**
+     * Dialog embed: viewport pixels reserved by the chat dialog along its
+     * anchored horizontal edge. Forwarded to {@link FloatingChartOverlay} so the
+     * compact chart card opens 16px from the dialog.
+     */
+    embedDialogReservedSidePx?: number;
+    /** Dialog embed: viewport edge the chat dialog is anchored to vertically. */
+    embedDialogVerticalAnchor?: 'top' | 'bottom';
+    /** Dialog embed: dialog's vertical anchor inset from the viewport edge in px. */
+    embedDialogVerticalInsetPx?: number;
+    /**
+     * 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;
+    /**
+     * Dialog embed: viewport pixels reserved by the chat dialog along its anchored
+     * horizontal edge (corner inset + dialog width). The compact chart card uses
+     * this to anchor itself 16px away from the dialog's chat-facing edge.
+     */
+    embedDialogReservedSidePx?: number;
+    /** Dialog embed: which viewport edge the chat dialog is anchored to vertically. */
+    embedDialogVerticalAnchor?: 'top' | 'bottom';
+    /** Dialog embed: dialog's vertical anchor inset from the viewport edge in px. */
+    embedDialogVerticalInsetPx?: number;
+}
+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>;
@@ -183,8 +550,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.
@@ -210,7 +578,7 @@ 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;
@@ -234,7 +602,153 @@ interface PaperCardProps {
 }
 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;
+/**
+ * Mirrors the main app's `insight` SSE payload — driven by the same
+ * `dashboards/:id/insights/stream` endpoint.
+ */
+type DashboardInsightType = 'highlight' | 'trends' | 'recommendation';
+interface DashboardInsight {
+    id: string;
+    insightType: DashboardInsightType;
+    headline: string;
+    body: string;
+    /** Opaque string. For `trends`, often `"<upside> | <downside>"` (split only on ` | `). */
+    metric: string | null;
+    /** Linked chat id for "Explore in chat" deep links. Omitted when `error`. */
+    chatId?: string;
+    error?: boolean;
+}
+interface DashboardInsightsResult {
+    insights: DashboardInsight[];
+    generationTime?: number;
+}
+interface StreamDashboardInsightsOptions {
+    dashboardId: string;
+    /** Inclusive start of the period. Accepts a `Date` or `yyyy-MM-dd` string. */
+    startDate: Date | string;
+    /** Inclusive end of the period. Accepts a `Date` or `yyyy-MM-dd` string. */
+    endDate: Date | string;
+    authHeaders: Record<string, string>;
+    apiUrl?: string;
+    /** Extra fields merged into the POST body. */
+    extraBody?: Record<string, unknown>;
+    /** Fired when the server emits `insights_started` — clear UI state here. */
+    onStarted?: () => void;
+    /** Fired once per `insight` SSE event with the parsed insight. */
+    onInsight?: (insight: DashboardInsight) => void;
+    /** Fired when the server emits `insights_complete`. */
+    onComplete?: (result: DashboardInsightsResult) => void;
+    /** Fired on transport error or an `error` SSE event. */
+    onError?: (error: Error) => void;
+    signal?: AbortSignal;
+}
+declare function normalizeInsightType(raw: unknown): DashboardInsightType;
+/** Stable display order (recommendation → highlight → trends). Preserves order within each type. */
+declare function orderInsightsForDisplay(insights: DashboardInsight[]): DashboardInsight[];
+/** Format a `Date` (or pass through a string) into `yyyy-MM-dd`. */
+declare function formatInsightDate(value: Date | string): string;
+/**
+ * Opens the dashboard insights SSE stream and dispatches the main app's
+ * named events (`insights_started`, `insight`, `insights_complete`, `error`)
+ * to the supplied callbacks. Returns `{ abort }` for lifecycle control.
+ */
+declare function streamDashboardInsights(options: StreamDashboardInsightsOptions): {
+    abort: () => void;
+};
+/** Pull a numeric percentage out of a `metric` string. Returns `null` when nothing parseable. */
+declare function parseInsightMetricToTrend(metric: string | null | undefined): number | null;
+
+/** Quick Insights period dropdown + timeline sync (not SSE `insight.type`). Mirrors main app. */
+type InsightsPeriodPreset = 'last_3_months' | 'this_week' | 'this_month' | 'this_year' | 'custom';
+type InsightsPeriodMenuPreset = Exclude<InsightsPeriodPreset, 'custom'>;
+declare const INSIGHTS_PERIOD_LABELS: Record<InsightsPeriodPreset, string>;
+declare const INSIGHTS_PERIOD_SELECT_OPTIONS: InsightsPeriodPreset[];
+/** Preset → [start, end]; end is always "now". */
+declare function computeInsightsPeriodRange(preset: InsightsPeriodMenuPreset, now?: Date): {
+    start: Date;
+    end: Date;
+};
+/** "Apr 25 – May 25, 2026" — matches main app `format(d, 'MMM d') – format(d, 'MMM d, yyyy')`. */
+declare function formatInsightsDateLabel(start: Date | undefined, end: Date | undefined): string | null;
+
+/** Named slots a host can target with `classNames` / `styles`. */
+type PaperInsightSlot = 'root' | 'header' | 'headerInner' | 'titleGroup' | 'icon' | 'title' | 'spinner' | 'loadingText' | 'dateLabel' | 'actions' | 'periodSelect' | 'refreshButton' | 'body' | 'list' | 'row' | 'rowIcon' | 'rowHeadline' | 'rowBody' | 'rowMetric' | 'exploreButton' | 'skeleton' | 'emptyState' | 'footer';
+type PaperInsightClassNames = Partial<Record<PaperInsightSlot, string>>;
+type PaperInsightStyles = Partial<Record<PaperInsightSlot, CSSProperties>>;
+interface PaperInsightProps {
+    /** Inclusive start of the period. `Date` or `yyyy-MM-dd` string. */
+    startDate?: Date | string;
+    /** Inclusive end of the period. `Date` or `yyyy-MM-dd` string. */
+    endDate?: Date | string;
+    /** Dashboard id. Falls back to the surrounding `PapermapProvider`. */
+    dashboardId?: string;
+    /** Connection (falls back to surrounding `PapermapProvider`). */
+    token?: string;
+    workspaceId?: string;
+    apiUrl?: string;
+    theme?: 'light' | 'dark' | 'system';
+    /** Themed dashboard styling (mirrors main app `dashboardTheme` mark color). */
+    dashboardTheme?: DashboardTheme | null;
+    /** Root element class. Merged after built-in classes. */
+    className?: string;
+    /** Root element inline style. */
+    style?: CSSProperties;
+    /** Per-slot class overrides (header, title, refreshButton, row, body, etc.). */
+    classNames?: PaperInsightClassNames;
+    /** Per-slot inline style overrides. */
+    styles?: PaperInsightStyles;
+    /** Disables interactions while the host's grid is in layout-edit mode. */
+    isEditMode?: boolean;
+    /**
+     * Period preset. Optional in standalone use — when omitted, the panel manages
+     * its own preset (defaults to `'last_3_months'`) and shows the dropdown so the
+     * user can switch range. Pass a value to control externally.
+     */
+    periodPreset?: InsightsPeriodPreset;
+    onPeriodPresetChange?: (preset: InsightsPeriodPreset) => void;
+    /** Hide the period dropdown entirely (e.g. host renders its own period picker). */
+    hidePeriodSelect?: boolean;
+    /**
+     * Fired when the user drags the inline custom-range scrubber. Required for the
+     * scrubber to function when `periodPreset === 'custom'` — the host owns the
+     * `startDate`/`endDate` state.
+     */
+    onRangeChange?: (start: Date, end: Date) => void;
+    /**
+     * Show the inline `TimelineRange` scrubber when `periodPreset === 'custom'`.
+     * Defaults to `true` for standalone use. Set `false` when a parent (e.g.
+     * `PaperBoard`) renders its own scrubber outside the panel.
+     */
+    showCustomRangeScrubber?: boolean;
+    /**
+     * Enable the "Custom range" option (dropdown entry + scrubber). Defaults to
+     * `true` for standalone use. Set `false` to remove the custom-range entry
+     * from the period dropdown and hide the scrubber entirely.
+     */
+    enableCustomRange?: boolean;
+    /** Click handler for the per-row "Explore in Chat" arrow. */
+    onExplore?: (chatId: string) => void;
+    /**
+     * When `true` and no `onExplore` handler is provided, clicking the per-row
+     * "Explore in Chat" arrow opens the Papermap chat assistant focused on the
+     * insight's linked chat. Requires a surrounding `PapermapProvider`. Defaults
+     * to `false`.
+     */
+    openChatAssistantOnExplore?: boolean;
+    /** Fired on each insight event. */
+    onInsight?: (insight: DashboardInsight) => void;
+    /** Fired when the stream completes. */
+    onComplete?: (result: DashboardInsightsResult) => void;
+    /** Fired on a stream error. */
+    onError?: (error: Error) => void;
+}
+declare function PaperInsight({ startDate, endDate, dashboardId: dashboardIdProp, token: tokenProp, workspaceId: workspaceIdProp, apiUrl: apiUrlProp, theme, dashboardTheme, className, style, classNames, styles, isEditMode, periodPreset, onPeriodPresetChange, hidePeriodSelect, onRangeChange, showCustomRangeScrubber, enableCustomRange, onExplore, openChatAssistantOnExplore, onInsight, onComplete, onError, }: PaperInsightProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Stable grid id for the dashboard insight tile. Mirrors the main app's
+ * `TIMELINE_INSIGHTS_GRID_ID`; the prefix avoids colliding with chart chat ids.
+ */
+declare const PAPER_INSIGHT_GRID_ID = "__papermap_insight_panel__";
 
 interface AgentThought {
     type: 'agent_thought';
@@ -243,6 +757,24 @@ 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: {
@@ -268,7 +800,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;
@@ -277,13 +809,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 {
@@ -298,10 +834,11 @@ interface StreamState {
     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 {
@@ -317,15 +854,90 @@ 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;
@@ -355,17 +967,52 @@ interface DashboardTabNavigationProps {
     className?: string;
     items: DashboardNavbarItem[];
     dashboardTheme?: DashboardTheme;
-    /** Renders on the right (e.g. `PaperDashboardSelect`). */
-    rightSlot?: React.ReactNode;
+    /** 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, rightSlot, }: DashboardTabNavigationProps): react_jsx_runtime.JSX.Element;
+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;
@@ -410,6 +1057,9 @@ interface ChartViewProps {
     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;
 
@@ -428,9 +1078,10 @@ interface ChartDialogProps {
     visualizationConfig: Record<string, any>;
     onMetaChange: (key: 'title' | 'description' | 'footer' | 'subtitle', value: string) => void;
     variant?: string;
+    hideChartArea?: boolean;
     /**
-     * Optional hook for the **minimize** control only: invoked immediately before `onOpenChange(false)`.
-     * Backdrop click and Escape call **only** `onOpenChange(false)` (Radix default).
+     * 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;
     /**
@@ -447,6 +1098,18 @@ interface ChartDialogProps {
      * 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;
 
@@ -464,12 +1127,12 @@ declare function StreamingChartDialog({ isOpen, onOpenChange, chartId, onClose,
 
 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> {
@@ -508,7 +1171,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;
@@ -561,8 +1228,19 @@ 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;
@@ -600,6 +1278,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;
@@ -608,6 +1292,66 @@ 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). */
@@ -646,6 +1390,7 @@ declare function createWorkspaceService(client: AxiosInstance): {
     getWorkspace: (workspaceId: string) => Promise<any>;
     updateWorkspace: (workspaceId: string, workspace: JsonObject) => Promise<any>;
     verifyDatabaseConnection: (workspaceId: string) => Promise<any>;
+    createUnifiedWorkspace: (name?: string) => Promise<any>;
 };
 
 type PapermapHttpServices = {
@@ -653,6 +1398,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: {
@@ -666,6 +1414,7 @@ type MessageProgressEvent = {
 };
 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';
@@ -747,6 +1496,21 @@ interface PapermapStoreConfig {
      * `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 {
@@ -802,6 +1566,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;
@@ -825,10 +1613,21 @@ interface PapermapActions {
     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[];
@@ -851,6 +1650,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 {
@@ -876,7 +1677,7 @@ 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.
@@ -884,7 +1685,7 @@ 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";
+declare const PAPERMAP_SDK_VERSION: "1.1.2";
 /** 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 & {});
@@ -941,6 +1742,12 @@ type PapermapConnectionValue = {
 };
 type PapermapProviderProps = Omit<PapermapStoreConfig, 'observability'> & {
     children: React__default.ReactNode;
+    /**
+     * 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. */
@@ -953,12 +1760,12 @@ type PapermapProviderProps = Omit<PapermapStoreConfig, 'observability'> & {
  * 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
+ * **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, onModelChange, observability: observabilityProp, plugin, }: PapermapProviderProps): react_jsx_runtime.JSX.Element;
+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).
@@ -1008,6 +1815,13 @@ interface UseAnalyticsStreamOptions {
     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.
@@ -1016,6 +1830,7 @@ 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[];
@@ -1078,7 +1893,16 @@ declare const papermapQueryKeys: {
     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 {
@@ -1090,7 +1914,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;
@@ -1149,8 +1983,58 @@ interface PaperBoardProps {
         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;
+    /**
+     * Mount the dashboard insight tile (mirrors main app `TimelineInsights`).
+     * The tile is injected at the top of every breakpoint layout via
+     * `ensurePaperInsightLayoutItem`. Default `false`.
+     */
+    showInsights?: boolean;
+    /**
+     * Initial / controlled period for the insight tile. Defaults to `'last_3_months'`
+     * when uncontrolled. Selecting `'custom'` keeps the host's existing range.
+     */
+    insightsPeriodPreset?: InsightsPeriodPreset;
+    onInsightsPeriodPresetChange?: (preset: InsightsPeriodPreset) => void;
+    /**
+     * Explicit date range for the insight tile. Overrides the auto-computed range
+     * from the preset (use this together with `'custom'` for timeline-scrubbed ranges).
+     */
+    insightsStartDate?: Date | string;
+    insightsEndDate?: Date | string;
+    /** Click handler for the per-insight "Explore in Chat" arrow. */
+    onInsightExplore?: (chatId: string) => void;
 }
-declare function PaperBoard({ token, workspaceId, dashboardId, apiUrl, showWorkspaceDashboardSelect, onWorkspaceDashboardChange, ...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;
+
+/**
+ * Mirrors the main app's `ensureTimelineInsightsLayoutItem`. Injects a layout slot
+ * for the dashboard insight tile across every breakpoint if one isn't already
+ * present. No-op for breakpoints that already include `gridId`.
+ */
+declare function ensurePaperInsightLayoutItem(layouts: PaperBoardLayouts, gridId: string, defaults?: Partial<TLayout>): PaperBoardLayouts;
 
 declare function readDashboardTourCompleted(key: string): boolean;
 declare function markDashboardTourCompleted(key: string): void;
@@ -1163,6 +2047,23 @@ type BuildDashboardTourStepsOptions = {
  */
 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';
 
 type ThemeSaveMeta = {
@@ -1242,4 +2143,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, 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 };
+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 DashboardInsight, type DashboardInsightType, type DashboardInsightsResult, type DashboardNavbarItem, DashboardTabNavigation, type DashboardTabNavigationProps, type DashboardTheme, DataTable, type DecodedToken, FeedbackButtons, type FinalResponse, FloatingChartOverlay, INSIGHTS_PERIOD_LABELS, INSIGHTS_PERIOD_SELECT_OPTIONS, type InsightsPeriodMenuPreset, type InsightsPeriodPreset, IntegrationsBar, type JsonObject, LogoStandAlone, type Message, type MessageProgressEvent, ModelSelector, MorphGradient, type OpenPapermapChatAssistantOptions, PAPERMAP_CHAT_GREETING_MESSAGE, PAPERMAP_PLUGIN_CONTRACT_VERSION, PAPERMAP_SDK_VERSION, PAPER_INSIGHT_GRID_ID, 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, PaperInsight, type PaperInsightClassNames, type PaperInsightProps, type PaperInsightSlot, type PaperInsightStyles, 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 StreamDashboardInsightsOptions, 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, computeInsightsPeriodRange, createApiClient, createPapermapObservability, createPapermapServices, createPapermapStore, createPluginContext, decodeToken, defaultTheme, ensurePaperInsightLayoutItem, formatInsightDate, formatInsightsDateLabel, getChartCardIdLink, markDashboardTourCompleted, normalizeInsightType, openPapermapChatAssistant, orderInsightsForDisplay, papermapApiBaseSegment, papermapQueryKeys, parseInsightMetricToTrend, parseSemverPrefix, presetDisplayNames, readDashboardTourCompleted, removeChartCardIdLink, resolveChartFetchChatId, resolveDashboardThemeFromWorkspace, streamDashboardInsights, themePresetList, themePresets, unwrapWorkspacePayload, upsertChartCardIdLink, useAnalyticsStream, useAutoFade, useAutoResize, useKeyboardShortcuts, usePapermapConnection, usePapermapConnectionOptional, usePapermapStore, usePapermapStoreApi, usePapermapStoreApiOptional, useTour };