@chrisflippen/blueprint-document-assembly 3.1.0 → 3.3.0

package/README.md

@@ -27,37 +27,40 @@ npm install @chrisflippen/blueprint-document-assembly motion lucide-react
 
 ## Styling Requirements
 
-This component requires **Tailwind CSS v4**. Your theme should include these CSS variables:
+This component uses **CSS Custom Properties** for all theme colors. It works with **Tailwind CSS v4** but does not require it — any CSS framework or plain CSS is fine.
+
+If your host app defines these CSS variables, the component will inherit them automatically:
 
 ```css
-@theme {
-  --color-background: #ffffff;
-  --color-foreground: #0a0a0a;
-  --color-muted: #f4f4f5;
-  --color-muted-foreground: #71717a;
-  --color-border: #e4e4e7;
+:root {
+  --background: #ffffff;
+  --foreground: #0a0a0a;
+  --muted: #f4f4f5;
+  --muted-foreground: #71717a;
+  --border: #e4e4e7;
 }
 
 @media (prefers-color-scheme: dark) {
-  @theme {
-    --color-background: #0a0a0a;
-    --color-foreground: #fafafa;
-    --color-muted: #27272a;
-    --color-muted-foreground: #a1a1aa;
-    --color-border: #27272a;
+  :root {
+    --background: #0a0a0a;
+    --foreground: #fafafa;
+    --muted: #27272a;
+    --muted-foreground: #a1a1aa;
+    --border: #27272a;
   }
 }
 ```
 
-### Tailwind Safelist (required when using ThemeProvider)
+If these variables are not defined, sensible defaults (white background, dark text) are used automatically.
 
-Dynamic theme colors generate Tailwind classes at runtime. Add them to your safelist:
+### Embedding in an Existing App
 
-```ts
-import { getThemeSafelist } from '@chrisflippen/blueprint-document-assembly';
+The root component uses `h-full` instead of `h-screen`, so it fills its parent container. Ensure the parent has a defined height:
 
-// In your Tailwind config
-safelist: getThemeSafelist({ primary: 'blue', success: 'green' })
+```tsx
+<div style={{ height: '600px' }}> {/* or h-full with a sized parent */}
+  <BlueprintDocumentAssembly />
+</div>
 ```
 
 ## Quick Start
@@ -90,29 +93,69 @@ function App() {
 }
 ```
 
-### ThemeProvider — Custom Colors
+### Theme — Custom Colors
 
-Pass a `theme` prop to recolor all components. Colors map to Tailwind color names.
+Pass a `theme` prop to recolor all components. Accepts CSS color values or Tailwind color names (backward compatible):
 
 ```tsx
+// CSS color values (recommended)
+<BlueprintDocumentAssembly
+  theme={{ primary: '#3b82f6', accent: '#6366f1', success: '#22c55e' }}
+/>
+
+// Tailwind color names (still works via built-in lookup)
 <BlueprintDocumentAssembly
   theme={{ primary: 'blue', success: 'green', processing: 'indigo' }}
 />
 ```
 
-Under the hood this wraps the component tree in a `<ThemeProvider>` that resolves color names into Tailwind class strings. Components read from context via `useThemeOptional()` and fall back to hardcoded styles when no provider is present.
+Under the hood, the component injects `--bda-*` CSS variables on its root element. All children reference these variables via inline styles. No Tailwind safelist is needed.
 
-You can also use the provider directly for sub-components:
+#### CSS Variable Override
 
-```tsx
-import { ThemeProvider, useTheme, resolveTheme } from '@chrisflippen/blueprint-document-assembly';
+You can also override colors directly in CSS without using the `theme` prop:
 
-function CustomUI() {
-  const theme = useTheme(); // throws if no provider
-  return <div className={theme.primary.bg}>Themed content</div>;
+```css
+/* Override in your app's CSS */
+.my-container {
+  --bda-primary: #3b82f6;
+  --bda-accent: #6366f1;
+  --bda-success: #22c55e;
+  --bda-processing: #8b5cf6;
+  --bda-secondary: #06b6d4;
+  --bda-warning: #f59e0b;
 }
 ```
 
+#### Available CSS Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `--bda-primary` | `#f97316` (orange) | Primary accent color |
+| `--bda-accent` | `#ef4444` (red) | Gradient endpoint, active state |
+| `--bda-success` | `#10b981` (emerald) | Completed states |
+| `--bda-processing` | `#8b5cf6` (purple) | Processing/in-progress states |
+| `--bda-secondary` | `#06b6d4` (cyan) | Document/info elements |
+| `--bda-warning` | `#f59e0b` (amber) | Warning log level |
+| `--bda-bg` | `var(--background, #ffffff)` | Background color |
+| `--bda-fg` | `var(--foreground, #0a0a0a)` | Foreground text color |
+| `--bda-muted` | `var(--muted, #f4f4f5)` | Muted background |
+| `--bda-muted-fg` | `var(--muted-foreground, #71717a)` | Muted text color |
+| `--bda-border` | `var(--border, #e4e4e7)` | Border color |
+
+#### Programmatic Access
+
+```tsx
+import { resolveTheme, buildCssVars, resolveColorValue, colorMix } from '@chrisflippen/blueprint-document-assembly';
+
+const theme = resolveTheme({ primary: 'blue' });
+// theme.primary.color === '#3b82f6'
+// theme.cssVars === { '--bda-primary': '#3b82f6', ... }
+
+resolveColorValue('blue'); // '#3b82f6'
+colorMix('#3b82f6', 10);  // 'color-mix(in srgb, #3b82f6 10%, transparent)'
+```
+
 ### Animation Presets
 
 Four built-in presets control all animation timings, springs, stagger delays, and typewriter speeds:
@@ -318,7 +361,7 @@ Or override via the `layout` prop:
 `BlueprintDocumentAssembly`, `StepItem`, `SubStepItem`, `LogLine`, `LogContainer`, `DocumentPreview`, `DocumentLine`, `WholeDocumentView`, `WholeDocumentContent`
 
 **Theme:**
-`ThemeProvider`, `useTheme`, `useThemeOptional`, `resolveTheme`, `getThemeSafelist`
+`ThemeProvider`, `useTheme`, `useThemeOptional`, `resolveTheme`, `buildCssVars`, `resolveColorValue`, `colorMix`, `TAILWIND_COLOR_MAP`, ~~`getThemeSafelist`~~ (deprecated)
 
 **Animation:**
 `AnimationProvider`, `useAnimation`, `useAnimationOptional`, `SMOOTH_PRESET`, `SNAPPY_PRESET`, `CINEMATIC_PRESET`, `MINIMAL_PRESET`
@@ -352,7 +395,8 @@ src/
 │   ├── WholeDocumentView.tsx           # Completion overlay (GPU-safe glow)
 │   └── WholeDocumentContent.tsx        # Static document renderer
 ├── theme/
-│   ├── ThemeContext.tsx                # ThemeProvider, resolveTheme, safelist
+│   ├── ThemeContext.tsx                # ThemeProvider, resolveTheme
+│   ├── css-vars.ts                    # CSS variable helpers, Tailwind color lookup
 │   └── index.ts
 ├── animation/
 │   ├── presets.ts                     # SMOOTH, SNAPPY, CINEMATIC, MINIMAL

package/dist/index.d.mts

@@ -1,5 +1,5 @@
 import * as react from 'react';
-import react__default, { ComponentType, CSSProperties, ReactNode, RefObject } from 'react';
+import react__default, { ComponentType, CSSProperties, ReactNode, ErrorInfo, RefObject, Component } from 'react';
 import * as react_jsx_runtime from 'react/jsx-runtime';
 
 interface LogEntry {
@@ -18,9 +18,10 @@ interface Step {
     id: string;
     number: number;
     title: string;
-    status: 'pending' | 'active' | 'processing' | 'completed';
+    status: 'pending' | 'active' | 'processing' | 'completed' | 'error';
     substeps?: SubStep[];
     documentSection?: string;
+    errorMessage?: string;
     logs: LogEntry[];
     icon?: ComponentType<{
         className?: string;
@@ -74,6 +75,7 @@ interface ClassNameSlots {
 }
 interface ThemeConfig {
     primary?: string;
+    accent?: string;
     secondary?: string;
     success?: string;
     processing?: string;
@@ -114,11 +116,9 @@ interface LayoutConfig {
     direction?: 'horizontal' | 'vertical';
 }
 interface ResolvedThemeColors {
-    bg: string;
+    color: string;
+    mutedBg: string;
     border: string;
-    text: string;
-    icon: string;
-    accent: string;
 }
 interface ResolvedTheme {
     primary: ResolvedThemeColors;
@@ -127,16 +127,17 @@ interface ResolvedTheme {
     processing: ResolvedThemeColors;
     warning: ResolvedThemeColors;
     stepStatus: Record<Step['status'], {
-        cardBg: string;
+        color: string;
+        mutedBg: string;
         border: string;
-        iconBg: string;
-        textColor: string;
+        iconGradient: string;
     }>;
     gradients: {
         progress: string;
         title: string;
         completion: string;
     };
+    cssVars: Record<string, string>;
 }
 interface AnimationPreset {
     name: string;
@@ -199,6 +200,12 @@ interface UseDocumentAssemblyOptions {
     onPause?: () => void;
     onResume?: () => void;
     onReset?: () => void;
+    externalMode?: boolean;
+    onError?: (error: {
+        stepIndex: number;
+        stepId: string;
+        message: string;
+    }) => void;
 }
 interface UseDocumentAssemblyReturn {
     steps: Step[];
@@ -220,6 +227,15 @@ interface UseDocumentAssemblyReturn {
     reset: () => void;
     goToStep: (stepIndex: number) => void;
     setShowWholeDocument: (show: boolean) => void;
+    updateStep: (stepIndex: number, update: Partial<Pick<Step, 'status' | 'errorMessage'>>) => void;
+    addLog: (stepIndex: number, substepId: string | null, level: LogEntry['level'], message: string) => void;
+    updateMetrics: (metrics: Partial<DocumentMetrics> | ((prev: DocumentMetrics) => DocumentMetrics)) => void;
+    completeStep: (stepIndex: number) => void;
+    completeSubstep: (stepIndex: number, substepId: string) => void;
+    setStepError: (stepIndex: number, message: string) => void;
+    retryStep: (stepIndex: number) => void;
+    getSnapshot: () => AssemblySnapshot;
+    restoreSnapshot: (snapshot: AssemblySnapshot) => void;
 }
 interface BlueprintDocumentAssemblyRef {
     start: () => void;
@@ -227,6 +243,23 @@ interface BlueprintDocumentAssemblyRef {
     resume: () => void;
     reset: () => void;
     goToStep: (stepIndex: number) => void;
+    updateStep: (stepIndex: number, update: Partial<Pick<Step, 'status' | 'errorMessage'>>) => void;
+    addLog: (stepIndex: number, substepId: string | null, level: LogEntry['level'], message: string) => void;
+    updateMetrics: (metrics: Partial<DocumentMetrics> | ((prev: DocumentMetrics) => DocumentMetrics)) => void;
+    completeStep: (stepIndex: number) => void;
+    completeSubstep: (stepIndex: number, substepId: string) => void;
+    setStepError: (stepIndex: number, message: string) => void;
+    retryStep: (stepIndex: number) => void;
+    getDocumentContentRef: () => HTMLDivElement | null;
+    getDocumentHTML: () => string | null;
+}
+interface AssemblySnapshot {
+    steps: Step[];
+    completedSections: string[];
+    completedSubsteps: string[];
+    metrics: DocumentMetrics;
+    currentStep: number;
+    timestamp: number;
 }
 interface StepItemProps$1 {
     step: Step;
@@ -291,6 +324,25 @@ interface WholeDocumentContentProps$1 {
     classNames?: ClassNameSlots;
     renderSection?: (section: DocumentSection) => ReactNode;
 }
+interface VisibilityConfig {
+    header?: boolean;
+    leftPanel?: boolean;
+    rightPanel?: boolean;
+    metricsFooter?: boolean;
+    progressBar?: boolean;
+}
+interface RenderSlots {
+    header?: (props: {
+        labels: Required<LabelConfig>;
+        currentStep: number;
+        totalSteps: number;
+        progress: number;
+    }) => ReactNode;
+    footer?: (props: {
+        metrics: DocumentMetrics;
+        labels: Required<LabelConfig>;
+    }) => ReactNode;
+}
 interface BlueprintDocumentAssemblyProps {
     /**
      * Array of steps to process in the document assembly
@@ -415,6 +467,43 @@ interface BlueprintDocumentAssemblyProps {
      * Callback when assembly is reset
      */
     onReset?: () => void;
+    /**
+     * External mode — disables the internal timer loop. Host drives state via ref methods.
+     * @default false
+     */
+    externalMode?: boolean;
+    /**
+     * Callback when a step encounters an error (external mode)
+     */
+    onError?: (error: {
+        stepIndex: number;
+        stepId: string;
+        message: string;
+    }) => void;
+    /**
+     * Portal target for the whole document view modal.
+     * - true = portal to document.body
+     * - string = CSS selector
+     * - HTMLElement = direct reference
+     * - undefined/false = no portal (current behavior)
+     */
+    portalTarget?: HTMLElement | string | boolean;
+    /**
+     * Control visibility of individual UI sections
+     */
+    visibility?: VisibilityConfig;
+    /**
+     * Custom render functions for header and footer slots
+     */
+    renderSlots?: RenderSlots;
+    /**
+     * Custom fallback UI for the error boundary
+     */
+    errorFallback?: ReactNode | ((error: Error, reset: () => void) => ReactNode);
+    /**
+     * Callback when a render error is caught by the error boundary
+     */
+    onRenderError?: (error: Error, errorInfo: ErrorInfo) => void;
 }
 
 declare const BlueprintDocumentAssembly: react.ForwardRefExoticComponent<BlueprintDocumentAssemblyProps & react.RefAttributes<BlueprintDocumentAssemblyRef>>;
@@ -497,19 +586,43 @@ interface WholeDocumentViewProps {
     sparkleCount?: number;
     celebrationEnabled?: boolean;
     children?: React.ReactNode;
+    portalTarget?: HTMLElement | null;
+    contentRef?: RefObject<HTMLDivElement | null>;
 }
-declare function WholeDocumentView({ show, onClose, documentIds, metrics, classNames, labels, celebrationTitle, sparkleCount, celebrationEnabled, }: WholeDocumentViewProps): react_jsx_runtime.JSX.Element;
+declare function WholeDocumentView({ show, onClose, documentIds, metrics, classNames, labels, celebrationTitle, sparkleCount, celebrationEnabled, portalTarget, contentRef: externalContentRef, }: WholeDocumentViewProps): react_jsx_runtime.JSX.Element;
 
 interface WholeDocumentContentProps {
     documentIds: DocumentIds;
     sections?: DocumentSection[];
     classNames?: ClassNameSlots;
     renderSection?: (section: DocumentSection) => React.ReactNode;
+    contentRef?: RefObject<HTMLDivElement | null>;
+}
+declare function WholeDocumentContent({ documentIds, sections, classNames, renderSection, contentRef, }: WholeDocumentContentProps): react_jsx_runtime.JSX.Element;
+
+interface ErrorBoundaryProps {
+    fallback?: ReactNode | ((error: Error, reset: () => void) => ReactNode);
+    onError?: (error: Error, errorInfo: ErrorInfo) => void;
+    children: ReactNode;
+}
+interface ErrorBoundaryState {
+    hasError: boolean;
+    error: Error | null;
+}
+declare class ErrorBoundary extends Component<ErrorBoundaryProps, ErrorBoundaryState> {
+    constructor(props: ErrorBoundaryProps);
+    static getDerivedStateFromError(error: Error): ErrorBoundaryState;
+    componentDidCatch(error: Error, errorInfo: ErrorInfo): void;
+    reset: () => void;
+    render(): ReactNode;
 }
-declare function WholeDocumentContent({ documentIds, sections, classNames, renderSection, }: WholeDocumentContentProps): react_jsx_runtime.JSX.Element;
 
 declare function resolveTheme(config?: ThemeConfig): ResolvedTheme;
-declare function getThemeSafelist(config?: ThemeConfig): string[];
+/**
+ * @deprecated No longer needed — CSS variables replace the Tailwind safelist.
+ * Will be removed in v4.0.0.
+ */
+declare function getThemeSafelist(_config?: ThemeConfig): string[];
 interface ThemeProviderProps {
     theme?: ThemeConfig;
     children: ReactNode;
@@ -518,6 +631,14 @@ declare function ThemeProvider({ theme, children }: ThemeProviderProps): react_j
 declare function useTheme(): ResolvedTheme;
 declare function useThemeOptional(): ResolvedTheme | null;
 
+declare const TAILWIND_COLOR_MAP: Record<string, string>;
+/** Resolve a color value: if it's a Tailwind name, return the hex; otherwise pass through */
+declare function resolveColorValue(input: string): string;
+/** Generate a CSS color-mix() expression for tinting/opacity effects */
+declare function colorMix(color: string, percent: number, mixWith?: string): string;
+/** Build the full --bda-* CSS variable map from a resolved theme config */
+declare function buildCssVars(theme: Required<ThemeConfig>): Record<string, string>;
+
 interface AnimationContextValue {
     preset: AnimationPreset;
     reducedMotion: boolean;
@@ -615,4 +736,6 @@ declare function resetStepCounter(): void;
  */
 declare function resolveContent(content: string, documentIds: DocumentIds): string;
 
-export { type AnimationPreset, AnimationProvider, type AnimationTimings, BlueprintDocumentAssembly, type BlueprintDocumentAssemblyProps, type BlueprintDocumentAssemblyRef, CINEMATIC_PRESET, type ClassNameSlots, DEFAULT_LABELS, DEFAULT_STEPS, DEFAULT_STEP_LOGS, DEFAULT_SUBSTEP_LOGS, DEFAULT_THEME, type DocumentIds, DocumentLine, type DocumentLineProps$1 as DocumentLineProps, type DocumentMetrics, DocumentPreview, type DocumentPreviewProps$1 as DocumentPreviewProps, type DocumentSection, type DocumentSubsection, LEGAL_DOCUMENT_SECTIONS, LEGAL_WHOLE_DOCUMENT_SECTIONS, type LabelConfig, type LayoutConfig, LogContainer, type LogContainerProps$1 as LogContainerProps, type LogEntry, LogLine, type LogLineProps$1 as LogLineProps, MINIMAL_PRESET, type ResolvedTheme, type ResolvedThemeColors, SMOOTH_PRESET, SNAPPY_PRESET, SQUIGGLE_DOCUMENT_SECTIONS, SQUIGGLE_STEPS, SQUIGGLE_STEP_LOGS, SQUIGGLE_SUBSTEP_LOGS, SQUIGGLE_WHOLE_DOCUMENT_SECTIONS, STEP_ICON_MAP, type Step, StepItem, type StepItemProps$1 as StepItemProps, type SubStep, SubStepItem, type SubStepItemProps$1 as SubStepItemProps, type ThemeConfig, ThemeProvider, type UseDocumentAssemblyOptions, type UseDocumentAssemblyReturn, WholeDocumentContent, type WholeDocumentContentProps$1 as WholeDocumentContentProps, WholeDocumentView, type WholeDocumentViewProps$1 as WholeDocumentViewProps, createDocumentSection, createStep, createSubStep, getThemeSafelist, resetStepCounter, resolveContent, resolveTheme, useAnimation, useAnimationOptional, useDocumentAssembly, useReducedMotion, useResponsiveLayout, useTheme, useThemeOptional };
+declare function injectStyle(id: string, css: string): void;
+
+export { type AnimationPreset, AnimationProvider, type AnimationTimings, type AssemblySnapshot, BlueprintDocumentAssembly, type BlueprintDocumentAssemblyProps, type BlueprintDocumentAssemblyRef, CINEMATIC_PRESET, type ClassNameSlots, DEFAULT_LABELS, DEFAULT_STEPS, DEFAULT_STEP_LOGS, DEFAULT_SUBSTEP_LOGS, DEFAULT_THEME, type DocumentIds, DocumentLine, type DocumentLineProps$1 as DocumentLineProps, type DocumentMetrics, DocumentPreview, type DocumentPreviewProps$1 as DocumentPreviewProps, type DocumentSection, type DocumentSubsection, ErrorBoundary, LEGAL_DOCUMENT_SECTIONS, LEGAL_WHOLE_DOCUMENT_SECTIONS, type LabelConfig, type LayoutConfig, LogContainer, type LogContainerProps$1 as LogContainerProps, type LogEntry, LogLine, type LogLineProps$1 as LogLineProps, MINIMAL_PRESET, type RenderSlots, type ResolvedTheme, type ResolvedThemeColors, SMOOTH_PRESET, SNAPPY_PRESET, SQUIGGLE_DOCUMENT_SECTIONS, SQUIGGLE_STEPS, SQUIGGLE_STEP_LOGS, SQUIGGLE_SUBSTEP_LOGS, SQUIGGLE_WHOLE_DOCUMENT_SECTIONS, STEP_ICON_MAP, type Step, StepItem, type StepItemProps$1 as StepItemProps, type SubStep, SubStepItem, type SubStepItemProps$1 as SubStepItemProps, TAILWIND_COLOR_MAP, type ThemeConfig, ThemeProvider, type UseDocumentAssemblyOptions, type UseDocumentAssemblyReturn, type VisibilityConfig, WholeDocumentContent, type WholeDocumentContentProps$1 as WholeDocumentContentProps, WholeDocumentView, type WholeDocumentViewProps$1 as WholeDocumentViewProps, buildCssVars, colorMix, createDocumentSection, createStep, createSubStep, getThemeSafelist, injectStyle, resetStepCounter, resolveColorValue, resolveContent, resolveTheme, useAnimation, useAnimationOptional, useDocumentAssembly, useReducedMotion, useResponsiveLayout, useTheme, useThemeOptional };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import * as react from 'react';
-import react__default, { ComponentType, CSSProperties, ReactNode, RefObject } from 'react';
+import react__default, { ComponentType, CSSProperties, ReactNode, ErrorInfo, RefObject, Component } from 'react';
 import * as react_jsx_runtime from 'react/jsx-runtime';
 
 interface LogEntry {
@@ -18,9 +18,10 @@ interface Step {
     id: string;
     number: number;
     title: string;
-    status: 'pending' | 'active' | 'processing' | 'completed';
+    status: 'pending' | 'active' | 'processing' | 'completed' | 'error';
     substeps?: SubStep[];
     documentSection?: string;
+    errorMessage?: string;
     logs: LogEntry[];
     icon?: ComponentType<{
         className?: string;
@@ -74,6 +75,7 @@ interface ClassNameSlots {
 }
 interface ThemeConfig {
     primary?: string;
+    accent?: string;
     secondary?: string;
     success?: string;
     processing?: string;
@@ -114,11 +116,9 @@ interface LayoutConfig {
     direction?: 'horizontal' | 'vertical';
 }
 interface ResolvedThemeColors {
-    bg: string;
+    color: string;
+    mutedBg: string;
     border: string;
-    text: string;
-    icon: string;
-    accent: string;
 }
 interface ResolvedTheme {
     primary: ResolvedThemeColors;
@@ -127,16 +127,17 @@ interface ResolvedTheme {
     processing: ResolvedThemeColors;
     warning: ResolvedThemeColors;
     stepStatus: Record<Step['status'], {
-        cardBg: string;
+        color: string;
+        mutedBg: string;
         border: string;
-        iconBg: string;
-        textColor: string;
+        iconGradient: string;
     }>;
     gradients: {
         progress: string;
         title: string;
         completion: string;
     };
+    cssVars: Record<string, string>;
 }
 interface AnimationPreset {
     name: string;
@@ -199,6 +200,12 @@ interface UseDocumentAssemblyOptions {
     onPause?: () => void;
     onResume?: () => void;
     onReset?: () => void;
+    externalMode?: boolean;
+    onError?: (error: {
+        stepIndex: number;
+        stepId: string;
+        message: string;
+    }) => void;
 }
 interface UseDocumentAssemblyReturn {
     steps: Step[];
@@ -220,6 +227,15 @@ interface UseDocumentAssemblyReturn {
     reset: () => void;
     goToStep: (stepIndex: number) => void;
     setShowWholeDocument: (show: boolean) => void;
+    updateStep: (stepIndex: number, update: Partial<Pick<Step, 'status' | 'errorMessage'>>) => void;
+    addLog: (stepIndex: number, substepId: string | null, level: LogEntry['level'], message: string) => void;
+    updateMetrics: (metrics: Partial<DocumentMetrics> | ((prev: DocumentMetrics) => DocumentMetrics)) => void;
+    completeStep: (stepIndex: number) => void;
+    completeSubstep: (stepIndex: number, substepId: string) => void;
+    setStepError: (stepIndex: number, message: string) => void;
+    retryStep: (stepIndex: number) => void;
+    getSnapshot: () => AssemblySnapshot;
+    restoreSnapshot: (snapshot: AssemblySnapshot) => void;
 }
 interface BlueprintDocumentAssemblyRef {
     start: () => void;
@@ -227,6 +243,23 @@ interface BlueprintDocumentAssemblyRef {
     resume: () => void;
     reset: () => void;
     goToStep: (stepIndex: number) => void;
+    updateStep: (stepIndex: number, update: Partial<Pick<Step, 'status' | 'errorMessage'>>) => void;
+    addLog: (stepIndex: number, substepId: string | null, level: LogEntry['level'], message: string) => void;
+    updateMetrics: (metrics: Partial<DocumentMetrics> | ((prev: DocumentMetrics) => DocumentMetrics)) => void;
+    completeStep: (stepIndex: number) => void;
+    completeSubstep: (stepIndex: number, substepId: string) => void;
+    setStepError: (stepIndex: number, message: string) => void;
+    retryStep: (stepIndex: number) => void;
+    getDocumentContentRef: () => HTMLDivElement | null;
+    getDocumentHTML: () => string | null;
+}
+interface AssemblySnapshot {
+    steps: Step[];
+    completedSections: string[];
+    completedSubsteps: string[];
+    metrics: DocumentMetrics;
+    currentStep: number;
+    timestamp: number;
 }
 interface StepItemProps$1 {
     step: Step;
@@ -291,6 +324,25 @@ interface WholeDocumentContentProps$1 {
     classNames?: ClassNameSlots;
     renderSection?: (section: DocumentSection) => ReactNode;
 }
+interface VisibilityConfig {
+    header?: boolean;
+    leftPanel?: boolean;
+    rightPanel?: boolean;
+    metricsFooter?: boolean;
+    progressBar?: boolean;
+}
+interface RenderSlots {
+    header?: (props: {
+        labels: Required<LabelConfig>;
+        currentStep: number;
+        totalSteps: number;
+        progress: number;
+    }) => ReactNode;
+    footer?: (props: {
+        metrics: DocumentMetrics;
+        labels: Required<LabelConfig>;
+    }) => ReactNode;
+}
 interface BlueprintDocumentAssemblyProps {
     /**
      * Array of steps to process in the document assembly
@@ -415,6 +467,43 @@ interface BlueprintDocumentAssemblyProps {
      * Callback when assembly is reset
      */
     onReset?: () => void;
+    /**
+     * External mode — disables the internal timer loop. Host drives state via ref methods.
+     * @default false
+     */
+    externalMode?: boolean;
+    /**
+     * Callback when a step encounters an error (external mode)
+     */
+    onError?: (error: {
+        stepIndex: number;
+        stepId: string;
+        message: string;
+    }) => void;
+    /**
+     * Portal target for the whole document view modal.
+     * - true = portal to document.body
+     * - string = CSS selector
+     * - HTMLElement = direct reference
+     * - undefined/false = no portal (current behavior)
+     */
+    portalTarget?: HTMLElement | string | boolean;
+    /**
+     * Control visibility of individual UI sections
+     */
+    visibility?: VisibilityConfig;
+    /**
+     * Custom render functions for header and footer slots
+     */
+    renderSlots?: RenderSlots;
+    /**
+     * Custom fallback UI for the error boundary
+     */
+    errorFallback?: ReactNode | ((error: Error, reset: () => void) => ReactNode);
+    /**
+     * Callback when a render error is caught by the error boundary
+     */
+    onRenderError?: (error: Error, errorInfo: ErrorInfo) => void;
 }
 
 declare const BlueprintDocumentAssembly: react.ForwardRefExoticComponent<BlueprintDocumentAssemblyProps & react.RefAttributes<BlueprintDocumentAssemblyRef>>;
@@ -497,19 +586,43 @@ interface WholeDocumentViewProps {
     sparkleCount?: number;
     celebrationEnabled?: boolean;
     children?: React.ReactNode;
+    portalTarget?: HTMLElement | null;
+    contentRef?: RefObject<HTMLDivElement | null>;
 }
-declare function WholeDocumentView({ show, onClose, documentIds, metrics, classNames, labels, celebrationTitle, sparkleCount, celebrationEnabled, }: WholeDocumentViewProps): react_jsx_runtime.JSX.Element;
+declare function WholeDocumentView({ show, onClose, documentIds, metrics, classNames, labels, celebrationTitle, sparkleCount, celebrationEnabled, portalTarget, contentRef: externalContentRef, }: WholeDocumentViewProps): react_jsx_runtime.JSX.Element;
 
 interface WholeDocumentContentProps {
     documentIds: DocumentIds;
     sections?: DocumentSection[];
     classNames?: ClassNameSlots;
     renderSection?: (section: DocumentSection) => React.ReactNode;
+    contentRef?: RefObject<HTMLDivElement | null>;
+}
+declare function WholeDocumentContent({ documentIds, sections, classNames, renderSection, contentRef, }: WholeDocumentContentProps): react_jsx_runtime.JSX.Element;
+
+interface ErrorBoundaryProps {
+    fallback?: ReactNode | ((error: Error, reset: () => void) => ReactNode);
+    onError?: (error: Error, errorInfo: ErrorInfo) => void;
+    children: ReactNode;
+}
+interface ErrorBoundaryState {
+    hasError: boolean;
+    error: Error | null;
+}
+declare class ErrorBoundary extends Component<ErrorBoundaryProps, ErrorBoundaryState> {
+    constructor(props: ErrorBoundaryProps);
+    static getDerivedStateFromError(error: Error): ErrorBoundaryState;
+    componentDidCatch(error: Error, errorInfo: ErrorInfo): void;
+    reset: () => void;
+    render(): ReactNode;
 }
-declare function WholeDocumentContent({ documentIds, sections, classNames, renderSection, }: WholeDocumentContentProps): react_jsx_runtime.JSX.Element;
 
 declare function resolveTheme(config?: ThemeConfig): ResolvedTheme;
-declare function getThemeSafelist(config?: ThemeConfig): string[];
+/**
+ * @deprecated No longer needed — CSS variables replace the Tailwind safelist.
+ * Will be removed in v4.0.0.
+ */
+declare function getThemeSafelist(_config?: ThemeConfig): string[];
 interface ThemeProviderProps {
     theme?: ThemeConfig;
     children: ReactNode;
@@ -518,6 +631,14 @@ declare function ThemeProvider({ theme, children }: ThemeProviderProps): react_j
 declare function useTheme(): ResolvedTheme;
 declare function useThemeOptional(): ResolvedTheme | null;
 
+declare const TAILWIND_COLOR_MAP: Record<string, string>;
+/** Resolve a color value: if it's a Tailwind name, return the hex; otherwise pass through */
+declare function resolveColorValue(input: string): string;
+/** Generate a CSS color-mix() expression for tinting/opacity effects */
+declare function colorMix(color: string, percent: number, mixWith?: string): string;
+/** Build the full --bda-* CSS variable map from a resolved theme config */
+declare function buildCssVars(theme: Required<ThemeConfig>): Record<string, string>;
+
 interface AnimationContextValue {
     preset: AnimationPreset;
     reducedMotion: boolean;
@@ -615,4 +736,6 @@ declare function resetStepCounter(): void;
  */
 declare function resolveContent(content: string, documentIds: DocumentIds): string;
 
-export { type AnimationPreset, AnimationProvider, type AnimationTimings, BlueprintDocumentAssembly, type BlueprintDocumentAssemblyProps, type BlueprintDocumentAssemblyRef, CINEMATIC_PRESET, type ClassNameSlots, DEFAULT_LABELS, DEFAULT_STEPS, DEFAULT_STEP_LOGS, DEFAULT_SUBSTEP_LOGS, DEFAULT_THEME, type DocumentIds, DocumentLine, type DocumentLineProps$1 as DocumentLineProps, type DocumentMetrics, DocumentPreview, type DocumentPreviewProps$1 as DocumentPreviewProps, type DocumentSection, type DocumentSubsection, LEGAL_DOCUMENT_SECTIONS, LEGAL_WHOLE_DOCUMENT_SECTIONS, type LabelConfig, type LayoutConfig, LogContainer, type LogContainerProps$1 as LogContainerProps, type LogEntry, LogLine, type LogLineProps$1 as LogLineProps, MINIMAL_PRESET, type ResolvedTheme, type ResolvedThemeColors, SMOOTH_PRESET, SNAPPY_PRESET, SQUIGGLE_DOCUMENT_SECTIONS, SQUIGGLE_STEPS, SQUIGGLE_STEP_LOGS, SQUIGGLE_SUBSTEP_LOGS, SQUIGGLE_WHOLE_DOCUMENT_SECTIONS, STEP_ICON_MAP, type Step, StepItem, type StepItemProps$1 as StepItemProps, type SubStep, SubStepItem, type SubStepItemProps$1 as SubStepItemProps, type ThemeConfig, ThemeProvider, type UseDocumentAssemblyOptions, type UseDocumentAssemblyReturn, WholeDocumentContent, type WholeDocumentContentProps$1 as WholeDocumentContentProps, WholeDocumentView, type WholeDocumentViewProps$1 as WholeDocumentViewProps, createDocumentSection, createStep, createSubStep, getThemeSafelist, resetStepCounter, resolveContent, resolveTheme, useAnimation, useAnimationOptional, useDocumentAssembly, useReducedMotion, useResponsiveLayout, useTheme, useThemeOptional };
+declare function injectStyle(id: string, css: string): void;
+
+export { type AnimationPreset, AnimationProvider, type AnimationTimings, type AssemblySnapshot, BlueprintDocumentAssembly, type BlueprintDocumentAssemblyProps, type BlueprintDocumentAssemblyRef, CINEMATIC_PRESET, type ClassNameSlots, DEFAULT_LABELS, DEFAULT_STEPS, DEFAULT_STEP_LOGS, DEFAULT_SUBSTEP_LOGS, DEFAULT_THEME, type DocumentIds, DocumentLine, type DocumentLineProps$1 as DocumentLineProps, type DocumentMetrics, DocumentPreview, type DocumentPreviewProps$1 as DocumentPreviewProps, type DocumentSection, type DocumentSubsection, ErrorBoundary, LEGAL_DOCUMENT_SECTIONS, LEGAL_WHOLE_DOCUMENT_SECTIONS, type LabelConfig, type LayoutConfig, LogContainer, type LogContainerProps$1 as LogContainerProps, type LogEntry, LogLine, type LogLineProps$1 as LogLineProps, MINIMAL_PRESET, type RenderSlots, type ResolvedTheme, type ResolvedThemeColors, SMOOTH_PRESET, SNAPPY_PRESET, SQUIGGLE_DOCUMENT_SECTIONS, SQUIGGLE_STEPS, SQUIGGLE_STEP_LOGS, SQUIGGLE_SUBSTEP_LOGS, SQUIGGLE_WHOLE_DOCUMENT_SECTIONS, STEP_ICON_MAP, type Step, StepItem, type StepItemProps$1 as StepItemProps, type SubStep, SubStepItem, type SubStepItemProps$1 as SubStepItemProps, TAILWIND_COLOR_MAP, type ThemeConfig, ThemeProvider, type UseDocumentAssemblyOptions, type UseDocumentAssemblyReturn, type VisibilityConfig, WholeDocumentContent, type WholeDocumentContentProps$1 as WholeDocumentContentProps, WholeDocumentView, type WholeDocumentViewProps$1 as WholeDocumentViewProps, buildCssVars, colorMix, createDocumentSection, createStep, createSubStep, getThemeSafelist, injectStyle, resetStepCounter, resolveColorValue, resolveContent, resolveTheme, useAnimation, useAnimationOptional, useDocumentAssembly, useReducedMotion, useResponsiveLayout, useTheme, useThemeOptional };