@papermap/papermap 1.1.1 → 1.1.2

package/dist/index.d.mts

@@ -1,6 +1,6 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import * as React$1 from 'react';
-import React__default, { ReactNode, RefObject } from 'react';
+import React__default, { CSSProperties, 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';
@@ -313,6 +313,16 @@ interface PaperChatSidePanelProps {
     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
@@ -381,6 +391,16 @@ interface PaperChatFloatingChartOverlayProps {
     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`. */
@@ -582,6 +602,154 @@ 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;
 
+/**
+ * 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';
     content: string;
@@ -1517,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.1";
+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 & {});
@@ -1838,9 +2006,36 @@ interface PaperBoardProps {
     /** 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, 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;
 type BuildDashboardTourStepsOptions = {
@@ -1948,4 +2143,4 @@ declare function resolveChartFetchChatId(params: {
     dashboardId?: string;
 }): string | undefined;
 
-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 };
+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 };

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import * as React$1 from 'react';
-import React__default, { ReactNode, RefObject } from 'react';
+import React__default, { CSSProperties, 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';
@@ -313,6 +313,16 @@ interface PaperChatSidePanelProps {
     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
@@ -381,6 +391,16 @@ interface PaperChatFloatingChartOverlayProps {
     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`. */
@@ -582,6 +602,154 @@ 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;
 
+/**
+ * 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';
     content: string;
@@ -1517,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.1";
+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 & {});
@@ -1838,9 +2006,36 @@ interface PaperBoardProps {
     /** 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, 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;
 type BuildDashboardTourStepsOptions = {
@@ -1948,4 +2143,4 @@ declare function resolveChartFetchChatId(params: {
     dashboardId?: string;
 }): string | undefined;
 
-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 };
+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 };