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.

---

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.
• 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, default mark colors. 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 (sketch)
import type { Config } from 'vega-lite';

export const lightChartConfig: Config = {
  background: 'transparent',
  font: '"Inter", sans-serif',
  title: { fontSize: 15, fontWeight: 600, color: '#1c1c1e' },
  axis: {
    domainColor: '#1c1c1e',
    gridColor: '#e4e4e7',
    gridDash: [3, 3],
    labelColor: '#52525b',
    titleColor: '#1c1c1e',
    labelFontSize: 11,
    titleFontSize: 12,
  },
  range: {
    category: ['#2f6df6', '#f5a524', '#17b890', '#e5484d', '#8b5cf6', '#0ea5e9'],
  },
  view: { stroke: 'transparent' },
};

export const experimentalChartConfig: Config = {
  background: 'transparent',
  font: '"Inter", sans-serif',
  title: { fontSize: 15, fontWeight: 600, color: '#f4f4f5' },
  axis: {
    domainColor: '#a1a1aa',
    gridColor: '#3f3f46',
    gridDash: [3, 3],
    labelColor: '#a1a1aa',
    titleColor: '#f4f4f5',
    labelFontSize: 11,
    titleFontSize: 12,
  },
  range: {
    category: ['#5b8def', '#f5a524', '#2dd4a7', '#f0666b', '#a78bfa', '#38bdf8'],
  },
  view: { stroke: 'transparent' },
};

One mapping, in one place, is the single source of truth for theme → config:

// src/core/vega-themes.ts
import type { UiTheme } from './theme'; // core-local — never import from src/app

const CHART_CONFIG: Record<UiTheme, Config> = {
  light: lightChartConfig,
  experimental: experimentalChartConfig,
};

export function chartConfigFor(theme: UiTheme): Config {
  return CHART_CONFIG[theme];
}

The renderer reads the active UI theme (from the store) and passes the matching config into renderSpec. When the theme changes, the same subscriber that drives re-rendering picks up the new config and the chart restyles automatically.

Rules

• Do keep chartConfigFor as the only place that maps a UI theme to a Vega config. Adding a UI theme = adding one config and one map entry.
• Do set chart background: 'transparent' so the pane's own background shows through and theme switches look seamless.
• 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 let the user's stored spec carry a config; the theme config is applied at embed time via the embed options, leaving the spec theme-agnostic.

---

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
  }
});

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.

---

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/Height/Full set the corresponding dimension(s) to "container"), 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 renderer: 'svg' plus "container" sizing to follow the pane; when the pane resizes, re-running prepareSpecForRender + re-embedding (a flush()) re-fits the chart.

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.

---

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.

---

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	createDebouncedRenderer, delay from renderDebounce setting	src/app/services/debounced-renderer.ts
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