Chart builder: data-aware defaults, one-click hint fixes, canvas preview, fullscreen modal

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

@@ -101,6 +101,23 @@ async function rerender(node: HTMLElement, spec: TopLevelSpec, config: Config) {
 
 - **Do** pass `actions: false`. Astrolabe owns its own export/copy affordances;
   the library's overlay menu does not belong on the preview.
+- **SVG is the default renderer, canvas is an opt-in for many-mark previews.** SVG is
+  crisp/inspectable/copyable and stays the default for the editor's LivePreview. But an
+  SVG chart renders one DOM node per mark, so a many-mark chart (e.g. the Chart Builder's
+  default one-bar-per-row on a 10k-row dataset) costs **seconds** of main-thread
+  layout/paint per render (measured ~6.5s on 9994 rows; the chart paints _after_ it first
+  appears, freezing the tab). The **Chart Builder preview** therefore passes
+  `renderSpec(…, { renderer: 'canvas' })` — canvas is a single node and paints in
+  milliseconds. The raster trade-off is invisible for an ephemeral preview, and image
+  export (`view.toImageURL`) is renderer-agnostic.
+- **Canvas has a hard max dimension; SVG doesn't.** A canvas larger than the browser's
+  limit (~32k px/side, less on Safari) fails to allocate and draws _nothing_ — silently.
+  So for canvas, `renderSpec` first runs a headless (`'none'`) layout probe, reads the
+  resolved height, and throws `ChartTooLargeError(heightPx, limitPx)` when it exceeds
+  `MAX_CANVAS_PX ÷ devicePixelRatio`, so the caller can show the real cause. This is a
+  **render-size** limit (the chart is physically too big), distinct from the readability
+  cardinality warnings — don't conflate them. Only an _unbounded_ axis overflows: a
+  `width: 'container'` axis is bounded, so it's the deleted (natural-height) axis to watch.
 - **Do** call `view.finalize()` on every previous view before rendering a new
   one, and on component unmount.
 - **Do** keep exactly one live view per preview node.