# ChargeForms Builder — Architecture

This document is the foundation referenced by every future milestone. It exists
so a new contributor (or a future session) can understand *why* the builder is
shaped the way it is without archaeology. Update it whenever an architectural
decision changes — a stale architecture doc is worse than none.

Status: **Milestone 3 — Interaction Layer (selection, multi-select,
clipboard, floating toolbar, keyboard) complete.** See the Milestone 3
section near the end of this document for what shipped, the selection
architecture it added, a real Playwright-tooling bug it uncovered along the
way, and the explicit list of interaction-polish work still open (context
menu, breadcrumbs, command palette, drag insertion lines, canvas visual
redesign). Milestones 1 and 2 (below) are unchanged history — this
milestone was built on top of them without touching the reducer/history/
dnd/keyboard-table/autosave systems they established.

Milestone 1 status note (historical): this milestone deliberately did not add
new user-facing features or UI polish. It replaced the load-bearing plumbing
(state, history, autosave, keyboard, drag orchestration, field registry) so
that milestones 2+ (nested containers, multi-step navigation, calculations,
AI assist, revision history, a11y pass, virtualization) can be built as
additions, not rewrites.

---

## 1. Feature-based folder structure

```
assets/src/builder/
  index.js                 # Entry point: mounts <App/> into #chargeforms-app
  app/
    App.js                 # Composition root — layout + providers only, no business logic
  core/                     # Framework-agnostic-ish engine: owns the document, not the UI
    ids.js                 # ID generation
    tree.js                 # Field-tree operations (works today on flat arrays, ready for nesting)
    store/
      actionTypes.js
      actions.js             # Action creators, each tagged with a history strategy
      builderReducer.js       # Pure reducer over { id, title, fields }
      BuilderProvider.js       # Wires reducer + history + selection + ui state into context
      useBuilderStore.js        # useBuilderStore() — the one hook features consume
      selectors.js               # Derived data (counts, active field, flattened tree)
    history/
      historyTypes.js            # Shared history-strategy constants
    autosave/
      draftStorage.js            # localStorage read/write, namespaced per form id
      useAutosave.js              # Debounced local draft + crash-recovery detection
    keyboard/
      shortcuts.js                # Declarative shortcut table
      useKeyboardShortcuts.js      # Binds the table to store actions, guards text inputs
    dnd/
      useCanvasDnd.js               # Sensors + drag-start/drag-end orchestration
  fields/                    # The field-type system — the plugin's real "content model"
    registry.js                # registerFieldType()/getFieldType()/getAllFieldTypes() — extensibility seam
    builtins.js                 # The ~50 shipped field-type definitions (data, not components)
    createField.js               # Factory: field-type definition -> a real field instance
    conditional.js                # Conditional-logic value helpers (normalize/empty builders)
    countries.js                   # Static country list data
    index.js                        # Barrel — stable import surface for the rest of the app
  features/                  # One folder per UI zone, each owning its own components
    toolbar/
      Toolbar.js
      DeviceSwitcher.js
    canvas/
      Canvas.js
      CanvasField.js
      FieldPreview.js
      QuickAddMenu.js
      InsertPoint.js
    settings-panel/
      FieldSettings.js
      ConditionalLogicEditor.js
    history/
      HistoryPanel.js
  shared/
    styles/
      tokens.css                # Builder-only design tokens, built ON TOP of .chargeforms-wrap's --fc-* scale
    hooks/
      useDebounce.js
  style.css                  # Existing visual styles — untouched this milestone (see §6)
```

Rule of thumb for where new code goes: **`core/` never imports from `features/`.**
`features/*` may import from `core/` and `fields/`, and from each other only via
props/context — never reach into another feature's internal files.

---

## 2. Application architecture

Three layers, one-directional dependency:

```
core/store  (the document + selection + undo/redo)
     ^
     |  useBuilderStore()
     |
features/*  (render the document, dispatch actions)
     ^
     |  props
     |
app/App.js  (composes features into the 4-zone layout)
```

The store is the single source of truth for the form being edited. Every
feature component reads from it via `useBuilderStore()` and writes to it by
dispatching actions — no feature holds a second copy of field data in local
state (field-level UI state like "is this settings section expanded" is fine
to keep local; the *data* never is).

---

## 3. Component hierarchy

```
<App>
  <BuilderProvider>                       core/store
    <DndProvider>                         core/dnd (wraps @dnd-kit's DndContext)
      <Toolbar />                         features/toolbar
      <div class="fc-builder-grid">
        <CanvasColumn>
          <DeviceSwitcher />               features/toolbar
          <Canvas>                         features/canvas
            <InsertPoint />
            <CanvasField>                  (recursive-ready: renders .children if present)
              <FieldPreview />
            </CanvasField>
          </Canvas>
        </CanvasColumn>
        <SidePanel>
          <FieldSettings>                  features/settings-panel  (tab: customize)
            <ConditionalLogicEditor />
          </FieldSettings>
          <HistoryPanel />                 features/history         (tab: history)
        </SidePanel>
      </div>
      <DragOverlay />
    </DndProvider>
  </BuilderProvider>
</App>
```

---

## 4. State management architecture

`useReducer` + `Context`, not Redux/Zustand — the document is small (one form's
fields), doesn't need cross-tab sync or time-travel middleware infrastructure,
and every engineer touching this code already knows `useReducer`. Revisit only
if a real need appears (e.g. collaborative editing) — see §14.

Store shape (`BuilderProvider`'s context value):

```js
{
  form: { id, title, fields },   // the undo/redo-able document — see core/store/builderReducer.js
  selection: { activeId },        // ephemeral, NOT part of history
  ui: { rightTab, device, isFullscreen },  // ephemeral, NOT part of history
  dispatch,                        // (action) => void — the only way to mutate `form`
  undo, redo, restoreSnapshot, canUndo, canRedo, timeline,
  select, setUi,
}
```

Splitting `form` (historied) from `selection`/`ui` (not historied) fixes a real
bug class: in the old `App.js`, everything lived in one component's
`useState` calls with no distinction, which made it easy to accidentally wire
a UI-only change through the same `setFields` path as a data change. The new
reducer only ever touches `form`; selection and UI toggles are plain state
that can't corrupt the document or pollute undo history.

Every action is tagged with a **history strategy** (see §9) instead of the
store deciding by field type — this keeps the reducer a pure function of
`(state, action) -> state` with zero side effects, and keeps the
undo/redo policy in one place (`BuilderProvider`) instead of scattered
`if (fieldType === 'x')` checks.

---

## 5. Builder engine architecture

"Engine" = everything under `core/` — it has no opinion about how fields are
drawn, only about what a valid document looks like and how it can change.
Concretely:

- `core/tree.js` — the only code allowed to reshape the `fields` array
  (`insertField`, `updateField`, `removeField`, `findField`, `flattenFields`).
  Every one of these already operates on a **tree** (a field may have a
  `children` array), not just a flat list — see §20. Nothing above the
  reducer touches `state.fields` directly with array splicing; that was
  the old `Canvas.js`'s `duplicate()`/`remove()`, which is exactly the kind
  of logic that silently breaks once fields can nest.
- `core/store/builderReducer.js` — the only code allowed to call `core/tree.js`.
- `core/ids.js` — one ID scheme (`f_<random>`), used everywhere a field or
  a duplicate needs an identity, so there's one place to change if IDs ever
  need to be collision-proof server-side instead of client-random.

---

## 6. Design system foundation

The builder already renders inside `.chargeforms-wrap`, which defines the
plugin-wide token scale (`--fc-primary*`, `--fc-border`, `--fc-text-*`,
`--fc-space-*`, `--fc-card-shadow`, `--fc-ease`, etc. — see `assets/css/admin.css`).
That's the right call and this milestone does not fight it: `shared/styles/tokens.css`
adds only the handful of tokens the builder needs that the shared scale
doesn't have an opinion on (panel widths, canvas z-index stack, drag-specific
motion durations) — every color/spacing/shadow/type value still resolves to
a `--fc-*` token, never a new hardcoded value.

**Explicitly out of scope for this milestone:** reformatting the existing
1600-line `style.css` to use the new tokens file, or any visual redesign.
That's real work with real regression risk and belongs in a dedicated polish
milestone with before/after Playground screenshots, not folded into a
plumbing refactor.

---

## 7. Four-zone layout

Toolbar (top, full width) / Left Sidebar (palette) / Canvas (center) / Right
Sidebar (settings) is already the shape of the current builder — `Toolbar`
sits above a grid of `Canvas` + a tabbed `SidePanel` that hosts palette,
settings, and history as tabs rather than three permanently-visible columns.
That tabbed-not-tri-column layout is a deliberate, existing decision (screen
real estate at laptop widths — see the topbar-overflow fix from the previous
session) and this milestone keeps it. `Toolbar` itself is extracted from
`App.js` into `features/toolbar/Toolbar.js` as a real component instead of
350 lines of inline JSX.

---

## 8. Autosave architecture

Two independent layers, because they answer two different questions:

1. **Local draft (`core/autosave/draftStorage.js` + `useAutosave.js`)** —
   answers "did the browser tab crash / did I navigate away by accident?"
   Debounced (800ms) write of `{ id, title, fields, savedAt }` to
   `localStorage`, namespaced `chargeforms_draft_<formId|'new'>`. On mount,
   if a draft exists and is newer than the last known server save, the UI
   can offer "Restore unsaved changes?" — the mechanism ships this
   milestone; the actual prompt UI is a milestone-2 concern (explicitly
   deferred per "no UI polish yet"). Cleared on successful server save.
2. **Server save** — unchanged this milestone: an explicit "Save Form"
   action (`PUT`/`POST` to `/chargeforms/v1/forms`). Auto-*publishing* to the
   server on every keystroke is not planned — explicit save matches every
   competitor's model and avoids surprising a user with half-finished edits
   going live.

---

## 9. History / undo-redo architecture

Full-state snapshot stack (`past[]` / `future[]` of `{ id, title, fields }`),
same approach as before — forms are small (dozens of fields, not thousands),
so structural sharing/patches would be premature optimization. What's new:
**every action declares a history strategy**, and the store applies it
consistently instead of the old "push a snapshot on literally every
`setFields` call" behavior:

- `immediate` — structural changes (add, insert, remove, duplicate, reorder,
  paste, load form). Commits a checkpoint before the action applies, clears
  `future`.
- `debounced` — rapid-fire edits to the same target (typing in a label,
  dragging a range-slider settings input). Keyed by `action.meta.debounceKey`
  (usually the field id + prop); a burst of edits to the *same* key within
  500ms collapses into a single checkpoint, so pressing Undo after typing a
  label undoes the whole edit, not one keystroke. A burst to a *different*
  key flushes the pending one immediately first.
- `none` — selection changes, tab switches, loading a form fresh from the
  server. Never touches history.

This fixes a real bug in the old implementation: `FieldSettings`'s `set()`
called `updateField` → `setFields` on every keystroke, which pushed one
undo-stack entry per character typed.

`restoreSnapshot(index)` (jump to any point in the flattened
`[...past, present, ...future]` timeline) is preserved from the old
`App.js` — it's a genuinely good pattern (Figma/Notion-style history list)
and moves into `core/store/BuilderProvider.js` unchanged in behavior.

---

## 10. Selection model

`selection: { activeId }` — single-select, intentionally. Multi-select
(shift-click range, cmd-click toggle, marquee-select on canvas) is real,
wanted, and explicitly deferred to a later milestone; the shape is chosen so
that migration is additive (`activeId` becomes `activeIds: []`, or stays as
"last selected / primary" alongside a new `selectedIds` set) rather than a
rewrite. Selection lives outside the historied `form` state (see §4) — moving
your cursor between fields should never be an undo step, matching every
reference app (Figma, Notion, Webflow).

---

## 11. Drag-and-drop architecture

Stays on `@dnd-kit` (confirmed direction — see decision log below), extracted
from `App.js` into `core/dnd/useCanvasDnd.js`: sensors config (pointer +
touch, distance/delay activation constraints tuned to not swallow plain
clicks — this was already correct, just relocated), `handleDragStart`,
`handleDragEnd`, `handleDragCancel`. The hook depends only on `dispatch` and
`form.fields`, not on any feature component, so `Canvas.js` and `Toolbar.js`
both stay free of drag-orchestration logic — they only render `useDraggable`/
`useSortable`/`useDroppable` primitives, same as today.

Nested drop targets (dropping a field *into* a container, not just between
siblings) are not implemented this milestone — `core/tree.js`'s
`insertField(fields, field, index, parentId)` already accepts a `parentId`
so the drag-end handler has a real seam to call into once container fields
ship, instead of needing a rewrite of the drag logic itself.

---

## 12. Keyboard shortcut system

`core/keyboard/shortcuts.js` — a declarative table (`{ combo, description,
handler, guard }`), not scattered `addEventListener('keydown', ...)` calls
per feature. `useKeyboardShortcuts(handlers)` binds it once at the `App`
level, resolves `Cmd` vs `Ctrl` by platform, and guards against firing while
the user is typing in an `<input>`/`<textarea>`/`[contenteditable]` (except
for shortcuts that must always work, like Escape). Shipped this milestone:
Undo, Redo, Save, Duplicate selected field, Delete selected field, Escape to
deselect. The table is the extensibility seam for milestone-later shortcuts
(zoom, search palette, etc.) — add a row, not a new listener.

---

## 13. Plugin extensibility architecture

`fields/registry.js` turns the field-type list from a hardcoded array
(`fields.js`'s old `FIELD_TYPES`) into a real registry:
`registerFieldType(definition)` / `getFieldType(type)` / `getAllFieldTypes()`.
Built-in types (`fields/builtins.js`) are registered at module load, but
nothing about the registry requires that — a separate WordPress plugin (a
"ChargeForms add-on") can register a new field type without patching this
codebase, the same extensibility pattern Gutenberg itself uses for blocks.

**Now wired to a public global** in `assets/src/builder/index.js`, because
the ChargeForms Bookings add-on needs exactly the case this section always
described. Earlier milestones deferred it on the grounds that a public
global is a support surface — docs and versioning promises — not just
code; both of those are committed to below.

```js
window.chargeformsBuilder.registerFieldType( {
    type: 'booking_calendar',   // required, unique
    label: 'Booking Calendar',
    icon: 'calendar',           // a Lucide name from shared/icon/Icon.js
    group: 'advanced',
} );
```

Also exposed: `getFieldType( type )`, `getAllFieldTypes()` and
`apiVersion` (currently `1`) so an add-on can feature-detect instead of
guessing at availability.

**Versioning promise.** `apiVersion` changes only when this contract's
shape changes, independently of the plugin's own release version. Adding
to the contract is a minor change that leaves `apiVersion` alone;
changing or removing anything already in it bumps `apiVersion`.

The global is assigned at module scope rather than inside the
`DOMContentLoaded` handler, so an add-on script enqueued after the builder
bundle can register during its own top-level execution and still land
before the app mounts and first reads the registry.

Registering a type makes it appear in the builder palette. A type the
add-on has not also taught the canvas to preview falls through
`Canvas.js`'s switch to its default rendering — so an add-on shipping a
genuinely custom preview still needs its own canvas contribution, which
is deliberately a separate concern from being *listed* as a field type.

---

## 14. Future AI integration points

Named explicitly so later work has a documented seam instead of bolting AI
in wherever's convenient:

- **Toolbar "AI" entry point** — already listed in the top toolbar spec;
  reserved slot in `features/toolbar/Toolbar.js`, not built this milestone.
- **`fields/createField.js`** is the single choke point where a field
  instance is constructed — an "AI: generate a field from a description"
  feature calls into the same factory a human's palette click does, so AI
  output can never produce a differently-shaped field than the UI does.
- **`core/store/actions.js`** is the only way to mutate the document — an
  AI assistant proposing "add these 4 fields and reorder" is just a sequence
  of the same actions a human triggers, which means it's automatically
  undo-able, autosaved, and validated exactly like manual edits, for free.
- **History `restoreSnapshot`** doubles as an AI "preview then confirm"
  mechanism later: apply the AI's proposed change, let the user see it live
  on canvas, Undo is the built-in "reject the suggestion" path.

---

## 15. Performance strategy

This milestone's job is to not make performance *worse* while fixing the
undo-per-keystroke bug (§9's debouncing is itself a perf win — fewer state
snapshots, fewer re-renders during typing). Concretely:

- `useBuilderStore()`'s context value is memoized (`useMemo`) so components
  that only read `ui.device`, say, don't re-render on every keystroke in a
  field label — everything currently re-renders together because `App.js`
  holds all state directly; splitting into `form` / `selection` / `ui` slices
  (§4) is what makes selective consumption possible later.
- `core/tree.js` functions are pure and allocate new arrays only along the
  path that changed (standard immutable-update shape), not a deep clone of
  the whole tree.
- Explicitly deferred to a later milestone, once there's a real 100+-field
  form to profile against: canvas virtualization (`react-window` or
  equivalent), `React.memo` on `CanvasField`/`FieldPreview`. Adding either
  now, against a builder nobody has stress-tested, is guessing.

---

## 16. Accessibility strategy

Not a retrofit — baked into the primitives this milestone introduces:

- `useKeyboardShortcuts` (§12) is itself an accessibility feature (keyboard
  parity with mouse drag for reordering is a later milestone item —
  `@dnd-kit`'s `KeyboardSensor` is the documented path and slots into
  `core/dnd/useCanvasDnd.js`'s existing `useSensors` call without touching
  anything else).
- Selection (§10) is designed to drive `aria-selected`/focus management from
  one place (`selection.activeId`) rather than each feature inferring "am I
  the selected one" independently.
- Full WCAG AA pass (contrast audit, screen-reader labeling of the canvas's
  drag handles, focus trapping in the rename modal, `prefers-reduced-motion`
  on drag/drop animations) is real, scoped work for its own milestone —
  listed here so it's tracked, not silently dropped.

---

## 17. Responsive strategy

The builder's own device-preview switcher (Desktop/Tablet/Mobile canvas
width) already exists and is preserved as-is, extracted into
`features/toolbar/DeviceSwitcher.js`. The builder *application UI itself*
(palette/settings panel width, topbar wrapping) at narrow admin viewport
widths was already addressed last session (topbar-overflow fix); this
milestone doesn't touch that CSS (§6 — no polish this milestone) but the new
`Toolbar` component boundary is where a future responsive pass would live.

---

## 18. Event system

`dispatch(action)` is the only event system the document has — no separate
pub/sub or event bus. Cross-cutting concerns that look like "events"
(autosave firing on document change, history checkpointing) are implemented
as effects that watch `form` inside `BuilderProvider`, not as emitted events,
so there's exactly one place data flows through and one place to add a
`console.log` when something's wrong.

---

## 19. Rendering pipeline

`BuilderProvider` (state) → `App` (layout) → feature components (presentation,
reading via `useBuilderStore()`). No component fetches data itself except
`App`'s one `apiFetch` on mount to load an existing form (`LOAD_FORM` action,
history strategy `none`) and `Toolbar`'s save action. This one-directional
flow is what makes `restoreSnapshot`/undo/redo correct by construction —
there's no component-local state that could drift out of sync with a
restored snapshot, because there isn't any for field data (§4).

---

## 20. Data model — forms, layouts, containers, fields

```ts
Form {
  id: number | null
  title: string
  fields: Field[]        // ordered, top-level
  settings: object        // unchanged — owned by Form Settings screen, not the builder
}

Field {
  id: string              // "f_<random>", core/ids.js
  type: string             // must match a registered field type (fields/registry.js)
  label: string
  required?: boolean
  conditional?: { enabled, action, groups: ConditionalGroup[] }
  children?: Field[]        // present only on container-type fields — see below
  // ...type-specific props (options, placeholder, min/max, content, etc.)
}
```

**Containers are modeled now, not built now.** `container` /
`accordion_container` / `repeat_container` are already registered field
types (currently `locked: true` in the palette — visible, not yet
placeable). The data model and every `core/tree.js` operation already
support a field having a `children: Field[]` array; only the *canvas
rendering* (`Canvas.js` currently maps `form.fields` one level deep) and the
*drag-drop-into-a-container* interaction are unbuilt. This is the concrete
answer to "must support hundreds of future features without major rewrites"
for the single biggest one (nesting/columns/repeaters): when that milestone
starts, it extends `CanvasField` to recursively render `field.children` and
teaches the drag-end handler to pass a `parentId`, it does not change the
reducer, the tree utilities, the history system, or the data model — all of
which already assume a field can have children.

Multi-step forms remain modeled as `page_break` marker fields in the flat
list (unchanged from before) rather than a separate `steps[]` array —
revisit only if step-level metadata (per-step custom validation messages,
progress-bar labels) outgrows what a marker field can hold.

---

## Decision log

- **Builder stays on React + `@dnd-kit`**, not migrated to the Vue 3 +
  Element Plus track the rest of the admin is moving to. Confirmed
  explicitly — dnd-kit's interaction model fits a drag canvas better than
  Vue's less mature drag ecosystem, and last session's rewrite onto dnd-kit
  is a real, working foundation, not something to discard.
- **`useReducer` + Context over a state library.** See §4 — revisit if/when
  the document needs to sync across more than one browser tab/collaborator.
- **This milestone ships zero new user-facing features or visual changes.**
  Every deliverable above is plumbing. The palette groups, field types,
  settings panel fields, and visual design are functionally identical to
  before the refactor — verified by Playground testing the rebuilt app
  against the same actions the old one supported.
- **Milestone 6 (Conditional Logic & Workflow Engine) added `assets/src/
  builder/logic/` and `includes/logic/`** — a standalone evaluation engine
  with zero dependency on this document's own React/`core/store`
  architecture (see the milestone doc's §4.3), consumed BY `core/store`
  (via `field.logicRule`, flowing through the existing `UPDATE_FIELD`
  action — no new store action types) rather than being part of it. Full
  research, architecture, and implementation report:
  `docs/research/milestone-06-conditional-logic.md` — the first doc under
  the new `docs/research/` per-milestone convention; later milestones'
  write-ups belong there too, not appended to this file.

---

## Milestone 2 — Layout Engine (section/row/column/container)

Builds the minimal nesting system every future layout/repeater/multi-step
feature depends on: real container node types, recursive canvas rendering,
multi-container drag-and-drop, and the interactions (Add Row/Add Column/
Split Column/duplicate/delete) needed to actually build a layout like:

```
[ Section ]
  [ Row ]
    [ Column 50% ]  [ Column 50% ]
      Name            Email
  [ Row ]
    [ Column 100% ]
      Message
```

### New architectural rule: a node knows only its children

Nothing in the data model or `core/tree.js` stores a `parentId` on a node —
not even after this milestone adds real nesting. Parent relationships are
computed on demand via `buildParentIndex()` (one pass over the tree, thrown
away after use) wherever something needs to answer "whose child is this"
(the drag-end handler, mainly). This was the single most important call
this milestone made, because the alternative — a `parentId` field kept in
sync on every node — is exactly the kind of dual-bookkeeping that undo/redo,
duplication, and serialization all have to fight forever after. With the
"only children" rule: a duplicate is a deep clone with no references to
fix up, undo/redo is a full-state snapshot swap with nothing to
re-normalize, and a JSON export is just the tree, no separate edge list.

### Data model changes (ARCHITECTURE.md §20, updated)

Four new node types, all just `Field` with a `children: Field[]` array
(reusing the exact tree shape Milestone 1 already assumed — no parallel
structure):

```ts
Field {
  // ...existing shape...
  children?: Field[]   // present on section/row/column/container
  width?: string        // column only: '25'|'33'|'50'|'66'|'75'|'100'
  responsive?: {          // column only: reserved for a future responsive-
    tablet: string|null,   // preview milestone — null means "use `width`"
    mobile: string|null,    // the front-end renderer and settings panel
  }                          // don't act on this yet; only the shape exists.
}
```

`row`'s children are always `column` nodes — enforced by convention (only
`createRowWithColumns()`/`addColumn()` ever insert into a row), not by a
schema check. `section`/`container` accept any field type as a child,
including other containers (a section can hold a row; a container could
hold another container) — `core/tree.js` never assumed a depth limit.

### Component changes

- `core/tree.js`: added `getChildren`, `buildParentIndex`,
  `isSameOrDescendant` (the cycle guard), `insertAfter`, `moveField`,
  `duplicateSubtree`. All pure, all operating on the same tree shape
  Milestone 1 shipped.
- `core/store/actions.js` / `builderReducer.js`: `DUPLICATE_FIELD`
  generalized to work at any depth (deep-clones a whole subtree); new
  `MOVE_FIELD` (reparent/reorder, one action for both) and `SPLIT_COLUMN`.
  `addRow`/`addColumn` are convenience action creators that reduce to the
  existing generic `INSERT_FIELD` — no new reducer cases needed for them.
  **Reducer purity note:** duplication needs fresh ids for an entire
  subtree, which the reducer can't safely generate itself (see Milestone
  1's purity fix) — `duplicateField()` mints a single `seed` string, and
  `duplicateSubtree(node, seed)` derives every descendant's new id
  deterministically as `seed + '_' + originalId`, so re-running the reducer
  with the same action twice (which `BuilderProvider.dispatch()` does)
  still produces identical results.
- `fields/createField.js`: `createField(type, id?)` now accepts an explicit
  id (needed for `SPLIT_COLUMN`'s deterministic new-column id); added
  `createColumn()` and `createRowWithColumns()`.
- `features/canvas/CanvasField.js`: now branches on whether a field is a
  container type — leaf fields render `FieldPreview` (unchanged), container
  types render the new `ContainerBody`. Stopped reading `dispatch`/`select`
  from `useBuilderStore()` directly and takes them as props instead — see
  the Performance section below for why that's load-bearing, not stylistic.
- `features/canvas/ContainerBody.js` (new): recursive rendering. `row`
  lays its columns out left-right by `width`; everything else is a single
  vertical droppable list — the same shape the root canvas already was.
- `core/dnd/useCanvasDnd.js`: rewritten for multi-container drops.
  `resolveDropTarget(overId)` is the one place that decides "is this drop
  landing directly in a container, or next to a sibling inside one" —
  everything else in the hook is unchanged in shape from Milestone 1.
  Collision detection switched from `closestCenter` to `pointerWithin`
  (nested droppables of very different sizes confuse "closest center").

### Performance

`React.memo(CanvasField)` and `React.memo(ContainerBody)` only actually
skip a branch if their props are referentially stable — which meant
`dispatch`/`undo`/`redo`/`restoreSnapshot` needed to stop being
`useCallback`s with a `form` dependency (recreated every edit) and become
truly stable across renders. Fixed in `BuilderProvider.js` via a `formRef`
that's updated every render but never a dependency — the standard
"stable callback, fresh closure via ref" pattern. Concretely: typing in one
column's field settings no longer re-renders every other field in the tree,
which is what "smooth with 100+ fields across nested rows/columns" actually
requires — memoizing the components alone, without this, would have done
nothing (a `useContext()` consumer re-renders on any context value change
regardless of `memo()`, which is why `CanvasField` takes props instead of
calling `useBuilderStore()` itself — see its doc comment).

### Accessibility

Container nodes render with `role="group"` and an `aria-label` naming the
node type (Section/Row/Column/Container). Full keyboard-navigation-through-
the-tree and drag-and-drop keyboard parity (`@dnd-kit`'s `KeyboardSensor`)
are **not** done this milestone — listed below as remaining work, not
silently dropped.

### A real bug found during this milestone's own build (not a pre-existing one)

Nested containers meant a click on a leaf field now also bubbles, in the
DOM, through every ancestor container's card. Without `stopPropagation()`
on each `CanvasField`'s select handler, clicking a field three levels deep
would select its outermost ancestor instead (React resolves bubbling
handlers outermost-last). Fixed before it ever reached verification, but
worth recording: it's the kind of bug recursive-card-in-card UIs produce by
default, and every future container-like component needs the same guard.

### Verified (real Chromium browser via Playwright against Playground, per the milestone's own required verification list)

1. Create a 2-column row — confirmed (Section → Add Row → 2 columns at
   50%/50%).
2. Drag fields into both columns — confirmed (1 field landed in each).
3. Move a field between columns — confirmed (column A: 1→0, column B:
   1→2).
4. Duplicate the row — confirmed, and confirmed **deep**: 2 leaf fields →
   4 after duplicating the row that contained them (both columns' contents
   came with it).
5. Undo/redo the entire sequence — confirmed: 8 undos from the fully-built
   state returned to 0 rows/0 sections (completely empty), 8 redos
   returned to exactly 2 rows/4 fields. Structural changes round-trip
   through history correctly, not just leaf-field edits.
6. Reload and confirm autosaved state restores — confirmed, but required
   completing a Milestone-1-deferred piece: the autosave *mechanism*
   detected a recoverable draft but never applied it. Added a one-shot
   auto-restore in `App.js` (applies the local draft over the server copy
   right after initial load, guarded so it can never re-fire and clobber
   later edits). A confirmation prompt ("Restore unsaved changes?") is
   still real, wanted UX and still not built — this milestone made the
   silent-restore path actually work, not the prompted one.
7. Zero console errors — confirmed across the entire sequence above.

Also verified beyond the required list, since it's the other half of "does
this actually work": explicit **Save Form** persists the nested structure
to the server with full fidelity — checked by intercepting the network
request/response (not just re-rendering) and by an independent REST GET
against the stored row afterward. Row/column/width/responsive metadata all
round-trip exactly.

### Explicit remaining work before Repeaters

Per the milestone brief's own instruction to measure progress by rewrites
avoided, not features shipped — here's what's genuinely still open, so it's
tracked rather than silently assumed done:

- **No click-to-insert into a nested container.** The root canvas keeps its
  "+" `InsertPoint`/`QuickAddMenu` popover; nested containers only accept a
  palette **drag**. Dragging covers the milestone's required verification,
  but "click a field in the palette while a column is selected" doesn't
  target that column yet.
- **No bare root-level Row.** A Row can currently only be created via a
  Section's "Add Row" button — there's no UI to drop a Row directly onto
  the root canvas without a Section wrapping it, even though the data model
  and `insertBuiltField` don't actually forbid it.
- **Split Column doesn't rebalance siblings.** Splitting a column always
  produces two 50%/50% columns regardless of the original width or what
  other columns in the row are set to — correct widths for a 3+-column row
  after a split currently need manual adjustment via the settings panel.
- **No keyboard navigation through the tree, no drag-and-drop keyboard
  parity.** `@dnd-kit`'s `KeyboardSensor` is the documented path for the
  latter and slots into the same `useSensors()` call in
  `core/dnd/useCanvasDnd.js`; tree keyboard navigation (arrow keys to move
  selection between siblings/into-and-out-of containers) is unbuilt.
- **No confirmation prompt for draft restore** — see point 6 above; the
  mechanism silently prefers the newer local draft, which is the right
  default but not a substitute for a real "Restore unsaved changes?" UI
  once there's a case where a user might actually want to discard it.
- **No full WCAG AA pass** — `role="group"`/`aria-label` on containers is a
  start, not the full accessibility strategy §16 of this document commits
  to (focus management after add/delete, screen-reader announcements for
  drag-and-drop, contrast audit).
- **No virtualization** — untested and unoptimized past what Milestone 1's
  structural-sharing + this milestone's stable-callback fix already buy;
  a real 100+-field nested form hasn't been profiled against yet.

---

## Milestone 3 — Interaction Layer (selection, multi-select, clipboard, floating toolbar, keyboard)

Scope note first: the brief for this milestone listed 15 deliverable
categories (drag polish, selection, multi-select, floating toolbar,
right-click context menu, breadcrumbs, command palette, canvas polish,
empty states, hover states, keyboard nav, accessibility, micro-interactions,
responsive, performance). Building all 15 shallowly in one pass would have
meant thin, under-tested versions of everything — exactly the "no
placeholder implementations" rule this project runs under. This milestone
ships a real, coherent, fully-verified slice instead: the **selection
model** (since almost everything else — the toolbar, multi-delete, a future
context menu — depends on it existing first) plus keyboard/clipboard
support built on top of it. Right-click context menu, breadcrumb
navigation, command palette (Cmd+K), drag insertion-line indicators, and
the full visual redesign are explicitly **not** in this milestone — see
"Remaining work" below, and the standalone UI Redesign milestone that
follows this one in the project's own sequencing.

### Regression baseline, taken seriously

Per the milestone's own ordering ("verify before implementing"), a
14-point regression suite covering every Milestone 1/2 capability (nested
layout creation, duplicate, undo, redo, delete, escape-deselect, autosave
+ reload, explicit Save + confirmation, REST persistence via full
navigate-away-and-back, field registry population, zero failed network
requests, zero console errors/React warnings) was written and run against
a clean Playground instance **before** any Milestone 3 code changed, then
re-run against the finished code on an equally clean instance. Both runs:
12/12 green, zero errors. This is the actual verification artifact, not a
claim — the script is `.playwright-regression.js` (repo root, not shipped
in the plugin zip) and is meant to be re-run before every future milestone
the same way.

### Selection architecture

`BuilderProvider`'s `selection` state grew from `{ activeId }` to
`{ activeId, selectedIds, anchorId }`:

- `activeId` — the one field the Settings panel targets and the floating
  toolbar anchors to. Always the most-recently-touched member of
  `selectedIds`, or `null`.
- `selectedIds` — the full multi-selection, an array of ids.
- `anchorId` — the shift-click range start, tracked separately from
  `activeId` so "shift-click A, then shift-click C" extends the range from
  the *original* anchor (A), not wherever the last click landed.

None of this is historied — selection remains ephemeral UI state per
Milestone 1's original design (§10), unaffected by undo/redo, exactly like
before. Four click behaviors, one per modifier combination:

- **Plain click** → `select(id)` — replaces the whole selection with just
  this field.
- **Ctrl/Cmd-click** → `toggleSelect(id)` — adds/removes one field without
  disturbing the rest.
- **Shift-click** → `selectRange(id)` — selects the contiguous *sibling*
  range from the anchor to this field (see `core/selection/
  selectionHelpers.js`'s `computeSiblingRange()`). Deliberately scoped to
  fields sharing the same parent — "select everything between this leaf
  field and a section header three levels up" has no unambiguous meaning
  in a tree the way it does in a flat list; a cross-parent shift-click
  falls back to a plain single-select rather than guessing.
- **Click empty canvas** → clears the selection entirely (`Canvas.js`'s own
  `onClick`, guarded by every field's `stopPropagation()` so it only fires
  when the click never touched a field).

Explicitly out of scope: a marquee/rubber-band selection box. The brief
listed it as "if architecture allows" — it doesn't cleanly without
conflicting with `@dnd-kit`'s `PointerSensor` (which activates on any
sufficient pointer movement, the same gesture a marquee drag needs),
enough of a real risk to defer rather than force in.

### Batch actions — why multi-delete/duplicate needed new reducer cases

Deleting or duplicating a multi-selection had to be **one action, one undo
step** — not a loop of single-field dispatches from the caller (three
separate `dispatch(removeField(id))` calls would be three separate undo
steps, wrong UX). `REMOVE_FIELDS`/`DUPLICATE_FIELDS`/`PASTE_FIELDS` are new
reducer cases for exactly this — each takes an array and applies it
atomically. `DUPLICATE_FIELDS` and `PASTE_FIELDS` mint fresh ids for
multiple fields in one action, which meant extending the seed-based purity
pattern from Milestone 2 (`seed + '_' + originalId`) to a **batch** of
seeds (`seed + '_' + index + '_' + originalId`) — still fully deterministic
given the same action object, still zero randomness inside the reducer
itself.

### Clipboard

An in-memory clipboard (`BuilderProvider`'s own `clipboard` state), not the
system clipboard — writing structured field JSON to `navigator.clipboard`
can silently fail under permissions in some embed contexts, and in-memory
is simpler and sufficient for copy/paste within one builder session.
`copySelection()` snapshots the actual field *objects* at copy time (not
ids), since the source may be deleted or moved before a later paste.
`pasteClipboard()` inserts right after the currently-active field (same
container it lives in), or appends to root if nothing's selected, then
selects the pasted copies — mirroring how duplicate already behaves.

### Floating context toolbar

`features/canvas/FloatingToolbar.js` — Copy/Paste/Duplicate/Settings/Delete,
appearing above the active selection whenever something's selected.
Positioned with `position: fixed` in real *viewport* coordinates (measured
via `getBoundingClientRect()` on the active field's `data-field-id` DOM
node), not container-relative — a container-relative absolute position
would get clipped the instant the canvas frame scrolls the selected field
near its own edge. Explicitly excludes Move/Wrap/Visibility/Lock from the
brief — those need reducer capability (wrap-in-container, a visibility
flag) this pass doesn't add.

### Keyboard model

Extended the Milestone 1 shortcut table (`core/keyboard/shortcuts.js`):
`mod+c`/`mod+v` (copy/paste), `mod+d` now correctly `preventDefault()`s (a
latent Milestone-1 bug — without it, Cmd+D also triggered the browser's own
"bookmark this page" dialog), `arrowup`/`arrowdown` for tree navigation.
Arrow-key navigation (`App.js`'s `moveSelection()`) walks
`flattenFields(form.fields)` in document order and moves real DOM focus to
the new selection via `data-field-id`, guarded to only engage when keyboard
focus is already inside `.fc-canvas` — otherwise Up/Down would hijack
normal page scrolling any time focus isn't in a text input (e.g. resting on
the Save button, or nowhere in particular).

Every `CanvasField` now carries `tabIndex={0}`, making Tab-navigation and a
visible focus ring free from the browser's native `:focus-visible`
pseudo-class — no JS needed to distinguish "keyboard-focused" from
"mouse-clicked," which is exactly the distinction the brief's "Focus Ring"
requirement calls for (a mouse click never triggers `:focus-visible`; a
Tab/arrow-key move always does). Enter promotes a Tab-focused field to the
full selection (opens it in the Settings panel), matching what a click
already does.

### Performance: making `React.memo` actually work

`React.memo(CanvasField)`/`React.memo(ContainerBody)` only skip a branch if
their props are referentially stable — a `useContext()` consumer re-renders
on *any* context value change regardless of `memo()`, which is why
`CanvasField` takes `dispatch`/`select`/`toggleSelect`/`selectRange` as
props rather than calling `useBuilderStore()` itself (this was already true
in Milestone 2; Milestone 3 adds three more callback props to the same
pattern, not a new one). `isSelected` is computed as a **boolean** at the
parent level (`selectedIds.includes(child.id)`) rather than passing the raw
`selectedIds` array down — passing the array itself would give every
`CanvasField` a "changed" prop on any selection change (new array
reference), defeating memoization for the entire tree on every click; a
boolean that stays `false` before and after for an unrelated sibling lets
`memo()` correctly skip it.

### A real bug found building this (not pre-existing)

Nested containers mean a click on a leaf field is also, from the DOM's
perspective, a click inside every ancestor container's card. Without
`stopPropagation()` in `CanvasField`'s click handler, selecting a field
three levels deep would bubble up and re-select its outermost ancestor
instead (React resolves bubbling handlers outermost-last). This was already
partially handled from Milestone 2 for the plain-click case; Milestone 3's
new shift/ctrl-click branches needed the same guard, verified via the
throw-based diagnostic described below.

### A real Playwright-tooling bug found — not a product bug

Verifying multi-select initially showed ctrl-click and shift-click
appearing to do nothing (`selectedIds` never grew past 1). Root-caused via
a deliberate throw planted inside the click handler (`if
(window.__fcThrowOnClick) throw new Error(...)`) plus two comparison
tests: a **native** `element.click()` (via `page.evaluate()`) reliably
fired the handler and threw as expected, every time; Playwright's own
`page.click()` action on the exact same element frequently did not fire it
at all, despite visibly appearing to click (no error, no timeout). This is
a real interaction between Playwright's synthetic mouse-event simulation
and having `useSortable`'s `setNodeRef` (not the drag listeners themselves,
just the ref) attached to the same DOM node — worth documenting since it
will bite the next person writing a canvas-interaction test in this repo.
**Fix applied to the test suite, not the product**: every subsequent
verification script dispatches clicks via `el.dispatchEvent(new
MouseEvent('click', { bubbles: true, ...modifiers }))` through
`page.evaluate()` instead of `page.locator().click()` when targeting a
`.fc-canvas-field`. Real users clicking with a real mouse are unaffected —
confirmed by the fact that plain (unmodified) clicks *did* work reliably
through `page.click()` in the regression suite; only the modifier-key path
showed the flakiness.

### Verified (real Chromium browser via Playwright against Playground)

Beyond the regression baseline (12/12, see above), a dedicated Milestone 3
feature suite — 15 checks, all passing, zero console errors:

1. Three fields added via palette.
2. Single select → exactly one `.is-active`, floating toolbar appears.
3. Ctrl-click a second field → exactly two selected, toolbar shows "2
   selected".
4. Shift-click a third (after resetting the anchor) → all three selected.
5. Multi-duplicate (toolbar button) → 3 fields become 6, deep-cloned.
6. Undo → back to 3 in **one** step (not three).
7. Multi-delete (Ctrl-click two, press Delete) → down to 1.
8. Undo → back to 3 in **one** step.
9. Copy one field, paste → 4 fields.
10. Escape → selection and floating toolbar both clear.
11. Arrow-Down from a focused field → moves selection to the next field in
    document order.
12. Clicking empty canvas → selection clears.

### Remaining work (explicit, not silently dropped)

- ~~**Right-click context menu**~~ — **built since this milestone shipped**
  (`features/canvas/ContextMenu.js`, wired into `CanvasField.js`'s
  `onContextMenu`), undocumented when it landed. Corrected here rather
  than left stale after being found and verified against real code during
  the design-system audit in `docs/DESIGN_SYSTEM.md`'s Slice 14 — that
  same audit found two other "not built" claims in that document were
  also wrong by the time it was written, so this list is worth spot-
  checking against the actual code again before trusting it, not just
  this one line.
- **Breadcrumb navigation** (Section > Row > Column > Field) — still not
  built, confirmed by grep (no `Breadcrumb` component exists anywhere in
  `assets/src/builder`) rather than assumed from this document.
  `core/selection/selectionHelpers.js`'s parent-index approach is still the
  direct input a breadcrumb trail needs (walk up via `buildParentIndex`
  from the active field), just not wired to a UI yet.
- **Command palette (Cmd/Ctrl+K)** — not built. The action creators in
  `core/store/actions.js` are already the right registration surface (a
  command palette entry is just "run this action creator"), but the
  palette UI itself, fuzzy search, and a command registry don't exist yet.
- **Drag insertion-line indicators** — the existing drop-target feedback
  (background tint + inset shadow on `.fc-dropzone`/container highlighting)
  is real but coarser than a precise "insert exactly here, between these
  two siblings" line; dnd-kit's own sortable reordering-preview
  (fields visibly shift to make room during drag) covers some of this
  already.
- **Keyboard drag-and-drop parity** — `@dnd-kit`'s `KeyboardSensor` is the
  documented path, slots into the same `useSensors()` call in
  `core/dnd/useCanvasDnd.js` — not added this pass.
- **Multi-move via drag** — dragging a multi-selection together as one
  unit isn't supported; dnd-kit doesn't have native multi-item drag, and
  building custom multi-item transfer correctly was judged too large/risky
  to fold into this pass. Multi-select still supports delete/duplicate/copy
  fully.
- **No selection box / marquee** — see the Selection architecture section
  above.
- **No full WCAG AA audit** — `tabIndex`, `:focus-visible`, `aria-label`,
  `aria-selected`, `role="group"` are real incremental improvements, not
  the complete accessibility strategy §16 commits to (screen-reader
  announcements for drag-and-drop and selection changes, a contrast audit,
  `prefers-reduced-motion` is handled for this milestone's own new
  animations but wasn't re-audited against Milestones 1–2's).
- **Visual redesign** — this milestone is interaction/behavior only; the
  premium-SaaS visual language (design tokens, typography/spacing scale,
  card/button/panel redesign) is explicitly the next milestone, sequenced
  deliberately *after* the interaction layer so the redesign has a stable,
  fully-functional interaction model to skin rather than a moving target.

---

## Toast + Tooltip Infrastructure

Two shared UI primitives, motivated by a real, twice-flagged gap: the
builder had no toast/notification system anywhere (confirmed by grep and
called out in the Design System audit — see docs/DESIGN_SYSTEM.md Slice
13) and no tooltip system (icon-only controls relied on bare `title`
attributes — inconsistent styling/delay across browsers, and unreliably
announced by screen readers). Building this now, before any specific
feature needs it, means the next feature that needs to reject an invalid
action or explain an icon-only control has somewhere real to put that
feedback instead of inventing a one-off `alert()` or another bare `title`.

### Where it lives

```
shared/
  toast/
    toastReducer.js      # pure { toasts: [] } state — no timers, no DOM
    ToastProvider.js      # owns the reducer, exposes success/error/warning/info/dismiss
    useToast.js            # useContext wrapper, throws outside a provider
    ToastViewport.js        # the rendered stack — timers, pause-on-hover, live regions
  tooltip/
    computeTooltipPosition.js  # pure viewport-rect placement math
    Tooltip.js                  # <Tooltip content="…">{trigger}</Tooltip>
```

Both are `shared/`, not `core/` — per the existing folder-structure rule
(§1: "`core/` never imports from `features/`"), a toast/tooltip is UI
infrastructure any feature can reach for, with zero dependency on the
document store. `ToastProvider` wraps `BuilderProvider` in `app/App.js`
rather than living inside it, for the same reason: a toast has no
business being coupled to the form-editing store's lifecycle.

### Design decisions or contents that intentionally follow existing patterns rather than inventing new ones

- **No new dependency for tooltip positioning.** `computeTooltipPosition()`
  is hand-rolled viewport-rect math (measure trigger + tooltip via
  `getBoundingClientRect()`, flip if clipped, clamp to viewport) — the
  same shape `FloatingToolbar.js` already established for its own
  positioning (see the "Floating context toolbar" section above). Adding
  a positioning library (`@floating-ui/dom` or similar) for a second,
  inconsistent approach was rejected in favor of reusing the one this
  codebase already trusts.
- **No DOM portal.** `@wordpress/element` doesn't re-export
  `createPortal`, and importing `react-dom` directly would risk a second
  ReactDOM instance alongside whatever `wp.element` already loaded on the
  page. `ToastViewport` and `Tooltip`'s bubble both use `position: fixed`
  instead — verified safe the same way `FloatingToolbar.js` already
  verified it: no ancestor in `.fc-app`'s stylesheet sets a `transform`/
  `contain`/`filter` that would create a containing block and break fixed
  positioning.
- **Reducer/effect split.** `toastReducer.js` is pure (add/dismiss/cap at
  `MAX_VISIBLE_TOASTS`, oldest dropped first) with zero timers; all timer
  lifecycle (auto-dismiss, pause-on-hover, cleanup) lives in
  `ToastViewport.js`'s `ToastItem` — the same reducer-is-pure /
  effects-watch-it split `core/store/BuilderProvider.js` already uses (§18).
- **Every color/spacing/shadow value resolves to an existing `--fc-` or
  `--fcb-` token** (`--fc-success`/`--fc-danger`/`--fc-warning`/`--fc-info`
  for toast type, `--fcb-shadow-panel`/`--fcb-shadow-card` for elevation,
  two new stacking tokens `--fcb-z-toast`/`--fcb-z-tooltip` added to
  `shared/styles/tokens.css` above the existing `--fcb-z-modal`) — no new
  color or shadow value invented, per §6.

### Toast semantics

- `success`/`info` default to a 4s auto-dismiss, `warning` to 6s,
  **`error` defaults to sticky (no auto-dismiss, manual close only)** —
  a message a user needed to actually read shouldn't be able to vanish
  before they've read it, which was the actual point of building this
  (a blocked/failed action previously gave no explanation at all). Any
  toast's duration can be overridden per-call via `{ duration }`.
- Capped at `MAX_VISIBLE_TOASTS` (4) — an unbounded stack from, say, a
  loop firing many error toasts would bury the canvas and become its own
  usability problem; oldest drops first (FIFO).
- Two separate `aria-live` regions (`polite` for success/info/warning,
  `assertive` for error) rather than one, so a screen reader finishes its
  current sentence before a routine toast interrupts, but an error is
  announced immediately.
- Auto-dismiss pauses on hover or keyboard focus and resumes with the
  *remaining* time (not a fresh full duration) on mouseleave/blur — a
  toast that vanishes mid-read is worse than one that never auto-dismisses.

### Tooltip semantics

- Shows on hover after a 400ms delay (avoids flashing a tooltip on every
  incidental mouse pass) **and shows immediately on keyboard focus** — a
  keyboard-only user gets the same information a mouse user does, without
  an artificial wait. This is the actual accessibility fix bare `title`
  attributes couldn't provide reliably.
- `aria-describedby` wires the trigger to the tooltip's real DOM content
  (`role="tooltip"`), which screen readers announce reliably, unlike
  `title`.
- Hides on mouseleave/blur/Escape/scroll. Closing on scroll (rather than
  continuously re-tracking position) matches how native browser tooltips
  already behave and avoids a resize/scroll listener staying attached for
  the tooltip's full open duration.
- The trigger is wrapped in a `<span style="display:contents">` rather
  than `cloneElement`-ing the child — cloning would need to merge any
  event handlers/ref the child already carries (easy to silently clobber
  one); the wrapper holds this component's own listeners without ever
  touching the child's own props.
- Content is always rendered as plain React text (`{content}`), never
  `dangerouslySetInnerHTML` — React's default escaping means a caller
  can never accidentally turn a tooltip into an XSS vector, verified by
  a dedicated test asserting an injected `<img onerror>` string renders
  as inert text, not a DOM element.

### First real usages (not shipped as inert infrastructure)

- `Toolbar.js`: Undo, Redo, Edit History, and Fullscreen icon buttons
  converted from bare `title` to `<Tooltip>`; the "Autosaved to this
  browser" hint (added alongside the Save-button dirty-state indicator —
  see the PayPal-gateway-era session's UX gap-analysis fixes) converted
  from `title` to `<Tooltip>` and made keyboard-focusable (`tabIndex={0}`)
  so its explanation is actually reachable without a mouse.
- `App.js`: the recoverable-draft banner's "Restore draft"/"Discard"
  buttons previously gave zero feedback beyond the banner disappearing —
  now call `toast.success('Draft restored.')` / `toast.info('Draft
  discarded.')` respectively. The existing persistent save-error alert
  (`.fc-builder-alert`) was deliberately left as-is rather than duplicated
  into a toast — it's already a clear, appropriately persistent pattern
  for a conflict/failure that important, and doubling up the feedback
  would be redundant, not a fix.

### Testing

This is the first JS unit-test infrastructure in the plugin (previously
only the PHP side had standalone test files under `tests/*.test.php`).
Added: `@wordpress/element`, `@testing-library/react`,
`@testing-library/jest-dom` as devDependencies; `test/jest.config.js`
extends `@wordpress/scripts`'s own default Jest preset
(`@wordpress/jest-preset-default` — jsdom, the wp-scripts Babel
transform, CSS-import mocking) rather than a hand-rolled config, adding
only jest-dom's matchers and scoping discovery to `assets/src`. Run via
`npm run test:unit`.

50 tests across 5 files: `toastReducer.test.js` and
`computeTooltipPosition.test.js` test the pure logic directly with no
rendering (fast, no jsdom quirks); `ToastProvider.test.js`,
`ToastViewport.test.js`, and `Tooltip.test.js` use
`@testing-library/react` with Jest fake timers to cover the real
component behavior a pure-logic test can't reach — auto-dismiss firing
exactly on schedule, pause-then-resume using the *remaining* time rather
than restarting, Escape/blur/scroll dismissal, focus-vs-hover timing
parity, and the XSS-safety assertion above. `renderHook`/`act` cover the
hook contract (`useToast()` throwing outside a provider, each convenience
method's default duration, dismiss/dismissAll) without needing a full
component tree.

### Explicit remaining work

- **No lint verification.** The project's `lint:js` script
  (`wp-scripts lint-js`) currently fails on every file, including files
  untouched by this change (`TypeError` from a `@typescript-eslint`/
  `ts-api-utils` version mismatch inside `@wordpress/eslint-plugin`'s
  dependency tree) — confirmed pre-existing, not introduced here, and out
  of scope to fix as part of this infrastructure. New code was reviewed
  manually against the codebase's existing style instead. `@wordpress/
  eslint-plugin` needs a compatible `@typescript-eslint` pin before
  `lint:js` is usable again — a dependency-tree fix, not something to
  patch around per-feature.
- **No promise-based toast (`toast.promise(fn)`)** — Sonner/react-hot-toast
  style "pending → success/error" auto-transitioning toasts weren't
  needed by either real usage site added this pass; the `show()` primitive
  in `ToastProvider.js` is the seam a later addition would extend, not a
  rewrite.
- **No toast action buttons** (e.g. an inline "Undo" button inside the
  toast itself) — every current real usage is pure notification, not an
  undoable action; the `toast` shape (`{ id, type, message, duration }`)
  would need an `action: { label, onClick }` field added, additively.
- **Tooltip does not yet support rich (JSX) content**, only plain text —
  deliberate: every real usage so far is a short explanatory sentence,
  and keeping content plain text is also what keeps the XSS-safety
  guarantee unconditional rather than needing a sanitizer.