Theme Builder: structured color/type controls, scheme catalog, diverging preview

docs/architecture/05-rendering-theming-preview.md

@@ -236,6 +236,30 @@ key-by-key), so a snippet can always override or opt out locally. The
 that boundary deliberately: merge bakes the selected theme into `spec.config`
 (spec keys win — rendering unchanged), extract lifts `spec.config` out.
 
+### Structured controls
+
+The builder's panels (`ColorControls`; the Type tab's font control) are
+accelerators over the same `draftConfig`: each reads a value and writes one back
+through `CustomThemeStore.mutateDraftConfig(fn)` — the single transform path,
+which reparses, reformats, and updates `draftConfig` so the JSON editor and
+gallery follow (a parse error disables the controls). The pure transforms live
+in `core/theme-controls.ts`: immutable config path get/set, the named-scheme
+catalog (`THEME_SCHEMES`), and `schemeColors` (scheme name → hex swatches, from
+the `vega-scale` registry — a focused vega sub-package). A color family holds
+**either** a named scheme string **or** an explicit color array; the picker
+materializes one to the other. Family by scale: `range.category` (nominal),
+`range.ramp` (continuous; `range.heatmap` for `rect`), `range.diverging`
+(continuous color with a `domainMid`).
+
+- **Do** route structured edits through `mutateDraftConfig` + `setConfigValue`,
+  which sets a value at a path **immutably, preserving sibling keys**, and
+  deletes (pruning emptied ancestors) on `undefined` so a theme stays a diff.
+- **Don't** rebuild the config from a fixed schema: vega-themes presets carry
+  Vega-_layer_ keys (`symbol`/`shape`/`path`/`group`) absent from the Vega-Lite
+  `Config` schema but forwarded to Vega — a rebuild drops them. Merge in place.
+- **Do** add a `theme-preview-specs.ts` gallery card for any new color family,
+  so no control ships without a visible mirror.
+
 ### Rules
 
 - **Do** keep `chartConfigForSelection` as the _only_ place that maps the user's