@pebble-software/bonsai 0.0.8 → 0.1.1

package/README.md

@@ -6,7 +6,7 @@
 
 > ⚠️ **Active development / preview** — this package is pre-1.0 and evolving quickly. APIs, the configuration schema, and the component set may change between releases without a deprecation cycle. Pin an exact version and read release notes before upgrading. Feedback and issues are very welcome!
 
-The React runtime that turns a validated Bonsai configuration into a fully interactive, styled experience. It's built for UI that has to be delivered remotely (email, SMS, embedded experiences) but rendered locally with real React components, consistent styling, and predictable data flow.
+The React runtime that turns a Bonsai configuration (a JSON template) into a fully interactive, styled experience. It's built for UI that has to be delivered remotely (email, SMS, embedded experiences) but rendered locally with real React components, consistent styling, and predictable data flow.
 
 Bonsai is the rendering engine behind [Pebble Bonsai](https://github.com/PebbleSoftwareInc/pebble-bonsai), an open-source form and signature service — but the renderer is useful anywhere you need to ship UI as data: define a screen as a JSON template, bind it to your data with `{{ }}` expressions, and let one component render it on the server (SSR, PDF) or in the browser (fully interactive).
 
@@ -16,6 +16,7 @@ Bonsai is the rendering engine behind [Pebble Bonsai](https://github.com/PebbleS
 - [Installation](#installation)
 - [Quick start](#quick-start)
 - [Package exports](#package-exports)
+- [The `Bonsai` component](#the-bonsai-component)
 - [Configuration schema](#configuration-schema)
 - [Dynamic data binding](#dynamic-data-binding)
 - [Expression language](#expression-language)
@@ -24,50 +25,62 @@ Bonsai is the rendering engine behind [Pebble Bonsai](https://github.com/PebbleS
 - [Component reference](#component-reference)
 - [Styling](#styling)
 - [Extending Bonsai](#extending-bonsai)
+- [Performance](#performance)
 - [Development](#development)
 
 ## Features
 
-- **Schema-driven UI** — every screen is a Zod-validated `Config` tree, so the renderer only ever processes known-safe structures.
+- **Template-driven UI** — every screen is a JSON `Config` tree of known component types, rendered by one component.
 - **Universal rendering** — one component (`Bonsai`) picks server (SSR) or client (interactive) rendering automatically based on environment, with `web`, `pdf`, and `preview` render modes.
-- **Composable components** — schema component identifiers map to real React implementations via a `componentMap`, so the same schema can target different component sets.
+- **Pluggable component registry** — schema component identifiers map to real React implementations, and `createBonsaiRenderer` lets you build a renderer with your own components added or swapped in.
+- **Opt-in heavy components** — the calendar and signature controls live in separate presets, so the lightweight `/core` entry never pulls in `react-day-picker` or `react-signature-canvas`.
 - **Isolated per-instance state** — each mounted `Bonsai` tree owns its own `valtio` store, scoped via React context. Nothing about which data renders lives in shared or module-level state.
 - **Fine-grained reactivity** — every leaf node reads the store itself and evaluates only its own bindings, so editing one field re-renders just that field and whatever depends on it.
-- **Structural nodes** — `each` and `if` handle looping and conditional rendering directly in the schema, with two-way binding preserved inside loops.
+- **Structural nodes** — `each` and `if` handle looping and conditional rendering directly in the template, with two-way binding preserved inside loops.
 - **Sandboxed expression language** — `{{ }}` bindings are evaluated by a small, fixed-surface formula language, never executable JavaScript.
-- **Tailwind CSS v4 design system** — a themeable token set (colors, typography, spacing, shadows) drives every component, and templates can layer on any Tailwind utility via `className`.
+- **Tailwind CSS v4 design system** — a themeable token set (colors, typography, spacing, shadows) drives every component, and templates can layer on Tailwind utilities via `className`.
 
 ## Installation
 
+The package ships three kinds of entry point (see [Package exports](#package-exports)). Install the peer dependencies for the ones you import.
+
+**Lightweight core** (`@pebble-software/bonsai/core`) — needs only React:
+
 ```bash
-npm install @pebble-software/bonsai
-# or
-pnpm add @pebble-software/bonsai
-# or
-yarn add @pebble-software/bonsai
+npm install @pebble-software/bonsai react react-dom
 ```
 
-Peer dependencies:
+**Batteries-included** (`@pebble-software/bonsai`) — the root entry imports every preset, so all of the optional peers must be installed:
 
-- `react` and `react-dom` 18 or 19
-- A bundler that understands ES modules (Vite, Next, Rspack, etc.)
+```bash
+npm install @pebble-software/bonsai react react-dom react-day-picker react-signature-canvas@1.1.0-alpha.2
+```
 
-> **Preview note:** while the package is pre-1.0, pin an exact version (`npm install @pebble-software/bonsai --save-exact`) — minor releases may contain breaking changes.
+Optional peer dependencies, by preset:
 
-### Working in this monorepo
+| Peer dependency | Needed by |
+| --- | --- |
+| `react-day-picker` | `@pebble-software/bonsai/presets/calendar` and `@pebble-software/bonsai` |
+| `react-signature-canvas` (`1.1.0-alpha.2`) | `@pebble-software/bonsai/presets/signature` and `@pebble-software/bonsai` |
 
-```bash
-pnpm install
-pnpm --filter @pebble-software/bonsai run build
-```
+npm and pnpm don't auto-install optional peers — if you import the root entry without them, your bundler will fail to resolve them.
+
+Requirements:
 
-The shared workspaces (`@bonsai/constants`, `@bonsai/schemas`) are aliased to their sources and bundled directly into `dist/` by Vite, so downstream consumers only ever install this one package.
+- `react` and `react-dom` 18 or 19
+- A bundler that understands ES modules (Vite, Next.js, Rspack, etc.) — the package is ESM-only.
+- Tailwind CSS v4 in your build, for the styles — `index.css` ships as Tailwind source (see [Styling](#styling)).
+
+> **Preview note:** while the package is pre-1.0, pin an exact version (`npm install @pebble-software/bonsai --save-exact`) — minor releases may contain breaking changes.
 
 ## Quick start
 
 ```tsx
-import { Bonsai, type Config } from "@pebble-software/bonsai";
+import { Bonsai, type Config } from "@pebble-software/bonsai/core";
+// Styles: `@import "@pebble-software/bonsai/index.css";` in your Tailwind v4 CSS entry — see Styling.
 
+// Module scope: templates are compiled once per object identity, and `data`
+// is read by identity too (see "The `data` prop" below).
 const template: Config = {
   type: "card",
   args: { className: "p-6 flex flex-col gap-4" },
@@ -79,70 +92,191 @@ const template: Config = {
     },
     {
       type: "input",
-      args: { id: "name", type: "text", value: "{{profile.name}}" },
+      args: { id: "name", value: "{{profile.name}}" },
     },
     {
       type: "button",
-      args: { variant: "animated" },
+      args: { type: "submit" },
       children: ["Continue"],
     },
   ],
 };
 
+const initialData = { profile: { name: "Ada Lovelace" } };
+
 export function Example() {
   return (
     <Bonsai
       template={template}
-      captureUrl="/v1/capture/some-form-id"
-      expiry="2026-12-31T00:00:00Z"
-      data={{ profile: { name: "Ada Lovelace" } }}
+      data={initialData}
+      onSubmit={async (data) => {
+        const res = await fetch("/api/profile", {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify(data),
+        });
+        if (!res.ok) throw new Error(`Save failed: ${res.status}`);
+      }}
     />
   );
 }
 ```
 
-`Bonsai` renders server-side (a plain, single-pass render) when `window` is undefined, and client-side (an interactive, `valtio`-backed tree) otherwise — no extra setup required either way.
+- The stylesheet is **not** imported by the JavaScript entries — `@import` `@pebble-software/bonsai/index.css` from your Tailwind v4 CSS entry (see [Styling](#styling)).
+- Buttons default to `type="button"`; give the one that should submit the form `type: "submit"`.
+- `Bonsai` renders server-side (a plain, single-pass render) when `window` is undefined, and client-side (an interactive, `valtio`-backed tree) otherwise — no extra setup required either way.
+- **React Server Components (Next.js App Router):** the published files carry no `"use client"` directive. Render `Bonsai` from a module marked `"use client"`; it is still server-rendered as part of that client component.
 
 ## Package exports
 
-| Export | Type | Description |
-| --- | --- | --- |
-| `Bonsai` | component | Universal entry point. Renders the SSR path on the server and the interactive client path in the browser. |
-| `useUpdateData()` | hook | Returns an `updateData(path, value)` function bound to the nearest `Bonsai` instance's store. Must be called from a component mounted inside it. |
-| `componentMap` | object | Maps schema component identifiers to React implementations. |
-| `controlledInputMap` | object | Defines how specific component types behave as controlled inputs (value prop, change handler, value extractor). |
-| `Config` | type | Runtime type describing a Bonsai node. |
-| `SignatureProps` | type | Props contract for the built-in signature capture component. |
-
-`Bonsai` accepts:
+| Entry point | What it gives you |
+| --- | --- |
+| `@pebble-software/bonsai` | Batteries-included: `Bonsai` bound to every built-in component (`pebbleRegistry`), including calendar and signature, plus the registry tooling (`validateTemplate`, manifests, drift checks). Requires all optional peers. |
+| `@pebble-software/bonsai/core` | Lightweight: `Bonsai` bound to the core components only (no calendar or signature). Requires only React. |
+| `@pebble-software/bonsai/presets/calendar` | `calendarPreset` and the `Calendar` component. |
+| `@pebble-software/bonsai/presets/signature` | `signaturePreset`, the `Signature` component, and the `SignatureProps` type (the signature component's props). |
+| `@pebble-software/bonsai/index.css` | The Tailwind v4 theme source, for your own Tailwind build (see [Styling](#styling)). |
+| `@pebble-software/bonsai/schemas` | Template tooling for editors: the zod `Config` and `NodeSchemas`, plus builder metadata (`getNodeRules`, `getArgsSchema`, `fieldHints`, `FieldControl`, `FieldGroup`). |
+| `@pebble-software/bonsai/constants` | Component type names (`COMPONENT`, `COMPONENT_LIST`) and webhook event names. |
+| `@pebble-software/bonsai/ast` | The expression engine (`compileExpression`, `isExpression`, `parseExpression`, `extractVariables`, `clearExpressionCache`). |
+| `@pebble-software/bonsai/styles/*` | The raw layer stylesheets (`css/*.css`, `vendor/*.css`) and `presets.json`, for compiling template CSS yourself, e.g. `styles/css/theme.css?raw` in Vite. |
+
+Named exports of `@pebble-software/bonsai` and `@pebble-software/bonsai/core`:
+
+| Export | Entry | Kind | Description |
+| --- | --- | --- | --- |
+| `Bonsai` | both | component | Universal renderer. Renders the SSR path on the server and the interactive client path in the browser. Bound to the full registry (root) or the core registry (`/core`). |
+| `createBonsaiRenderer(options?)` | both | function | Returns `{ Bonsai }` bound to `options.registry` (default: the core registry) plus the `components`/`controlledInputs` you pass (yours win on a key collision). See [Extending Bonsai](#extending-bonsai). |
+| `useUpdateData()` | both | hook | Returns an `updateData(path, value)` function bound to the nearest `Bonsai` instance's store. Client render only — see [Controlled inputs & state](#controlled-inputs--state). |
+| `pebbleRegistry` | root | object | The full built-in `BonsaiRegistry` (core + every preset, with each component's `propsSchema`). |
+| `componentMap`, `controlledInputMap` | root | object | The same built-ins as plain component / controlled-input maps. Read-only reference: renderers copy their registry when created, so mutating these has no effect — use `createBonsaiRenderer` instead. |
+| `coreRegistry` | both | object | The core built-in `BonsaiRegistry` (no calendar or signature). |
+| `coreComponents`, `coreControlledInputs` | `/core` | object | The core built-ins as plain component / controlled-input maps. |
+| `extendRegistry(base, preset)`, `defineBonsaiRegistry`, `defineComponent` | both | function | Build a `BonsaiRegistry`: layer a preset over a base registry, or declare one from scratch. Pass it as `createBonsaiRenderer({ registry })` or per instance as `<Bonsai registry={…} />`. |
+| `useBonsaiRenderMode()` | both | hook | The nearest `Bonsai` root's `render` mode (`web` / `pdf` / `preview`), for components that render differently in a PDF. |
+| `Config` | both | type | A template node. Currently typed as `any` — see [Configuration schema](#configuration-schema). |
+| `BonsaiProps` | both | type | Props of `Bonsai`. |
+| `BonsaiRendererOptions`, `BonsaiRendererInstance` | both | type | Argument and return type of `createBonsaiRenderer`. |
+| `BonsaiRegistry`, `ComponentDefinition`, `ControlledFieldSpec`, `ComponentCapability` | both | type | The registry the renderer resolves component types against. |
+| `BonsaiPreset`, `ComponentRegistry`, `ControlledInput`, `ControlledInputEntry`, `ControlledInputRegistry` | both | type | Preset shapes, for building your own presets. |
+| `validateTemplate`, `resolveRegistryPin`, `resolveManifest`, `loadRegistryManifest`, `checkArtifactDrift`, … | root | function | Registry tooling: validate a template against a registry, resolve registry pins and manifests, check generated artifacts for drift. See [Validating templates](#validating-templates). |
+
+## The `Bonsai` component
 
 ```ts
 interface BonsaiProps {
   template: Config;
-  captureUrl: string; // POST target for the submit handler
-  expiry: string;
-  data?: any; // initial store data
+  data?: Record<string, unknown>;
+  onDataChange?: (data: Record<string, unknown>) => void;
+  onSubmit?: (data: Record<string, unknown>) => void | Promise<void>;
+  onError?: (error: unknown) => void;
+  captureUrl?: string;
+  expiry?: string;
   status?: "pending" | "captured" | "completed" | "error" | "revoked";
   render?: "web" | "pdf" | "preview";
+  as?: "form" | "div";
+  registry?: BonsaiRegistry; // overrides the renderer's registry for this instance
 }
 ```
 
-- `render: "web"` (default) mounts the tree inside a `<form>` whose submit handler POSTs the captured data to `captureUrl`. `"preview"` renders the same form UI flagged with `data-mode="preview"` for host styling. `"pdf"` renders a plain `<div>` wrapper with no form — the layout used for print/PDF output.
-- `status` other than `"pending"` disables capture: the submit handler no-ops instead of POSTing.
+`template` is the only required prop — everything else is optional, so a display-only instance is just `<Bonsai template={template} data={data} />`.
+
+- `status` (default `"pending"`) and `expiry` (default `""`) seed the instance's store and are readable from bindings (`{{status}}`, `{{expiry}}`). In the browser they are read **once, on mount** — changing them later has no effect on a mounted instance (remount it with a new React `key` instead). `expiry` is informational only: Bonsai does not enforce it.
+
+### The `data` prop: seeded by reference
+
+`data` is neither a fully controlled value nor a write-once default. It's read **by object identity**:
+
+- **On mount**, the instance's store is seeded from a deep copy of `data` (`{}` when omitted).
+- **User edits** mutate that internal copy only. Your `data` object is never written back to, so typing never produces a new `data` reference and can't feed a re-render loop.
+- **When a different object is passed** (`Object.is(previous, next) === false`), the store's data is resynced to match the new object. This is the supported way to push fresh data into a mounted instance.
+- **Passing the same object again is a no-op**, even if you mutated it in place. The mental model is: *pass a new object to force an update, don't mutate in place.*
+
+This is not tick-by-tick two-way binding like a controlled `<input value>`; the instance reacts to reference changes, not to every store mutation.
+
+> **Because identity is the signal, don't pass a freshly-built object literal on every render.** `data={{ profile }}` inline in JSX creates a new reference each time the parent re-renders, which resyncs the store and discards in-progress edits. Keep it in state, a module-level constant, or `useMemo`, and replace it deliberately when you want to push new data in.
+
+`onDataChange(data)` fires with a fresh, read-only (frozen) snapshot whenever something inside the instance changes the store's data — a user edit or a `useUpdateData()` call. A parent-driven resync is deliberately *not* echoed back through it.
+
+> **Never feed `onDataChange`'s output back into the `data` prop.** `onDataChange={setData}` paired with `data={data}` looks like the natural controlled-component wiring, but it isn't one:
+>
+> ```tsx
+> // Don't do this:
+> const [data, setData] = useState(initialData);
+> <Bonsai template={template} data={data} onDataChange={setData} />
+> ```
+>
+> Every keystroke fires `onDataChange`, which calls `setData`, which produces a *new* `data` reference on the next render — and since `data` is read by identity (see above), that reference change is indistinguishable from a host-initiated resync. The store gets resynced from data it just produced, on every keystroke, which can drop a fast second keystroke and defeats per-path reactivity: replacing the entire `data` object re-triggers every subscribed node instead of just the one that changed.
+>
+> `data` is for **host-initiated** updates only — loading a different record, resetting the form, undo/redo — deliberate, infrequent reference changes you make. `onDataChange` is for **observing** what the user typed — saving a draft, mirroring it into your own separate store, enabling a submit button — not for round-tripping back into `data`:
+>
+> ```tsx
+> // Do this instead: observe without feeding back in.
+> function ProfileForm({ initialData }: { initialData: Record<string, unknown> }) {
+>   const [draft, setDraft] = useState(initialData);
+>   return (
+>     <>
+>       <Bonsai
+>         template={template}
+>         data={initialData} // stable: only changes when you load a different record
+>         onDataChange={setDraft} // observe only — never passed back into `data`
+>       />
+>       <SaveDraftButton draft={draft} />
+>     </>
+>   );
+> }
+> ```
+
+### Submission
+
+Submission only happens when the instance renders a `<form>` (see below) and the form is submitted — typically by a `button` with `type: "submit"`.
+
+- `onSubmit(data)` — when supplied, it replaces the `captureUrl` POST entirely and receives a read-only snapshot of the current data. Throw (or reject) to signal failure.
+- `captureUrl` — the compatibility path, used only when `onSubmit` is absent: the submit handler sends `fetch(captureUrl, { method: "POST", credentials: "include", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ data }) })`. Cookies are sent (`credentials: "include"`). A network failure or a non-`2xx` response is a failure, thrown as `Error("Capture failed: <status> <statusText>")`. Use `onSubmit` if you need custom headers, a different body shape, or the response itself.
+- With neither supplied, submitting is a clean no-op (the browser's default navigation is still prevented).
+- While a submit is in flight, `{{submitting}}` is `true`.
+- A successful submit through either path moves `status` to `"captured"`; a failure leaves it `"pending"` so the submit can be retried.
+- `onError(error)` receives anything either path throws. Without it, the error propagates out of the submit handler.
+- When `status` is anything other than `"pending"`, submitting sends nothing.
+
+### Wrapper element and render mode
+
+- `render: "web"` (default) mounts the tree inside a `<form>`. `"preview"` renders the same form UI flagged with `data-mode="preview"` for host styling. `"pdf"` renders a plain `<div>` wrapper with no form — the layout used for print/PDF output.
+- `as: "div"` renders the whole instance as a `<div>` instead of a `<form>` (and no submit handler is attached). Use it when embedding an instance inside a host `<form>`, or when rendering sibling/nested instances, where nested `<form>` elements would be invalid HTML.
+- The two combine predictably: `render: "pdf"` always wins and produces a `<div>`; otherwise `as` decides.
+- Components read the mode with `useBonsaiRenderMode()`. The built-in `signature` uses it: under `render: "pdf"` it shows the captured image (or an empty signature line) instead of the interactive pad.
 
 Each mounted instance owns its own store — there's no shared module-level state and no global `updateData`; `useUpdateData()` is the only way to reach a given instance's data, and only from within its subtree.
 
 ## Configuration schema
 
-The schema is defined in [`library/schemas/src/bonsai.schema.ts`](https://github.com/PebbleSoftwareInc/pebble-bonsai/blob/main/library/schemas/src/bonsai.schema.ts) and exported as `Config`.
+The template format is defined by the Zod schema in [`library/schemas/src/bonsai.schema.ts`](https://github.com/PebbleSoftwareInc/pebble-bonsai/blob/main/library/schemas/src/bonsai.schema.ts), which is the source of truth for every component's allowed `args`.
 
 - **Node shape**: each node is either a string literal (rendered directly, and itself eligible for `{{ }}` bindings) or an object with:
-  - `type`: a value from `COMPONENT` (see [Component reference](#component-reference)), including the structural `each` and `if` types (see [Structural nodes](#structural-nodes-each--if)).
-  - `args`: props for the resolved React component. All `args` values are eligible for dynamic bindings.
-  - `children`: an optional array of nested `Config` nodes.
-- **Validation**: `Config` is a strict, discriminated union with a tailored prop contract per component (e.g. inputs define `value`, `placeholder`, etc.) — unknown props on a known component type are rejected, not silently dropped. Invalid configs fail fast during parsing.
+  - `type`: a component type (see [Component reference](#component-reference)), including the structural `each` and `if` types (see [Structural nodes](#structural-nodes-each--if)).
+  - `args`: props for the resolved React component. Any `args` value can be a binding.
+  - `children`: an optional array of nested nodes.
 - **Conditional rendering** is a dedicated `if` node, not a generic `condition` prop on any component — see [Structural nodes](#structural-nodes-each--if).
 
+**The renderer does not validate templates; it renders whatever it is given.** The schema is a discriminated union on `type` with a per-component `args` contract, and the Pebble Bonsai platform validates every template against it before rendering. At render time:
+
+- An unknown `type` (one not in the active registry) follows the registry's `fallback`: a plain `<div>` by default (all built-in registries), a component of your choosing, or — with `fallback: "error"` — an error, which the node's error guard logs and renders as nothing.
+- A node that throws while rendering is logged with `console.error` and rendered as nothing; the rest of the tree still renders.
+- The exported `Config` type is `any`, so TypeScript won't catch template mistakes either.
+
+### Validating templates
+
+Validation is a separate, explicit step. The root entry exports `validateTemplate(template, registry, options?)`, which checks a template against a registry — unknown types, each component's `args` against its `propsSchema`, whether it accepts children, and whether it supports the target `mode` (`"web"` or `"pdf"`):
+
+```ts
+import { validateTemplate, pebbleRegistry } from "@pebble-software/bonsai";
+
+const result = validateTemplate(template, pebbleRegistry, { mode: "pdf" });
+if (!result.valid) console.error(result.errors); // [{ path, message, componentType? }]
+```
+
+`pebbleRegistry` carries the platform schema's `args` contract for every built-in. `coreRegistry` and registries built with `createBonsaiRenderer` have no `propsSchema`s, so validating against them checks types and structure but not `args`. If your templates come from an untrusted source, validate them before rendering.
+
 Example node:
 
 ```json
@@ -161,11 +295,14 @@ Complete example templates live in the repo's [`examples/`](https://github.com/P
 
 ## Dynamic data binding
 
-- Use `{{ }}` to declare bindings. A binding must span the *entire* string value — `"{{a}}"` is evaluated, `"{{a}} of {{b}}"` is not (put each placeholder in its own child/string instead). Whitespace inside `{{ }}` is trimmed automatically.
+- Use `{{ }}` to declare bindings. A value is a binding only when the *entire* string starts with `{{` and ends with `}}`; whitespace inside is trimmed.
+  - `"Hello {{name}}"` doesn't start with `{{`, so it renders literally, braces included.
+  - `"{{a}} of {{b}}"` starts and ends with braces but isn't one valid expression, so it fails to parse: it renders blank on the server and as the literal text in the browser. Don't rely on either.
+  - To mix text and values, put each part in its own child (`["{{a}}", " of ", "{{b}}"]`), or build the string in one expression (`"{{ concat(a, ' of ', b) }}"`).
 - Paths support dot notation (`user.email`) and array indexing (`addresses[0].street`).
 - Missing keys resolve to `undefined`; use the `default(value, fallback)` helper for a fallback inline, or handle defaults in host data.
 - Any `args` prop or string child can contain a binding.
-- Besides your own `data`, the instance's top-level state fields — `status`, `expiry`, and `submitting` — are readable from bindings too (e.g. an `if` on `{{submitting}}`).
+- Besides your own `data`, the instance's top-level state fields — `status`, `expiry`, and `submitting` — are readable from bindings (e.g. an `if` on `{{submitting}}`). **These names are reserved:** a top-level `data` key called `status`, `expiry`, or `submitting` is shadowed by the state field and can't be read from a binding. Nest it (`{{order.status}}`) instead.
 - Inside an `each` row, an identifier resolves against the loop alias first (e.g. `applicant.name`), then falls back to the surrounding data for anything the alias doesn't shadow (e.g. `orgName` from outside the loop) — see [Structural nodes](#structural-nodes-each--if).
 - On the client, evaluating a node's bindings is also what subscribes that node to the store — see [Controlled inputs & state](#controlled-inputs--state).
 
@@ -182,9 +319,10 @@ Everything inside `{{ }}` is a small, sandboxed **formula language** — never e
 {{ "literal string" }}     string literal ('single' or "double" quotes)
 {{ 42 }}  {{ 3.14 }}       number literal
 {{ true }}  {{ false }}  {{ null }}
+{{ [a, b, 3] }}            array literal
 ```
 
-Paths only ever read **own properties** of the data you pass in — `__proto__`, `constructor`, and `prototype` are always blocked, and inherited methods/fields are never visible to a template. A missing path evaluates to `undefined`, never throws.
+Paths only ever read **own properties** of the data you pass in — `__proto__`, `constructor`, and `prototype` are always blocked, and inherited methods/fields are never visible to a template. (Own properties such as an array's or string's `length` do work.) A missing path evaluates to `undefined`, never throws.
 
 ### Operators
 
@@ -202,15 +340,15 @@ a ? b : c                                     ternary
 
 ### Helpers
 
-Bare function calls resolve against a fixed, pure helper registry — anything not in the list below is a parse-time error, not a silent no-op:
+Bare function calls resolve against a fixed, pure helper registry:
 
 | Helper | Signature | Notes |
 | --- | --- | --- |
-| `formatDate` | `formatDate(value, format?)` | `format` is a token string (`"YYYY-MM-DD"`, `"HH:mm"`, default `"YYYY-MM-DD"`) or a named style (`"short"`/`"medium"`/`"long"`/`"full"`). Always reads UTC fields, so SSR and the client render the same calendar date regardless of either machine's timezone. |
-| `formatCurrency` | `formatCurrency(value, currency?, locale?)` | Defaults `"USD"` / `"en-US"`. |
+| `formatDate` | `formatDate(value, format?)` | `format` is a token string built from `YYYY`, `MM`, `DD`, `HH`, `mm`, `ss` (default `"YYYY-MM-DD"`), or a named style (`"short"`/`"medium"`/`"long"`/`"full"`, always formatted in `en-US`). Always reads UTC fields, so SSR and the client render the same calendar date regardless of either machine's timezone. Invalid dates render `""`. |
+| `formatCurrency` | `formatCurrency(value, currency?, locale?)` | Defaults `"USD"` / `"en-US"`. Non-numeric values format as `0`. |
 | `upper` / `lower` / `trim` | `(value)` | String utilities; nullish-safe. |
 | `concat` | `(...values)` | Joins with no separator, nullish-safe. |
-| `join` | `(array, separator?)` | Default separator `", "`. |
+| `join` | `(array, separator?)` | Default separator `", "`; `""` for non-arrays. |
 | `default` | `(value, fallback)` | Falls back on `null`/`undefined`/`""` (not `0` or `false`). |
 | `length` | `(value)` | String or array length; `0` otherwise. |
 | `count` | `(array)` | Array length; `0` for non-arrays. |
@@ -218,7 +356,7 @@ Bare function calls resolve against a fixed, pure helper registry — anything n
 | `min` / `max` | `(...values)` | Accepts nested arrays or bare numbers. |
 | `round` | `(value, digits?)` | Default `0` digits. |
 
-A function reached any other way — `data.someField()`, `x.constructor()`, a helper name that isn't registered — is always a hard error rather than `undefined`, so a typo'd helper fails loudly instead of silently rendering blank.
+Anything outside the allowed surface — a helper name that isn't registered, `data.someField()`, `x.constructor()`, an unsupported array method — is rejected, never executed. A rejected (or malformed) expression is logged with `console.error` and evaluates to `undefined`, so the binding renders blank. Watch the console while authoring templates: a typo'd helper shows up there, not as an exception.
 
 Every helper is **pure and synchronous** — no network calls, no `Date.now()`/`new Date()` (ambient clock reads), no randomness. SSR output is a pure function of `(template, data)`, so nothing a helper does can desync a server render from the client.
 
@@ -232,15 +370,16 @@ A fixed set of array methods accept an inline arrow-style callback:
 {{ applicants.every(a => a.verified) }}
 {{ applicants.find(a => a.age > 65) }}
 {{ applicants.map((a, i) => i) }}          -- second param is the index
+{{ join(applicants.map(a => a.name), " & ") }}
 ```
 
 Allowlisted methods: `map`, `filter`, `some`, `every`, `find`. Anything else — `.push()`, `.constructor()`, a method on a non-array value — is rejected before the receiver is even touched. The `a => …` syntax isn't compiled or `eval`'d into a real JavaScript function: the arrow body is walked by the same interpreter that evaluates the rest of the expression, with the parameter bound in a scope frame that falls back to the surrounding data for any other identifier the body references.
 
 ## Structural nodes: each & if
 
-`each` and `if` are structural node types — they control what renders, not what's rendered. Both are strict schemas: an `each`/`if` node with an unrecognized arg fails validation rather than silently ignoring it.
+`each` and `if` are structural node types — they control what renders, not what's rendered. Neither introduces a wrapper element; their children render as siblings.
 
-**`if`** — renders its children when `condition` is truthy, nothing otherwise. No wrapper element is introduced; multiple children render as siblings.
+**`if`** — renders its children when `condition` is truthy, nothing otherwise.
 
 ```json
 {
@@ -260,73 +399,217 @@ Allowlisted methods: `map`, `filter`, `some`, `every`, `find`. Anything else —
 }
 ```
 
-- `items` (required): a binding resolving to an array.
+- `items` (required): a binding that resolves to an array — either a plain path (`{{applicants}}`, `{{order.lines}}`) or a computed expression (`{{applicants.filter(a => a.active)}}`).
 - `as` (required): the alias name each row's children use to refer to the current item (`applicant.name`, not `applicants[i].name`).
 - `index` (optional): an alias for the current loop index (a plain number, not a store path — an index has nothing to write back to).
-- `key` (optional): a binding evaluated per-row to key React's reconciliation (e.g. `{{applicant.id}}`). **Strongly recommended** whenever rows can be reordered or removed — without it, rows fall back to positional (array-index) identity, which can silently reuse a DOM/component instance for the wrong logical row after a reorder.
+- `key` (optional): a binding evaluated per-row to key React's reconciliation (e.g. `{{applicant.id}}`). **Strongly recommended** whenever rows can be reordered or removed — without it, rows fall back to positional (array-index) identity, which can silently reuse a DOM/component instance for the wrong logical row after a reorder. Keys must be unique within the list.
 - Identifiers inside a row resolve against the alias first, then fall back to the surrounding data for anything the alias doesn't shadow — so `{{orgName}}` still works inside a loop over `applicants` even though `orgName` isn't a field on `applicant`.
-- Two-way binding inside a row (e.g. an `<input>` bound to `{{applicant.name}}`) writes back to the row's real store path (`applicants.<index>.name`), as long as `items` is a plain path binding. A computed/filtered array (`{{applicants.filter(...)}}`) has no 1:1 index correspondence back to the store, so rows render read-only in that case.
+- Two-way binding inside a row (e.g. an `input` bound to `{{applicant.name}}`) writes back to the row's real store path (`applicants.<index>.name`) when `items` is a plain path. Rows of a computed `items` expression have no 1:1 mapping back to the store, so inputs in them show their value but are read-only (edits are ignored). To make a filtered list editable, loop over the full array and put an `if` inside the row (`"condition": "{{applicant.active}}"`).
 - `each` nodes can nest; each level's alias stacks on top of the outer one.
 
 ## Controlled inputs & state
 
 - Each mounted `Bonsai` instance gets its own `valtio` store — not a shared module-level singleton — holding `{ status, expiry, data, submitting }`. It's reachable only via React context, from components mounted inside that instance's subtree.
-- `useUpdateData()` (call it from inside the subtree) returns an `updateData(path, value)` function that mutates the store's `data` using the same path grammar as bindings.
-- Controlled components registered in `controlledInputMap` automatically wire up change handlers:
-  - Value props point at a binding (e.g. `value: "{{profile.name}}"`).
-  - Change events feed straight into `updateData` — no debounce, no local-echo state. Per-node subscriptions make every keystroke's store write and re-render cheap enough that this stays snappy, and it's what lets dependent expressions (`{{price*qty}}`, an `if` condition) update in the same event as the keystroke that changed them.
+- `useUpdateData()` returns an `updateData(path, value)` function that mutates the store's `data` using the same path grammar as bindings (`"applicants.0.name"`, `"addresses[0].street"`). Call it from a custom component you've registered (see [Extending Bonsai](#extending-bonsai)). It only works in the client render: the server render has no store, so a component that calls `useUpdateData()` unconditionally will throw during SSR.
+- Controlled components (see the list in [Component reference](#component-reference)) automatically wire up a value prop and change handler:
+  - Bind the value prop to a plain path (e.g. `value: "{{profile.name}}"`) — that path is where edits are written. A formula (`value: "{{first + ' ' + last}}"`) has no path to write to, so the input shows its result and is read-only.
+  - Change events feed straight into the store — no debounce, no local-echo state. Per-node subscriptions make every keystroke's store write and re-render cheap enough that this stays snappy, and it's what lets dependent expressions (`{{price * qty}}`, an `if` condition) update in the same event as the keystroke that changed them.
   - When something mutates the store's data, every node whose binding reads that path re-renders; unrelated nodes don't.
-- Non-controlled components simply receive evaluated props and behave as standard React elements.
-- Submission is handled internally: the client render mounts its own `<form>` and POSTs `{ data: store.data }` to `captureUrl` on submit.
-- **Reactivity model**: every leaf reads the store itself (via `valtio`'s `useSnapshot`) and evaluates its own bindings against that snapshot — the read *is* the subscription. A node with no bindings at all (a plain layout `<div>`) is detected and skipped from this entirely, so it never re-renders due to an unrelated store write. This is what keeps a keystroke in one field from re-rendering the rest of the form.
+- Non-controlled components simply receive their evaluated `args` as props and behave as standard React elements.
+- The store's `data` is deep-copied from the `data` prop *for plain objects and arrays* — an instance never mutates the object you passed in, and two instances seeded from the same plain-object `data` still get fully independent state. **Non-plain values nested inside `data` (class instances, `Map`/`Set`, functions, `Date`, `File`, etc.) are passed through by reference, not cloned.** If `data` nests something like `{ profile: new SomeClass() }`, that nested value is shared between every instance seeded from it, and writes through it are visible to the caller. Keep non-plain values out of `data` if you need per-instance isolation.
+- **Reactivity model**: every leaf reads the store itself (via `valtio`'s `useSnapshot`) and evaluates its own bindings against that snapshot — the read *is* the subscription. A node with no bindings at all (a plain layout `div`) is detected and skipped from this entirely, so it never re-renders due to an unrelated store write. This is what keeps a keystroke in one field from re-rendering the rest of the form.
 
 ## Component reference
 
-The full, authoritative list of component types is the `COMPONENT` enum in `@bonsai/constants` ([`library/constants/src/components.ts`](https://github.com/PebbleSoftwareInc/pebble-bonsai/blob/main/library/constants/src/components.ts)) — `componentMap` (`src/lib/ui/registry.ts`) has an entry for every value in it.
+The full list of built-in component types is the `COMPONENT` enum in [`library/constants/src/components.ts`](https://github.com/PebbleSoftwareInc/pebble-bonsai/blob/main/library/constants/src/components.ts); allowed `args` for each are in the [schema](#configuration-schema).
 
 | Category | Schema types |
 | --- | --- |
 | Structural (control what renders, not a real element) | `each`, `if` |
-| Plain elements | `div`, `span`, `a`, `p`, `h`, `ol`, `ul`, `li`, `image` |
+| Plain elements | `div`, `span`, `a`, `p`, `h`, `ol`, `ul`, `li`, `image` (an `<img>`; renders nothing when `src` is empty) |
 | Layout / display | `card` (+ `card-header`, `card-title`, `card-description`, `card-content`, `card-footer`, `card-action`, `card-icon`), `accordion` (+ `accordion-item`, `accordion-trigger`, `accordion-content`), `collapsible` (+ `collapsible-trigger`, `collapsible-content`), `alert`, `avatar`, `badge`, `separator`, `skeleton`, `loader`, `progress` |
 | Tabular | `table` (+ `table-header`, `table-body`, `table-footer`, `table-head`, `table-row`, `table-cell`, `table-caption`) |
-| Interactive / controlled inputs | `input` (subtypes: `text`, `email`, `password`, `number`, and a `default` fallback), `textarea`, `checkbox`, `switch`, `otp`, `calendar`, `map`, `signature`, `input-group` (+ `input-group-text`, `input-group-addon`, `input-group-input`, `input-group-button`, `input-group-textarea`) |
+| Inputs | `input` (`type`: `text` (default), `email`, `password`, `number`), `textarea`, `checkbox`, `switch`, `otp`, `input-group` (+ `input-group-text`, `input-group-addon`, `input-group-input`, `input-group-button`, `input-group-textarea`) |
+| Heavy inputs (preset only) | `calendar`, `signature` |
 | Other | `button`, `label` |
 
-Controlled inputs (registered in `controlledInputMap` — `input`, `otp`, `checkbox`, `textarea`, `input-group-input`, `input-group-textarea`, `switch`, `signature`, `calendar`, `map`) automatically wire up a value prop and change handler as described in [Controlled inputs & state](#controlled-inputs--state). Everything else just receives its evaluated `args` as props.
+**Controlled inputs** — `input`, `textarea`, `checkbox`, `switch`, `otp`, `input-group-input`, `input-group-textarea`, plus `calendar` and `signature` when their preset is registered — two-way bind as described in [Controlled inputs & state](#controlled-inputs--state):
 
-> Need a component that isn't listed? Add it to `COMPONENT`/`COMPONENT_LIST` in `@bonsai/constants`, add its prop contract to `@bonsai/schemas`, and register the React implementation in `componentMap` (and `controlledInputMap` if it should behave as a controlled input) — see [Extending Bonsai](#extending-bonsai).
+| Type | Bound prop | Stored value |
+| --- | --- | --- |
+| `input`, `textarea`, `otp`, `input-group-input`, `input-group-textarea` | `value` | the input's string value; an `input` with `type: "number"` stores a number (or `""` while empty) |
+| `checkbox`, `switch` | `checked` | `boolean` |
+| `calendar` | `selected` | the selected date |
+| `signature` | `value` | a data-URL image string, or `null` when cleared |
+
+Everything else just receives its evaluated `args` as props.
+
+**Heavy inputs** are not in the `/core` registry: with `@pebble-software/bonsai/core`, a `calendar` or `signature` node renders as a plain `<div>` until you add its preset (see [Extending Bonsai](#extending-bonsai)). The root entry includes both.
 
 ## Styling
 
-Bonsai is styled with **Tailwind CSS v4**. Components emit plain Tailwind utility classes, and templates can pass any additional utilities through `className` on any node.
+Bonsai is styled with **Tailwind CSS v4**. Components emit plain Tailwind utility classes, and templates can pass additional utilities through `className` on any node.
+
+```css
+/* your app's Tailwind v4 entry, e.g. app.css */
+@import "@pebble-software/bonsai/index.css";
+@source "./src"; /* your own templates/components */
+```
 
-- The design system lives in [`src/index.css`](https://github.com/PebbleSoftwareInc/pebble-bonsai/blob/main/apps/bonsai/src/index.css): an `@theme` token set (an OKLCH color palette with swappable accent colors, typography, shadows) plus base and utility layers, custom fonts (Sora, Fredoka, and Great Vibes for signatures) loaded via `@font-face`, and style overrides for the embedded map (MapLibre) and chart (Recharts) widgets.
-- Every rendered tree is wrapped in a `.bonsai-root` element carrying a `data-mode` attribute (`web` / `pdf` / `preview`), so hosts can scope their own overrides per render mode.
-- **Getting the stylesheet**: inside the Pebble Bonsai platform, CSS is compiled per-template at form-creation time — only the classes a template actually uses are emitted. When consuming this package standalone, compile the styles with your own Tailwind v4 build: import the Bonsai theme and add the package (and your template sources) as content via `@source` so the utilities your templates reference are generated. A prebuilt, ready-to-import stylesheet export is planned while the packaging story stabilizes during the preview period.
-- **Theming**: the theme is token-driven — redefine the CSS variables (e.g. `--color-main`, `--font-heading`) after the theme to restyle every component at once, or target `.bonsai-root` descendants for finer overrides.
+- **Compile it with your own Tailwind v4 build.** `index.css` ships as uncompiled Tailwind source: it opens with `@import "tailwindcss"` and carries the full theme (an OKLCH color palette with swappable accent colors, typography, shadows) and base styles. Its `@source "./"` points Tailwind at Bonsai's compiled `dist/`, so every class the built-in components use is generated. `tailwindcss` and `tw-animate-css` are optional peers for this reason. None of the JavaScript entry points import it; it is the only side effect the package declares (`"sideEffects": ["**/*.css"]`), so bundlers can tree-shake everything else.
+- **It styles the whole page, not just Bonsai.** The stylesheet includes Tailwind's Preflight reset plus base rules for `body` (font, background, text color) and `h1`–`h6` (heading font). On a page that has its own design system, load it deliberately — for example, only on the routes that render Bonsai.
+- **Fonts load from Pebble's CDN.** Sora, Fredoka, and Great Vibes (used by the signature control) are declared with `@font-face` pointing at `https://brand.pebble.software/fonts/`. If you use a Content Security Policy, allow that origin in `font-src`, or override `--font-body`, `--font-heading`, and `--font-signature` with fonts you host.
+- **Scoping**: every rendered tree is wrapped in a `.bonsai-root` element carrying a `data-mode` attribute (`web` / `pdf` / `preview`), so hosts can scope their own overrides per render mode.
+- **Accent colors**: set `data-theme` on any ancestor (`<body data-theme="indigo">`) to switch the accent palette. Available values: `red`, `orange`, `amber`, `yellow`, `lime`, `green`, `emerald` (default), `teal`, `cyan`, `sky`, `blue`, `indigo`, `violet`, `purple`, `fuchsia`, `pink`, `rose`.
+- **Theming**: the theme is token-driven — redefine the CSS variables (e.g. `--color-main`, `--font-heading`) after the stylesheet to restyle every component at once, or target `.bonsai-root` descendants for finer overrides.
+- **Utilities in your templates**: a `className` utility that no built-in component uses (say, `grid-cols-5`) is only generated if your build also scans the templates that use it — add their location with `@source`. Inside the Pebble Bonsai platform, CSS is compiled per template so this never comes up.
 
 ## Extending Bonsai
 
-1. **Add a component**:
-   - Extend `COMPONENT` and `COMPONENT_LIST` in `@bonsai/constants`.
-   - Add prop validation in `@bonsai/schemas`.
-   - Register the React implementation in `componentMap`.
-   - Optionally register controlled behaviour in `controlledInputMap`.
-2. **Custom data handling**:
-   - Use `useUpdateData()` from a component mounted inside a `Bonsai` instance's subtree for simple mutations.
-3. **Alternate styling**:
-   - Redefine the theme's CSS variables before mounting Bonsai — see [Styling](#styling).
+### Add or replace components
+
+`createBonsaiRenderer` builds a renderer whose registry is `options.registry` (the core set by default) plus whatever components you pass. Your entries win on a key collision, so you can add new types or swap out built-ins. Call it **once, at module scope** — each call returns a new component type, so calling it during render would remount the whole tree every time.
+
+```tsx
+import { createBonsaiRenderer, useUpdateData } from "@pebble-software/bonsai/core";
+import { calendarPreset } from "@pebble-software/bonsai/presets/calendar";
+
+// A custom component receives the node's evaluated `args` as props.
+function Rating({ value = 0, onChange }: { value?: number; onChange?: (next: number) => void }) {
+  return (
+    <div role="radiogroup" aria-label="Rating">
+      {[1, 2, 3, 4, 5].map((n) => (
+        <button key={n} type="button" aria-pressed={n <= value} onClick={() => onChange?.(n)}>
+          {n <= value ? "★" : "☆"}
+        </button>
+      ))}
+    </div>
+  );
+}
+
+// Custom components can also write to the instance's store directly.
+// (Client render only — `useUpdateData` throws during SSR.)
+function ClearButton({ path }: { path: string }) {
+  const updateData = useUpdateData();
+  return (
+    <button type="button" onClick={() => updateData(path, "")}>
+      Clear
+    </button>
+  );
+}
+
+export const { Bonsai } = createBonsaiRenderer({
+  components: {
+    ...calendarPreset.components,
+    rating: Rating,
+    "clear-button": ClearButton,
+  },
+  controlledInputs: {
+    ...calendarPreset.controlledInputs,
+    // `{ "type": "rating", "args": { "value": "{{review.stars}}" } }` now
+    // two-way binds `review.stars`.
+    rating: { valueProp: "value", changeProp: "onChange", extractor: (next) => next },
+  },
+});
+```
+
+A controlled-input entry names the prop that carries the value (`valueProp`), the prop that reports a change (`changeProp`), and how to turn whatever that change prop is called with into the value to store (`extractor`). An entry can also be a map of `args.type` → entry with a `default` fallback, as the built-in `input` uses.
+
+Custom types aren't part of the platform schema, so templates that use them only render with your renderer.
+
+### Bring your own registry
+
+For a component library of your own, declare a full `BonsaiRegistry` instead of layering onto the built-ins. Each entry can carry a `propsSchema` (used by `validateTemplate`), `capabilities`, and a `controlled` binding (`{ valueProp, changeProp, extract }`):
+
+```tsx
+import { createBonsaiRenderer, defineBonsaiRegistry, defineComponent } from "@pebble-software/bonsai/core";
+import { z } from "zod";
+
+// `Rating` as defined in the previous example.
+const acmeRegistry = defineBonsaiRegistry({
+  id: "acme-ui",
+  version: "1.0.0",
+  fallback: "error", // unknown types fail instead of rendering a <div>
+  components: {
+    rating: defineComponent({
+      component: Rating,
+      propsSchema: z.object({ value: z.string().optional() }),
+      capabilities: ["bindings", "formField", "ssr"],
+      controlled: { valueProp: "value", changeProp: "onChange", extract: (next) => next },
+    }),
+  },
+});
+
+export const { Bonsai } = createBonsaiRenderer({ registry: acmeRegistry });
+```
+
+A `registry` prop on an individual `<Bonsai>` replaces the renderer's registry for that instance only. `extendRegistry(base, preset)` layers a preset-shaped `{ components, controlledInputs }` over any registry — `createBonsaiRenderer` uses it for its `components`/`controlledInputs` options.
+
+### Contributing a built-in component
+
+To add a component to Bonsai itself (in this monorepo):
+
+1. Add it to `COMPONENT` in `library/constants/src/components.ts`.
+2. Add its node and `args` contract to `library/schemas/src/bonsai.schema.ts`, and list it in `PEBBLE_COMPONENT_SCHEMAS` there (that is where `pebbleRegistry` gets its `propsSchema`).
+3. Register the React implementation in `coreComponents` (`apps/bonsai/src/renderer/core-registry.ts`) — or, if it pulls in a heavy dependency, in a new preset under `apps/bonsai/src/renderer/presets/`, with a matching entry in `vite.config.ts` and `package.json#exports`.
+4. If it's an input, add its binding to `coreControlledInputs` (or the preset's `controlledInputs`).
+
+## Performance
+
+- **Compilation is cached per template identity** — reusing the same `Config` object across many `Bonsai` instances (or across re-renders) compiles its expressions exactly once, no matter how many instances mount. Passing a fresh object (e.g. `structuredClone`d or freshly parsed) is a cache miss and compiles again, so parse a template once and keep the object — the same by-identity principle as [the `data` prop](#the-data-prop-seeded-by-reference).
+- **A field update only re-evaluates its own binding** — thanks to per-node `useSnapshot` subscriptions (see [Controlled inputs & state](#controlled-inputs--state)), editing one row in an `each` list of any size re-evaluates only that row's bindings, not the whole list.
+- **Long visible trees**: Bonsai renders every node in the template; it does not paginate or virtualize a long tree for you. For a very long visible page (a long `each` list, a long scrollable form), consider handling it at the host-application layer:
+  - CSS `content-visibility: auto` on off-screen sections/rows, so the browser skips layout and paint work for content that isn't visible yet.
+  - Pagination or "load more" — page the `data` array yourself (e.g. only pass the current page's `rows` into `data`) rather than rendering thousands of `each` rows at once.
+  - Virtualization (e.g. `react-window`/`react-virtual`) for read-only/display rows.
+
+  **Do not virtualize rows that contain form fields without preserving focus and input state.** A naive virtualized list unmounts off-screen DOM nodes as the user scrolls; if a row's `<input>` is focused or mid-keystroke when it scrolls out and gets unmounted, the focus and any in-progress keystroke are lost. If you virtualize a form with Bonsai-rendered rows, keep the underlying `data` (Bonsai's store) intact across virtualization and make sure the currently-focused row is never unmounted while the user is actively editing it.
+- **Heavy controls are opt-in and lazy-loadable**: the calendar and signature controls are not part of the core bundle — `@pebble-software/bonsai/core` never pulls in `react-day-picker` or `react-signature-canvas` (see [Package exports](#package-exports)). Import only the preset(s) a given template actually uses, and if a screen only sometimes needs one, load it on demand with `React.lazy`:
+
+  ```tsx
+  import { lazy, Suspense } from "react";
+  import { createBonsaiRenderer, type Config } from "@pebble-software/bonsai/core";
+
+  // Module scope: the preset is fetched (and the renderer created) once, the
+  // first time a <SignatureBonsai> actually renders.
+  const SignatureBonsai = lazy(async () => {
+    const { signaturePreset } = await import("@pebble-software/bonsai/presets/signature");
+    return {
+      default: createBonsaiRenderer({
+        components: signaturePreset.components,
+        controlledInputs: signaturePreset.controlledInputs,
+      }).Bonsai,
+    };
+  });
+
+  export function SignStep({ template }: { template: Config }) {
+    return (
+      <Suspense fallback={<p>Loading signature pad…</p>}>
+        <SignatureBonsai template={template} />
+      </Suspense>
+    );
+  }
+  ```
+
+  This keeps the initial bundle to the core renderer (see the gzip budgets in [`scripts/check-bundle-size.mjs`](https://github.com/PebbleSoftwareInc/pebble-bonsai/blob/main/apps/bonsai/scripts/check-bundle-size.mjs)) and defers the cost of any heavy control until a screen that actually renders one is reached.
 
 ## Development
 
 Issues and pull requests are welcome at [PebbleSoftwareInc/pebble-bonsai](https://github.com/PebbleSoftwareInc/pebble-bonsai). This package lives at `apps/bonsai` in the monorepo.
 
+```bash
+pnpm install
+pnpm --filter @pebble-software/bonsai run build
+```
+
+From `apps/bonsai`:
+
 ```bash
 pnpm lint        # Static analysis using ESLint
 pnpm test        # Run the test suite (vitest)
 pnpm type-check  # TypeScript without emit
-pnpm build       # Bundles dist/ (ESM + type declarations) via Vite
+pnpm build       # Bundles dist/ (ESM + type declarations) via Vite and copies the raw index.css theme
+pnpm size-check  # Checks each entry against its gzip budget (run after build)
 ```
 
-`dist/` contains the ESM bundle and TypeScript declarations consumed by downstream applications. The shared `@bonsai/constants` and `@bonsai/schemas` workspaces are bundled in, so the published package has no workspace dependencies.
+`dist/` contains the ESM bundle, TypeScript declarations, and the uncompiled `index.css` theme consumed by downstream Tailwind builds. The shared `@bonsai/constants` and `@bonsai/schemas` workspaces are aliased to their sources and bundled in, so the published package has no workspace dependencies.