@arbidocs/blocks 0.3.115 → 0.3.117

package/dist/index.d.cts

@@ -2,11 +2,11 @@ import { UseBoundStore, StoreApi } from 'zustand';
 import * as react from 'react';
 import react__default, { ReactNode } from 'react';
 import * as _arbidocs_react from '@arbidocs/react';
-import { AiRunOptions, useArbi, AiTaskStatus } from '@arbidocs/react';
+import { AiRunOptions, UserMenuItem, NotifyVariant, useArbi, AiTaskStatus } from '@arbidocs/react';
 export { AiRunOptions, AiTaskStatus, ArtifactEvent, SearchChunk, Table, TableBody, TableCell, TableHead, TableHeader, TableRow, redlineStats, textToArtifact, toRedlineMarkdown } from '@arbidocs/react';
 import { ColDef, GridOptions, GridApi, CellValueChangedEvent, GridState } from 'ag-grid-community';
 import { LucideIcon } from 'lucide-react';
-import { Data, Config, CustomField, Field, ComponentConfig } from '@measured/puck';
+import { CustomField, Field, ComponentConfig, Data, Config } from '@measured/puck';
 
 /**
  * The reusable AI-native law-firm prompt library.
@@ -296,6 +296,10 @@ type ConnectionStatus = 'demo' | 'disconnected' | 'connecting' | 'authenticated'
 interface ArbiUser {
     name: string;
     email: string;
+    /** The user's external_id (usr-…), when known (live sessions). */
+    externalId?: string;
+    /** Avatar image URL / data-URL from the backend profile, when set. */
+    picture?: string | null;
 }
 /** A retrieval-augmented answer step surfaced from the agent loop. */
 interface AssistantStep {
@@ -1082,6 +1086,64 @@ interface AppNavSection {
     items: AppNavItem[];
 }
 
+interface AppShellProps {
+    /** Nav sections to render (already filtered/ordered by the app). */
+    sections: AppNavSection[];
+    /** Footer nav items pinned to the bottom of the sidebar (e.g. Settings). */
+    footerItems?: AppNavItem[];
+    /** Brand mark shown in the sidebar header. */
+    logo?: ReactNode;
+    /** Where the logo links to (omit to render the logo without a link). */
+    logoHref?: string;
+    logoLabel?: string;
+    /** Extra content below the footer nav (e.g. a connection-status pill). */
+    sidebarFooter?: ReactNode;
+    /** Topbar content, rendered to the right of the mobile hamburger. */
+    topbar?: ReactNode;
+    /** Optional docked panel on the far right (e.g. an AI chat rail). */
+    rightRail?: ReactNode;
+    /** Main scroll region content (typically a router `<Outlet/>` wrapper). */
+    children: ReactNode;
+    /** Extra classes for the `<main>` scroll region (e.g. a slim-scrollbar util). */
+    mainClassName?: string;
+    /** Testid namespace for the shell/topbar/sidebar. Default "app". */
+    testIdPrefix?: string;
+}
+declare function AppShell({ sections, footerItems, logo, logoHref, logoLabel, sidebarFooter, topbar, rightRail, children, mainClassName, testIdPrefix, }: AppShellProps): react.JSX.Element;
+
+interface AppHeaderUser {
+    name: string;
+    email?: string | null;
+    picture?: string | null;
+}
+interface AppHeaderProps {
+    /** Open the command palette (⌘K). Bound to the search trigger. */
+    onSearch: () => void;
+    /** Open the palette in ask mode (defaults to `onSearch`). */
+    onAsk?: () => void;
+    searchPlaceholder?: string;
+    searchKbd?: string;
+    askLabel?: string;
+    /** Right-cluster content before the action buttons (e.g. a running-timer). */
+    leading?: ReactNode;
+    /** Extra icon buttons between Ask AI and the bell (e.g. a chat toggle). */
+    actions?: ReactNode;
+    user: AppHeaderUser;
+    /** Account actions above sign-out (e.g. Settings). */
+    userItems?: UserMenuItem[];
+    onLogout: () => void;
+    /** Called with a notification's href when an entry is clicked. */
+    onNotificationNavigate?: (href: string) => void;
+    /** Override per-variant notification glyph colours (e.g. brand accent). */
+    notificationTones?: Partial<Record<NotifyVariant, string>>;
+    classNames?: {
+        search?: string;
+        askButton?: string;
+    };
+    testIdPrefix?: string;
+}
+declare function AppHeader({ onSearch, onAsk, searchPlaceholder, searchKbd, askLabel, leading, actions, user, userItems, onLogout, onNotificationNavigate, notificationTones, classNames, testIdPrefix, }: AppHeaderProps): react.JSX.Element;
+
 /**
  * Shared studio types — the persistence contract, page metadata and the AI
  * prompt-builder signature the firm supplies. Firm-agnostic: a firm app wires
@@ -1129,6 +1191,95 @@ type BuildPrompt = (a: {
     current: string;
 }) => string;
 
+interface AiFieldsConfig {
+    /** The marketing workspace the AI grounds on. */
+    workspaceId: string;
+    /** Turns a field's kind/label/current text into an instruction. */
+    buildPrompt: BuildPrompt;
+    /** Default prompt kind when a field does not specify one. */
+    defaultKind?: string;
+    /** Testid namespace for the field + write button. */
+    testIdPrefix?: string;
+}
+interface AiFields {
+    aiText: (label: string, placeholder?: string) => CustomField<string>;
+    aiTextarea: (label: string, placeholder?: string, kind?: string) => CustomField<string>;
+}
+declare function createAiFields(cfg: AiFieldsConfig): AiFields;
+
+/**
+ * Shared field helpers for the block registry. Every block config — the built-ins
+ * in {@link createArbiBlocksConfig} and the website blocks in
+ * {@link file://./websiteBlocks.tsx} — builds its Puck fields from this one kit so
+ * the AI-or-plain copy fallback, the icon `select`, the tone/bool radios and the
+ * stable render-time testid are declared once.
+ */
+
+declare const iconMap: Record<string, LucideIcon>;
+/** The bundle of field helpers a block config needs. */
+interface BlockKit {
+    /** Single-line copy: AI-authorable when a firm supplies aiFields, else plain text. */
+    textField: (label: string, placeholder?: string) => Field;
+    /** Multi-line copy: AI-authorable when a firm supplies aiFields, else plain textarea. */
+    textareaField: (label: string, placeholder?: string, kind?: string) => Field;
+    /** Image source: a workspace-asset picker when a firm supplies imageField, else a URL input. */
+    imageField: (label: string) => Field;
+    /** A Yes/No radio. */
+    boolRadio: (label: string) => Field;
+    /** A `select` over {@link iconMap} names. */
+    iconField: (label?: string) => Field;
+    /** Resolve an icon name to its Lucide component. */
+    resolveIcon: (name?: string) => LucideIcon | undefined;
+    /** Stable, e2e-locatable testid derived from a block's Puck id. */
+    blockTestId: (id: string) => string;
+    /**
+     * Optional firm override for the eyebrow style on heading-bearing blocks
+     * (Hero, Section heading). Lets a consumer render a brand accent (e.g. a brass
+     * eyebrow) without forking the blocks. Undefined → the default token classes.
+     */
+    eyebrowClassName?: string;
+}
+/** Build the shared field helpers, closing over the firm's optional AI + image fields. */
+declare function createBlockKit(ai?: AiFields, image?: (label: string) => Field, eyebrowClassName?: string): BlockKit;
+
+/**
+ * Live-widget block factory for @arbidocs/blocks.
+ *
+ * Mirrors the other `create*Blocks` factories: it only WIRES pre-built block
+ * components (from {@link ./liveWidgetRuntime}) into Puck `ComponentConfig`s, so
+ * it exports a single function and defines no components of its own — keeping it
+ * fast-refresh clean. The blocks gate on the live-data flag ({@link ./liveData}),
+ * rendering real ARBI data inside an authenticated app tree and a placeholder in
+ * the editor/public. They read the SHARED `@arbidocs/react` hooks, so any client
+ * with an ARBI workspace gets them; a client supplies only *composition* via
+ * `createArbiBlocksConfig({ liveWidgets: true })`.
+ */
+
+/**
+ * Build the live-widget block set, closing over the shared {@link BlockKit} for
+ * stable testids. Registered under a "Widgets" category when a consumer opts in
+ * with `createArbiBlocksConfig({ liveWidgets: true })`.
+ */
+declare function createLiveWidgets(kit: BlockKit): Record<string, ComponentConfig>;
+
+/** Marks the subtree as an authenticated app tree, so live widgets resolve data. */
+declare function LiveDataProvider({ children }: {
+    children: ReactNode;
+}): react.JSX.Element;
+/**
+ * What a live widget shows when it can't (or shouldn't) resolve data: a labelled,
+ * dashed card. Used in the Studio canvas and the public renderer so authoring a
+ * dashboard is WYSIWYG-ish without leaking live back-office data.
+ */
+declare function WidgetPlaceholder({ label, icon: Icon, testId, }: {
+    label: string;
+    icon?: LucideIcon;
+    testId?: string;
+}): react.JSX.Element;
+
+/** Whether live widgets may resolve backend data here (false in editor/public). */
+declare function useLiveDataActive(): boolean;
+
 /**
  * Publish-time asset materialization.
  *
@@ -1207,8 +1358,27 @@ interface PageRendererProps {
         body: string;
     };
     testIdPrefix?: string;
+    /**
+     * Render inside a {@link LiveDataProvider}, so live-widget blocks resolve real
+     * ARBI data. Only pass this when mounting the renderer INSIDE the authenticated
+     * app tree (providers + a selected workspace present); on the public site leave
+     * it off and widgets render placeholders.
+     */
+    liveData?: boolean;
+    /**
+     * Render this page verbatim instead of loading a slug from persistence — for an
+     * in-code page (e.g. a config-authored in-app board) that isn't a published
+     * studio document. The slug is ignored.
+     */
+    initialData?: Data;
+    /**
+     * Apply the persisted studio theme to the document (default true). Turn OFF for
+     * an in-app renderer so it keeps the ambient app theme instead of repainting the
+     * whole document with the marketing palette.
+     */
+    applyTheme?: boolean;
 }
-declare function PageRenderer({ config, persistence, defaultTheme, live, slug: slugProp, emptyState, testIdPrefix, }: PageRendererProps): react.JSX.Element;
+declare function PageRenderer({ config, persistence, defaultTheme, live, slug: slugProp, emptyState, testIdPrefix, liveData, initialData, applyTheme, }: PageRendererProps): react.JSX.Element;
 
 interface StudioPersistenceConfig {
     /** The public marketing workspace that backs the site builder. */
@@ -1228,22 +1398,6 @@ interface StudioPersistenceConfig {
 }
 declare function createStudioPersistence(cfg: StudioPersistenceConfig): StudioPersistence;
 
-interface AiFieldsConfig {
-    /** The marketing workspace the AI grounds on. */
-    workspaceId: string;
-    /** Turns a field's kind/label/current text into an instruction. */
-    buildPrompt: BuildPrompt;
-    /** Default prompt kind when a field does not specify one. */
-    defaultKind?: string;
-    /** Testid namespace for the field + write button. */
-    testIdPrefix?: string;
-}
-interface AiFields {
-    aiText: (label: string, placeholder?: string) => CustomField<string>;
-    aiTextarea: (label: string, placeholder?: string, kind?: string) => CustomField<string>;
-}
-declare function createAiFields(cfg: AiFieldsConfig): AiFields;
-
 interface ImageFieldConfig {
     /** The workspace uploads/generations are saved to, and assets are picked from. */
     workspaceId: string;
@@ -1307,41 +1461,6 @@ interface SectionProps {
 }
 declare function Section({ children, tone, padding, maxWidth, texture, className, }: SectionProps): react.JSX.Element;
 
-/**
- * Shared field helpers for the block registry. Every block config — the built-ins
- * in {@link createArbiBlocksConfig} and the website blocks in
- * {@link file://./websiteBlocks.tsx} — builds its Puck fields from this one kit so
- * the AI-or-plain copy fallback, the icon `select`, the tone/bool radios and the
- * stable render-time testid are declared once.
- */
-
-declare const iconMap: Record<string, LucideIcon>;
-/** The bundle of field helpers a block config needs. */
-interface BlockKit {
-    /** Single-line copy: AI-authorable when a firm supplies aiFields, else plain text. */
-    textField: (label: string, placeholder?: string) => Field;
-    /** Multi-line copy: AI-authorable when a firm supplies aiFields, else plain textarea. */
-    textareaField: (label: string, placeholder?: string, kind?: string) => Field;
-    /** Image source: a workspace-asset picker when a firm supplies imageField, else a URL input. */
-    imageField: (label: string) => Field;
-    /** A Yes/No radio. */
-    boolRadio: (label: string) => Field;
-    /** A `select` over {@link iconMap} names. */
-    iconField: (label?: string) => Field;
-    /** Resolve an icon name to its Lucide component. */
-    resolveIcon: (name?: string) => LucideIcon | undefined;
-    /** Stable, e2e-locatable testid derived from a block's Puck id. */
-    blockTestId: (id: string) => string;
-    /**
-     * Optional firm override for the eyebrow style on heading-bearing blocks
-     * (Hero, Section heading). Lets a consumer render a brand accent (e.g. a brass
-     * eyebrow) without forking the blocks. Undefined → the default token classes.
-     */
-    eyebrowClassName?: string;
-}
-/** Build the shared field helpers, closing over the firm's optional AI + image fields. */
-declare function createBlockKit(ai?: AiFields, image?: (label: string) => Field, eyebrowClassName?: string): BlockKit;
-
 interface ArbiBlocksConfigOptions {
     /**
      * Firm AI fields from {@link createAiFields}. When present, every string copy
@@ -1370,6 +1489,14 @@ interface ArbiBlocksConfigOptions {
      * heading) — e.g. a brand accent like a brass eyebrow. Undefined → token default.
      */
     eyebrowClassName?: string;
+    /**
+     * Register the live-widget blocks (a "Widgets" category) that read shared ARBI
+     * hooks — Agent activity, Live metric. They render placeholders in the editor
+     * and on the public site, resolving real data only inside an authenticated
+     * in-app renderer (`PageRenderer liveData`). Opt-in so a pure marketing builder
+     * doesn't surface back-office widgets.
+     */
+    liveWidgets?: boolean;
 }
 
 declare function createArbiBlocksConfig(opts?: ArbiBlocksConfigOptions): Config;
@@ -1563,4 +1690,4 @@ interface AgentsPanelProps {
 }
 declare function AgentsPanel({ store, testIdPrefix }: AgentsPanelProps): react.JSX.Element;
 
-export { ASSET_REF_PREFIX, Accordion, type AccordionItem, type AccordionProps, type AgentSelectionStore, AgentsPanel, type AgentsPanelProps, type AiFields, type AiFieldsConfig, type AppNavItem, type AppNavSection, type ApplyThemeOptions, type ArbiBlocksConfigOptions, type ArbiMode, type ArbiUser, type AssetMaterializer, AssetResolverProvider, type AssistantCitation, type AssistantMessage, type AssistantStep, AvatarBlock, type AvatarBlockProps, Banner, type BannerProps, type BannerTone, BlockImage, type BlockImageProps, type BlockKit, type BuildPrompt, type BuilderModule, CTABanner, type CTABannerProps, Callout, type CalloutProps, type CalloutVariant, type ColorToken, type Column, Columns, type ColumnsProps, ConnectionProvider, type ConnectionStatus, type ContactField, ContactForm, type ContactFormProps, Container, type ContainerProps, DataTable, DataTableBlock, type DataTableBlockColumn, type DataTableBlockProps, EmptyState, type ExportedModule, FAQ, type FAQProps, type FaqItem, FeatureGrid, type FeatureGridProps, type FeatureItem, type FirmArbiConfig, Footer, type FooterColumn, type FooterLink, type FooterProps, Gallery, type GalleryImage, type GalleryProps, GridView, type GridViewEmptyState, type GridViewProps, type GridViewSelection, Hero, type HeroCta, type HeroProps, type ImageFieldConfig, type ImageFieldFactory, LegalArbiProvider, ListBlock, type ListBlockProps, type ListItem, type LoadResult, LogoCloud, type LogoCloudProps, type LogoItem, type MaterializeOptions, type MatterContext, MediaText, type MediaTextProps, MetricCard, type MetricCardProps, ModuleManager, type ModuleManagerProps, type ModuleRegistry, type ModuleStoreBundle, type NavLink, Navbar, type NavbarProps, PageHeader, PageRenderer, type PageRendererProps, type PersistVia, type PricingPlan, PricingTable, type PricingTableProps, type PromptConfig, type PromptLibrary, type Prompts, type ResolvedModule, RichTextBlock, type RichTextBlockProps, Section, SectionHeading, type SectionProps, Spacer, type SpacerProps, StatGroup, type StatGroupProps, type StatItem, type StepItem, Steps, type StepsProps, StudioEditor, type StudioEditorProps, type StudioPageMeta, type StudioPersistence, type StudioPersistenceConfig, THEME_STYLE_ID, type TabItem, Tabs, type TabsProps, TeamGrid, type TeamGridProps, type TeamMember, Testimonial, TestimonialGrid, type TestimonialGridProps, type TestimonialItem, type TestimonialProps, type ThemeBundle, ThemeEditor, type ThemeEditorProps, type ThemeEmitMode, type ThemeFonts, type ThemePreset, type ThemeState, type ThemeStoreConfig, type ThemeTokens, Toolbar, type UseImageGen, VerticalBuilder, type VerticalBuilderProps, type VerticalConfig, type VerticalExport, type VerticalExportConfig, type VideoAspect, VideoEmbed, type VideoEmbedProps, applyStoredTheme, applyThemeVars, asAssetRef, assetRefId, clearThemeVars, createAgentSelectionStore, createAiFields, createArbiBlocksConfig, createArbiMaterializer, createBlockKit, createImageField, createModuleRegistry, createModuleStore, createPromptLibrary, createSiteBlocks, createStudioPersistence, createThemeStore, createVerticalExport, createWebsiteBlocks, daysUntil, fmtDate, fmtDateTime, fromNow, gbp, hrs, iconMap, initials, isAssetRef, isAuthenticated, materializePageData, matterToContext, pct, tid, toEmbedUrl, toHslTriplet, useAssetResolverActive, useConnection, useFirmAiTask, useImageGen, useSemanticSearch, useWorkspaceDocs };
+export { ASSET_REF_PREFIX, Accordion, type AccordionItem, type AccordionProps, type AgentSelectionStore, AgentsPanel, type AgentsPanelProps, type AiFields, type AiFieldsConfig, AppHeader, type AppHeaderProps, type AppHeaderUser, type AppNavItem, type AppNavSection, AppShell, type AppShellProps, type ApplyThemeOptions, type ArbiBlocksConfigOptions, type ArbiMode, type ArbiUser, type AssetMaterializer, AssetResolverProvider, type AssistantCitation, type AssistantMessage, type AssistantStep, AvatarBlock, type AvatarBlockProps, Banner, type BannerProps, type BannerTone, BlockImage, type BlockImageProps, type BlockKit, type BuildPrompt, type BuilderModule, CTABanner, type CTABannerProps, Callout, type CalloutProps, type CalloutVariant, type ColorToken, type Column, Columns, type ColumnsProps, ConnectionProvider, type ConnectionStatus, type ContactField, ContactForm, type ContactFormProps, Container, type ContainerProps, DataTable, DataTableBlock, type DataTableBlockColumn, type DataTableBlockProps, EmptyState, type ExportedModule, FAQ, type FAQProps, type FaqItem, FeatureGrid, type FeatureGridProps, type FeatureItem, type FirmArbiConfig, Footer, type FooterColumn, type FooterLink, type FooterProps, Gallery, type GalleryImage, type GalleryProps, GridView, type GridViewEmptyState, type GridViewProps, type GridViewSelection, Hero, type HeroCta, type HeroProps, type ImageFieldConfig, type ImageFieldFactory, LegalArbiProvider, ListBlock, type ListBlockProps, type ListItem, LiveDataProvider, type LoadResult, LogoCloud, type LogoCloudProps, type LogoItem, type MaterializeOptions, type MatterContext, MediaText, type MediaTextProps, MetricCard, type MetricCardProps, ModuleManager, type ModuleManagerProps, type ModuleRegistry, type ModuleStoreBundle, type NavLink, Navbar, type NavbarProps, PageHeader, PageRenderer, type PageRendererProps, type PersistVia, type PricingPlan, PricingTable, type PricingTableProps, type PromptConfig, type PromptLibrary, type Prompts, type ResolvedModule, RichTextBlock, type RichTextBlockProps, Section, SectionHeading, type SectionProps, Spacer, type SpacerProps, StatGroup, type StatGroupProps, type StatItem, type StepItem, Steps, type StepsProps, StudioEditor, type StudioEditorProps, type StudioPageMeta, type StudioPersistence, type StudioPersistenceConfig, THEME_STYLE_ID, type TabItem, Tabs, type TabsProps, TeamGrid, type TeamGridProps, type TeamMember, Testimonial, TestimonialGrid, type TestimonialGridProps, type TestimonialItem, type TestimonialProps, type ThemeBundle, ThemeEditor, type ThemeEditorProps, type ThemeEmitMode, type ThemeFonts, type ThemePreset, type ThemeState, type ThemeStoreConfig, type ThemeTokens, Toolbar, type UseImageGen, VerticalBuilder, type VerticalBuilderProps, type VerticalConfig, type VerticalExport, type VerticalExportConfig, type VideoAspect, VideoEmbed, type VideoEmbedProps, WidgetPlaceholder, applyStoredTheme, applyThemeVars, asAssetRef, assetRefId, clearThemeVars, createAgentSelectionStore, createAiFields, createArbiBlocksConfig, createArbiMaterializer, createBlockKit, createImageField, createLiveWidgets, createModuleRegistry, createModuleStore, createPromptLibrary, createSiteBlocks, createStudioPersistence, createThemeStore, createVerticalExport, createWebsiteBlocks, daysUntil, fmtDate, fmtDateTime, fromNow, gbp, hrs, iconMap, initials, isAssetRef, isAuthenticated, materializePageData, matterToContext, pct, tid, toEmbedUrl, toHslTriplet, useAssetResolverActive, useConnection, useFirmAiTask, useImageGen, useLiveDataActive, useSemanticSearch, useWorkspaceDocs };

package/dist/index.d.ts

@@ -2,11 +2,11 @@ import { UseBoundStore, StoreApi } from 'zustand';
 import * as react from 'react';
 import react__default, { ReactNode } from 'react';
 import * as _arbidocs_react from '@arbidocs/react';
-import { AiRunOptions, useArbi, AiTaskStatus } from '@arbidocs/react';
+import { AiRunOptions, UserMenuItem, NotifyVariant, useArbi, AiTaskStatus } from '@arbidocs/react';
 export { AiRunOptions, AiTaskStatus, ArtifactEvent, SearchChunk, Table, TableBody, TableCell, TableHead, TableHeader, TableRow, redlineStats, textToArtifact, toRedlineMarkdown } from '@arbidocs/react';
 import { ColDef, GridOptions, GridApi, CellValueChangedEvent, GridState } from 'ag-grid-community';
 import { LucideIcon } from 'lucide-react';
-import { Data, Config, CustomField, Field, ComponentConfig } from '@measured/puck';
+import { CustomField, Field, ComponentConfig, Data, Config } from '@measured/puck';
 
 /**
  * The reusable AI-native law-firm prompt library.
@@ -296,6 +296,10 @@ type ConnectionStatus = 'demo' | 'disconnected' | 'connecting' | 'authenticated'
 interface ArbiUser {
     name: string;
     email: string;
+    /** The user's external_id (usr-…), when known (live sessions). */
+    externalId?: string;
+    /** Avatar image URL / data-URL from the backend profile, when set. */
+    picture?: string | null;
 }
 /** A retrieval-augmented answer step surfaced from the agent loop. */
 interface AssistantStep {
@@ -1082,6 +1086,64 @@ interface AppNavSection {
     items: AppNavItem[];
 }
 
+interface AppShellProps {
+    /** Nav sections to render (already filtered/ordered by the app). */
+    sections: AppNavSection[];
+    /** Footer nav items pinned to the bottom of the sidebar (e.g. Settings). */
+    footerItems?: AppNavItem[];
+    /** Brand mark shown in the sidebar header. */
+    logo?: ReactNode;
+    /** Where the logo links to (omit to render the logo without a link). */
+    logoHref?: string;
+    logoLabel?: string;
+    /** Extra content below the footer nav (e.g. a connection-status pill). */
+    sidebarFooter?: ReactNode;
+    /** Topbar content, rendered to the right of the mobile hamburger. */
+    topbar?: ReactNode;
+    /** Optional docked panel on the far right (e.g. an AI chat rail). */
+    rightRail?: ReactNode;
+    /** Main scroll region content (typically a router `<Outlet/>` wrapper). */
+    children: ReactNode;
+    /** Extra classes for the `<main>` scroll region (e.g. a slim-scrollbar util). */
+    mainClassName?: string;
+    /** Testid namespace for the shell/topbar/sidebar. Default "app". */
+    testIdPrefix?: string;
+}
+declare function AppShell({ sections, footerItems, logo, logoHref, logoLabel, sidebarFooter, topbar, rightRail, children, mainClassName, testIdPrefix, }: AppShellProps): react.JSX.Element;
+
+interface AppHeaderUser {
+    name: string;
+    email?: string | null;
+    picture?: string | null;
+}
+interface AppHeaderProps {
+    /** Open the command palette (⌘K). Bound to the search trigger. */
+    onSearch: () => void;
+    /** Open the palette in ask mode (defaults to `onSearch`). */
+    onAsk?: () => void;
+    searchPlaceholder?: string;
+    searchKbd?: string;
+    askLabel?: string;
+    /** Right-cluster content before the action buttons (e.g. a running-timer). */
+    leading?: ReactNode;
+    /** Extra icon buttons between Ask AI and the bell (e.g. a chat toggle). */
+    actions?: ReactNode;
+    user: AppHeaderUser;
+    /** Account actions above sign-out (e.g. Settings). */
+    userItems?: UserMenuItem[];
+    onLogout: () => void;
+    /** Called with a notification's href when an entry is clicked. */
+    onNotificationNavigate?: (href: string) => void;
+    /** Override per-variant notification glyph colours (e.g. brand accent). */
+    notificationTones?: Partial<Record<NotifyVariant, string>>;
+    classNames?: {
+        search?: string;
+        askButton?: string;
+    };
+    testIdPrefix?: string;
+}
+declare function AppHeader({ onSearch, onAsk, searchPlaceholder, searchKbd, askLabel, leading, actions, user, userItems, onLogout, onNotificationNavigate, notificationTones, classNames, testIdPrefix, }: AppHeaderProps): react.JSX.Element;
+
 /**
  * Shared studio types — the persistence contract, page metadata and the AI
  * prompt-builder signature the firm supplies. Firm-agnostic: a firm app wires
@@ -1129,6 +1191,95 @@ type BuildPrompt = (a: {
     current: string;
 }) => string;
 
+interface AiFieldsConfig {
+    /** The marketing workspace the AI grounds on. */
+    workspaceId: string;
+    /** Turns a field's kind/label/current text into an instruction. */
+    buildPrompt: BuildPrompt;
+    /** Default prompt kind when a field does not specify one. */
+    defaultKind?: string;
+    /** Testid namespace for the field + write button. */
+    testIdPrefix?: string;
+}
+interface AiFields {
+    aiText: (label: string, placeholder?: string) => CustomField<string>;
+    aiTextarea: (label: string, placeholder?: string, kind?: string) => CustomField<string>;
+}
+declare function createAiFields(cfg: AiFieldsConfig): AiFields;
+
+/**
+ * Shared field helpers for the block registry. Every block config — the built-ins
+ * in {@link createArbiBlocksConfig} and the website blocks in
+ * {@link file://./websiteBlocks.tsx} — builds its Puck fields from this one kit so
+ * the AI-or-plain copy fallback, the icon `select`, the tone/bool radios and the
+ * stable render-time testid are declared once.
+ */
+
+declare const iconMap: Record<string, LucideIcon>;
+/** The bundle of field helpers a block config needs. */
+interface BlockKit {
+    /** Single-line copy: AI-authorable when a firm supplies aiFields, else plain text. */
+    textField: (label: string, placeholder?: string) => Field;
+    /** Multi-line copy: AI-authorable when a firm supplies aiFields, else plain textarea. */
+    textareaField: (label: string, placeholder?: string, kind?: string) => Field;
+    /** Image source: a workspace-asset picker when a firm supplies imageField, else a URL input. */
+    imageField: (label: string) => Field;
+    /** A Yes/No radio. */
+    boolRadio: (label: string) => Field;
+    /** A `select` over {@link iconMap} names. */
+    iconField: (label?: string) => Field;
+    /** Resolve an icon name to its Lucide component. */
+    resolveIcon: (name?: string) => LucideIcon | undefined;
+    /** Stable, e2e-locatable testid derived from a block's Puck id. */
+    blockTestId: (id: string) => string;
+    /**
+     * Optional firm override for the eyebrow style on heading-bearing blocks
+     * (Hero, Section heading). Lets a consumer render a brand accent (e.g. a brass
+     * eyebrow) without forking the blocks. Undefined → the default token classes.
+     */
+    eyebrowClassName?: string;
+}
+/** Build the shared field helpers, closing over the firm's optional AI + image fields. */
+declare function createBlockKit(ai?: AiFields, image?: (label: string) => Field, eyebrowClassName?: string): BlockKit;
+
+/**
+ * Live-widget block factory for @arbidocs/blocks.
+ *
+ * Mirrors the other `create*Blocks` factories: it only WIRES pre-built block
+ * components (from {@link ./liveWidgetRuntime}) into Puck `ComponentConfig`s, so
+ * it exports a single function and defines no components of its own — keeping it
+ * fast-refresh clean. The blocks gate on the live-data flag ({@link ./liveData}),
+ * rendering real ARBI data inside an authenticated app tree and a placeholder in
+ * the editor/public. They read the SHARED `@arbidocs/react` hooks, so any client
+ * with an ARBI workspace gets them; a client supplies only *composition* via
+ * `createArbiBlocksConfig({ liveWidgets: true })`.
+ */
+
+/**
+ * Build the live-widget block set, closing over the shared {@link BlockKit} for
+ * stable testids. Registered under a "Widgets" category when a consumer opts in
+ * with `createArbiBlocksConfig({ liveWidgets: true })`.
+ */
+declare function createLiveWidgets(kit: BlockKit): Record<string, ComponentConfig>;
+
+/** Marks the subtree as an authenticated app tree, so live widgets resolve data. */
+declare function LiveDataProvider({ children }: {
+    children: ReactNode;
+}): react.JSX.Element;
+/**
+ * What a live widget shows when it can't (or shouldn't) resolve data: a labelled,
+ * dashed card. Used in the Studio canvas and the public renderer so authoring a
+ * dashboard is WYSIWYG-ish without leaking live back-office data.
+ */
+declare function WidgetPlaceholder({ label, icon: Icon, testId, }: {
+    label: string;
+    icon?: LucideIcon;
+    testId?: string;
+}): react.JSX.Element;
+
+/** Whether live widgets may resolve backend data here (false in editor/public). */
+declare function useLiveDataActive(): boolean;
+
 /**
  * Publish-time asset materialization.
  *
@@ -1207,8 +1358,27 @@ interface PageRendererProps {
         body: string;
     };
     testIdPrefix?: string;
+    /**
+     * Render inside a {@link LiveDataProvider}, so live-widget blocks resolve real
+     * ARBI data. Only pass this when mounting the renderer INSIDE the authenticated
+     * app tree (providers + a selected workspace present); on the public site leave
+     * it off and widgets render placeholders.
+     */
+    liveData?: boolean;
+    /**
+     * Render this page verbatim instead of loading a slug from persistence — for an
+     * in-code page (e.g. a config-authored in-app board) that isn't a published
+     * studio document. The slug is ignored.
+     */
+    initialData?: Data;
+    /**
+     * Apply the persisted studio theme to the document (default true). Turn OFF for
+     * an in-app renderer so it keeps the ambient app theme instead of repainting the
+     * whole document with the marketing palette.
+     */
+    applyTheme?: boolean;
 }
-declare function PageRenderer({ config, persistence, defaultTheme, live, slug: slugProp, emptyState, testIdPrefix, }: PageRendererProps): react.JSX.Element;
+declare function PageRenderer({ config, persistence, defaultTheme, live, slug: slugProp, emptyState, testIdPrefix, liveData, initialData, applyTheme, }: PageRendererProps): react.JSX.Element;
 
 interface StudioPersistenceConfig {
     /** The public marketing workspace that backs the site builder. */
@@ -1228,22 +1398,6 @@ interface StudioPersistenceConfig {
 }
 declare function createStudioPersistence(cfg: StudioPersistenceConfig): StudioPersistence;
 
-interface AiFieldsConfig {
-    /** The marketing workspace the AI grounds on. */
-    workspaceId: string;
-    /** Turns a field's kind/label/current text into an instruction. */
-    buildPrompt: BuildPrompt;
-    /** Default prompt kind when a field does not specify one. */
-    defaultKind?: string;
-    /** Testid namespace for the field + write button. */
-    testIdPrefix?: string;
-}
-interface AiFields {
-    aiText: (label: string, placeholder?: string) => CustomField<string>;
-    aiTextarea: (label: string, placeholder?: string, kind?: string) => CustomField<string>;
-}
-declare function createAiFields(cfg: AiFieldsConfig): AiFields;
-
 interface ImageFieldConfig {
     /** The workspace uploads/generations are saved to, and assets are picked from. */
     workspaceId: string;
@@ -1307,41 +1461,6 @@ interface SectionProps {
 }
 declare function Section({ children, tone, padding, maxWidth, texture, className, }: SectionProps): react.JSX.Element;
 
-/**
- * Shared field helpers for the block registry. Every block config — the built-ins
- * in {@link createArbiBlocksConfig} and the website blocks in
- * {@link file://./websiteBlocks.tsx} — builds its Puck fields from this one kit so
- * the AI-or-plain copy fallback, the icon `select`, the tone/bool radios and the
- * stable render-time testid are declared once.
- */
-
-declare const iconMap: Record<string, LucideIcon>;
-/** The bundle of field helpers a block config needs. */
-interface BlockKit {
-    /** Single-line copy: AI-authorable when a firm supplies aiFields, else plain text. */
-    textField: (label: string, placeholder?: string) => Field;
-    /** Multi-line copy: AI-authorable when a firm supplies aiFields, else plain textarea. */
-    textareaField: (label: string, placeholder?: string, kind?: string) => Field;
-    /** Image source: a workspace-asset picker when a firm supplies imageField, else a URL input. */
-    imageField: (label: string) => Field;
-    /** A Yes/No radio. */
-    boolRadio: (label: string) => Field;
-    /** A `select` over {@link iconMap} names. */
-    iconField: (label?: string) => Field;
-    /** Resolve an icon name to its Lucide component. */
-    resolveIcon: (name?: string) => LucideIcon | undefined;
-    /** Stable, e2e-locatable testid derived from a block's Puck id. */
-    blockTestId: (id: string) => string;
-    /**
-     * Optional firm override for the eyebrow style on heading-bearing blocks
-     * (Hero, Section heading). Lets a consumer render a brand accent (e.g. a brass
-     * eyebrow) without forking the blocks. Undefined → the default token classes.
-     */
-    eyebrowClassName?: string;
-}
-/** Build the shared field helpers, closing over the firm's optional AI + image fields. */
-declare function createBlockKit(ai?: AiFields, image?: (label: string) => Field, eyebrowClassName?: string): BlockKit;
-
 interface ArbiBlocksConfigOptions {
     /**
      * Firm AI fields from {@link createAiFields}. When present, every string copy
@@ -1370,6 +1489,14 @@ interface ArbiBlocksConfigOptions {
      * heading) — e.g. a brand accent like a brass eyebrow. Undefined → token default.
      */
     eyebrowClassName?: string;
+    /**
+     * Register the live-widget blocks (a "Widgets" category) that read shared ARBI
+     * hooks — Agent activity, Live metric. They render placeholders in the editor
+     * and on the public site, resolving real data only inside an authenticated
+     * in-app renderer (`PageRenderer liveData`). Opt-in so a pure marketing builder
+     * doesn't surface back-office widgets.
+     */
+    liveWidgets?: boolean;
 }
 
 declare function createArbiBlocksConfig(opts?: ArbiBlocksConfigOptions): Config;
@@ -1563,4 +1690,4 @@ interface AgentsPanelProps {
 }
 declare function AgentsPanel({ store, testIdPrefix }: AgentsPanelProps): react.JSX.Element;
 
-export { ASSET_REF_PREFIX, Accordion, type AccordionItem, type AccordionProps, type AgentSelectionStore, AgentsPanel, type AgentsPanelProps, type AiFields, type AiFieldsConfig, type AppNavItem, type AppNavSection, type ApplyThemeOptions, type ArbiBlocksConfigOptions, type ArbiMode, type ArbiUser, type AssetMaterializer, AssetResolverProvider, type AssistantCitation, type AssistantMessage, type AssistantStep, AvatarBlock, type AvatarBlockProps, Banner, type BannerProps, type BannerTone, BlockImage, type BlockImageProps, type BlockKit, type BuildPrompt, type BuilderModule, CTABanner, type CTABannerProps, Callout, type CalloutProps, type CalloutVariant, type ColorToken, type Column, Columns, type ColumnsProps, ConnectionProvider, type ConnectionStatus, type ContactField, ContactForm, type ContactFormProps, Container, type ContainerProps, DataTable, DataTableBlock, type DataTableBlockColumn, type DataTableBlockProps, EmptyState, type ExportedModule, FAQ, type FAQProps, type FaqItem, FeatureGrid, type FeatureGridProps, type FeatureItem, type FirmArbiConfig, Footer, type FooterColumn, type FooterLink, type FooterProps, Gallery, type GalleryImage, type GalleryProps, GridView, type GridViewEmptyState, type GridViewProps, type GridViewSelection, Hero, type HeroCta, type HeroProps, type ImageFieldConfig, type ImageFieldFactory, LegalArbiProvider, ListBlock, type ListBlockProps, type ListItem, type LoadResult, LogoCloud, type LogoCloudProps, type LogoItem, type MaterializeOptions, type MatterContext, MediaText, type MediaTextProps, MetricCard, type MetricCardProps, ModuleManager, type ModuleManagerProps, type ModuleRegistry, type ModuleStoreBundle, type NavLink, Navbar, type NavbarProps, PageHeader, PageRenderer, type PageRendererProps, type PersistVia, type PricingPlan, PricingTable, type PricingTableProps, type PromptConfig, type PromptLibrary, type Prompts, type ResolvedModule, RichTextBlock, type RichTextBlockProps, Section, SectionHeading, type SectionProps, Spacer, type SpacerProps, StatGroup, type StatGroupProps, type StatItem, type StepItem, Steps, type StepsProps, StudioEditor, type StudioEditorProps, type StudioPageMeta, type StudioPersistence, type StudioPersistenceConfig, THEME_STYLE_ID, type TabItem, Tabs, type TabsProps, TeamGrid, type TeamGridProps, type TeamMember, Testimonial, TestimonialGrid, type TestimonialGridProps, type TestimonialItem, type TestimonialProps, type ThemeBundle, ThemeEditor, type ThemeEditorProps, type ThemeEmitMode, type ThemeFonts, type ThemePreset, type ThemeState, type ThemeStoreConfig, type ThemeTokens, Toolbar, type UseImageGen, VerticalBuilder, type VerticalBuilderProps, type VerticalConfig, type VerticalExport, type VerticalExportConfig, type VideoAspect, VideoEmbed, type VideoEmbedProps, applyStoredTheme, applyThemeVars, asAssetRef, assetRefId, clearThemeVars, createAgentSelectionStore, createAiFields, createArbiBlocksConfig, createArbiMaterializer, createBlockKit, createImageField, createModuleRegistry, createModuleStore, createPromptLibrary, createSiteBlocks, createStudioPersistence, createThemeStore, createVerticalExport, createWebsiteBlocks, daysUntil, fmtDate, fmtDateTime, fromNow, gbp, hrs, iconMap, initials, isAssetRef, isAuthenticated, materializePageData, matterToContext, pct, tid, toEmbedUrl, toHslTriplet, useAssetResolverActive, useConnection, useFirmAiTask, useImageGen, useSemanticSearch, useWorkspaceDocs };
+export { ASSET_REF_PREFIX, Accordion, type AccordionItem, type AccordionProps, type AgentSelectionStore, AgentsPanel, type AgentsPanelProps, type AiFields, type AiFieldsConfig, AppHeader, type AppHeaderProps, type AppHeaderUser, type AppNavItem, type AppNavSection, AppShell, type AppShellProps, type ApplyThemeOptions, type ArbiBlocksConfigOptions, type ArbiMode, type ArbiUser, type AssetMaterializer, AssetResolverProvider, type AssistantCitation, type AssistantMessage, type AssistantStep, AvatarBlock, type AvatarBlockProps, Banner, type BannerProps, type BannerTone, BlockImage, type BlockImageProps, type BlockKit, type BuildPrompt, type BuilderModule, CTABanner, type CTABannerProps, Callout, type CalloutProps, type CalloutVariant, type ColorToken, type Column, Columns, type ColumnsProps, ConnectionProvider, type ConnectionStatus, type ContactField, ContactForm, type ContactFormProps, Container, type ContainerProps, DataTable, DataTableBlock, type DataTableBlockColumn, type DataTableBlockProps, EmptyState, type ExportedModule, FAQ, type FAQProps, type FaqItem, FeatureGrid, type FeatureGridProps, type FeatureItem, type FirmArbiConfig, Footer, type FooterColumn, type FooterLink, type FooterProps, Gallery, type GalleryImage, type GalleryProps, GridView, type GridViewEmptyState, type GridViewProps, type GridViewSelection, Hero, type HeroCta, type HeroProps, type ImageFieldConfig, type ImageFieldFactory, LegalArbiProvider, ListBlock, type ListBlockProps, type ListItem, LiveDataProvider, type LoadResult, LogoCloud, type LogoCloudProps, type LogoItem, type MaterializeOptions, type MatterContext, MediaText, type MediaTextProps, MetricCard, type MetricCardProps, ModuleManager, type ModuleManagerProps, type ModuleRegistry, type ModuleStoreBundle, type NavLink, Navbar, type NavbarProps, PageHeader, PageRenderer, type PageRendererProps, type PersistVia, type PricingPlan, PricingTable, type PricingTableProps, type PromptConfig, type PromptLibrary, type Prompts, type ResolvedModule, RichTextBlock, type RichTextBlockProps, Section, SectionHeading, type SectionProps, Spacer, type SpacerProps, StatGroup, type StatGroupProps, type StatItem, type StepItem, Steps, type StepsProps, StudioEditor, type StudioEditorProps, type StudioPageMeta, type StudioPersistence, type StudioPersistenceConfig, THEME_STYLE_ID, type TabItem, Tabs, type TabsProps, TeamGrid, type TeamGridProps, type TeamMember, Testimonial, TestimonialGrid, type TestimonialGridProps, type TestimonialItem, type TestimonialProps, type ThemeBundle, ThemeEditor, type ThemeEditorProps, type ThemeEmitMode, type ThemeFonts, type ThemePreset, type ThemeState, type ThemeStoreConfig, type ThemeTokens, Toolbar, type UseImageGen, VerticalBuilder, type VerticalBuilderProps, type VerticalConfig, type VerticalExport, type VerticalExportConfig, type VideoAspect, VideoEmbed, type VideoEmbedProps, WidgetPlaceholder, applyStoredTheme, applyThemeVars, asAssetRef, assetRefId, clearThemeVars, createAgentSelectionStore, createAiFields, createArbiBlocksConfig, createArbiMaterializer, createBlockKit, createImageField, createLiveWidgets, createModuleRegistry, createModuleStore, createPromptLibrary, createSiteBlocks, createStudioPersistence, createThemeStore, createVerticalExport, createWebsiteBlocks, daysUntil, fmtDate, fmtDateTime, fromNow, gbp, hrs, iconMap, initials, isAssetRef, isAuthenticated, materializePageData, matterToContext, pct, tid, toEmbedUrl, toHslTriplet, useAssetResolverActive, useConnection, useFirmAiTask, useImageGen, useLiveDataActive, useSemanticSearch, useWorkspaceDocs };