@sonata-innovations/fiber-fbre 3.3.0 → 3.4.0

package/README.md

@@ -1,6 +1,6 @@
-# @sonata-innovations/fiber-fbre v2
+# @sonata-innovations/fiber-fbre
 
-Fiber Render Engine — consumes Flow JSON and renders data collection forms. Handles conditional logic, validation, screen transitions, and outputs collected FlowData back to the parent application.
+Fiber Render Engine — consumes Flow JSON and renders data collection forms. Handles conditional logic, validation, calculations, screen transitions, theming, and outputs collected FlowData back to the parent application. Renders 30 component types across standard and conversational modes; zero UI-framework dependency (custom CSS only).
 
 ## Quick Start
 
@@ -68,7 +68,7 @@ function App() {
 npm install @sonata-innovations/fiber-fbre
 ```
 
-Then import the CSS in your app entry point:
+Then import the CSS **once** in your app entry point — without it the form renders unstyled:
 
 ```ts
 import "@sonata-innovations/fiber-fbre/styles";
@@ -78,6 +78,22 @@ import "@sonata-innovations/fiber-fbre/styles";
 
 **Runtime dependencies:** `zustand`, `@sonata-innovations/fiber-types`, `@sonata-innovations/fiber-shared`
 
+## Documentation
+
+This README covers evaluation and day-to-day API lookup. Deeper guides ship **inside the package** under `docs/` (and an `AGENTS.md` routing guide at the package root), and are browsable in the public docs mirror at [github.com/sonata-innovations/fiber-docs](https://github.com/sonata-innovations/fiber-docs).
+
+| Topic | In package | Mirror |
+|-------|-----------|--------|
+| Concepts overview | `docs/fiber-concepts.md` | [fiber-concepts.md](https://github.com/sonata-innovations/fiber-docs/blob/main/fiber-concepts.md) |
+| FBRE integration guide | `docs/integration/fbre.md` | [integration/fbre.md](https://github.com/sonata-innovations/fiber-docs/blob/main/integration/fbre.md) |
+| Theming reference | `docs/features/fbre-theming.md` | [features/fbre-theming.md](https://github.com/sonata-innovations/fiber-docs/blob/main/features/fbre-theming.md) |
+| Confirmation screen | `docs/features/confirmation-screen.md` | [features/confirmation-screen.md](https://github.com/sonata-innovations/fiber-docs/blob/main/features/confirmation-screen.md) |
+
+Schema references (Flow input and FlowData output) ship in the **`@sonata-innovations/fiber-types`** package under `docs/schema/`, and are mirrored at:
+
+- [schema/flow-schema.md](https://github.com/sonata-innovations/fiber-docs/blob/main/schema/flow-schema.md) · [schema/flow-quick-reference.md](https://github.com/sonata-innovations/fiber-docs/blob/main/schema/flow-quick-reference.md)
+- [schema/flow-data-schema.md](https://github.com/sonata-innovations/fiber-docs/blob/main/schema/flow-data-schema.md) · [schema/flow-schema.json](https://github.com/sonata-innovations/fiber-docs/blob/main/schema/flow-schema.json)
+
 ## API
 
 ### `<FBRE />` Props
@@ -91,7 +107,7 @@ Render a Flow object you already have in memory.
 | Prop | Type | Required | Description |
 |------|------|----------|-------------|
 | `flow` | `Flow` | Yes | Flow JSON object |
-| `data` | `FlowData` | No | Pre-populated form data |
+| `data` | `FlowData` | No | Pre-populated form data (not reactive — read once at mount) |
 | `mode` | `FlowModeType` | No | Override form mode (`"standard"` \| `"conversational"`) |
 | `screenIndex` | `number` | No | Initial screen index (default `0`) |
 | `theme` | `ThemeConfig` | No | Override theme settings (merged over `flow.config.theme`) |
@@ -101,7 +117,6 @@ Render a Flow object you already have in memory.
 | `storeRef` | `MutableRefObject<StoreApi<FBREStoreState> \| null>` | No | Ref to access the Zustand store |
 | `onFlowComplete` | `(data: FlowData) => void \| ConfirmationResult \| Promise<void \| ConfirmationResult>` | Yes | Called when the user completes the flow. Return/resolve a `ConfirmationResult` to override the configured confirmation message; a rejected Promise surfaces a completion error |
 | `onScreenChange` | `(index: number, data: FlowData) => void` | No | Called on screen navigation |
-| `onScreenValidationChange` | `(index: number, data: any) => void` | No | Called when screen validity changes |
 
 #### Remote Mode
 
@@ -112,7 +127,7 @@ Fetch a published flow from a Fiber API by ID.
 | `flowId` | `string` | Yes | ID of the published flow |
 | `apiEndpoint` | `string` | Yes | Base URL of the Fiber API |
 | `apiKey` | `string` | No | API key for authentication |
-| `data` | `FlowData` | No | Pre-populated form data |
+| `data` | `FlowData` | No | Pre-populated form data (not reactive) |
 | `mode` | `FlowModeType` | No | Override form mode (`"standard"` \| `"conversational"`) |
 | `screenIndex` | `number` | No | Initial screen index (default `0`) |
 | `theme` | `ThemeConfig` | No | Override theme settings |
@@ -120,13 +135,12 @@ Fetch a published flow from a Fiber API by ID.
 | `controls` | `ControlsConfig` | No | Override controls settings |
 | `context` | `Record<string, string \| boolean \| number>` | No | External context values for condition evaluation and calculations |
 | `storeRef` | `MutableRefObject<StoreApi<FBREStoreState> \| null>` | No | Ref to access the Zustand store |
-| `onFlowComplete` | `(data: FlowData) => void \| ConfirmationResult \| Promise<void \| ConfirmationResult>` | Yes | Called when the user completes the flow. Return/resolve a `ConfirmationResult` to override the configured confirmation message; a rejected Promise surfaces a completion error |
+| `onFlowComplete` | `(data: FlowData) => void \| ConfirmationResult \| Promise<void \| ConfirmationResult>` | Yes | Called when the user completes the flow (see Local Mode) |
 | `onScreenChange` | `(index: number, data: FlowData) => void` | No | Called on screen navigation |
-| `onScreenValidationChange` | `(index: number, data: any) => void` | No | Called when screen validity changes |
 
 #### Server-Driven Mode
 
-Session-based rendering. The server evaluates conditions and validation; the client renders one screen at a time.
+Session-based rendering. The server evaluates conditions and validation; the client renders one screen at a time. On completion it resets the submit button and shows a terminal confirmation (from `config.confirmation`, else a generic "Thank you"); `onFlowComplete` still fires with the server result if you want to drive your own post-completion UI.
 
 | Prop | Type | Required | Description |
 |------|------|----------|-------------|
@@ -137,7 +151,7 @@ Session-based rendering. The server evaluates conditions and validation; the cli
 | `theme` | `ThemeConfig` | No | Override theme settings |
 | `context` | `Record<string, string \| boolean \| number>` | No | External context values for condition evaluation and calculations |
 | `onFlowComplete` | `(data: FlowData) => void` | Yes | Called when the user completes the flow |
-| `onScreenChange` | `(screenNumber: number) => void` | No | Called on screen navigation (note: receives screen number, not index + data) |
+| `onScreenChange` | `(screenNumber: number) => void` | No | Called on screen navigation (receives screen number, not index + data) |
 
 ### Imperative Access
 
@@ -155,6 +169,8 @@ const data = storeApi.getState().getFlowData();
 const apiContext = useFBREApi();
 ```
 
+`getMaxScreenIndex()` on the store returns the maximum screen **index** (screen count − 1). (Renamed from `getMaxScreenCount`, whose name implied a count.)
+
 ### Events
 
 ```tsx
@@ -165,10 +181,12 @@ addFBREEventListener("file-upload", handler);
 removeFBREEventListener("file-upload", handler);
 ```
 
+Note: the `file-upload` event bus is **module-global** — a listener fires for uploads from every `<FBRE />` instance on the page, not just one. Filter by the emitted component id if you run multiple instances.
+
 ### Exports
 
 ```ts
-// Components
+// Component
 import { FBRE } from "@sonata-innovations/fiber-fbre";
 
 // Store hooks
@@ -180,7 +198,7 @@ import { addFBREEventListener, removeFBREEventListener } from "@sonata-innovatio
 // Error classes
 import { ApiError, TimeoutError } from "@sonata-innovations/fiber-fbre";
 
-// Types
+// Types — props, store, and the full Flow/FlowData/Component type surface
 import type {
   FBREProps,
   FBRELocalProps,
@@ -196,356 +214,62 @@ import type {
   ControlsConfig,
   ConfirmationConfig,
   ConfirmationResult,
-  FlowMetadata,
   Component,
   ComponentProperties,
-  ComponentDisplayProperties,
-  ComponentDividerProperties,
-  ComponentInputProperties,
-  ComponentOptionProperties,
-  ComponentSliderProperties,
-  ComponentSwitchProperties,
-  ComponentRatingProperties,
-  ComponentFileUploadProperties,
-  ComponentGroupProperties,
   FlowData,
   ScreenData,
   ComponentData,
   FileUploadData,
-  FileUploadBase64Data,
-  FileUploadS3Data,
   FlowConditionConfig,
   ConditionOperator,
-  ConditionRule,
-  ConditionGroup,
-  ConditionDependency,
+  // …plus per-component property types and condition/rule types
 } from "@sonata-innovations/fiber-fbre";
 ```
 
-## Confirmation Screen
-
-A terminal "thank you" screen shown after submission, configured on the flow (`config.confirmation`) — not a `Screen`. Renders only when `show` is not `false` and `title`/`body` has content, replacing the final screen and hiding the controls/stepper. `title`/`body` support `${...}` reference markup (collected fields, calculations, and `context` values by name).
-
-```tsx
-const flow = {
-  ...myFlow,
-  config: { ...myFlow.config, confirmation: { show: true, title: "Thank you!", body: "Submitted, ${email}." } },
-};
-<FBRE flow={flow} onFlowComplete={handleComplete} />
-```
-
-`onFlowComplete` decides *when* it shows: return `void` → shows immediately; return a `Promise` → the submit button stays in-flight until it settles (resolve shows it, **reject** shows a completion error instead); return/resolve a `ConfirmationResult` (`{ title?, body? }`) → overrides the configured message, e.g. with a server reference number.
-
-```tsx
-const handleComplete = async (data: FlowData): Promise<ConfirmationResult> => {
-  const { referenceId } = await saveToBackend(data);
-  return { title: "All done!", body: `Reference: ${referenceId}.` };
-};
-```
-
-## Flow JSON Schema
-
-```
-Flow
-├── uuid: string
-├── metadata: { name?, description?, ...}
-├── config?: { mode?, theme?: { color?, colorScheme?, style?, background?, surface?, text?, border?, radius?, fontFamily?, error?, success?, warning? }, navigation?: { transition?, allowInvalidTransition? }, controls?: { show?, layout?, showStepper? }, summary?, confirmation?: { show?, title?, body? } }
-└── screens: FlowScreen[]
-    ├── uuid: string
-    ├── label?: string
-    ├── conditions?: FlowConditionConfig
-    └── components: Component[]
-        ├── uuid: string
-        ├── type: string
-        ├── properties: { ... }
-        ├── conditions?: FlowConditionConfig
-        └── components?: Component[]  (groups and repeaters)
-```
-
-### Component Types
-
-| Type | Category | Description |
-|------|----------|-------------|
-| `header` | Display | Heading text |
-| `text` | Display | Rich text with markup support |
-| `divider` | Display | Horizontal rule with optional label |
-| `callout` | Display | Styled alert/info box with variant coloring (info, success, warning, neutral) |
-| `table` | Display | Static comparison/data table with optional column highlighting |
-| `inputText` | Input | Single-line text field |
-| `inputTextArea` | Input | Multi-line text field |
-| `inputNumber` | Input | Numeric input (supports decimal restriction and start adornment) |
-| `dropDown` | Selection | Native select dropdown |
-| `dropDownMulti` | Selection | Multi-select with tag chips |
-| `checkbox` | Selection | Checkbox group |
-| `radio` | Selection | Radio button group |
-| `toggleSwitch` | Selection | On/off toggle |
-| `yesNo` | Selection | Two large tappable buttons for binary yes/no |
-| `cardSelect` | Selection | Card-based visual selection with image/icon support |
-| `date` | Date & Time | Calendar popup date picker |
-| `time` | Date & Time | Hour/minute time selector |
-| `dateTime` | Date & Time | Combined date + time picker |
-| `dateRange` | Date & Time | Two date pickers for start/end |
-| `timeRange` | Date & Time | Two time pickers for start/end |
-| `dateTimeRange` | Date & Time | Two datetime pickers for start/end |
-| `fileUpload` | Interactive | File picker with size validation |
-| `rating` | Interactive | Star rating with half-star precision |
-| `slider` | Interactive | Range slider with value label |
-| `colorPicker` | Interactive | Saturation/hue picker with hex input |
-| `computed` | Display | Calculated field with formula-based computed values |
-| `signature` | Interactive | Signature pad — draw on canvas, type name, or both |
-| `group` | Container | Component container with layout grid, collapsible |
-| `repeater` | Container | Iterable component container (add/remove iterations, pre-populated rows) |
-
-### Conditions
-
-Components and screens can be conditionally shown/hidden using `FlowConditionConfig`:
-
-```json
-{
-  "action": "show",
-  "when": {
-    "logic": "and",
-    "rules": [
-      {
-        "source": "other-component-uuid",
-        "operator": "equals",
-        "value": "yes"
-      }
-    ]
-  }
-}
-```
+## Flow schema, conditions, validation, calculations
 
-**Logic:** `"and"` (all rules must match) or `"or"` (any rule matches).
+The Flow JSON hierarchy (Flow → Screen → Component), all **30 component types**, the **19 condition operators**, the **17 validators**, calculation formulas, and inline markup are documented in the schema references — `docs/schema/` in `@sonata-innovations/fiber-types`, mirrored at [schema/flow-schema.md](https://github.com/sonata-innovations/fiber-docs/blob/main/schema/flow-schema.md) (with a [quick reference](https://github.com/sonata-innovations/fiber-docs/blob/main/schema/flow-quick-reference.md)).
 
-**Context rules:** Set `sourceType: "context"` on a rule to reference an external context value instead of a component. In this case, `source` is a context key (not a component UUID).
+A few runtime facts worth knowing up front:
 
-**Operators:**
+- **No auto-migration.** Legacy flat `required` / `regex` properties are **not** converted at load. Pre-migrate flows to `validation.rules` (and `conditions`) before passing them to FBRE.
+- **Calculation formulas use single braces** to reference component values: `{uuid}`. They support arithmetic, comparisons, `IF()`, aggregation (`SUM`/`COUNT`/`AVG`/`MIN`/`MAX` over repeaters), and update reactively.
+- **Condition and validation results live on the store** (`conditionResults`, `validationErrors`), not in the Flow JSON. Components hidden by a condition are excluded from FlowData and don't block screen validity.
 
-| Category | Operators |
-|----------|-----------|
-| Equality | `equals`, `notEquals` |
-| String | `contains`, `notContains`, `startsWith`, `endsWith` |
-| Presence | `isEmpty`, `isNotEmpty` |
-| Numeric | `greaterThan`, `greaterThanOrEqual`, `lessThan`, `lessThanOrEqual` |
-| Set (single) | `isOneOf`, `isNotOneOf` |
-| Set (multi) | `includesAny`, `includesAll`, `includesNone` |
-| Boolean | `isTrue`, `isFalse` |
-
-Condition results are stored separately from the Flow JSON in a `conditionResults` map (keyed by target UUID). Hidden components are excluded from FlowData output.
-
-### Validation
-
-Components support a rules-based validation system via `properties.validation`:
-
-```json
-{
-  "validation": {
-    "rules": [
-      { "type": "required" },
-      { "type": "email" },
-      { "type": "minLength", "params": { "min": 5 } }
-    ]
-  }
-}
-```
-
-**17 built-in validators:** `required`, `email`, `phone`, `url`, `minLength`, `maxLength`, `exactLength`, `minValue`, `maxValue`, `pattern`, `minSelected`, `maxSelected`, `fileType`, `fileSize`, `contains`, `excludes`, `matchesField`
-
-Each validator has a default error message. Custom messages can be set per rule via the `message` field.
-
-**Error display:** The first failing message is shown below the field with an "(and N more)" count when multiple rules fail.
-
-**Cross-field validation:** `matchesField` enables bidirectional re-evaluation — changing either field re-validates the other.
-
-**Migration:** Legacy `required` and `regex` flat properties are automatically converted to validation rules on load.
-
-Validation errors are stored in `validationErrors: Record<string, string[]>` on the store (keyed by component UUID). Hidden components (by conditions) do not block screen validity.
-
-### Calculations
-
-Flows can include formula-based computed values via `FlowCalculation`:
-
-```json
-{
-  "calculations": [
-    {
-      "uuid": "calc-uuid",
-      "formula": "{{comp-a-uuid}} + {{comp-b-uuid}} * 0.1",
-      "label": "Total"
-    }
-  ]
-}
-```
-
-- Formulas reference component values via `{uuid}` tokens and support standard arithmetic (`+`, `-`, `*`, `/`)
-- Aggregation functions: `SUM()`, `COUNT()`, `AVG()`, `MIN()`, `MAX()` over repeater iterations
-- Scalar `MIN(expr, ...)` / `MAX(expr, ...)` for capping values (e.g. `MIN({discount}, 25)`)
-- `IF(condition, then, else)` for conditional formulas (e.g. tiered pricing)
-- Comparison operators: `>`, `<`, `>=`, `<=`, `==`, `!=` (return 1/0)
-- Option metadata is accessible for option-based components
-- Results update reactively when source values change
-- Access results via `getCalculationResult(uuid)` on the store
-
-### Markup
-
-Text components and `detail` fields support inline markup:
+## Confirmation Screen
 
-- `[b]bold[/b]` → **bold**
-- `[i]italic[/i]` → *italic*
-- `[l href="url"]link[/l]` → [link](url)
+A terminal "thank you" screen shown after submission, configured on the flow (`config.confirmation`) rather than as a `Screen`. It replaces the final screen and hides the controls/stepper; `title`/`body` support reference markup (collected fields, calculations, and `context` values by name). `onFlowComplete` decides *when* it shows — return `void` for immediate, a `Promise` to keep the submit button in-flight until it settles, or a `ConfirmationResult` (`{ title?, body? }`) to override the configured message (e.g. with a server reference number). Full guide: [features/confirmation-screen.md](https://github.com/sonata-innovations/fiber-docs/blob/main/features/confirmation-screen.md).
 
 ## Conversational Mode
 
-Set `mode: "conversational"` to transform FBRE into a one-question-per-screen experience:
-
-```tsx
-// Via JSX prop
-<FBRE flow={myFlow} mode="conversational" onFlowComplete={handleComplete} />
-
-// Via flow config
-const flow = {
-  ...myFlow,
-  config: { ...myFlow.config, mode: "conversational" }
-};
-<FBRE flow={flow} onFlowComplete={handleComplete} />
-```
-
-**What changes:**
-
-- Content is vertically and horizontally centered
-- Single-select components (`radio`, `yesNo`, `cardSelect`, `dropDown`) auto-advance ~500ms after selection
-- Pressing Enter on `inputText` / `inputNumber` advances to the next screen
-- Auto-advance (both Enter and on-change) only fires when the screen renders **exactly one interactive component**. Multi-input screens — including those produced by FBTL's per-card page-break toggle — behave like a normal form: the user fills every field and clicks Continue. Display-only components (text, header, callout, divider, table, computed) and components hidden by conditions don't count toward the input total.
-- Components animate in with fade + scale + stagger on screen transitions (respects `prefers-reduced-motion`)
-- Option items, Yes/No buttons, card-select cards, and input fields are enlarged for easier tapping
-- Each of the 6 existing styles has a tailored conversational presentation (e.g. clean = bordered cards, soft-outlined = pill-shaped options, defined-outlined = inverted selection)
-
-**What doesn't change:**
+Set `mode: "conversational"` (via the JSX prop or `flow.config.mode`) to turn FBRE into a one-question-per-screen experience: content is centered, single-select components auto-advance ~500ms after selection, and Enter advances text/number fields. Auto-advance only fires when a screen renders **exactly one** interactive component (display-only and condition-hidden components don't count); multi-input screens behave like a normal form. Components fade/scale/stagger in on transitions (respecting `prefers-reduced-motion`), and controls are enlarged for tapping.
 
-- FlowData output is identical
-- Conditions, validation, calculations all work the same
-- Navigation buttons still work alongside auto-advance
-- Works with all 6 transition types and dark mode
+FlowData output, conditions, validation, calculations, transitions, and dark mode all behave identically to standard mode. Styles partition by mode: **6 standard** (`clean`, `outlined`, `refined-clean`, `airy-clean`, `soft-outlined`, `defined-outlined`) and **4 conversational** (`centered-minimal`, `stacked-cards`, `soft-float`, `bold-statement`).
 
 ## Theming
 
-FBRE's appearance is driven entirely by CSS custom properties (the `--fbre-*` tokens). There are two independent axes — **`style`** controls the *shape* (borders vs. underlines, fills, spacing; set via `theme.style`), and the **palette** controls the *colors*. This section is a complete reference for the palette.
-
-Palette values resolve through four layers, each overriding the one above, so you only specify what you want to change:
-
-```
-1.  Light defaults                  base.css                       (lowest)
-2.  Preset:  colorScheme: "dark"    base.css [data-mode="dark"]
-3.  Knobs:   theme.{surface,text…}  inline custom properties
-4.  Raw CSS: your own --fbre-* rules your stylesheet               (highest)
-```
-
-### Color scheme (presets)
-
-`theme.colorScheme` (`"light"` default | `"dark"`) seeds the **entire** token set with a coherent light or dark palette and sets `data-mode` on the container. Set it on the `theme` prop or in the flow config (the prop takes precedence):
-
-```tsx
-<FBRE flow={myFlow} theme={{ colorScheme: "dark" }} onFlowComplete={handleComplete} />
-```
-
-> Replaces the former `darkMode: boolean`: `darkMode: true` → `colorScheme: "dark"`, `darkMode: false`/absent → `colorScheme: "light"`. There is no runtime fallback — migrate stored flows before upgrading.
-
-### Theme knobs
+FBRE's appearance is driven entirely by `--fbre-*` CSS custom properties. Two independent axes: **`theme.style`** controls shape (borders vs. underlines, fills, spacing), and the **palette** controls colors. There are three ways to set the palette, and they **layer** — each overrides the one before, so you specify only what you want to change:
 
-Layer brand colors on top of the preset with the `theme` palette knobs. Each knob sets its primary `--fbre-*` token **plus the tokens derived from it** (e.g. `surface` also drives the input fills and hover/alt surfaces, via mode-aware `color-mix`). Any subset may be set; unset knobs fall through to the preset.
+1. **`colorScheme` preset** — `theme.colorScheme` (`"light"` default | `"dark"`) seeds the entire token set with a coherent palette and sets `data-mode` on the container. (Replaces the former `darkMode` boolean; there is no runtime fallback — migrate stored flows.)
+2. **Palette knobs** — `theme.{color, background, surface, text, border, radius, fontFamily, error, success, warning}` set their primary token plus the tokens derived from it (e.g. `surface` also drives input fills and hover/alt surfaces). Any subset; unset knobs fall through to the preset.
+3. **Raw `--fbre-*` CSS** — override any token directly (including ones with no knob, like `--fbre-star-filled`) by scoping rules to your wrapper.
 
 ```tsx
 <FBRE
   flow={myFlow}
-  theme={{
-    colorScheme: "dark",
-    color: "#bcd3cd",       // accent
-    background: "#1a2a3a",  // form ground
-    surface: "#243244",     // input fills / cards
-    text: "#e8ede9",
-    border: "#2e4158",
-    radius: "3px",
-    fontFamily: '"Inter", system-ui, sans-serif',
-  }}
+  theme={{ colorScheme: "dark", color: "#bcd3cd", surface: "#243244", radius: "3px" }}
   onFlowComplete={handleComplete}
 />
 ```
 
-| Knob | Primary token | Also derives |
-| --- | --- | --- |
-| `color` | `--fbre-theme-color` | light/dark accent tints |
-| `background` | `--fbre-bg` | — |
-| `surface` | `--fbre-surface` | input fills, hover/alt/subtle surfaces, control surface |
-| `text` | `--fbre-text` | secondary/placeholder/disabled, label |
-| `border` | `--fbre-border` | hover/light/subtle |
-| `radius` | `--fbre-radius` | — |
-| `fontFamily` | `--fbre-font` | — |
-| `error` / `success` / `warning` | `--fbre-{error,success,warning}` | their `-bg` / `-border` (and `error-light`) |
-
-### Raw CSS (escape hatch)
-
-For tokens not exposed as a knob (e.g. `--fbre-star-filled`, `--fbre-shadow-color`) — or for surgical control — override the `--fbre-*` variables directly. Scope to your wrapper so you out-specify the engine defaults regardless of load order:
-
-```css
-.my-form-wrapper .fbre-container {
-  --fbre-surface: #243244;
-  --fbre-star-filled: #bcd3cd;
-}
-```
-
-Knobs are inline (highest specificity among engine-supplied values), so a knob and a raw rule on the *same* token: the knob wins unless your selector is also high-specificity. Use knobs for the common palette, raw CSS for the long tail.
-
-### Token catalog
-
-Every themeable value, with light/dark preset defaults. Tokens marked **(derived)** are produced from a knob when it's set; you can also set any of them raw.
-
-**Accent** — `--fbre-theme-color` (`#1976d2` / `#42a5f5`, knob `color`), `--fbre-theme-light` (`#e3f2fd` / `#1a2332`, derived), `--fbre-theme-dark` (`#1565c0` / `#1e88e5`, derived), `--fbre-on-primary` (`#fff` / `#fff`).
-
-**Ground & surfaces**
-
-| Token | Light | Dark | Knob |
-| --- | --- | --- | --- |
-| `--fbre-bg` | `#fff` | `#121212` | `background` |
-| `--fbre-surface` | `#fff` | `#1e1e1e` | `surface` |
-| `--fbre-surface-hover` | `#f5f5f5` | `#2a2a2a` | (derived) |
-| `--fbre-surface-alt` | `#e0e0e0` | `#333` | (derived) |
-| `--fbre-surface-subtle` | `#e8e8e8` | `#2a2a2a` | (derived) |
-| `--fbre-control-surface` | `#fff` | `#e0e0e0` | (derived) |
-| `--fbre-input-bg` | `var(--fbre-surface)` | `var(--fbre-surface)` | (derived) |
-| `--fbre-input-bg-focus` | `var(--fbre-bg)` | `var(--fbre-bg)` | (derived) |
-
-**Text** — `--fbre-text` (`#212121` / `#e0e0e0`, knob `text`), `--fbre-text-secondary` (`#666` / `#9e9e9e`, derived), `--fbre-text-placeholder` (`#aaa` / `#666`, derived), `--fbre-text-disabled` (`#bbb` / `#555`, derived), `--fbre-label` (`var(--fbre-text-secondary)`, derived).
-
-**Borders** — `--fbre-border` (`#ccc` / `#444`, knob `border`), `--fbre-border-hover` (`#999` / `#666`, derived), `--fbre-border-light` (`#ddd` / `#444`, derived), `--fbre-border-subtle` (`#eee` / `#333`, derived).
-
-**State colors**
+Defaults worth noting: `--fbre-radius` is `4px` and `--fbre-font` is `"Segoe UI", system-ui, -apple-system, sans-serif`. The complete token catalog with light/dark defaults is in [features/fbre-theming.md](https://github.com/sonata-innovations/fiber-docs/blob/main/features/fbre-theming.md).
 
-| Token | Light | Dark | Knob |
-| --- | --- | --- | --- |
-| `--fbre-error` | `#d32f2f` | `#ef5350` | `error` |
-| `--fbre-error-light` | `#fdecea` | `#2c1b1b` | (derived) |
-| `--fbre-success` | `#2d6a28` | `#a8e6a0` | `success` |
-| `--fbre-success-bg` | `#ddffda` | `#1a3318` | (derived) |
-| `--fbre-success-border` | `#b8e6b4` | `#2d5a28` | (derived) |
-| `--fbre-warning` | `#7a5900` | `#ffe082` | `warning` |
-| `--fbre-warning-bg` | `#fff8e1` | `#332b00` | (derived) |
-| `--fbre-warning-border` | `#ffe082` | `#665500` | (derived) |
-
-**Controls (no knob — set raw)** — `--fbre-toggle-track` (`#ccc` / `#555`), `--fbre-star-empty` (`#ddd` / `#444`), `--fbre-star-filled` (`#ffc107` / `#ffca28`), `--fbre-slider-track` (`#ddd` / `#444`), `--fbre-shadow-color` (`rgba(0,0,0,.12)` / `rgba(0,0,0,.4)`).
-
-**Shape & motion** — `--fbre-radius` (`4px`, knob `radius`), `--fbre-font` (`"Segoe UI", system-ui, sans-serif`, knob `fontFamily`), `--fbre-layout-gap` (`4px`, varies by style), `--fbre-transition-duration` (`250ms`), `--fbre-transition-easing` (`cubic-bezier(0.4, 0, 0.2, 1)`).
-
-### Screen Transitions
+## Screen Transitions
 
 Animate screen changes by setting `navigation.transition` in the flow config:
 
 ```json
-{
-  "config": {
-    "navigation": { "transition": "slideFade" }
-  }
-}
+{ "config": { "navigation": { "transition": "slideFade" } } }
 ```
 
 | Type | Effect | Direction-aware? |
@@ -557,76 +281,25 @@ Animate screen changes by setting `navigation.transition` in the flow config:
 | `"rise"` | Vertical rise/sink | Yes |
 | `"scaleFade"` | Scale + opacity | No |
 
-Direction-aware transitions reverse when navigating backward. Buttons are disabled during animation to prevent overlapping transitions.
-
-Customize timing via CSS custom properties:
-
-```css
-.fbre-container {
-  --fbre-transition-duration: 250ms;
-  --fbre-transition-easing: cubic-bezier(0.4, 0, 0.2, 1);
-}
-```
-
-`@media (prefers-reduced-motion: reduce)` sets duration to `0ms` automatically.
-
-## Architecture
-
-| Concern | Implementation |
-|---------|---------------|
-| UI framework | Zero-dependency custom CSS |
-| Styling | CSS custom properties + BEM (`fbre-` prefix) |
-| Display detection | `isDisplayComponent()` checks type against constant set (`header`, `text`, `divider`, `callout`, `table`) |
-| State | Zustand store factory, one store per `<FBRE />` instance via React Context |
-| Re-renders | Zustand selectors — granular, automatic |
-| Build | Vite library mode |
-| Components | Registry pattern (`Map<string, FC>`), one file per type |
-| Dependencies | react, zustand, @sonata-innovations/fiber-types, @sonata-innovations/fiber-shared |
+Direction-aware transitions reverse when navigating backward; buttons are disabled mid-animation to prevent overlap. Customize timing via `--fbre-transition-duration` / `--fbre-transition-easing`. `@media (prefers-reduced-motion: reduce)` sets the duration to `0ms` automatically.
 
 ## FlowData Output
 
-`getFlowData()` returns collected form data. Display-only components (`header`, `text`, `divider`, `callout`, `table`) are excluded automatically based on their type.
-
-```
-FlowData
-├── uuid: string
-├── metadata: Record<string, string>
-└── screens: ScreenData[]
-    ├── uuid: string
-    ├── label?: string
-    └── components: ComponentData[]
-        ├── uuid: string
-        ├── type: string
-        ├── label?: string          (omitted when empty)
-        ├── value: string | string[] | number | number[] | boolean | null | FileUploadData
-        └── components?: ComponentData[][]  (groups and repeaters)
-```
-
-## Build
-
-```bash
-npm run build
-```
-
-Output:
-
-```
-dist/
-├── index.d.ts        # Bundled type declarations
-├── fiber-fbre.js     # ES module
-├── fiber-fbre.cjs    # CommonJS
-└── fiber-fbre.css    # All styles
-```
+`getFlowData()` returns the collected form data, mirroring the Flow structure (Flow → ScreenData → ComponentData, with `components?: ComponentData[][]` for groups and repeaters). Display-only components — `header`, `text`, `divider`, `callout`, `table` — are excluded automatically; `computed` fields **are** included. Full shape and field semantics: [schema/flow-data-schema.md](https://github.com/sonata-innovations/fiber-docs/blob/main/schema/flow-data-schema.md).
 
 ## Responsive Sizing
 
-FBRE uses CSS container queries to automatically scale controls in narrow containers (under 400px). Buttons, stepper dots, and toggle switches shrink proportionally. No configuration needed — just embed in a smaller container and the compact sizing kicks in.
+FBRE uses CSS container queries to automatically scale controls in narrow containers (under 400px). Buttons, stepper dots, and toggle switches shrink proportionally — no configuration needed; just embed in a smaller container and the compact sizing kicks in.
 
 ## Multiple Instances
 
-Each `<FBRE />` creates its own isolated Zustand store. Multiple instances can run simultaneously on the same page without state conflicts.
+Each `<FBRE />` creates its own isolated Zustand store, so multiple instances run simultaneously on the same page without state conflicts. (The one exception is the module-global `file-upload` event bus noted under Events.)
 
 ```tsx
 <FBRE flow={flowA} onFlowComplete={handleA} />
 <FBRE flow={flowB} onFlowComplete={handleB} />
-```
+```
+
+## License
+
+MIT