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

Rendering, Theming & Live Preview

How Astrolabe turns a user-authored Vega-Lite specification into a live chart in the preview pane. This covers four mechanics: embedding a spec via vega-embed, theming so charts match the active UI theme, debounced re-rendering so typing stays smooth, and error handling so a broken spec produces a readable message and self-heals. It deliberately stops at the embedding boundary — the content of the spec (resolving named-dataset references, applying fit-mode sizing) is prepared upstream by a pure transform; see §6.

---

1. The Embedding Boundary

The preview is a thin imperative layer wrapping the vega-embed library, driven by reactive store state. The flow is always the same:

spec text  ──parse──▶  Vega-Lite spec object
                            │
                            ▼
              prepareSpecForRender(spec, { fitMode })   ← pure, src/core/rendering.ts
                            │  (operates on a COPY; never mutates the stored spec)
                            ▼
                       render(node, preparedSpec, config)   ← src/app, this doc
                            │
                  vega-embed ─▶ View ─▶ SVG in the DOM node

vega-embed is the only place in the app that touches the chart DOM. Everything above it is data; everything below it is a Vega View we own and must tear down.

Rules

• Do keep all vega-embed calls behind one small renderer module. Components ask the renderer to draw a spec into a node; they never import vega-embed directly.
• Do treat the renderer as imperative glue driven by store state (via a subscribe listener), not as reactive state itself.
• Don't scatter vegaEmbed(...) calls across components.

Forward note — data inspector. A planned vega-editor-style inspector (show the resolved, post-transform data tables, in the builder and as a togglable panel below the main Live Preview) reads runtime rows via view.data(name). It rides this same boundary: a RenderHandle.data() accessor wraps the view (like toImageURL), so no component touches the raw view. Parked, not built — see docs/data-inspector-exploration.md.

---

2. vega-embed Integration

A single async render function embeds a prepared spec into a DOM node. Three non-negotiable embed options, plus disciplined teardown of the previous view:

// src/app/services/chart-renderer.ts (sketch)
import vegaEmbed, { type Result as EmbedResult } from 'vega-embed';
import type { Config, TopLevelSpec } from 'vega-lite';

export interface RenderHandle {
  /** Finalize the underlying Vega view and release its resources. */
  destroy(): void;
}

export async function renderSpec(
  node: HTMLElement,
  spec: TopLevelSpec,
  config: Config,
): Promise<RenderHandle> {
  const result: EmbedResult = await vegaEmbed(node, spec, {
    actions: false, // no built-in export/source/editor menu — clean chart
    renderer: 'svg', // crisp, inspectable, copyable output
    config, // theme config (see §3)
  });

  return {
    destroy() {
      // Frees timers, listeners, and the canvas/SVG the view created.
      result.view.finalize();
      node.replaceChildren(); // drop any leftover DOM the embed inserted
    },
  };
}

The view lifecycle is the bug surface

Every successful vegaEmbed returns a result.view (a live Vega View instance). It owns timers, signal listeners, and DOM. If you embed a new spec into the same node without finalizing the old view, the old one leaks — its listeners keep firing and resources accumulate over a long editing session.

The renderer that drives re-rendering must therefore hold the previous handle and destroy it before (or while) creating the next:

let current: RenderHandle | null = null;

async function rerender(node: HTMLElement, spec: TopLevelSpec, config: Config) {
  current?.destroy(); // tear down the previous view first
  current = await renderSpec(node, spec, config);
}

Rules

• Do pass actions: false. Astrolabe owns its own export/copy affordances; the library's overlay menu does not belong on the preview.
• The per-chart export goes through the handle, not the raw view. RenderHandle exposes toImageURL('png' | 'svg', { scale, background }) so the preview's Export control can rasterize/serialize the live chart without any component importing vega-embed or touching the View directly — the embedding boundary holds. PNG goes via view.toCanvas → blob: URL (revoked after the download); SVG via view.toSVG → data: URL. Renderer-agnostic: both work from the SVG-backed LivePreview view, since Vega draws to its own off-screen surface here. Two non-obvious details live in the handle, not the caller: (1) dpr-aware scale — the PNG is drawn at scale × devicePixelRatio, so a 1× export is as crisp as the chart on a Retina screen (raw toImageURL scaleFactor ignores dpr, so a naive 1× looks half-resolution on a 2× display). (2) background fill — the chart config renders a transparent background (so the on-screen chart shows the pane colour), which would make a naive export transparent; an opaque colour is composited under the PNG canvas and added as a full-bleed <rect> to the SVG. The spec-text exports (copy / .vl.json) need no view.
• 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.
• Don't re-embed into a node whose previous view you have not finalized.
• Don't keep a reference to a finalized view; null it out.

---

3. Theme Follows the UI Theme

A Vega-Lite config object styles every chart globally — fonts, axis colors, background, the categorical color range. Astrolabe ships one config per UI theme so charts visually belong to the app rather than looking like stock Vega-Lite. src/core/vega-themes.ts is the single source of truth; each house config is two merged layers (the full audit and forward plan live in docs/chart-theming-scope.md):

• Base (lightBaseConfig/darkBaseConfig) — the legibility minimum: background: 'transparent' (the pane shows through) plus guide colors on the app's text/border tokens. Without it, stock black-on-white chart text is illegible on the dark pane.
• Expressive (lightExpressiveConfig/darkExpressiveConfig) — the house style: IBM Plex, the Carbon data-viz 14-color categorical palette, dotted grid, bumped guide sizes/weights, no plot border.

mergeChartLayers(base, expressive) produces lightChartConfig/ darkChartConfig, and chartConfigFor(uiTheme) is the one UI-theme → config mapping. The split exists so a non-house style can keep the base layer while swapping the expressive one (future custom themes).

Selectable chart themes

On top of the house pair, the user picks a chart theme (spec §04 → Chart theme) — ChartThemeSelection = 'astrolabe' | 'stock' | <vega-themes preset id> | 'custom:<id>':

• 'astrolabe' resolves via chartConfigFor(uiTheme) (follows light/dark);
• 'stock' resolves to {} — nothing injected, pure Vega-Lite defaults;
• preset ids resolve to the vega-themes package's configs verbatim (the same presets as the Vega editor's theme dropdown; the package is already in the tree as a vega-embed dependency);
• custom:<id> resolves to a saved CustomTheme record's config (spec §09G). Selection is keyed by record id, not name, so a rename never invalidates the persisted preference; a missing record (themes hydrate async from IndexedDB; the record may be deleted) resolves to the house config rather than rendering unstyled, and deleting the actively-selected theme resets AppStore.chartTheme to 'astrolabe' (CustomThemeStore.remove).

chartConfigForSelection(selection, uiTheme, customThemes) is the only resolver; chartThemeOptions(customThemes) derives the full picker list (built-ins, customs, presets — memoize the call: it returns a fresh array). The choice lives in AppStore.chartTheme, persisted as ui.chartTheme by orchestration/preferences.ts (the previewFitMode pattern; persistence validates with isChartThemeSelection, which accepts custom:<id> on shape alone), and is surfaced by a SelectControl in the LivePreview header — not inside the PreviewSettings popover: SelectControl and SettingsPopover share the one-open-popover registry, so a select nested in the popover would close (and unmount) its own parent on open. The "Edit themes…" action row opens the Theme Builder without changing the selection (the VS Code theme-picker pattern); it closes the custom-themes block — after the built-ins, before the long preset roster — so it's visible without scrolling and sits next to the entries it manages.

Custom themes & the Theme Builder

CustomTheme records (core/custom-theme.ts) persist in their own IndexedDB store through the standard stack: infrastructure/theme-store.ts (+ read-time theme-migrations.ts), stores/CustomThemeStore.ts (the themes array plus the builder's draft state), and orchestration/theme-persistence.ts (diffing write-through, wired after hydrate in startup.ts) — the exact dataset pattern, one tier each.

The Theme Builder modal (ThemeBuilderModal, registered as themeBuilder, xlarge shell, no backdrop dismissal) edits a draft held in the store: { name, configText } plus draftConfig — the last text state that parsed. The gallery (core/theme-preview-specs.ts, fixed inline-data swatch specs) renders draftConfig per card through the shared renderSpec with the canvas renderer and a per-card debounce + chain-lock (the LivePreview serialization pattern, one lock per card) — so invalid JSON mid-edit never blanks the preview, and seven concurrent embeds never interleave on a node. applyFontToConfig(config, family) is the font control's transform: it sets the top-level font and rewrites every font/*Font string slot at any depth — explicit slots would otherwise keep overriding the new default.

Creation paths: the builder's "New theme" duplicates the currently selected chart theme's resolved config, and the editor's Extract Config to New Theme action (runExtractConfigToTheme, spec §03G) lifts a spec's config block into a theme, selects it, and removes the block — the spec-to-library direction of the same boundary the merge action crosses the other way.

Render-time precedence: vega-lite merges the injected config under the spec's own config (mergeConfig(opt.config, spec.config) — the spec wins key-by-key), so a snippet can always override or opt out locally. The core/spec-config.ts merge/extract operations (spec §03G) move styling across that boundary deliberately: merge bakes the selected theme into spec.config (spec keys win — rendering unchanged), extract lifts spec.config out.

Rules

• Do keep chartConfigForSelection as the only place that maps the user's selection (and UI theme) to a Vega config.
• Do set chart background: 'transparent' in the house configs so the pane's own background shows through and theme switches look seamless. Preset themes carry their own backgrounds (often white) and render as their authors intended — honest preview beats pane-matching.
• Do keep the Chart Builder preview and onboarding thumbnails on chartConfigFor(uiTheme) — they are app surfaces, not destination previews.
• Don't inline colors or fonts into individual specs to "match the theme" — that is the config's job, and per-spec styling drifts from the app.
• Don't write the injected config into the user's stored spec implicitly; it is applied at embed time, leaving the spec theme-agnostic. Baking it in is the explicit, user-invoked merge action only.

Theme flow (end to end)

Theme spans several layers; the path is:

AppStore.uiTheme (+ toggleTheme) → orchestration/theme.ts mirrors it onto <html data-theme> and writes through to infrastructure/settings-store.ts (localStorage ui.theme). On load, initTheme() — called from main.tsx before createRoot().render — hydrates the saved theme. Chart and editor follow by subscribing to uiTheme: LivePreview re-embeds with chartConfigForSelection(chartTheme, uiTheme), SpecEditor sets the Monaco theme. UI chrome repaints purely from the [data-theme] token swap in styles/tokens.css. The header ThemeToggle is the user control.

• Do hydrate the theme synchronously before first paint — an async hydrate (e.g. inside initApp) flashes the default theme on load.
• Do keep the store browser-free: the data-theme write and the localStorage write-through live in orchestration/theme.ts, never in the store or a component.
• The control currently lives in the header; spec §07 houses it in the Settings modal (M5), which will share the same ui.theme key.

---

4. Field-Name Escaping

Vega-Lite treats ., [, and ] inside a field: string as nested-property accessors: field: "user.age" reads row.user.age, not a column literally named "user.age". Astrolabe renders arbitrary user data whose column names may contain those characters, so any column name placed into a field: (or as:, groupby:, tooltip field:, etc.) must be escaped first.

// src/core/rendering.ts (sketch)
/** Escape `.`/`[`/`]` so Vega-Lite treats the string as a literal field name. */
export function escapeVegaField(name: string): string {
  return name.replace(/([.[\]])/g, '\\$1');
}

// usage when constructing/normalizing an encoding that references a column:
encoding.x = { field: escapeVegaField(columnName), type: 'quantitative' };

This matters wherever Astrolabe constructs spec fragments from data-derived column names — most notably the chart builder (see Chart Builder spec) and any helper that injects an encoding. For specs the user authored by hand, escaping is the user's responsibility; Astrolabe does not rewrite hand-authored field: values.

Rules

• Do route every data-derived column name through escapeVegaField before it lands in a field: (or any field-position key).
• Don't ever pass a raw column name to field:. If the name came from data, it is unescaped until proven otherwise.

---

5. Debounced Preview

Rendering must never compete with typing. The preview re-renders only after the user pauses, the pending render is cancelled on each new keystroke, and a render in flight never blocks the editor.

The debounce delay is user-configurable via the performance.renderDebounce setting (range ~500–5000 ms). Read it live so changes take effect without reload.

// src/app/services/debounced-renderer.ts (sketch)
export interface DebouncedRenderer {
  /** Schedule a render after the debounce window; resets the timer. */
  schedule(): void;
  /** Render now, skipping the debounce (e.g. on fit-mode change or theme flip). */
  flush(): void;
  /** Cancel a pending render without rendering. */
  cancel(): void;
}

export function createDebouncedRenderer(opts: {
  /** Current debounce delay in ms; read fresh each schedule so settings apply live. */
  delayMs: () => number;
  /** Performs one render. Reads the current spec/theme; awaits the embed. */
  render: () => Promise<void>;
  /** Toggle the non-blocking busy indicator. */
  setBusy: (busy: boolean) => void;
}): DebouncedRenderer {
  let timer: ReturnType<typeof setTimeout> | null = null;
  let generation = 0; // guards against a stale in-flight render finishing late

  const run = async () => {
    timer = null;
    const mine = ++generation;
    opts.setBusy(true);
    try {
      await opts.render();
    } finally {
      // Only the most recent render clears the indicator.
      if (mine === generation) opts.setBusy(false);
    }
  };

  return {
    schedule() {
      if (timer) clearTimeout(timer); // cancel the pending render
      timer = setTimeout(run, opts.delayMs());
    },
    flush() {
      if (timer) {
        clearTimeout(timer);
        timer = null;
      }
      void run();
    },
    cancel() {
      if (timer) {
        clearTimeout(timer);
        timer = null;
      }
      generation++; // abandon any in-flight result
    },
  };
}

Wiring it to the store

Startup subscribers observe the inputs that affect the picture — the current spec text, the active fit mode, the UI theme — and call schedule() (debounced) for spec edits, or flush() for instantaneous controls like a fit-mode toggle:

// wired once at startup
useEditorStore.subscribe((s, prev) => {
  if (s.currentSpecText !== prev.currentSpecText) renderer.schedule(); // react to edits
});

useSettingsStore.subscribe((s, prev) => {
  if (s.previewFitMode !== prev.previewFitMode || s.uiTheme !== prev.uiTheme) {
    renderer.flush(); // immediate, no debounce
  }
});

Implemented policy: what renders immediately vs. debounced

The service above is a sketch — its useEditorStore/useSettingsStore are illustrative placeholders; the real inputs are useAppStore (previewFitMode + uiTheme) and useSnippetStore (draft text / bufferEpoch). The shipped renderer lives inline in LivePreview.tsx (one setTimeout whose delay is computed per change) and subscribes to the stores via hooks rather than startup subscribers. When it is extracted into a service, preserve this policy.

The debounce exists to stay out of the way while typing — nothing else. So the delay is 0 (immediate) for everything except keystrokes (spec §03C):

• Immediate — a programmatic buffer load (SnippetStore.bufferEpoch changed: select / create / duplicate / revert / hydrate) or a Draft↔Published switch (editorView changed). These are the cases §03C names; the editor and preview both key off bufferEpoch to tell a load from a keystroke.
• Debounced — a keystroke (only shownText changed). This is the churn the debounce protects against.

Detect "this was a keystroke" by elimination: shownText changed but bufferEpoch and editorView did not. Fit-mode and theme changes currently fall through the debounce too (harmless; not typing) — flush them if instant feedback is wanted, but never debounce a load or a view switch.

Busy indicator

setBusy(true/false) toggles store state that the preview reads to overlay a subtle, non-blocking spinner/shimmer. It sits over the existing chart so the last good render stays visible while the next one computes — the pane never goes blank mid-edit.

Rules

• Do read renderDebounce fresh on each schedule() (via the delayMs() thunk) so a settings change applies immediately.
• Do cancel the pending timer on every new input before scheduling the next.
• Do guard against out-of-order completion (the generation counter): a slow render that resolves after a newer one must not clobber the indicator or view.
• Do keep the busy indicator non-blocking and overlaid; never clear the chart to show "rendering…".
• Don't render synchronously on every keystroke.
• Don't await a render inside an input/keydown handler.

A second preview surface: the Chart Builder

The editor's LivePreview is bound to the snippet editor — it reads SnippetStore (shown spec), AppStore (fit mode/theme), and PreviewStore (shared error). The Chart Builder modal needs a preview of a different spec source (its config), so it does not reuse LivePreview; it runs its own small debounced render over the same chart-renderer.renderSpec + prepareSpecForRender, with local error state (never the shared PreviewStore, which would cross-talk with the editor). Two preview surfaces, one renderer service. Builder flow: chart-builder.ts (pure spec assembler) → ChartBuilderStore (config + create) → ChartBuilderModal's BuilderPreview. Reach for a reusable preview component only if a third surface appears.

The builder's X/Y axis controls live in the preview pane, not the config pane: the on-chart Columns/Rows shelves (OnChartShelves) sit above BuilderPreview, because axis position is a property of the chart (Tableau's Columns/Rows metaphor). The field shelf and the Colour/Size Marks card stay in the config pane. A reserved faceting slot in each shelf is a placeholder only.

---

6. Rendering Contract Lives Upstream (reference)

Before a spec reaches renderSpec, it passes through a pure transform in src/core/rendering.ts:

prepareSpecForRender(spec, { fitMode }): TopLevelSpec

It does two deterministic things, on a deep copy of the spec:

1. Dataset reference resolution — replaces any named-data reference with the referenced dataset's actual contents (inline values, raw CSV/TSV text, or a URL reference), recursing into layered/concat/child sub-specs.
2. Fit-mode sizing — rewrites width/height per the active fit mode using Vega-Lite's "container" keyword (Original = untouched; Width sets width:"container" and removes height; Height sets height:"container" and removes width; Full sets both — see spec §04 → Fit-mode sizing), recursing the same way.

This is content preparation, not embedding, and it is fully covered by the Live Preview spec. The only invariant this doc cares about:

prepareSpecForRender runs on a copy and returns a new spec. The renderer embeds that returned spec. The user's stored spec is never mutated by rendering.

The container-relative fit modes (Width/Height/Full) depend on "container" sizing to follow the pane. Re-fitting on a pane resize is not a re-embed: the existing view is re-measured via a ResizeObserver-driven event — see §8.

Rules

• Do call prepareSpecForRender between parse and embed, every render.
• Don't put reference resolution or fit-mode logic in the renderer — it is pure core logic and must be unit-testable without a DOM.
• Don't mutate the input spec anywhere in the pipeline.
• Fit modes overwrite the spec's own sizing (Width replaces width and deletes height, etc.), so a surface that lets the user set an explicit width/height must pass fitMode: 'default' while either is set and reserve the container fit for auto sizing — the Chart Builder preview does exactly this.

---

7. Error Handling

A spec that cannot be rendered must produce a readable message in the preview area and recover on its own once the spec is valid again. Errors arise at three stages, all funneled to one error field the preview reads:

Stage	Failure	Surfaced as
Parse	Invalid JSON	"Invalid JSON: …"
Prepare (prepareSpecForRender)	Referenced dataset missing/unfetchable	"Dataset not found: …"
Embed (vega-embed)	Vega-Lite compile / data error	"Rendering error: …"

// inside render(), driven by the debounced renderer
async function render(): Promise<void> {
  const text = useEditorStore.getState().currentSpecText.trim();

  // Empty/blank is NOT an error — render nothing, clean pane.
  if (!text) {
    current?.destroy();
    current = null;
    usePreviewStore.getState().setError(null);
    return;
  }

  let parsed: unknown;
  try {
    parsed = JSON.parse(text);
  } catch (e) {
    usePreviewStore.getState().setError(`Invalid JSON: ${(e as Error).message}`);
    return; // keep the last good chart underneath the error, or show the message
  }

  try {
    const { previewFitMode, uiTheme } = useSettingsStore.getState();
    const prepared = prepareSpecForRender(parsed, { fitMode: previewFitMode });
    const config = chartConfigFor(uiTheme);
    current?.destroy();
    current = await renderSpec(node, prepared, config);
    usePreviewStore.getState().setError(null); // success clears any prior error
  } catch (e) {
    usePreviewStore
      .getState()
      .setError(
        `Rendering error: ${(e as Error).message}. ` +
          `Check your JSON syntax and that the spec is valid Vega-Lite.`,
      );
  }
}

The preview component renders the chart node when error is null, and the error panel when it is set. Because every successful render clears the error, recovery is automatic: the next valid edit re-renders and wipes the message — no manual retry, no reload.

Rules

• Do treat empty/blank spec text as "render nothing" — finalize the current view, clear the error, show a clean empty pane.
• Do clear the error state on every successful render.
• Do make messages legible and actionable (the underlying reason plus a hint to check JSON/Vega-Lite validity), never a raw stack trace dump.
• Do distinguish the failing stage in the message (Invalid JSON vs Dataset not found vs Rendering error).
• Don't show a broken/partial chart — replace the chart area with the message.
• Don't require a manual "retry"; validity restores the chart on its own.

---

8. Container Sizing & Pane Resize (two gotchas that cost real time)

Vega-Lite's "container" sizing is responsible for the Width/Height/Full fit modes, and it has two non-obvious failure modes. Both were rediscovered the hard way; this section is the shortcut.

Gotcha 1 — the embed host shrink-wraps, collapsing width:"container"

vega-embed brands the element you embed into with its own .vega-embed { display: inline-block }, injected into <head> at runtime so it wins the cascade over a class you put on that same element. inline-block shrink-wraps horizontally, and "container" width reads host.clientWidth — so the chart collapses to near-zero width. (Height often survives because a tall box keeps clientHeight, which is why the symptom is "Width broken, Height fine".) Note also: vega-embed only adds its responsive chart-wrapper (the element its width:100% rule targets) when actions are enabled — we pass actions: false, so that path is dead and the host is branded directly.

Fix: embed into a dedicated inner host with a static className (React never re-reconciles it, so Vega's runtime classes survive) nested inside a React-owned frame that carries the fit-mode class. Size the host with two-class selectors (.fitWidth .host { width: 100% }) that out-specify .vega-embed. Original mode lets the host stay natural and the pane scrolls.

Gotcha 2 — Vega re-measures only on window:resize

The compiled width/height signals re-evaluate containerSize() only on events: "window:resize". Consequences: view.resize() re-runs layout with the stale size (it does not re-measure), and a pane drag fires no window resize, so a responsive chart does not follow the pane on its own.

Fix: a ResizeObserver on the host → window.dispatchEvent(new Event('resize')) (behind RenderHandle.resize(), keeping the Vega knowledge in the renderer). ResizeObserver callbacks are frame-batched, so this tracks a drag without a debounce. Because only the container-bound dimension carries the resize handler, Width re-fits width and leaves height natural automatically — no fit-mode bookkeeping. Gate the observer to responsive modes (Original needs no re-fit).

Rules

• Do give vega-embed its own inner host element; never put a React-managed, changing className on the element vega-embed brands.
• Do out-specify .vega-embed (two-class selectors) when you must size the host.
• Do bridge pane-resize via a synthetic window:resize, not view.resize().
• Don't assume actions: false leaves you the responsive chart-wrapper — it doesn't.
• Don't re-embed just to re-fit a resize; re-measure the existing view.

---

Summary

Concern	Mechanism	Source of truth
Embedding	One renderSpec over vega-embed, actions: false, renderer: 'svg'	src/app/services/chart-renderer.ts
View teardown	view.finalize() before each re-render and on unmount	the renderer's RenderHandle
Theming	Vega Config per UI theme, applied at embed time	chartConfigFor() in src/core/vega-themes.ts
Field names	escapeVegaField on every data-derived field:	src/core/rendering.ts
Debounce	Inline timer; 0 on buffer-load/view-switch, renderDebounce on keystroke (§5)	LivePreview.tsx (service not yet extracted)
Spec prep	prepareSpecForRender (pure, on a copy)	src/core/rendering.ts (see Live Preview)
Errors	One error field, cleared on success, empty = nothing	PreviewStore.error
Container fit	Inner host + frame (out-specify .vega-embed); resize via synthetic window:resize	§8 (LivePreview + chart-renderer)