diff --git a/.changeset/guided-imports-live-overviews.md b/.changeset/guided-imports-live-overviews.md
new file mode 100644
index 0000000..b318750
--- /dev/null
+++ b/.changeset/guided-imports-live-overviews.md
@@ -0,0 +1,12 @@
+---
+"@modernrelay/orbit-core": minor
+"@modernrelay/orbit-data": minor
+"@modernrelay/orbit-react": patch
+"@modernrelay/orbit-engine-cosmos": patch
+---
+
+Add bounded, cancellable graph preparation with progress notifications and a CSV preview helper. All preparation formats now support optional columnar output while retaining object snapshots as the default and preserving the v1 artifact format.
+
+Expose live overview subscriptions and share a bounded position cache between labels and the minimap. Cosmos uses asynchronous position reads for scenes up to 10,000 nodes when available and a conservative synchronous cadence for larger scenes, rejects stale results after graph or engine changes, and stops sampling at rest.
+
+Add a guided CSV import flow to the demo and a complete first-graph quickstart verified against packed packages.
diff --git a/README.md b/README.md
index a06d1e1..84219d8 100644
--- a/README.md
+++ b/README.md
@@ -26,6 +26,10 @@ Handles 100K+ node graphs. UI components included: search, tables, histograms, a
 npm install @modernrelay/orbit-react @modernrelay/orbit-core @modernrelay/orbit-engine-cosmos
 ```
 
+Start with [Your first Orbit graph](docs/core/getting-started.md): a complete
+React + TypeScript app with a three-node graph, search, and controlled selection.
+The example is compiled and exercised against the published package shape in CI.
+
 The Cosmos engine and OmniGraph adapter require Node.js 22 or newer.
 
 All five packages release in lockstep. See
diff --git a/apps/demo/e2e/csv-import.spec.ts b/apps/demo/e2e/csv-import.spec.ts
new file mode 100644
index 0000000..08b8631
--- /dev/null
+++ b/apps/demo/e2e/csv-import.spec.ts
@@ -0,0 +1,109 @@
+import { expect, test } from '@playwright/test';
+import type { Page } from '@playwright/test';
+
+const csv = (name: string, text: string) => ({ name, mimeType: 'text/csv', buffer: Buffer.from(text) });
+const dialog = (page: Page) => page.getByRole('dialog', { name: 'Import CSV graph' });
+
+async function ready(page: Page): Promise<void> {
+  await page.goto('/?declNodes=100');
+  await page.waitForSelector('[data-testid="status-dot"][title="ready"]');
+}
+
+// Delay actual File reads, preserving real CSV parsing and AbortSignal handling.
+// This makes cancellation/replacement deterministic without waiting for a huge file.
+async function slowFileReads(page: Page): Promise<void> {
+  await page.addInitScript(() => {
+    const stream = File.prototype.stream;
+    File.prototype.stream = function () {
+      const source = stream.call(this);
+      if (this.name !== 'slow.csv') return source;
+      const reader = source.getReader();
+      let cancelled = false;
+      return new ReadableStream<Uint8Array>({
+        async pull(controller) {
+          await new Promise((resolve) => setTimeout(resolve, 250));
+          if (cancelled) return;
+          const next = await reader.read();
+          if (cancelled) return;
+          if (next.done) controller.close(); else controller.enqueue(next.value);
+        },
+        async cancel() { cancelled = true; await reader.cancel(); },
+      });
+    };
+  });
+}
+const slowCsv = () => csv('slow.csv', 'source,target,weight\n' + Array.from({ length: 20_000 }, (_, i) => `n${i},n${i + 1},${i}\n`).join(''));
+
+test('preview and map custom headers, with node attributes and string IDs', async ({ page }) => {
+  await ready(page);
+  const before = await page.getByTestId('node-count').innerText();
+  await page.getByTestId('csv-file-input').setInputFiles(csv('connections.csv',
+    'relation,from_person,to_person,notes\nr1,001,002,"a,b"\nr2,002,003,hello\n'));
+  await expect(dialog(page).getByRole('table', { name: 'Edges preview' })).toContainText('a,b');
+  await expect(page.getByTestId('node-count')).toHaveText(before);
+  await dialog(page).getByRole('combobox', { name: 'Source column', exact: true }).selectOption('from_person');
+  await dialog(page).getByRole('combobox', { name: 'Target column', exact: true }).selectOption('to_person');
+  await dialog(page).getByRole('combobox', { name: 'Edge ID column', exact: true }).selectOption('relation');
+  await page.getByTestId('csv-nodes-input').setInputFiles(csv('people.csv',
+    'person_id,name,cluster,degree\n001,Alice,west,many\n002,Bob,east,2\n003,Carol,north,3\n'));
+  await expect(dialog(page).getByRole('table', { name: 'Nodes preview' })).toContainText('Alice');
+  await dialog(page).getByRole('combobox', { name: 'Node ID column', exact: true }).selectOption('person_id');
+  await dialog(page).getByRole('button', { name: 'Import graph', exact: true }).click();
+  await expect(dialog(page)).not.toBeVisible();
+  await expect(page.getByTestId('node-count')).toHaveText('3');
+  await expect(page.getByTestId('csv-summary')).toContainText('2 edges');
+  await page.locator('[data-orbit-search-input]').fill('Alice');
+  await expect(page.locator('[data-orbit-search-result]').first()).toContainText('Alice');
+  await page.getByTestId('explorer-toggle').click();
+  const explorer = page.getByRole('region', { name: 'Graph exploration' });
+  await expect(explorer.locator('[data-orbit-table-row="001"]')).toBeVisible();
+});
+
+test('cancelling an in-flight import keeps the current dataset', async ({ page }) => {
+  await slowFileReads(page);
+  await ready(page);
+  const before = await page.getByTestId('node-count').innerText();
+  await page.getByTestId('csv-file-input').setInputFiles(slowCsv());
+  await dialog(page).getByRole('button', { name: 'Import graph', exact: true }).click();
+  await expect(page.getByTestId('csv-progress')).toContainText('Preparing graph');
+  await dialog(page).getByRole('button', { name: 'Cancel import', exact: true }).click();
+  await expect(dialog(page)).not.toBeVisible();
+  await expect(page.getByTestId('csv-panel')).toContainText('Import cancelled');
+  await expect(page.getByTestId('node-count')).toHaveText(before);
+  // A subsequent successful import must remain authoritative when the old read settles.
+  await page.getByTestId('csv-file-input').setInputFiles(csv('small.csv', 'source,target\na,b\n'));
+  await dialog(page).getByRole('button', { name: 'Import graph', exact: true }).click();
+  await expect(page.getByTestId('node-count')).toHaveText('2');
+  await expect(page.getByTestId('csv-summary')).toContainText('small.csv');
+});
+
+test('a second upload replaces an active preparation instead of being ignored', async ({ page }) => {
+  await slowFileReads(page);
+  await ready(page);
+  await page.getByTestId('csv-file-input').setInputFiles(slowCsv());
+  await dialog(page).getByRole('button', { name: 'Import graph', exact: true }).click();
+  await expect(page.getByTestId('csv-progress')).toBeVisible();
+  const chooseReplacement = page.waitForEvent('filechooser');
+  await dialog(page).getByRole('button', { name: 'Choose different edges file', exact: true }).click();
+  await (await chooseReplacement).setFiles(csv('replacement.csv', 'source,target\nnew-a,new-b\nnew-b,new-c\n'));
+  await expect(dialog(page)).toContainText('replacement.csv');
+  await dialog(page).getByRole('button', { name: 'Import graph', exact: true }).click();
+  await expect(page.getByTestId('csv-summary')).toContainText('replacement.csv');
+  await expect(page.getByTestId('node-count')).toHaveText('3');
+});
+
+test('preview errors preserve the graph and the importer fits a narrow screen', async ({ page }) => {
+  await ready(page);
+  const before = await page.getByTestId('node-count').innerText();
+  await page.setViewportSize({ width: 390, height: 844 });
+  await page.getByTestId('csv-file-input').setInputFiles(csv('empty.csv', ''));
+  await expect(dialog(page).getByRole('alert')).toContainText(/header|empty/i);
+  await expect(dialog(page).getByRole('button', { name: 'Import graph', exact: true })).toBeDisabled();
+  await expect(page.getByTestId('node-count')).toHaveText(before);
+  const bounds = await dialog(page).boundingBox();
+  expect(bounds).not.toBeNull();
+  expect(bounds!.x).toBeGreaterThanOrEqual(0);
+  expect(bounds!.x + bounds!.width).toBeLessThanOrEqual(390);
+  await page.keyboard.press('Escape');
+  await expect(dialog(page)).not.toBeVisible();
+});
diff --git a/apps/demo/e2e/data-search.spec.ts b/apps/demo/e2e/data-search.spec.ts
index 85af3a9..9a7d32a 100644
--- a/apps/demo/e2e/data-search.spec.ts
+++ b/apps/demo/e2e/data-search.spec.ts
@@ -1,5 +1,5 @@
 /**
- * Data + search smoke for the v0.9 surface.
+ * Data, search and live minimap integration checks.
  *
  * Drives the packaged <GraphSearch>, the <GraphMinimap>, the
  * <GraphTooltip>, and the CSV prepared-data lane through the demo
@@ -10,15 +10,15 @@
  * - a host-filtered target activates to 'unavailable/filtered', surfaced by
  * the demo's status-bar `search-unavailable` line (the result
  * contract: search NEVER mutates scope/filters itself);
- * - the minimap rasterizes (the demo declares seeded node positions — the
- * documented v0.9 CPU-fallback scene source) and a corner click issues a
- * REAL `setViewport` pan, asserted via the status bar's data-viewport-x/y;
+ * - the minimap rasterizes both seeded data and unpositioned CSV nodes from
+ * the shared live position cache; a corner click pans the real viewport,
+ * asserted via the status bar's data-viewport-x/y;
  * - hovering a node (grid hunt around the center — the same strategy as the
  * ingestion spec's right-click, hit-testing exact centers is flaky) shows
  * the hover card with label + attr rows;
  * - `setInputFiles` on the CSV panel's hidden input feeds a 50-row edges
- * fixture through `prepareGraphData` (deriveNodes) — the header counts
- * swap to the derived 51/50 and the summaries line renders.
+ * fixture through preview/confirmation and `prepareGraphData` (deriveNodes):
+ * counts swap to 51/50, summaries render and live force positions paint.
  *
  * CI note (repo pattern): the force simulation is paused before interaction
  * phases — cosmos free-runs its rAF while data is present and on
@@ -127,9 +127,8 @@ test('minimap: canvas rasterizes and a corner click pans the real viewport', asy
 
   const canvas = page.locator(MINIMAP_CANVAS);
   await expect(canvas).toBeVisible();
-  // The viewport RECTANGLE only displays once a frame has rasterized (the
-  // demo's seeded declared positions are the v0.9 CPU-fallback scene source)
-  // AND the store has a live viewport — so its visibility proves the blit.
+  // The viewport rectangle displays only after a position snapshot has
+  // rasterized and the store has a live viewport.
   await expect(page.locator(MINIMAP_RECT)).toBeVisible({ timeout: 10_000 });
 
   const zoom = page.locator(ZOOM_VALUE);
@@ -155,6 +154,9 @@ test('minimap: canvas rasterizes and a corner click pans the real viewport', asy
 test('tooltip: hovering a node shows the hover card with label and attr rows', async ({
   page,
 }) => {
+  // Pausing physics does not cancel the mount camera fit. Freeze the camera
+  // as well so the picked node remains under the pointer through the delay.
+  await page.emulateMedia({ reducedMotion: 'reduce' });
   await gotoReady(page);
   await pauseSimulation(page);
 
@@ -212,6 +214,7 @@ test('csv drop: a 50-row edges fixture derives nodes and swaps the dataset', asy
 
   // The drop-zone's hidden input is the testability seam for DnD.
   await page.setInputFiles('[data-testid="csv-file-input"]', fixture);
+  await page.getByRole('button', { name: 'Import graph', exact: true }).click();
 
   // prepared snapshot applied on a fresh instance (key remount) → new counts.
   await expect(page.getByTestId('node-count')).toHaveText('51', { timeout: 20_000 });
@@ -226,6 +229,19 @@ test('csv drop: a 50-row edges fixture derives nodes and swaps the dataset', asy
   await expect(summary).toContainText('weight');
   await expect(page.getByTestId('csv-error')).toHaveCount(0);
 
+  // Derived CSV nodes have no declared x/y. Their force layout must still
+  // produce a nonempty live minimap and a usable world-space pan mapping.
+  await pauseSimulation(page);
+  await expect(page.locator(MINIMAP_RECT)).toBeVisible({ timeout: 10_000 });
+  await expect.poll(() => page.locator(MINIMAP_CANVAS).evaluate((el) => {
+    const canvas = el as HTMLCanvasElement;
+    const pixels = canvas.getContext('2d')?.getImageData(0, 0, canvas.width, canvas.height).data;
+    return pixels?.some((value, i) => i % 4 === 3 && value > 0) ?? false;
+  }), { message: 'unpositioned force nodes should paint the live overview' }).toBe(true);
+  const centerBefore = await page.locator(ZOOM_VALUE).getAttribute('data-viewport-x');
+  await page.locator(MINIMAP_CANVAS).click({ position: { x: 18, y: 18 } });
+  await expect.poll(() => page.locator(ZOOM_VALUE).getAttribute('data-viewport-x')).not.toBe(centerBefore);
+
   // The CSV dataset is searchable by id (derived nodes carry no attrs, so
   // the index is id-only here).
   await pauseSimulation(page);
@@ -234,7 +250,7 @@ test('csv drop: a 50-row edges fixture derives nodes and swaps the dataset', asy
   await expect(page.locator(SEARCH_LABEL).first()).toHaveText(/^c17/);
 });
 
-test('a newer data-mode choice supersedes an in-flight CSV preparation', async ({
+test('cancelling an in-flight CSV preparation permits choosing another data mode', async ({
   page,
 }, testInfo) => {
   // Make the otherwise-small fixture deterministically asynchronous. Orbit's
@@ -261,6 +277,7 @@ test('a newer data-mode choice supersedes an in-flight CSV preparation', async (
           } else controller.enqueue(next.value);
         },
         cancel(reason) {
+          state.__orbitCsvStreamFinished = true;
           return reader.cancel(reason);
         },
       });
@@ -272,12 +289,15 @@ test('a newer data-mode choice supersedes an in-flight CSV preparation', async (
   await gotoReady(page);
 
   await page.setInputFiles('[data-testid="csv-file-input"]', fixture);
+  await page.getByRole('button', { name: 'Import graph', exact: true }).click();
+  await page.keyboard.press('Escape');
+  await expect(page.getByRole('dialog')).not.toBeVisible();
   await page.getByTestId('semantic-mode').click();
   await expect(page.getByTestId('m5-panel')).toBeVisible({ timeout: 15_000 });
 
-  // Wait for EOF rather than a wall-clock approximation, then give the
-  // preparation promise and React commit a chance to drain. Its completion
-  // must not replace the newer semantic mode or publish a CSV summary.
+  // Wait for EOF/cancellation rather than a wall-clock approximation, then
+  // give preparation and React a chance to drain. A cancelled import must
+  // not replace the newer mode or publish a CSV summary.
   await page.waitForFunction(
     () =>
       (window as typeof window & { __orbitCsvStreamFinished?: boolean })
diff --git a/apps/demo/e2e/exploration-workflows.spec.ts b/apps/demo/e2e/exploration-workflows.spec.ts
index 9cf0544..1547fb4 100644
--- a/apps/demo/e2e/exploration-workflows.spec.ts
+++ b/apps/demo/e2e/exploration-workflows.spec.ts
@@ -7,6 +7,7 @@ test('CSV exploration connects search, paths, table filtering, and checkpoint re
     name: 'suppliers.csv', mimeType: 'text/csv',
     buffer: Buffer.from('source,target,type,evidence\nAcme,Beta,SUPPLIES,Contract\nBeta,Cedar,SUPPLIES,Invoice\n'),
   });
+  await page.getByRole('button', { name: 'Import graph', exact: true }).click();
   await expect(page.getByTestId('node-count')).toHaveText('3');
   await page.getByTestId('explorer-toggle').click();
   const explorer = page.getByRole('region', { name: 'Graph exploration' });
diff --git a/apps/demo/e2e/ingestion.spec.ts b/apps/demo/e2e/ingestion.spec.ts
index 9588181..171a101 100644
--- a/apps/demo/e2e/ingestion.spec.ts
+++ b/apps/demo/e2e/ingestion.spec.ts
@@ -54,18 +54,34 @@ async function openNodeContextMenu(page: Page): Promise<void> {
     }
   }
   const candidates: readonly [number, number][] = [[cx, cy], ...dense, ...grid];
-  for (const [x, y] of candidates) {
-    await page.mouse.click(x, y, { button: 'right' });
-    try {
-      await expect(page.locator(CONTEXT_MENU)).toBeVisible({ timeout: 1_000 });
-    } catch {
-      continue; // click landed before pointer wiring settled — try the next
+  // Candidate misses can open Chromium's native macOS menu, whose tracking
+  // loop blocks context teardown and ignores CDP Escape. Prevent only that
+  // browser default during probing; Orbit's context-menu handlers still run.
+  const nativeMenuGuard = await page.evaluateHandle(() => {
+    const controller = new AbortController();
+    document.addEventListener('contextmenu', (event) => event.preventDefault(), {
+      signal: controller.signal,
+    });
+    return controller;
+  });
+  try {
+    for (const [x, y] of candidates) {
+      await page.mouse.click(x, y, { button: 'right' });
+      try {
+        await expect(page.locator(CONTEXT_MENU)).toBeVisible({ timeout: 1_000 });
+      } catch {
+        await page.keyboard.press('Escape');
+        continue;
+      }
+      if ((await page.locator(ISOLATE_ITEM).count()) > 0) return; // node menu
+      await page.keyboard.press('Escape'); // background menu — dismiss, retry
+      await expect(page.locator(CONTEXT_MENU)).toHaveCount(0);
     }
-    if ((await page.locator(ISOLATE_ITEM).count()) > 0) return; // node menu
-    await page.keyboard.press('Escape'); // background menu — dismiss, retry
-    await expect(page.locator(CONTEXT_MENU)).toHaveCount(0);
+    throw new Error('no right-click candidate landed on a node');
+  } finally {
+    await nativeMenuGuard.evaluate((controller) => controller.abort());
+    await nativeMenuGuard.dispose();
   }
-  throw new Error('no right-click candidate landed on a node');
 }
 
 test('stream feed → live meter → commit → isolate via context menu → reset scope', async ({
diff --git a/apps/demo/src/App.tsx b/apps/demo/src/App.tsx
index d49baac..b9d7017 100644
--- a/apps/demo/src/App.tsx
+++ b/apps/demo/src/App.tsx
@@ -55,8 +55,8 @@
  * live sim positions in the reconciler, so force layouts keep drifting).
  * - <GraphTooltip> always mounted; <GraphInspector> right dock behind a
  * toolbar toggle (it replaces the workbench sidebar while open).
- * - CSV drop (csvDrop.tsx): one edges CSV → `prepareGraphData`
- * edges-only/deriveNodes → applied as a declarative snapshot on a
+ * - CSV import (csvDrop.tsx): preview and map edges/optional nodes → `prepareGraphData`
+ * → applied as a declarative snapshot on a
  * fresh instance (`key` remount — the previous mode may have been a
  * replace-session stream), summaries as a panel line.
  *
@@ -139,7 +139,7 @@ import { GraphTimeline } from '@modernrelay/orbit-react/components/Timeline';
 import { GraphToolbar } from '@modernrelay/orbit-react/components/Toolbar';
 import { GraphTooltip } from '@modernrelay/orbit-react/components/Tooltip';
 
-import { CsvDropZone, loadCsvEdgesFile } from './csvDrop';
+import { CsvDropZone } from './csvDrop';
 import type { CsvDropResult } from './csvDrop';
 import { DEFAULT_GENERATE, clusterName, generateGraph, nextSeed } from './generate';
 import type { DemoEdgeAttrs, DemoNodeAttrs } from './generate';
@@ -179,10 +179,10 @@ import type { StreamFamily, StreamProgress } from './streamFeed';
 import * as S from './styles';
 import { BACKGROUND, LIGHT_BACKGROUND, clusterColor, typeColor } from './styles';
 
-/** Union attrs: generated demo shapes or Omnigraph-loaded shapes, discriminated
- * by the adapter-injected type field that demo attrs lack. */
-type AppNodeAttrs = DemoNodeAttrs | OmnigraphDisplayNodeAttrs;
-type AppEdgeAttrs = DemoEdgeAttrs | OmnigraphDisplayEdgeAttrs;
+/** Generated, Omnigraph, or imported CSV attributes. Narrow caller fields
+ * before applying demo-specific rendering. */
+type AppNodeAttrs = DemoNodeAttrs | OmnigraphDisplayNodeAttrs | Record<string, unknown>;
+type AppEdgeAttrs = DemoEdgeAttrs | OmnigraphDisplayEdgeAttrs | Record<string, unknown>;
 
 type NodeMap = ReadonlyMap<NodeId, GraphNode<AppNodeAttrs>>;
 
@@ -213,15 +213,15 @@ const SIMULATION: SimulationConfig = { repulsion: 0.6, gravity: 0.25 };
 const nodeColor = (node: GraphNode<AppNodeAttrs>): string => {
   const a = node.attrs;
   if (a === undefined) return clusterColor(0);
-  if (ORBIT_TYPE_KEY in a) return typeColor(a[ORBIT_TYPE_KEY]);
-  return clusterColor(a.cluster);
+  if (ORBIT_TYPE_KEY in a && typeof a[ORBIT_TYPE_KEY] === 'string') return typeColor(a[ORBIT_TYPE_KEY]);
+  return clusterColor('cluster' in a && typeof a.cluster === 'number' && Number.isFinite(a.cluster) ? a.cluster : 0);
 };
 
 /** Degree-scaled size; omnigraph degree is host-computed during ingest and
  * absent attrs fall back to the base size. */
 const nodeSize = (node: GraphNode<AppNodeAttrs>): number => {
   const a = node.attrs;
-  const degree = a !== undefined && 'degree' in a ? a.degree ?? 0 : 0;
+  const degree = a !== undefined && 'degree' in a && typeof a.degree === 'number' && Number.isFinite(a.degree) ? Math.max(0, a.degree) : 0;
   return 2 + Math.sqrt(degree);
 };
 
@@ -278,10 +278,10 @@ const CLUSTER_COLOR_SCALE: Scale<string, AppNodeAttrs> = {
 const labelOf = (node: GraphNode<AppNodeAttrs>): string => {
   const a = node.attrs;
   if (a === undefined) return node.id;
-  if (ORBIT_TYPE_KEY in a) {
-    return `${a[ORBIT_TYPE_KEY]} · ${'title' in a ? a.title : a.name}`;
-  }
-  return a.label;
+  const label = 'label' in a && typeof a.label === 'string' ? a.label
+    : 'title' in a && typeof a.title === 'string' ? a.title
+      : 'name' in a && typeof a.name === 'string' ? a.name : node.id;
+  return ORBIT_TYPE_KEY in a && typeof a[ORBIT_TYPE_KEY] === 'string' ? `${a[ORBIT_TYPE_KEY]} · ${label}` : label;
 };
 
 /** Hover-card title for an EDGE. Omnigraph edges carry the relationship name
@@ -358,14 +358,15 @@ const ACCESSIBILITY: AccessibilityConfig<AppNodeAttrs> = {
 // below takes effect on every mode switch. The default local service indexes
 // node ids ALWAYS plus exactly these attr fields — it never guesses attr names.
 
-/** Generated data (declarative/stream/CSV): the `label` attr. CSV-derived
- * nodes carry no attrs at all, so search degrades to id-only there. */
+/** Generated data indexes labels. Imported nodes can also name a person or
+ * title a document; edge-only CSV imports remain searchable by node ID. */
 const SEARCH_INDEX: readonly string[] = ['label'];
+const CSV_SEARCH_INDEX: readonly string[] = ['label', 'name', 'title'];
 
 /** Omnigraph mode: the intel-fixture content fields. */
 const OG_SEARCH_INDEX: readonly string[] = ['name', 'title', 'brief'];
 
-// --- minimap seed positions --------------------------------------------------
+// --- generated graph seed positions -----------------------------------------
 
 const GOLDEN_ANGLE = 2.399963229728653;
 /** Cosmos space is [0, 4096] with unknown-position ring seeding at r=1024
@@ -374,9 +375,9 @@ const SEED_CENTER = 2048;
 const SEED_RADIUS_STEP = 17; // r = 17·√i → ≈1005 at i=3500
 
 /**
- * v0.9 minimap trim: the CPU fallback rasterizes DECLARED node
- * positions, so the demo declares a deterministic golden-angle sunflower
- * seed for every position-less node. Seeds depend ONLY on the node's array
+ * Give generated graphs deterministic golden-angle sunflower positions.
+ * Imported graphs use the engine's default seeds and the live minimap cache.
+ * These seeds depend only on the node's array
  * index — stable across the Add-500 superset — and the reconciler defers
  * UNCHANGED declarations to live sim positions, so the force layout still
  * owns motion; the declaration doubles as the sim's initial placement.
@@ -626,11 +627,9 @@ export function App() {
   const [inspectorOpen, setInspectorOpen] = useState(false);
   /** Last unavailable activation ("<label>: <reason>") — sticky. */
   const [searchNote, setSearchNote] = useState<string | null>(null);
-  const [csvError, setCsvError] = useState<string | null>(null);
-  /** Invalidates an in-flight CSV preparation when a newer data-mode action
-   * wins. Preparation intentionally runs before the graph mode changes. */
+  /** A newer data action remounts the importer and aborts pending preparation.
+   * Successful preparation is the only CSV action that replaces the graph. */
   const csvLoadEpochRef = useRef(0);
-  const csvBusyRef = useRef(false);
 
   // --- M5 semantic-exploration state (see semantic.tsx) ---
   const [m5Grouping, setM5Grouping] = useState<M5Grouping>('none');
@@ -680,16 +679,12 @@ export function App() {
     [snapshot],
   );
 
-  /** CSV mode: the prepared snapshot under the app's attr generics
-   * safe because derived nodes carry NO attrs and edge attrs are never field-
-   * accessed here; every accessor handles `attrs === undefined`. Seeded like
-   * the generated data so the minimap rasterizes it. */
+  /** CSV attributes are arbitrary caller data. Display accessors above narrow
+   * values before using them; the original fields remain available in the inspector. */
   const csvSnapshot = useMemo<GraphSnapshot<AppNodeAttrs, AppEdgeAttrs> | null>(
     () =>
       mode.kind === 'csv'
-        ? seedSnapshotPositions(
-            mode.result.prepared.snapshot as unknown as GraphSnapshot<AppNodeAttrs, AppEdgeAttrs>,
-          )
+        ? mode.result.prepared.snapshot
         : null,
     [mode],
   );
@@ -859,7 +854,6 @@ export function App() {
     setMode(DECLARATIVE);
     setMeter(null);
     resetOmnigraphState();
-    setCsvError(null);
     setSelection([]);
     setPendingIsolate(false);
     setDragNote(null);
@@ -980,35 +974,17 @@ export function App() {
   // mode change remounts <Graph> (`key`) — the previous mode may have been a
   // replace-session stream, and a fresh instance takes the declarative
   // prepared snapshot without racing it.
-  const onCsvFile = useCallback(
-    (file: File) => {
-      if (csvBusyRef.current) return; // one prepare at a time
-      csvBusyRef.current = true;
-      const requestEpoch = ++csvLoadEpochRef.current;
-      setCsvError(null);
-      loadCsvEdgesFile(file)
-        .then((result) => {
-          if (csvLoadEpochRef.current !== requestEpoch) return;
-          setSelection([]);
-          setPendingIsolate(false);
-          setDragNote(null);
-          setError(null);
-          setMeter(null);
-          resetOmnigraphState();
-          setExcludedClusters(EMPTY_CLUSTER_SET);
-          setExcludedTypes(EMPTY_TYPE_SET);
-          setMode((m) => ({ kind: 'csv', runId: m.kind === 'csv' ? m.runId + 1 : 1, result }));
-        })
-        .catch((err: unknown) => {
-          if (csvLoadEpochRef.current !== requestEpoch) return;
-          setCsvError(err instanceof Error ? err.message : String(err));
-        })
-        .finally(() => {
-          csvBusyRef.current = false;
-        });
-    },
-    [resetOmnigraphState],
-  );
+  const onCsvPrepared = useCallback((result: CsvDropResult) => {
+    setSelection([]);
+    setPendingIsolate(false);
+    setDragNote(null);
+    setError(null);
+    setMeter(null);
+    resetOmnigraphState();
+    setExcludedClusters(EMPTY_CLUSTER_SET);
+    setExcludedTypes(EMPTY_TYPE_SET);
+    setMode((current) => ({ kind: 'csv', runId: current.kind === 'csv' ? current.runId + 1 : 1, result }));
+  }, [resetOmnigraphState]);
 
   // --- M5 semantic mode -----------------------------------------------
   // Same remount discipline as every other mode switch (`graphKey`): the M5
@@ -1023,7 +999,6 @@ export function App() {
       setError(null);
       setMeter(null);
       resetOmnigraphState();
-      setCsvError(null);
       setExcludedClusters(EMPTY_CLUSTER_SET);
       setExcludedTypes(EMPTY_TYPE_SET);
       setM5Groups(M5_MANUAL_GROUPS);
@@ -1493,7 +1468,7 @@ export function App() {
         onGroupClick={onGroupClick}
         onMetaEdgeClick={onMetaEdgeClick}
         accessibility={ACCESSIBILITY}
-        searchIndex={mode.kind === 'omnigraph' ? OG_SEARCH_INDEX : SEARCH_INDEX}
+        searchIndex={mode.kind === 'omnigraph' ? OG_SEARCH_INDEX : mode.kind === 'csv' ? CSV_SEARCH_INDEX : SEARCH_INDEX}
         onSearchResultUnavailable={onSearchUnavailable}
         // The FIXED M5 layout states its own camera (M5_HOME_VIEW) once the
         // engine is live, so the mount-time fit — a heuristic over whatever the
@@ -1603,9 +1578,9 @@ export function App() {
               )}
               {/* CSV drop lane: drop overlay + hidden-input seam. */}
               <CsvDropZone
+                key={csvLoadEpochRef.current}
                 summary={mode.kind === 'csv' ? mode.result.summaryLine : null}
-                error={csvError}
-                onFile={onCsvFile}
+                onPrepared={onCsvPrepared}
               />
             </div>
             <div style={S.toolbarColumn}>
diff --git a/apps/demo/src/csvDrop.tsx b/apps/demo/src/csvDrop.tsx
index 59abf98..f0164e0 100644
--- a/apps/demo/src/csvDrop.tsx
+++ b/apps/demo/src/csvDrop.tsx
@@ -1,108 +1,206 @@
-/**
- * CSV drop lane.
- *
- * ONE edges CSV with `source`/`target` columns → `prepareGraphData` with
- * `deriveNodes: true` (nodes synthesized from endpoints, first-occurrence
- * order; extra columns become edge attrs and show up in the column
- * summaries). The prepared snapshot is applied DECLARATIVELY by <App> — the
- * datasetKey derives from the file name, so every distinct file is a full
- * dataset swap, and the summaries render as one panel line.
- *
- * Two ways in, one handler:
- * - drag a.csv anywhere over the window — a full-window overlay appears
- * while the drag is active and the window-level `drop` listener takes the
- * first file (the overlay itself is pointer-inert);
- * - the panel's "Choose CSV…" button / hidden file input — the input is the
- * e2e seam (`page.setInputFiles` on `[data-testid="csv-file-input"]`).
- *
- * Errors stay inline (the caller renders them next to the summary line)
- * a bad file never takes the running graph down.
- */
-
-import { useEffect, useRef, useState } from 'react';
-import type { ChangeEvent, ReactElement } from 'react';
-import { prepareGraphData } from '@modernrelay/orbit-data';
-import type { ColumnSummary, PreparedGraph } from '@modernrelay/orbit-data';
-
+/** Guided CSV preparation. A successful import is the only dataset write. */
+import { useCallback, useEffect, useRef, useState } from 'react';
+import type { ChangeEvent, CSSProperties, ReactElement } from 'react';
+import { prepareGraphData, previewCsv } from '@modernrelay/orbit-data';
+import type { ColumnSummary, GraphColumnMapping, GraphPrepareProgress, PreparedGraph } from '@modernrelay/orbit-data';
 import * as S from './styles';
 
+const MAX_BYTES = 128 * 1024 * 1024;
+const MAX_NODES = 100_000;
+const MAX_EDGES = 250_000;
+const PREVIEW_BYTES = 256 * 1024;
+
 export interface CsvDropResult {
   fileName: string;
-  /** Default-generic prepared output — derived nodes carry NO attrs (builder
-   * contract), so the caller may safely apply it under its own attr generics. */
   prepared: PreparedGraph;
-  /** One-line summaries digest for the panel. */
   summaryLine: string;
 }
 
-/** `weight (50/50 · 0–6)`-style fragment for one summarized column. */
-function summarizeColumn(name: string, s: ColumnSummary): string {
-  const bits: string[] = [`${s.count - s.nullCount}/${s.count}`];
-  if (s.min !== undefined && s.max !== undefined) bits.push(`${s.min}–${s.max}`);
-  else if (s.approximateUnique !== undefined) bits.push(`${s.approximateUnique} uniq`);
-  return `${name} (${bits.join(' · ')})`;
+type Preview = Awaited<ReturnType<typeof previewCsv>>;
+interface Draft {
+  edges: File;
+  edgePreview: Preview;
+  nodes: File | null;
+  nodePreview: Preview | null;
+  source: string;
+  target: string;
+  edgeId: string;
+  nodeId: string;
+}
+
+const fieldStyle: CSSProperties = { display: 'flex', flexDirection: 'column', gap: 5, minWidth: 140, flex: 1 };
+const inputStyle: CSSProperties = { ...S.button, width: '100%', color: 'var(--fg)', background: 'var(--app-bg)' };
+const cellStyle: CSSProperties = { borderBottom: '1px solid var(--panel-border)', padding: '6px 10px', textAlign: 'left', maxWidth: 240, overflowWrap: 'anywhere' };
+
+function ColumnField(props: {
+  label: string; columns: readonly string[]; value: string; onChange: (value: string) => void; optional?: boolean;
+}): ReactElement {
+  return <label style={fieldStyle}>
+    {props.label}
+    <select style={inputStyle} value={props.value} onChange={(event) => props.onChange(event.target.value)}>
+      {props.optional && <option value="">Generate automatically</option>}
+      {props.columns.map((column) => <option key={column} value={column}>{column}</option>)}
+    </select>
+  </label>;
+}
+
+function PreviewTable({ preview, label }: { preview: Preview; label: string }): ReactElement {
+  return <div style={{ overflow: 'auto', maxHeight: 200, border: '1px solid var(--panel-border)', borderRadius: 6 }}>
+    <table aria-label={label} style={{ borderCollapse: 'collapse', fontSize: 12, width: '100%' }}>
+      <thead><tr>{preview.columns.map((column) => <th key={column} scope="col" style={cellStyle}>{column}</th>)}</tr></thead>
+      <tbody>{preview.rows.map((row, index) => <tr key={index}>
+        {preview.columns.map((column) => <td key={column} style={cellStyle}>{String(row[column] ?? '')}</td>)}
+      </tr>)}</tbody>
+    </table>
+  </div>;
 }
 
-/** Parse + prepare one edges CSV (edges-only lane, `deriveNodes: true`).
- * The mapping is fixed to `source`/`target` header columns; anything else
- * rides along as edge attrs and gets a column summary. */
-export async function loadCsvEdgesFile(file: File): Promise<CsvDropResult> {
-  const prepared = await prepareGraphData(
-    { edges: file, deriveNodes: true },
-    { edges: { source: 'source', target: 'target' } },
-    {
-      // File name = dataset identity: a different file is a full swap.
-      datasetKey: `csv:${file.name}`,
-      sourceRevision: file.lastModified === 0 ? 1 : file.lastModified,
-      format: 'csv',
-    },
-  );
-  const { snapshot, summaries } = prepared;
-  const edgeCols = Object.keys(summaries.edges);
-  const colBits = edgeCols.slice(0, 4).map((c) => summarizeColumn(c, summaries.edges[c]!));
-  const summaryLine =
-    `${file.name}: ${snapshot.nodes.length} nodes · ${snapshot.edges.length} edges` +
-    (colBits.length > 0 ? ` · ${colBits.join(', ')}` : '') +
-    ` · fp ${prepared.mappingFingerprint.slice(0, 8)}`;
-  return { fileName: file.name, prepared, summaryLine };
+function summarizeColumn(name: string, summary: ColumnSummary): string {
+  const range = summary.min !== undefined && summary.max !== undefined
+    ? ` · ${summary.min}–${summary.max}` : '';
+  return `${name} (${summary.count - summary.nullCount}/${summary.count}${range})`;
+}
+
+function assertFileSize(edges: File, nodes: File | null): void {
+  if (edges.size + (nodes?.size ?? 0) > MAX_BYTES) {
+    throw new Error('These files exceed the 128 MiB import limit. Choose smaller files.');
+  }
+}
+
+async function readPreview(file: File, signal: AbortSignal): Promise<Preview> {
+  const preview = await previewCsv(file, { signal, maxRows: 5, maxBytes: PREVIEW_BYTES });
+  if (preview.columns.length === 0) throw new Error(`${file.name} has no CSV header. Add a header row naming each column.`);
+  if (preview.rows.length === 0) throw new Error(`${file.name} has no data rows.`);
+  return preview;
 }
 
 export function CsvDropZone(props: {
-  /** Last successful load's summary line (null = nothing loaded yet). */
   summary: string | null;
-  /** Last failed load's message (null = no error). */
-  error: string | null;
-  onFile: (file: File) => void;
+  onPrepared: (result: CsvDropResult) => void;
 }): ReactElement {
-  const { onFile } = props;
   const [dragActive, setDragActive] = useState(false);
+  const [open, setOpen] = useState(false);
+  const [draft, setDraft] = useState<Draft | null>(null);
+  const [phase, setPhase] = useState<'preview' | 'preparing' | null>(null);
+  const [progress, setProgress] = useState<GraphPrepareProgress | null>(null);
+  const [error, setError] = useState<string | null>(null);
+  const [notice, setNotice] = useState<string | null>(null);
   const inputRef = useRef<HTMLInputElement | null>(null);
+  const nodeInputRef = useRef<HTMLInputElement | null>(null);
+  const dialogRef = useRef<HTMLDialogElement | null>(null);
+  const controllerRef = useRef<AbortController | null>(null);
 
-  // Window-level drag lane: dragenter/leave pairs are depth-counted (they
-  // fire per element crossed), dragover MUST preventDefault or the browser
-  // navigates to the dropped file, and drop takes the first file.
+  useEffect(() => () => controllerRef.current?.abort(), []);
   useEffect(() => {
-    let depth = 0;
-    const hasFiles = (e: DragEvent): boolean =>
-      e.dataTransfer !== null && Array.from(e.dataTransfer.types).includes('Files');
-    const onEnter = (e: DragEvent): void => {
-      if (!hasFiles(e)) return;
-      depth += 1;
-      setDragActive(true);
-    };
-    const onOver = (e: DragEvent): void => {
-      if (hasFiles(e)) e.preventDefault();
-    };
-    const onLeave = (): void => {
-      depth = Math.max(0, depth - 1);
-      if (depth === 0) setDragActive(false);
+    const dialog = dialogRef.current;
+    if (open && dialog !== null && !dialog.open) dialog.showModal();
+    if (!open && dialog?.open) dialog.close();
+  }, [open]);
+
+  const startRequest = useCallback((): AbortController => {
+    controllerRef.current?.abort();
+    const controller = new AbortController();
+    controllerRef.current = controller;
+    setError(null);
+    setNotice(null);
+    setProgress(null);
+    return controller;
+  }, []);
+
+  const onFile = useCallback((file: File) => {
+    const controller = startRequest();
+    setDraft(null);
+    setOpen(true);
+    setPhase('preview');
+    void (async () => {
+      assertFileSize(file, null);
+      const preview = await readPreview(file, controller.signal);
+      if (controller.signal.aborted) return;
+      const source = preview.columns.includes('source') ? 'source' : preview.columns[0]!;
+      const target = preview.columns.includes('target') ? 'target' : preview.columns.find((name) => name !== source) ?? source;
+      setDraft({ edges: file, edgePreview: preview, nodes: null, nodePreview: null, source, target, edgeId: '', nodeId: '' });
+    })().catch((cause: unknown) => {
+      if (!controller.signal.aborted) setError(cause instanceof Error ? cause.message : String(cause));
+    }).finally(() => {
+      if (!controller.signal.aborted) setPhase(null);
+    });
+  }, [startRequest]);
+
+  const onNodesFile = (file: File): void => {
+    if (draft === null) return;
+    const controller = startRequest();
+    setPhase('preview');
+    void (async () => {
+      assertFileSize(draft.edges, file);
+      const preview = await readPreview(file, controller.signal);
+      if (controller.signal.aborted) return;
+      setDraft((current) => current === null ? null : {
+        ...current, nodes: file, nodePreview: preview,
+        nodeId: preview.columns.includes('id') ? 'id' : preview.columns[0]!,
+      });
+    })().catch((cause: unknown) => {
+      if (!controller.signal.aborted) setError(cause instanceof Error ? cause.message : String(cause));
+    }).finally(() => {
+      if (!controller.signal.aborted) setPhase(null);
+    });
+  };
+
+  const cancel = (): void => {
+    controllerRef.current?.abort();
+    setPhase(null);
+    setOpen(false);
+    setDraft(null);
+    setError(null);
+    setNotice('Import cancelled. Your current graph is unchanged.');
+  };
+
+  const importGraph = (): void => {
+    if (draft === null || phase !== null) return;
+    const controller = startRequest();
+    setPhase('preparing');
+    const mapping: GraphColumnMapping = {
+      edges: { source: draft.source, target: draft.target, ...(draft.edgeId ? { id: draft.edgeId } : {}) },
+      ...(draft.nodes !== null ? { nodes: { id: draft.nodeId } } : {}),
     };
-    const onDrop = (e: DragEvent): void => {
-      depth = 0;
-      setDragActive(false);
-      if (!hasFiles(e)) return;
-      e.preventDefault();
-      const file = e.dataTransfer?.files[0];
+    // The mapping belongs to the source coordinate: changing it must not look
+    // like an idempotent replay of a previous import of the same file.
+    const identity = JSON.stringify([draft.edges.name, draft.edges.size, draft.edges.lastModified,
+      draft.nodes === null ? null : [draft.nodes.name, draft.nodes.size, draft.nodes.lastModified], mapping]);
+    void prepareGraphData(
+      draft.nodes === null ? { edges: draft.edges, deriveNodes: true } : { edges: draft.edges, nodes: draft.nodes },
+      mapping,
+      {
+        datasetKey: `csv:${draft.edges.name}`, sourceRevision: identity, format: 'csv',
+        signal: controller.signal, maxBytes: MAX_BYTES, maxNodes: MAX_NODES, maxEdges: MAX_EDGES,
+        onProgress: (value) => { if (!controller.signal.aborted) setProgress(value); },
+      },
+    ).then((prepared) => {
+      if (controller.signal.aborted) return;
+      const fileName = draft.nodes === null ? draft.edges.name : `${draft.edges.name} + ${draft.nodes.name}`;
+      const columns = Object.entries(prepared.summaries.edges).slice(0, 4).map(([name, summary]) => summarizeColumn(name, summary));
+      props.onPrepared({ fileName, prepared,
+        summaryLine: `${fileName}: ${prepared.snapshot.nodes.length.toLocaleString('en-US')} nodes · ${prepared.snapshot.edges.length.toLocaleString('en-US')} edges` +
+          (columns.length > 0 ? ` · ${columns.join(', ')}` : '') });
+      setOpen(false);
+      setDraft(null);
+    }).catch((cause: unknown) => {
+      if (!controller.signal.aborted) setError(cause instanceof Error ? cause.message : String(cause));
+    }).finally(() => {
+      if (!controller.signal.aborted) setPhase(null);
+    });
+  };
+
+  useEffect(() => {
+    let depth = 0;
+    const hasFiles = (event: DragEvent): boolean => event.dataTransfer !== null && Array.from(event.dataTransfer.types).includes('Files');
+    const onEnter = (event: DragEvent): void => { if (hasFiles(event)) { depth++; setDragActive(true); } };
+    const onOver = (event: DragEvent): void => { if (hasFiles(event)) event.preventDefault(); };
+    const onLeave = (): void => { depth = Math.max(0, depth - 1); if (depth === 0) setDragActive(false); };
+    const onDrop = (event: DragEvent): void => {
+      depth = 0; setDragActive(false);
+      if (!hasFiles(event)) return;
+      event.preventDefault();
+      const file = event.dataTransfer?.files[0];
       if (file !== undefined) onFile(file);
     };
     window.addEventListener('dragenter', onEnter);
@@ -110,61 +208,69 @@ export function CsvDropZone(props: {
     window.addEventListener('dragleave', onLeave);
     window.addEventListener('drop', onDrop);
     return () => {
-      window.removeEventListener('dragenter', onEnter);
-      window.removeEventListener('dragover', onOver);
-      window.removeEventListener('dragleave', onLeave);
-      window.removeEventListener('drop', onDrop);
+      window.removeEventListener('dragenter', onEnter); window.removeEventListener('dragover', onOver);
+      window.removeEventListener('dragleave', onLeave); window.removeEventListener('drop', onDrop);
     };
   }, [onFile]);
 
-  const onInputChange = (e: ChangeEvent<HTMLInputElement>): void => {
-    const file = e.target.files?.[0];
-    if (file !== undefined) onFile(file);
-    e.target.value = ''; // re-selecting the same file must fire change again
+  const takeFile = (event: ChangeEvent<HTMLInputElement>, receive: (file: File) => void): void => {
+    const file = event.target.files?.[0];
+    if (file !== undefined) receive(file);
+    event.target.value = '';
+  };
+  const updateMapping = (key: 'source' | 'target' | 'edgeId' | 'nodeId', value: string): void => {
+    setDraft((current) => current === null ? null : { ...current, [key]: value }); setError(null);
   };
 
-  return (
-    <section style={S.csvPanel} data-testid="csv-panel" aria-label="CSV data">
-      <div style={S.dataPanelTitle}>csv</div>
-      <div style={S.csvHint}>
-        drop an edges .csv (source,target[,attrs…]) anywhere — nodes derive from endpoints
-      </div>
+  return <section style={S.csvPanel} data-testid="csv-panel" aria-label="CSV data">
+    <style>{'.csv-import-dialog::backdrop { background: rgba(0,0,0,.55); } .csv-import-dialog button:focus-visible, .csv-import-dialog select:focus-visible { outline: 2px solid #58a6ff; outline-offset: 2px; }'}</style>
+    <div style={S.dataPanelTitle}>Import your data</div>
+    <div style={S.csvHint}>Drop an edges CSV, preview its columns, and choose how to connect your graph.</div>
+    <button type="button" className="demo-btn" style={S.button} data-testid="csv-choose" onClick={() => inputRef.current?.click()}>Choose CSV…</button>
+    <input ref={inputRef} type="file" accept=".csv,text/csv" aria-label="Load edges CSV file" data-testid="csv-file-input"
+      style={S.csvHiddenInput} tabIndex={-1} onChange={(event) => takeFile(event, onFile)} />
+    {props.summary !== null && <div style={S.csvSummary} data-testid="csv-summary">{props.summary}</div>}
+    {notice !== null && <div role="status" style={S.csvHint}>{notice}</div>}
+    <dialog ref={dialogRef} className="csv-import-dialog" aria-labelledby="csv-import-title" onCancel={(event) => { event.preventDefault(); cancel(); }}
+      style={{ ...S.csvDialog }}>
+      <h2 id="csv-import-title" style={{ margin: 0, fontSize: 20 }}>Import CSV graph</h2>
+      <p style={S.csvHint}>Up to 128 MiB total, 100,000 nodes and 250,000 edges. Your graph stays unchanged until the import succeeds.</p>
       <div style={S.dataPanelRow}>
-        <button
-          type="button"
-          className="demo-btn"
-          style={S.button}
-          data-testid="csv-choose"
-          onClick={() => inputRef.current?.click()}
-        >
-          Choose CSV…
-        </button>
+        <button type="button" style={S.button} onClick={() => inputRef.current?.click()}>Choose different edges file</button>
+        <button type="button" style={S.button} onClick={cancel}>{phase === 'preparing' ? 'Cancel import' : 'Cancel'}</button>
       </div>
-      <input
-        ref={inputRef}
-        type="file"
-        accept=".csv,text/csv"
-        aria-label="Load edges CSV file"
-        data-testid="csv-file-input"
-        style={S.csvHiddenInput}
-        tabIndex={-1}
-        onChange={onInputChange}
-      />
-      {props.summary !== null && (
-        <div style={S.csvSummary} data-testid="csv-summary">
-          {props.summary}
-        </div>
-      )}
-      {props.error !== null && (
-        <div style={S.ogError} data-testid="csv-error">
-          {props.error}
+      {draft !== null && <fieldset disabled={phase !== null} style={{ border: 0, padding: 0, margin: '16px 0 0', minWidth: 0 }}>
+        <legend style={{ padding: '0 0 10px', fontWeight: 600, overflowWrap: 'anywhere' }}>Edges: {draft.edges.name}</legend>
+        <PreviewTable preview={draft.edgePreview} label="Edges preview" />
+        <p style={S.csvHint}>Previewing up to five rows. Other columns are kept as attributes.</p>
+        <div style={{ display: 'flex', flexWrap: 'wrap', gap: 12 }}>
+          <ColumnField label="Source column" columns={draft.edgePreview.columns} value={draft.source} onChange={(value) => updateMapping('source', value)} />
+          <ColumnField label="Target column" columns={draft.edgePreview.columns} value={draft.target} onChange={(value) => updateMapping('target', value)} />
+          <ColumnField label="Edge ID column" columns={draft.edgePreview.columns} value={draft.edgeId} optional onChange={(value) => updateMapping('edgeId', value)} />
         </div>
-      )}
-      {dragActive && (
-        <div style={S.csvDropOverlay} data-testid="csv-drop-overlay">
-          <div style={S.csvDropOverlayInner}>drop CSV to load</div>
+        <div style={{ marginTop: 18 }}>
+          <button type="button" style={S.button} onClick={() => nodeInputRef.current?.click()}>{draft.nodes === null ? 'Add nodes CSV (optional)' : 'Change nodes CSV'}</button>
+          <input ref={nodeInputRef} type="file" accept=".csv,text/csv" aria-label="Load nodes CSV file" data-testid="csv-nodes-input" style={S.csvHiddenInput} tabIndex={-1}
+            onChange={(event) => takeFile(event, onNodesFile)} />
+          {draft.nodes === null ? <p style={S.csvHint}>Without a nodes file, nodes are created from the edge endpoints.</p> : <>
+            <p style={{ overflowWrap: 'anywhere' }}>Nodes: {draft.nodes.name}</p>
+            {draft.nodePreview !== null && <>
+              <PreviewTable preview={draft.nodePreview} label="Nodes preview" />
+              <div style={{ margin: '12px 0' }}><ColumnField label="Node ID column" columns={draft.nodePreview.columns} value={draft.nodeId} onChange={(value) => updateMapping('nodeId', value)} /></div>
+            </>}
+            <button type="button" style={S.button} onClick={() => { setDraft({ ...draft, nodes: null, nodePreview: null, nodeId: '' }); setError(null); }}>Remove nodes file</button>
+          </>}
         </div>
-      )}
-    </section>
-  );
+      </fieldset>}
+      {phase !== null && <div role="status" aria-live="polite" data-testid="csv-progress" style={{ marginTop: 16 }}>
+        {phase === 'preview' ? 'Reading preview…' : progress === null ? 'Preparing graph…' :
+          `Preparing graph… ${(progress.bytes / 1048576).toFixed(1)} MiB read · ${progress.nodes.toLocaleString('en-US')} nodes · ${progress.edges.toLocaleString('en-US')} edges`}
+      </div>}
+      {error !== null && <div role="alert" style={{ ...S.ogError, marginTop: 14 }} data-testid="csv-error">{error}</div>}
+      <div style={{ marginTop: 20, display: 'flex', justifyContent: 'flex-end' }}>
+        <button type="button" style={S.button} disabled={draft === null || phase !== null} onClick={importGraph}>Import graph</button>
+      </div>
+    </dialog>
+    {dragActive && <div style={S.csvDropOverlay} data-testid="csv-drop-overlay"><div style={S.csvDropOverlayInner}>Drop CSV to preview</div></div>}
+  </section>;
 }
diff --git a/apps/demo/src/styles.ts b/apps/demo/src/styles.ts
index c82105c..a597a3a 100644
--- a/apps/demo/src/styles.ts
+++ b/apps/demo/src/styles.ts
@@ -755,6 +755,19 @@ export const csvPanel: CSSProperties = {
   maxWidth: 280,
 };
 
+export const csvDialog: CSSProperties = {
+  ...panelBase,
+  background: 'var(--app-bg)',
+  width: 'min(720px, calc(100vw - 32px))',
+  maxWidth: 'calc(100vw - 32px)',
+  maxHeight: 'calc(100dvh - 32px)',
+  boxSizing: 'border-box',
+  overflow: 'auto',
+  padding: 24,
+  margin: 'auto',
+  fontSize: 13,
+};
+
 export const csvHint: CSSProperties = {
   color: 'var(--fg-muted)',
   fontSize: 11.5,
diff --git a/docs/core/getting-started.md b/docs/core/getting-started.md
new file mode 100644
index 0000000..7b44697
--- /dev/null
+++ b/docs/core/getting-started.md
@@ -0,0 +1,182 @@
+# Your first Orbit graph
+
+This example renders three people and two relationships. Click a node to select
+it, or type **Grace** in the search box and press Enter. The selected ID appears
+below the graph; **Clear selection** updates both the text and the graph.
+
+Use Node.js 22.18+ or 24.11+ and a browser with WebGL. Orbit supports React 18 and
+newer. The Cosmos renderer is imported lazily when the graph mounts.
+
+## Create an app
+
+Start with the Vite React TypeScript template:
+
+```bash
+npm create vite@latest orbit-first -- --template react-ts
+cd orbit-first
+npm install
+npm install @modernrelay/orbit-core @modernrelay/orbit-react @modernrelay/orbit-engine-cosmos
+```
+
+Replace `src/App.tsx` with this complete example:
+
+<!-- quickstart:App.tsx -->
+```tsx
+import { useState } from 'react';
+import type { GraphSnapshot, NodeId } from '@modernrelay/orbit-core';
+import type { EngineFactory } from '@modernrelay/orbit-core/engine';
+import { CosmosEngine } from '@modernrelay/orbit-engine-cosmos';
+import { Graph } from '@modernrelay/orbit-react';
+import { GraphSearch } from '@modernrelay/orbit-react/components/Search';
+
+type Person = { label: string };
+type Relationship = { label: string };
+
+const data: GraphSnapshot<Person, Relationship> = {
+  datasetKey: 'first-graph',
+  sourceRevision: 1,
+  nodes: [
+    { id: 'ada', x: -160, y: -100, attrs: { label: 'Ada' } },
+    { id: 'grace', x: 0, y: 100, attrs: { label: 'Grace' } },
+    { id: 'katherine', x: 160, y: -100, attrs: { label: 'Katherine' } },
+  ],
+  edges: [
+    { id: 'ada-grace', source: 'ada', target: 'grace', attrs: { label: 'works with' } },
+    { id: 'grace-katherine', source: 'grace', target: 'katherine', attrs: { label: 'works with' } },
+  ],
+};
+
+// Keep the factory stable; create a fresh engine for every mount.
+export const createEngine: EngineFactory = () => new CosmosEngine();
+
+// The optional engine prop also lets tests supply Orbit's FakeEngine.
+export default function App({ engine = createEngine }: { engine?: EngineFactory }) {
+  const [selection, setSelection] = useState<readonly NodeId[]>([]);
+  const [error, setError] = useState<string | null>(null);
+
+  return (
+    <main style={{ maxWidth: 960, margin: '0 auto', padding: 24, fontFamily: 'system-ui' }}>
+      <h1>My first graph</h1>
+      <p>Click a node, or search for Grace and press Enter to select her.</p>
+      <div style={{ height: 420, position: 'relative' }}>
+        <Graph<Person, Relationship>
+          engine={engine}
+          data={data}
+          layout="fixed"
+          labels={{ minZoom: 0, maxVisible: 3 }}
+          theme={{ base: 'light' }}
+          nodeSize={12}
+          searchIndex={['label']}
+          selection={selection}
+          onSelectionChange={({ nodeIds }) => setSelection(nodeIds)}
+          onError={({ error: graphError }) => setError(graphError.message)}
+        >
+          <GraphSearch
+            placeholder="Search people…"
+            onResultActivate={(result) => setSelection([result.id])}
+          />
+        </Graph>
+      </div>
+      <p role="status">Selected: {selection.join(', ') || 'none'}</p>
+      <button type="button" onClick={() => setSelection([])} disabled={selection.length === 0}>
+        Clear selection
+      </button>
+      {error !== null && <p role="alert">Could not open the graph: {error}</p>}
+    </main>
+  );
+}
+```
+
+Replace `src/main.tsx` with the entry below. It does not import the Vite starter's
+CSS, so the starter layout does not constrain the graph container.
+
+<!-- quickstart:main.tsx -->
+```tsx
+import { StrictMode } from 'react';
+import { createRoot } from 'react-dom/client';
+import App from './App';
+
+const container = document.getElementById('root');
+if (container === null) throw new Error('Missing #root element');
+
+createRoot(container).render(
+  <StrictMode>
+    <App />
+  </StrictMode>,
+);
+```
+
+Run the app and open the local URL printed by Vite:
+
+```bash
+npm run dev
+```
+
+The graph needs a container with a real height: the example gives it 420 pixels.
+The fixed layout uses each node's `x`/`y` coordinates to form a readable triangle.
+Name labels are enabled even when zoomed out, with a maximum of three labels.
+To let the force simulation arrange a larger dataset, omit `layout="fixed"`
+and the coordinates.
+`GraphSearch` is a child of `Graph`, so it automatically shares the graph instance.
+No separate `GraphProvider` is needed. Built-in search always indexes IDs;
+`searchIndex={['label']}` adds the label stored in each node's `attrs`.
+
+## Update data and selection
+
+`datasetKey` identifies the dataset. Increment or replace `sourceRevision` when
+its contents change, and pass a new snapshot to `data`. Reusing the same dataset
+and revision is an idempotent replay. Changing `datasetKey` clears per-dataset
+state, such as selection.
+
+The example owns selection in React: `selection` contains node IDs, and
+`onSelectionChange` reflects the graph's selection intent into that state.
+Search activation focuses the result; this example's `onResultActivate` callback
+also selects it by updating the same React state.
+Always wire both when controlling selection. To let Orbit own selection, omit
+the `selection` prop and optionally listen to `onSelectionChange`. Providing a
+controlled prop once establishes that ownership for the instance; do not switch
+between controlled and uncontrolled modes mid-mount. Groups and pins follow the
+same ownership pattern through their corresponding props and callbacks.
+
+The engine factory is defined outside the component so its identity stays stable.
+It returns a **new** `CosmosEngine` for each mount, including React StrictMode's
+remount checks. The optional `engine` prop on this example app lets a test pass
+`() => new FakeEngine()` from `@modernrelay/orbit-core/testing`.
+
+## Change configuration
+
+Data, theme, styling, and filters can update on the existing graph. For example,
+set `filter={null}` to explicitly clear a filter.
+
+Engine, services, search index, execution options, and limits are read when an
+instance is constructed. Changing those props later is ignored with a warning.
+To change one, key-remount the graph with a stable identity for that configuration,
+for example `<Graph key={sourceId} ... />`. A remount creates a fresh instance;
+save any state you want to restore. Camera fit options are also construction-only.
+Keep `sourceId` stable during ordinary renders.
+
+For a server-rendered React app, place this component behind the framework's
+client-component boundary (for example, add `'use client'` in Next.js). The
+WebGL canvas mounts in the browser.
+
+Next, use the [exploration workflow guide](exploration-workflows.md) to add
+inspection, bounded expansion, paths, and saved investigations. See the
+[package and component inventory](../../README.md#packages) for other building
+blocks.
+
+## Run this exact example from the repository
+
+The source lives in [`fixtures/quickstart`](../../fixtures/quickstart). The
+packaging gate checks that both code blocks above match those files, typechecks
+against freshly packed packages, bundles the real Cosmos renderer, and exercises
+click selection, search, clearing, and teardown with `FakeEngine` in jsdom.
+
+```bash
+pnpm install
+pnpm build
+pnpm smoke
+python3 -m http.server 5200 --directory .smoke/bundles/quickstart
+```
+
+Open <http://localhost:5200> to drive the same example with the real WebGL renderer.
+The browser bundle remains after the temporary consumer installation is cleaned up.
diff --git a/fixtures/quickstart/App.tsx b/fixtures/quickstart/App.tsx
new file mode 100644
index 0000000..c074001
--- /dev/null
+++ b/fixtures/quickstart/App.tsx
@@ -0,0 +1,63 @@
+import { useState } from 'react';
+import type { GraphSnapshot, NodeId } from '@modernrelay/orbit-core';
+import type { EngineFactory } from '@modernrelay/orbit-core/engine';
+import { CosmosEngine } from '@modernrelay/orbit-engine-cosmos';
+import { Graph } from '@modernrelay/orbit-react';
+import { GraphSearch } from '@modernrelay/orbit-react/components/Search';
+
+type Person = { label: string };
+type Relationship = { label: string };
+
+const data: GraphSnapshot<Person, Relationship> = {
+  datasetKey: 'first-graph',
+  sourceRevision: 1,
+  nodes: [
+    { id: 'ada', x: -160, y: -100, attrs: { label: 'Ada' } },
+    { id: 'grace', x: 0, y: 100, attrs: { label: 'Grace' } },
+    { id: 'katherine', x: 160, y: -100, attrs: { label: 'Katherine' } },
+  ],
+  edges: [
+    { id: 'ada-grace', source: 'ada', target: 'grace', attrs: { label: 'works with' } },
+    { id: 'grace-katherine', source: 'grace', target: 'katherine', attrs: { label: 'works with' } },
+  ],
+};
+
+// Keep the factory stable; create a fresh engine for every mount.
+export const createEngine: EngineFactory = () => new CosmosEngine();
+
+// The optional engine prop also lets tests supply Orbit's FakeEngine.
+export default function App({ engine = createEngine }: { engine?: EngineFactory }) {
+  const [selection, setSelection] = useState<readonly NodeId[]>([]);
+  const [error, setError] = useState<string | null>(null);
+
+  return (
+    <main style={{ maxWidth: 960, margin: '0 auto', padding: 24, fontFamily: 'system-ui' }}>
+      <h1>My first graph</h1>
+      <p>Click a node, or search for Grace and press Enter to select her.</p>
+      <div style={{ height: 420, position: 'relative' }}>
+        <Graph<Person, Relationship>
+          engine={engine}
+          data={data}
+          layout="fixed"
+          labels={{ minZoom: 0, maxVisible: 3 }}
+          theme={{ base: 'light' }}
+          nodeSize={12}
+          searchIndex={['label']}
+          selection={selection}
+          onSelectionChange={({ nodeIds }) => setSelection(nodeIds)}
+          onError={({ error: graphError }) => setError(graphError.message)}
+        >
+          <GraphSearch
+            placeholder="Search people…"
+            onResultActivate={(result) => setSelection([result.id])}
+          />
+        </Graph>
+      </div>
+      <p role="status">Selected: {selection.join(', ') || 'none'}</p>
+      <button type="button" onClick={() => setSelection([])} disabled={selection.length === 0}>
+        Clear selection
+      </button>
+      {error !== null && <p role="alert">Could not open the graph: {error}</p>}
+    </main>
+  );
+}
diff --git a/fixtures/quickstart/index.html b/fixtures/quickstart/index.html
new file mode 100644
index 0000000..10258f8
--- /dev/null
+++ b/fixtures/quickstart/index.html
@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Orbit — first graph</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="./main.js"></script>
+  </body>
+</html>
diff --git a/fixtures/quickstart/main.tsx b/fixtures/quickstart/main.tsx
new file mode 100644
index 0000000..be41f45
--- /dev/null
+++ b/fixtures/quickstart/main.tsx
@@ -0,0 +1,12 @@
+import { StrictMode } from 'react';
+import { createRoot } from 'react-dom/client';
+import App from './App';
+
+const container = document.getElementById('root');
+if (container === null) throw new Error('Missing #root element');
+
+createRoot(container).render(
+  <StrictMode>
+    <App />
+  </StrictMode>,
+);
diff --git a/fixtures/quickstart/smoke.mjs b/fixtures/quickstart/smoke.mjs
new file mode 100644
index 0000000..08c77c5
--- /dev/null
+++ b/fixtures/quickstart/smoke.mjs
@@ -0,0 +1,63 @@
+import assert from 'node:assert/strict';
+import { JSDOM } from 'jsdom';
+
+const dom = new JSDOM('<!doctype html><div id="root"></div>', {
+  url: 'http://localhost/',
+  pretendToBeVisual: true,
+});
+for (const key of ['window', 'document', 'navigator', 'HTMLElement', 'HTMLInputElement', 'Element', 'Node', 'MutationObserver']) {
+  Object.defineProperty(globalThis, key, { configurable: true, value: dom.window[key] });
+}
+globalThis.IS_REACT_ACT_ENVIRONMENT = true;
+
+// React DOM must load after the DOM exists, so its event system is active.
+const { act, createElement } = await import('react');
+const { createRoot } = await import('react-dom/client');
+const { FakeEngine } = await import('@modernrelay/orbit-core/testing');
+const { CosmosEngine } = await import('@modernrelay/orbit-engine-cosmos');
+const { default: App, createEngine } = await import('./App.js');
+
+// Resolve and construct the real public adapter before using the WebGL-free seam.
+const cosmos = await createEngine();
+assert.ok(cosmos instanceof CosmosEngine);
+cosmos.destroy();
+
+const engine = new FakeEngine();
+const root = createRoot(document.getElementById('root'));
+try {
+  await act(async () => root.render(createElement(App, { engine: () => engine })));
+  assert.equal(engine.lastStructure?.pointCount, 3, 'the documented graph reaches the engine');
+  assert.equal(engine.lastStructure?.links.length, 4, 'two edges reach the engine');
+
+  // Exercise selection intents and the host's controlled prop round-trip.
+  await act(async () => engine.injectPointClick(0));
+  assert.match(document.querySelector('p[role="status"]').textContent, /Selected: ada/);
+  assert.deepEqual(Array.from(engine.selectedIndices ?? []), [0]);
+
+  const search = document.querySelector('[role="combobox"]');
+  assert.ok(search, 'the packaged search component is mounted inside Graph context');
+  await act(async () => {
+    // Use the native setter so React observes an actual user edit.
+    Object.getOwnPropertyDescriptor(HTMLInputElement.prototype, 'value').set.call(search, 'Grace');
+    search.dispatchEvent(new dom.window.Event('input', { bubbles: true }));
+  });
+  // The documented component uses the public default 200 ms debounce.
+  await act(async () => new Promise((resolve) => setTimeout(resolve, 250)));
+  const option = document.querySelector('[role="option"]');
+  assert.ok(option?.textContent.includes('Grace'), 'search indexes the declared label attribute');
+  await act(async () => {
+    search.dispatchEvent(new dom.window.KeyboardEvent('keydown', { key: 'Enter', bubbles: true }));
+  });
+  assert.match(document.querySelector('p[role="status"]').textContent, /Selected: grace/);
+  assert.deepEqual(Array.from(engine.selectedIndices ?? []), [1]);
+
+  await act(async () => document.querySelector('button').click());
+  assert.match(document.querySelector('p[role="status"]').textContent, /Selected: none/);
+  assert.deepEqual(Array.from(engine.selectedIndices ?? []), []);
+  assert.equal(document.querySelector('[role="alert"]'), null);
+} finally {
+  await act(async () => root.unmount());
+  dom.window.close();
+}
+assert.ok(engine.destroyed, 'unmount releases the engine');
+console.log('quickstart: mount, click, search, controlled selection, clear, and teardown passed');
diff --git a/fixtures/quickstart/verify.mjs b/fixtures/quickstart/verify.mjs
new file mode 100644
index 0000000..304b37c
--- /dev/null
+++ b/fixtures/quickstart/verify.mjs
@@ -0,0 +1,53 @@
+import { execFileSync } from 'node:child_process';
+import { copyFileSync, mkdirSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import * as esbuild from 'esbuild';
+
+/** Run against an isolated install of packed packages, never workspace exports. */
+export async function verifyQuickstart({ root, consumerDir, outdir }) {
+  const sourceDir = path.join(root, 'fixtures', 'quickstart');
+  const guide = readFileSync(path.join(root, 'docs', 'core', 'getting-started.md'), 'utf8');
+  for (const file of ['App.tsx', 'main.tsx']) {
+    const marker = `<!-- quickstart:${file} -->`;
+    const start = guide.indexOf(marker);
+    const block = start < 0 ? null : /^\s*```tsx\n([\s\S]*?)\n```/.exec(guide.slice(start + marker.length));
+    const source = readFileSync(path.join(sourceDir, file), 'utf8');
+    if (block === null || block[1] + '\n' !== source) {
+      throw new Error(`getting-started.md must contain the exact fixtures/quickstart/${file} source after ${marker}`);
+    }
+    copyFileSync(path.join(sourceDir, file), path.join(consumerDir, file));
+  }
+
+  // Native TS checks the published declarations and the browser entry together.
+  execFileSync(process.execPath, [
+    path.join(root, 'packages', 'core', 'node_modules', 'typescript', 'bin', 'tsc'),
+    '--ignoreConfig', '--strict', '--noEmit', '--target', 'ES2022',
+    '--module', 'ESNext', '--moduleResolution', 'Bundler', '--jsx', 'react-jsx',
+    'App.tsx', 'main.tsx',
+  ], { cwd: consumerDir, encoding: 'utf8', stdio: 'pipe' });
+
+  // Keep a runnable browser harness for real GPU QA. All modules resolve from
+  // the fresh consumer, including the real Cosmos adapter and its lazy import.
+  mkdirSync(outdir, { recursive: true });
+  await esbuild.build({
+    absWorkingDir: consumerDir,
+    entryPoints: ['main.tsx'], outdir,
+    bundle: true, splitting: true, format: 'esm', platform: 'browser',
+    jsx: 'automatic', logLevel: 'silent',
+  });
+  copyFileSync(path.join(sourceDir, 'index.html'), path.join(outdir, 'index.html'));
+
+  // Execute the same example with a deterministic engine; imports remain
+  // external so this also checks the installed packages' runtime exports.
+  await esbuild.build({
+    absWorkingDir: consumerDir,
+    entryPoints: ['App.tsx'], outfile: path.join(consumerDir, 'App.js'),
+    format: 'esm', jsx: 'automatic', logLevel: 'silent',
+  });
+  copyFileSync(path.join(sourceDir, 'smoke.mjs'), path.join(consumerDir, 'quickstart-smoke.mjs'));
+  const output = execFileSync(process.execPath, ['quickstart-smoke.mjs'], {
+    cwd: consumerDir, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'],
+    timeout: 30_000,
+  });
+  return { browserHarness: outdir, checks: output.trim() };
+}
diff --git a/packages/core/src/engine/index.ts b/packages/core/src/engine/index.ts
index 805c05c..bd8a537 100644
--- a/packages/core/src/engine/index.ts
+++ b/packages/core/src/engine/index.ts
@@ -247,6 +247,10 @@ export interface GraphEngine {
 
   // --- event-time readback ---
   getPositions(): Float32Array | null;
+  /** Optional nonblocking snapshot for bounded overlay sampling. Returns an
+   * owned buffer, or null when unavailable/invalidated by engine recovery.
+   * Core stamps the request against its scene and render revision. */
+  getPositionsAsync?(): Promise<Float32Array | null>;
 
   destroy(): void;
 }
diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts
index 4182537..0a630a6 100644
--- a/packages/core/src/index.ts
+++ b/packages/core/src/index.ts
@@ -377,6 +377,7 @@ export {
 } from './overview';
 export type {
   OverviewScene,
+  OverviewSnapshot,
   OverviewControllerOptions,
   OverviewBounds,
   OverviewRaster,
@@ -447,3 +448,7 @@ export type {
   SerializableTransform,
   TypedFieldPath,
 } from './descriptors';
+
+// Canonical synthesized edge identities shared by row and columnar adapters.
+export { nextSynthesizedEdgeId } from './edgeIdentity';
+export type { EdgePairCounters } from './edgeIdentity';
diff --git a/packages/core/src/instance.ts b/packages/core/src/instance.ts
index 94e8b63..e7a7983 100644
--- a/packages/core/src/instance.ts
+++ b/packages/core/src/instance.ts
@@ -9,6 +9,7 @@
  * Vanilla zustand only — no React, no DOM access at module scope.
  */
 
+import type { OverviewSnapshot } from './overview';
 import { createStore } from 'zustand/vanilla';
 import type { StoreApi } from 'zustand/vanilla';
 
@@ -969,6 +970,12 @@ export interface GraphInstance<N = Record<string, unknown>, E = Record<string, u
   getMetricValue(metric: MetricName, id: NodeId): number | null;
 
   // --- reads ---
+  /** Latest live position cache, falling back to reconciled positions before
+   * the first sample. Pure read; buffers are borrowed and must not be mutated. */
+  getOverviewScene(): OverviewSnapshot | null;
+  /** Observe position/roster changes and request bounded live sampling while
+   * mounted. Replays once; unsubscribe removes this consumer's demand. */
+  subscribeOverview(listener: () => void): () => void;
   getRevisions(): Revisions;
   getDiagnostics(): readonly GraphDiagnostic[];
   getNode(id: NodeId): GraphNode<N> | undefined;
@@ -1043,6 +1050,11 @@ const FRAME_PRESSURE_CLEAR_MS = 28;
 const LABEL_RERANK_THROTTLE_MS = 100;
 /** sim-hot degradation: minimum spacing between cache readbacks (ms). */
 const SIM_HOT_REFRESH_MS = 500;
+/** Nonblocking copies may refresh small-scene label/overview caches at 10 Hz.
+ * Full async transfers cost more at L scale, so larger scenes retain the
+ * existing 2 Hz synchronous lane. No additional rAF or recurring timer. */
+const ASYNC_POSITION_REFRESH_MS = 100;
+const ASYNC_POSITION_MAX_NODES = 10_000;
 
 /** Per-attach engine session; `alive` gates stale mount continuations and
  * stale engine events after detach/destroy. */
@@ -1669,6 +1681,17 @@ export function createGraphInstance<N = Record<string, unknown>, E = Record<stri
   /** Latest per-event readback aligned to the current scene (null → the
    * reconciled scene.positions, which already merged the live cache). */
   let labelPositionCache: Float32Array | null = null;
+  const overviewSubs = new Set<() => void>();
+  let overviewSnapshot: OverviewSnapshot | null = null;
+  let overviewScene: RenderScene | null = null;
+  let overviewRevision = 0;
+  let notifiedOverviewSnapshot: OverviewSnapshot | null | undefined;
+  let overviewNotificationQueued = false;
+  // Event-time reads supersede pending samples even when the render revision
+  // and roster did not change (e.g. a drag, settle or context restoration).
+  let positionGeneration = 0;
+  let positionFlight: object | null = null;
+  let positionClockMs = 0;
   /** Shared hit-test cadence: ONE counter, advanced once per engine
    * onFrame tick, read by every sampling route (native hover events and the
    * CPU fallback edge samplers throttle against the SAME clock — never a
@@ -1957,6 +1980,7 @@ export function createGraphInstance<N = Record<string, unknown>, E = Record<stri
     }
     pendingHistoryDepths = null;
     store.setState((prev) => ({ ...prev, ...patch }));
+    scheduleOverviewNotification();
     // the ladder's count triggers are edge-evaluated wherever
     // the visible counts move — publish is the single store funnel.
     if (patch.visible !== undefined || patch.nodeCount !== undefined) {
@@ -3933,7 +3957,7 @@ export function createGraphInstance<N = Record<string, unknown>, E = Record<stri
       }
       scopedAccepted = computeScopedAccepted();
       const result = reconcileScene(scopedAccepted ?? accepted);
-      labelPositionCache = null;
+      invalidatePositionCache();
       adjacency = null;
       sceneIncidence = null;
       structuralChange = result.structuralChange;
@@ -4507,7 +4531,7 @@ export function createGraphInstance<N = Record<string, unknown>, E = Record<stri
    */
   function ensureMetricModel(): boolean {
     if (accepted === null) return false;
-    const key = `${accepted.datasetKey}${String(accepted.sourceRevision)}${String(acceptedModelSeq)}`;
+    const key = `${accepted.datasetKey}\0${String(accepted.sourceRevision)}\0${String(acceptedModelSeq)}`;
     if (metricModelKey === key) return true;
     const { edges, nodeIndex, nodes } = accepted;
     const links = new Uint32Array(edges.length * 2);
@@ -4520,7 +4544,7 @@ export function createGraphInstance<N = Record<string, unknown>, E = Record<stri
       nodes,
       adjacency: buildAdjacency(links, nodes.length),
       links,
-      datasetRevision: `${accepted.datasetKey}${String(accepted.sourceRevision)}`,
+      datasetRevision: `${accepted.datasetKey}\0${String(accepted.sourceRevision)}`,
       modelRevision: acceptedModelSeq,
     });
     metricModelKey = key;
@@ -4768,7 +4792,7 @@ export function createGraphInstance<N = Record<string, unknown>, E = Record<stri
       } catch {
         sample = '
err';
       }
-      fp += sample + '';
+      fp += sample + '\0';
     }
     if (state.fp === fp) {
       state.streak += 1;
@@ -5123,6 +5147,99 @@ export function createGraphInstance<N = Record<string, unknown>, E = Record<stri
     };
   }
 
+  function invalidatePositionCache(): void {
+    positionGeneration += 1;
+    labelPositionCache = null;
+  }
+
+  function getOverviewScene(): OverviewSnapshot | null {
+    if (destroyed || scene === null || scene.count === 0) {
+      overviewSnapshot = null;
+      overviewScene = scene;
+      return null;
+    }
+    const positions = labelPositionCache ?? scene.positions;
+    if (overviewScene !== scene || overviewSnapshot?.positions !== positions) {
+      overviewScene = scene;
+      overviewSnapshot = { positions, count: scene.count, revision: ++overviewRevision };
+    }
+    return overviewSnapshot;
+  }
+
+  /** Coalesce notifications after the current atomic host transaction. */
+  function scheduleOverviewNotification(): void {
+    if (destroyed || overviewSubs.size === 0 || overviewNotificationQueued) return;
+    overviewNotificationQueued = true;
+    queueMicrotask(() => {
+      overviewNotificationQueued = false;
+      if (destroyed) return;
+      const next = getOverviewScene();
+      if (notifiedOverviewSnapshot === next) return;
+      notifiedOverviewSnapshot = next;
+      for (const cb of Array.from(overviewSubs)) {
+        try { cb(); } catch { /* isolate host observers */ }
+      }
+    });
+  }
+
+  function subscribeOverview(cb: () => void): () => void {
+    if (destroyed) return () => {};
+    overviewSubs.add(cb);
+    try { cb(); } catch { /* isolate host observers */ }
+    sampleOverlayPositions(positionClockMs);
+    return () => { overviewSubs.delete(cb); };
+  }
+
+  /** One shared, bounded readback lane. No scheduler of its own: activity
+   * ticks drive it, and settle/drag already bank authoritative event reads. */
+  function sampleOverlayPositions(timeMs: number): void {
+    const s = session;
+    const labelsActive = labelsEnabled();
+    if (destroyed || s === null || !s.alive || scene === null || scene.count === 0 || layout !== 'force' ||
+        store.getState().status !== 'ready' || (overviewSubs.size === 0 && !labelsActive)) return;
+    const issuedRender = store.getState().revisions.render;
+    // A deferred adapter may still expose the preceding roster/positions.
+    // Desired coordinates alone cannot make that old GPU state admissible.
+    if (s.engine.appliedRevision() !== issuedRender) return;
+    const asyncRead = scene.count <= ASYNC_POSITION_MAX_NODES ? s.engine.getPositionsAsync : undefined;
+    const interval = asyncRead === undefined || !labelsActive ? SIM_HOT_REFRESH_MS : ASYNC_POSITION_REFRESH_MS;
+    if (positionFlight !== null || (lastHotRefreshMs !== null && timeMs >= lastHotRefreshMs &&
+        timeMs - lastHotRefreshMs < interval)) return;
+    lastHotRefreshMs = timeMs;
+    if (asyncRead === undefined) {
+      const pos = s.engine.getPositions();
+      if (pos !== null && pos.length === scene.count * 2) bankEnginePositions(pos);
+      return;
+    }
+    const flight = {};
+    positionFlight = flight;
+    const issuedScene = scene;
+    const issuedPins = store.getState().pins;
+    const issuedGeneration = positionGeneration;
+    let read: Promise<Float32Array | null>;
+    try {
+      read = asyncRead.call(s.engine);
+    } catch {
+      positionFlight = null;
+      return;
+    }
+    void read.then((pos) => {
+      if (destroyed || session !== s || !s.alive || store.getState().status !== 'ready' ||
+          scene !== issuedScene || store.getState().revisions.render !== issuedRender ||
+          s.engine.appliedRevision() !== issuedRender || store.getState().pins !== issuedPins ||
+          positionGeneration !== issuedGeneration || (overviewSubs.size === 0 && !labelsEnabled()) ||
+          pos === null || pos.length !== issuedScene.count * 2) return;
+      bankEnginePositions(pos);
+      projectPlacements(s.engine);
+      notifyLabelSubs(positionSubs);
+    }).catch(() => {
+      // A failed sample keeps the last cache. Event reads remain available;
+      // the next active tick retries within the same bounded cadence.
+    }).finally(() => {
+      if (positionFlight === flight) positionFlight = null;
+    });
+  }
+
   /**
    * per-event readback bank with the pin overlay: the pin slice is
    * authoritative for pinned coordinates, so an engine that does not mirror
@@ -5131,6 +5248,7 @@ export function createGraphInstance<N = Record<string, unknown>, E = Record<stri
    * per-event readback they own).
    */
   function bankEnginePositions(pos: Float32Array): void {
+    positionGeneration += 1;
     const pins = store.getState().pins;
     if (pins.size > 0 && scene !== null) {
       for (const [id, xy] of pins) {
@@ -5145,6 +5263,7 @@ export function createGraphInstance<N = Record<string, unknown>, E = Record<stri
     // the freshest per-event readback also feeds the label lane's
     // projection cache (pin overlay already applied above).
     labelPositionCache = pos;
+    scheduleOverviewNotification();
   }
 
   /** Mirror the selection highlight into the engine. Reads the PUBLISHED
@@ -6354,7 +6473,7 @@ export function createGraphInstance<N = Record<string, unknown>, E = Record<stri
     const groupsResolutionChanged = refreshGroupsResolution();
     const result = reconcileScene(scopedAccepted ?? p.merged);
     const ingestScene = scene!;
-    labelPositionCache = null;
+    invalidatePositionCache();
     const structuralChange = result.structuralChange;
     const positionChange = result.positionChange;
     dataDiags = p.merged.diagnostics;
@@ -7663,7 +7782,7 @@ export function createGraphInstance<N = Record<string, unknown>, E = Record<stri
     }
     scopedAccepted = computeScopedAccepted();
     const result = reconcileScene(scopedAccepted ?? accepted);
-    labelPositionCache = null;
+    invalidatePositionCache();
     adjacency = null;
     sceneIncidence = null;
     hardScopeGen += 1;
@@ -8597,7 +8716,7 @@ export function createGraphInstance<N = Record<string, unknown>, E = Record<stri
       const result = reconcileScene(scopedAccepted ?? accepted);
       // the reconciled scene already merged the banked live cache; the
       // old readback buffer is misaligned with the new slot order.
-      labelPositionCache = null;
+      invalidatePositionCache();
       adjacency = null;
       sceneIncidence = null;
       structuralChange = result.structuralChange;
@@ -8618,7 +8737,7 @@ export function createGraphInstance<N = Record<string, unknown>, E = Record<stri
       if (!dataChanged && !scopeChanged && !groupsSceneDirty && !parallelSceneDirty && accepted !== null) {
         bankReadyEnginePositions();
         const result = reconcileScene(scopedAccepted ?? accepted);
-        labelPositionCache = null;
+        invalidatePositionCache();
         adjacency = null;
         sceneIncidence = null;
         structuralChange = structuralChange || result.structuralChange;
@@ -9548,6 +9667,15 @@ export function createGraphInstance<N = Record<string, unknown>, E = Record<stri
         // are always instance-owned, even under controlled selection.
         const prevented = emit('nodeDragEnd', { node, x, y });
         if (!prevented) writePin(node.id, [x, y]);
+        else if (overviewSubs.size > 0 || labelsEnabled()) {
+          // Cancelling automatic pinning does not undo the drag itself.
+          const pos = s.engine.getPositions();
+          if (pos !== null) {
+            pos[2 * index] = x;
+            pos[2 * index + 1] = y;
+            bankEnginePositions(pos);
+          }
+        }
       },
       // Right-click or long-press → typed 'contextMenu' event. The
       // core adds NO built-in follow-up — components own the menu.
@@ -9564,10 +9692,8 @@ export function createGraphInstance<N = Record<string, unknown>, E = Record<stri
       },
       /**
        * Overlay scheduler tick (adapter activity clock). Per tick:
-       * (1) sim-hot degradation — while the simulation runs, ONE getPositions
-       * readback refreshes the CPU cache at a capped >=500ms cadence (M0:
-       * tracked readback stalls ~18ms, so the lane NEVER reads back per
-       * frame); (2) O(k) projection of the CURRENT candidate set through
+       * (1) the shared position cache samples at most 10 Hz asynchronously
+       * (2 Hz synchronous fallback), with one copy in flight; (2) O(k) projection of the CURRENT candidate set through
        * spaceToScreen for the positions channel. No re-rank ever happens here.
        */
       onFrame(timeMs) {
@@ -9612,17 +9738,8 @@ export function createGraphInstance<N = Record<string, unknown>, E = Record<stri
           }
           pressureSampler.resetCounters(); // counters are per-sample-period
         }
-        if (store.getState().simulationRunning && labelsEnabled()) {
-          if (
-            lastHotRefreshMs === null ||
-            timeMs - lastHotRefreshMs >= SIM_HOT_REFRESH_MS ||
-            timeMs < lastHotRefreshMs // clock went backwards (fresh adapter)
-          ) {
-            lastHotRefreshMs = timeMs;
-            const pos = s.engine.getPositions();
-            if (pos !== null) bankEnginePositions(pos);
-          }
-        }
+        positionClockMs = timeMs;
+        if (store.getState().simulationRunning) sampleOverlayPositions(timeMs);
         if (positionSubs.size > 0 && currentPlacements.length > 0) {
           projectPlacements(s.engine);
           notifyLabelSubs(positionSubs);
@@ -9714,6 +9831,9 @@ export function createGraphInstance<N = Record<string, unknown>, E = Record<stri
         if (!active()) return;
         const status = store.getState().status;
         if (ev.type === 'lost') {
+          positionGeneration += 1;
+          positionFlight = null;
+          lastHotRefreshMs = null;
           // transient loss is a status transition + warning diagnostic,
           // never an 'error' event. Only meaningful from 'ready'.
           if (status !== 'ready') return;
@@ -9795,6 +9915,7 @@ export function createGraphInstance<N = Record<string, unknown>, E = Record<stri
       // the replay re-runs stage 3 too (deterministic — same model +
       // resolved groups reproduce the same rewritten scene).
       reconcileScene(replayModel);
+      invalidatePositionCache();
       const replayScene = scene!;
       const phaseProjectStart = performance.now();
       const commit: EngineCommit = {
@@ -9929,6 +10050,9 @@ export function createGraphInstance<N = Record<string, unknown>, E = Record<stri
     };
     session = s;
     const ownsMount = (): boolean => s.alive && !destroyed && session === s;
+    positionGeneration += 1;
+    positionFlight = null;
+    positionClockMs = 0;
     lastHotRefreshMs = null; // fresh adapter, fresh activity clock
     publish({ status: 'mounting' });
     mountPromise = s.engine
@@ -10098,6 +10222,13 @@ export function createGraphInstance<N = Record<string, unknown>, E = Record<stri
     cancelRerankTimer();
     candidateSubs.clear();
     positionSubs.clear();
+    overviewSubs.clear();
+    overviewSnapshot = null;
+    notifiedOverviewSnapshot = null;
+    overviewScene = null;
+    labelPositionCache = null;
+    positionGeneration += 1;
+    positionFlight = null;
     listeners.clear();
     publish({ status: 'destroyed' });
   }
@@ -10646,7 +10777,7 @@ export function createGraphInstance<N = Record<string, unknown>, E = Record<stri
               // mounting; the next full replay reads this reconciler cache.
               reconciler.noteEnginePositions(next);
               scene = { ...scene, positions: next };
-              labelPositionCache = null;
+              invalidatePositionCache();
               const prevState = store.getState();
               const nextRevisions: Revisions = {
                 ...prevState.revisions,
@@ -11385,7 +11516,23 @@ export function createGraphInstance<N = Record<string, unknown>, E = Record<stri
       if (destroyed) return;
       const eng = engineIfReady();
       if (eng === null) return;
+      const wasRunning = store.getState().simulationRunning;
+      // A later visual write can re-arm activity ticks. It must not revive
+      // automatic first-settle camera following after an explicit pause.
+      cancelSettleFollow();
       eng.pause();
+      // Capture a running force simulation's final frame. A fixed/already
+      // paused scene keeps its authoritative CPU positions: onReady can pause
+      // before the first GPU draw, whose readback is not a placed scene yet.
+      if (wasRunning && layout === 'force' && eng.appliedRevision() === store.getState().revisions.render &&
+          (overviewSubs.size > 0 || labelsEnabled())) {
+        const pos = eng.getPositions();
+        if (pos !== null) {
+          bankEnginePositions(pos);
+          projectPlacements(eng);
+          notifyLabelSubs(positionSubs);
+        }
+      }
       if (store.getState().simulationRunning) publish({ simulationRunning: false });
     },
     resumeSimulation: () => {
@@ -11414,6 +11561,8 @@ export function createGraphInstance<N = Record<string, unknown>, E = Record<stri
     redo,
     getScaleInfo,
     getMetricValue,
+    getOverviewScene,
+    subscribeOverview,
     getRevisions: () => store.getState().revisions,
     getDiagnostics: () => store.getState().diagnostics,
     getNode,
diff --git a/packages/core/src/overview.ts b/packages/core/src/overview.ts
index e15a97b..3ce30ce 100644
--- a/packages/core/src/overview.ts
+++ b/packages/core/src/overview.ts
@@ -31,6 +31,13 @@ export interface OverviewScene {
   count: number;
 }
 
+/** Borrowed read-only view of the current scene's cached positions. The
+ * revision changes when the roster or positions change, including settling
+ * and dragging without a render revision. Do not mutate the position buffer. */
+export interface OverviewSnapshot extends OverviewScene {
+  readonly revision: number;
+}
+
 export interface OverviewControllerOptions {
   /** Latest scene snapshot, or null when nothing is loaded yet. */
   getScene: () => OverviewScene | null;
@@ -128,7 +135,10 @@ export class OverviewController {
    */
   rasterize(): OverviewRaster | null {
     const scene = this.getScene();
-    if (!scene || scene.count <= 0) return null;
+    if (!scene || scene.count <= 0) {
+      this.frame = null;
+      return null;
+    }
     const { positions, count } = scene;
     const pairs = Math.min(count, Math.floor(positions.length / 2));
 
@@ -145,7 +155,10 @@ export class OverviewController {
       if (y < minY) minY = y;
       if (y > maxY) maxY = y;
     }
-    if (!Number.isFinite(minX) || !Number.isFinite(minY)) return null; // all NaN
+    if (!Number.isFinite(minX) || !Number.isFinite(minY)) {
+      this.frame = null;
+      return null; // all NaN
+    }
 
     const size = this.size;
     const pad = size * PADDING_FRACTION;
diff --git a/packages/core/test/live-overview.test.ts b/packages/core/test/live-overview.test.ts
new file mode 100644
index 0000000..2452400
--- /dev/null
+++ b/packages/core/test/live-overview.test.ts
@@ -0,0 +1,350 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { createGraphInstance } from '../src/instance';
+import type { GraphInstance } from '../src/instance';
+import { FakeEngine } from '../src/testing/FakeEngine';
+import { container, snap } from './helpers';
+
+class AsyncEngine extends FakeEngine {
+  reads: Array<{ resolve: (p: Float32Array | null) => void; reject: (e: Error) => void }> = [];
+  getPositionsAsync(): Promise<Float32Array | null> {
+    return new Promise((resolve, reject) => { this.reads.push({ resolve, reject }); });
+  }
+}
+
+const instances: GraphInstance[] = [];
+async function setup(engine = new AsyncEngine()) {
+  const instance = createGraphInstance({ engine: () => engine, fitViewOnFirstData: false });
+  instances.push(instance);
+  instance.applyHostUpdate({ data: snap(1, ['a', 'b']), labels: { enabled: false } });
+  await instance.attach(container);
+  return { instance, engine };
+}
+async function flush() {
+  // copy admission → observer microtask → finally clearing the in-flight slot
+  await Promise.resolve(); await Promise.resolve(); await Promise.resolve();
+}
+afterEach(() => { for (const i of instances.splice(0)) i.destroy(); });
+
+describe('shared live position cache', () => {
+  it('publishes unpositioned force nodes with one async read in flight at a bounded cadence', async () => {
+    const { instance, engine } = await setup();
+    instance.applyHostUpdate({ labels: { minZoom: 0, overlap: 'allow' } });
+    const sync = vi.spyOn(engine, 'getPositions');
+    const observer = vi.fn();
+    const unsub = instance.subscribeOverview(observer);
+    expect(engine.reads).toHaveLength(1);
+    engine.emitFrame(1000);
+    engine.emitFrame(2000);
+    expect(engine.reads).toHaveLength(1);
+    engine.reads[0]!.resolve(Float32Array.of(3, 4, 8, 9));
+    await flush();
+    expect([...instance.getOverviewScene()!.positions]).toEqual([3, 4, 8, 9]);
+    expect(observer).toHaveBeenCalledTimes(2); // replay + admitted copy
+    engine.emitFrame(2001);
+    expect(engine.reads).toHaveLength(2);
+    engine.reads[1]!.resolve(Float32Array.of(4, 5, 9, 10));
+    await flush();
+    engine.emitFrame(2050);
+    expect(engine.reads).toHaveLength(2);
+    engine.emitFrame(2101);
+    expect(engine.reads).toHaveLength(3);
+    expect(sync).not.toHaveBeenCalled();
+    unsub();
+    instance.applyHostUpdate({ labels: { enabled: false } });
+    engine.reads[2]!.resolve(null);
+    await flush();
+    engine.emitFrame(10000);
+    expect(engine.reads).toHaveLength(3);
+  });
+
+  it.each(['roster', 'same-roster positions', 'render'])('rejects a copy after a %s revision changes', async (change) => {
+    const { instance, engine } = await setup();
+    instance.subscribeOverview(() => {});
+    if (change === 'roster') instance.applyHostUpdate({ data: snap(2, ['b', 'a']) });
+    if (change === 'same-roster positions') instance.applyHostUpdate({ data: {
+      ...snap(2, ['a', 'b']), nodes: [{ id: 'a', x: 20, y: 30 }, { id: 'b', x: 40, y: 50 }],
+    } });
+    if (change === 'render') instance.applyHostUpdate({ nodeSize: 17 });
+    const expected = [...instance.getOverviewScene()!.positions];
+    engine.reads[0]!.resolve(Float32Array.of(900, 900, 901, 901));
+    await flush();
+    expect([...instance.getOverviewScene()!.positions]).toEqual(expected);
+  });
+
+  it.each(['settle', 'drag', 'pause'])('keeps the final %s positions when an older copy resolves', async (event) => {
+    const { instance, engine } = await setup();
+    instance.subscribeOverview(() => {});
+    engine.nudgePositions(30, 40);
+    if (event === 'settle') engine.injectSimulationEnd();
+    if (event === 'pause') instance.pauseSimulation();
+    if (event === 'drag') engine.injectDragEnd(0, 100, 200);
+    const final = [...instance.getOverviewScene()!.positions];
+    expect(final[0]).toBe(event === 'drag' ? 100 : 30);
+    engine.reads[0]!.resolve(Float32Array.of(900, 900, 901, 901));
+    await flush();
+    expect([...instance.getOverviewScene()!.positions]).toEqual(final);
+    const reads = engine.reads.length;
+    if (event !== 'drag') engine.emitFrame(10000);
+    expect(engine.reads).toHaveLength(reads); // settled ticks never read
+  });
+
+  it('retires pre-loss copies even after the same adapter recovers', async () => {
+    const { instance, engine } = await setup();
+    instance.subscribeOverview(() => {});
+    engine.injectContextLost();
+    engine.injectContextRestored();
+    engine.emitFrame(500);
+    expect(engine.reads).toHaveLength(2);
+    engine.reads[1]!.resolve(Float32Array.of(50, 60, 70, 80));
+    await flush();
+    engine.reads[0]!.resolve(Float32Array.of(900, 900, 901, 901));
+    await flush();
+    expect([...instance.getOverviewScene()!.positions]).toEqual([50, 60, 70, 80]);
+  });
+
+  it('rejects retired mount copies and does not notify after disposal', async () => {
+    const engines: AsyncEngine[] = [];
+    const instance = createGraphInstance({ engine: () => {
+      const engine = new AsyncEngine(); engines.push(engine); return engine;
+    } });
+    instances.push(instance);
+    instance.applyHostUpdate({ data: snap(1, ['a', 'b']) });
+    await instance.attach(container);
+    const listener = vi.fn();
+    instance.subscribeOverview(listener);
+    instance.detach();
+    await instance.attach(container);
+    engines[1]!.emitFrame(500);
+    engines[1]!.reads[0]!.resolve(Float32Array.of(50, 60, 70, 80));
+    await flush();
+    engines[0]!.reads[0]!.resolve(Float32Array.of(900, 900, 901, 901));
+    await flush();
+    expect([...instance.getOverviewScene()!.positions]).toEqual([50, 60, 70, 80]);
+    engines[1]!.emitFrame(1000);
+    instance.destroy();
+    const notifications = listener.mock.calls.length;
+    engines[1]!.reads[1]!.resolve(Float32Array.of(90, 90, 91, 91));
+    await flush();
+    expect(listener).toHaveBeenCalledTimes(notifications);
+    expect(instance.getOverviewScene()).toBeNull();
+  });
+
+  it('retains cache on failed or wrong-sized copies and retries on activity', async () => {
+    const { instance, engine } = await setup();
+    instance.subscribeOverview(() => {});
+    const initial = instance.getOverviewScene();
+    engine.reads[0]!.reject(new Error('copy unavailable'));
+    await flush();
+    expect(instance.getOverviewScene()).toBe(initial);
+    engine.emitFrame(500);
+    engine.reads[1]!.resolve(Float32Array.of(1, 2));
+    await flush();
+    expect(instance.getOverviewScene()).toBe(initial);
+    engine.emitFrame(1000);
+    expect(engine.reads).toHaveLength(3);
+  });
+
+  it('bounds the synchronous fallback and does no periodic work after settlement', async () => {
+    const engine = new FakeEngine();
+    const instance = createGraphInstance({ engine: () => engine });
+    instances.push(instance);
+    instance.applyHostUpdate({ data: snap(1, ['a', 'b']) });
+    await instance.attach(container);
+    const read = vi.spyOn(engine, 'getPositions');
+    instance.subscribeOverview(() => {});
+    expect(read).toHaveBeenCalledTimes(1);
+    engine.emitFrame(499);
+    expect(read).toHaveBeenCalledTimes(1);
+    engine.emitFrame(500);
+    expect(read).toHaveBeenCalledTimes(2);
+    engine.injectSimulationEnd();
+    const finalReads = read.mock.calls.length;
+    for (let t = 1000; t < 10000; t += 16) engine.emitFrame(t);
+    expect(read).toHaveBeenCalledTimes(finalReads);
+  });
+
+  it('uses declared fixed positions without sampling the engine', async () => {
+    const { instance, engine } = await setup();
+    instance.applyHostUpdate({ layout: 'fixed', data: {
+      ...snap(2, ['a', 'b']), nodes: [{ id: 'a', x: 20, y: 30 }, { id: 'b', x: 40, y: 50 }],
+    } });
+    instance.subscribeOverview(() => {});
+    engine.emitFrame(1000);
+    expect(engine.reads).toHaveLength(0);
+    expect([...instance.getOverviewScene()!.positions]).toEqual([20, 30, 40, 50]);
+  });
+
+  it('observes drag results even when automatic pinning is prevented', async () => {
+    const { instance, engine } = await setup();
+    instance.subscribeOverview(() => {});
+    instance.on('nodeDragEnd', (_event, control) => { control.preventDefault(); });
+    engine.injectDragEnd(0, 100, 200);
+    expect([...instance.getOverviewScene()!.positions].slice(0, 2)).toEqual([100, 200]);
+    expect(instance.store.getState().pins.size).toBe(0);
+  });
+
+  it('limits overview-only async sampling to 2 Hz', async () => {
+    const { instance, engine } = await setup();
+    instance.subscribeOverview(() => {});
+    engine.reads[0]!.resolve(Float32Array.of(1, 2, 3, 4));
+    await flush();
+    engine.emitFrame(100);
+    engine.emitFrame(499);
+    expect(engine.reads).toHaveLength(1);
+    engine.emitFrame(500);
+    expect(engine.reads).toHaveLength(2);
+  });
+
+  it('uses the bounded synchronous lane above 10K nodes and switches back after shrinking', async () => {
+    const { instance, engine } = await setup();
+    instance.applyHostUpdate({
+      data: snap(2, Array.from({ length: 10_001 }, (_, i) => `n${i}`)),
+      labels: { minZoom: 0, overlap: 'allow' },
+    });
+    const sync = vi.spyOn(engine, 'getPositions');
+    instance.subscribeOverview(() => {});
+    expect(sync).toHaveBeenCalledTimes(1);
+    expect(engine.reads).toHaveLength(0);
+    engine.nudgePositions(20, 30);
+    engine.emitFrame(100);
+    engine.emitFrame(499);
+    expect(sync).toHaveBeenCalledTimes(1);
+    engine.emitFrame(500);
+    expect(sync).toHaveBeenCalledTimes(2);
+    expect(instance.getOverviewScene()!.positions[0]).toBe(20);
+
+    instance.applyHostUpdate({ data: snap(3, Array.from({ length: 10_000 }, (_, i) => `n${i}`)) });
+    sync.mockClear(); // roster replacement may preserve live positions with an event read
+    engine.emitFrame(600);
+    expect(engine.reads).toHaveLength(1);
+    const positions = new Float32Array(20_000).fill(40);
+    engine.reads[0]!.resolve(positions);
+    await flush();
+    expect(instance.getOverviewScene()!.positions[0]).toBe(40);
+    engine.emitFrame(699);
+    expect(engine.reads).toHaveLength(1);
+    engine.emitFrame(700);
+    expect(engine.reads).toHaveLength(2);
+    expect(sync).not.toHaveBeenCalled();
+  });
+
+  it('rejects a pending small-scene copy after growing and shrinking back to the same count', async () => {
+    const { instance, engine } = await setup();
+    instance.subscribeOverview(() => {});
+    expect(engine.reads).toHaveLength(1);
+
+    instance.applyHostUpdate({ data: snap(2, Array.from({ length: 10_001 }, (_, i) => `n${i}`)) });
+    engine.emitFrame(500);
+    expect(instance.getOverviewScene()!.count).toBe(10_001);
+
+    instance.applyHostUpdate({ data: {
+      ...snap(3, ['a', 'b']),
+      nodes: [{ id: 'a', x: 20, y: 30 }, { id: 'b', x: 40, y: 50 }],
+    } });
+    const expected = [...instance.getOverviewScene()!.positions];
+    // Length alone cannot reject this old copy: the current roster has the
+    // original two IDs again, but belongs to a different scene generation.
+    engine.reads[0]!.resolve(Float32Array.of(900, 900, 901, 901));
+    await flush();
+    expect([...instance.getOverviewScene()!.positions]).toEqual(expected);
+
+    engine.emitFrame(1000);
+    expect(engine.reads).toHaveLength(2);
+    engine.reads[1]!.resolve(Float32Array.of(21, 31, 41, 51));
+    await flush();
+    expect([...instance.getOverviewScene()!.positions]).toEqual([21, 31, 41, 51]);
+  });
+
+  it('rejects a copy after unpinning even when the render revision is unchanged', async () => {
+    const { instance, engine } = await setup();
+    instance.pinNode('a', [5, 6]);
+    instance.subscribeOverview(() => {});
+    const render = instance.getRevisions().render;
+    instance.unpinNode('a');
+    expect(instance.getRevisions().render).toBe(render);
+    const expected = [...instance.getOverviewScene()!.positions];
+    engine.reads[0]!.resolve(Float32Array.of(900, 900, 901, 901));
+    await flush();
+    expect([...instance.getOverviewScene()!.positions]).toEqual(expected);
+  });
+
+  it.each([false, true])('never samples a deferred old engine roster (async=%s)', async (async) => {
+    const engine = async ? new AsyncEngine({ manualFrames: true }) : new FakeEngine({ manualFrames: true });
+    const instance = createGraphInstance({ engine: () => engine });
+    instances.push(instance);
+    instance.applyHostUpdate({ data: { ...snap(1, ['a', 'b']), nodes: [{ id: 'a', x: 0, y: 0 }, { id: 'b', x: 10, y: 0 }] } });
+    await instance.attach(container);
+    engine.stepFrame();
+    instance.applyHostUpdate({ data: { ...snap(2, ['b', 'a']), nodes: [{ id: 'b', x: 100, y: 100 }, { id: 'a', x: 200, y: 200 }] } });
+    const read = vi.spyOn(engine, 'getPositions');
+    instance.subscribeOverview(() => {});
+    await flush();
+    expect([...instance.getOverviewScene()!.positions]).toEqual([100, 100, 200, 200]);
+    expect(read).not.toHaveBeenCalled();
+    if (engine instanceof AsyncEngine) expect(engine.reads).toHaveLength(0);
+    engine.stepFrame();
+    if (engine instanceof AsyncEngine) {
+      expect(engine.reads).toHaveLength(1);
+      engine.reads[0]!.resolve(engine.getPositions());
+      await flush();
+    } else expect(read).toHaveBeenCalledTimes(1);
+    expect([...instance.getOverviewScene()!.positions]).toEqual([100, 100, 200, 200]);
+  });
+
+  it('pausing an already fixed scene does not replace declared positions with pre-draw GPU state', async () => {
+    const engine = new AsyncEngine();
+    const instance = createGraphInstance({ engine: () => engine });
+    instances.push(instance);
+    instance.applyHostUpdate({ layout: 'fixed', data: { ...snap(1, ['a', 'b']), nodes: [{ id: 'a', x: 100, y: 100 }, { id: 'b', x: 200, y: 200 }] } });
+    await instance.attach(container);
+    instance.subscribeOverview(() => {});
+    const read = vi.spyOn(engine, 'getPositions').mockReturnValue(Float32Array.of(0, 0, 0, 0));
+    instance.pauseSimulation();
+    expect(read).not.toHaveBeenCalled();
+    expect([...instance.getOverviewScene()!.positions]).toEqual([100, 100, 200, 200]);
+  });
+
+  it('does not bank an unapplied roster when a force simulation is paused', async () => {
+    const engine = new FakeEngine({ manualFrames: true });
+    const instance = createGraphInstance({ engine: () => engine });
+    instances.push(instance);
+    instance.applyHostUpdate({ data: snap(1, ['a', 'b']) });
+    await instance.attach(container);
+    engine.stepFrame();
+    instance.subscribeOverview(() => {});
+    instance.applyHostUpdate({ data: { ...snap(2, ['a', 'b']), nodes: [{ id: 'a', x: 100, y: 100 }, { id: 'b', x: 200, y: 200 }] } });
+    const read = vi.spyOn(engine, 'getPositions');
+    instance.pauseSimulation();
+    expect(read).not.toHaveBeenCalled();
+    expect([...instance.getOverviewScene()!.positions]).toEqual([100, 100, 200, 200]);
+  });
+
+  it('projects final pause positions without waiting for another engine frame', async () => {
+    const { instance, engine } = await setup();
+    instance.applyHostUpdate({ labels: { minZoom: 0, overlap: 'allow' } });
+    engine.injectSimulationEnd();
+    instance.resumeSimulation();
+    const positions = vi.fn();
+    instance.labels.subscribePositions(positions);
+    engine.nudgePositions(30, 40);
+    instance.pauseSimulation();
+    expect(positions.mock.lastCall![0].map((p: { x: number; y: number }) => [p.x, p.y])).toEqual([[30, 40], [40, 40]]);
+  });
+
+  it('shares accepted snapshots with labels without per-sample re-ranking or store writes', async () => {
+    const { instance, engine } = await setup();
+    instance.applyHostUpdate({ labels: { minZoom: 0, overlap: 'allow' } });
+    engine.injectSimulationEnd(); // populate candidates from seeded engine positions
+    instance.resumeSimulation();
+    const positions = vi.fn();
+    instance.labels.subscribePositions(positions);
+    instance.subscribeOverview(() => {});
+    const publish = vi.fn();
+    const unsubStore = instance.store.subscribe(publish);
+    engine.reads[0]!.resolve(Float32Array.of(3, 4, 8, 9));
+    await flush();
+    expect(positions.mock.lastCall![0].map((p: { x: number; y: number }) => [p.x, p.y])).toEqual([[3, 4], [8, 9]]);
+    expect(publish).not.toHaveBeenCalled();
+    unsubStore();
+  });
+});
diff --git a/packages/core/test/overview.test.ts b/packages/core/test/overview.test.ts
index 43196e8..280964f 100644
--- a/packages/core/test/overview.test.ts
+++ b/packages/core/test/overview.test.ts
@@ -41,6 +41,21 @@ function pixel(bitmap: Uint8ClampedArray, size: number, px: number, py: number):
 }
 
 describe('OverviewController.rasterize', () => {
+  it('clears the old pan transform when the current scene has no finite positions', () => {
+    let scene: OverviewScene | null = { positions: FIVE_POINTS, count: 5 };
+    const overview = new OverviewController({ getScene: () => scene });
+    expect(overview.rasterize()).not.toBeNull();
+    expect(overview.minimapToWorld(10, 10)).not.toBeNull();
+    scene = { positions: Float32Array.of(NaN, NaN), count: 1 };
+    expect(overview.rasterize()).toBeNull();
+    expect(overview.minimapToWorld(10, 10)).toBeNull();
+    scene = { positions: FIVE_POINTS, count: 5 };
+    expect(overview.rasterize()).not.toBeNull();
+    scene = null;
+    expect(overview.rasterize()).toBeNull();
+    expect(overview.worldToMinimap(10, 10)).toBeNull();
+  });
+
   it('places the 5 known points at exact pixels (5% padding, uniform scale, y flipped)', () => {
     // size 100 → pad 5, inner 90; world span 10 → scale 9.
     // px = 5 + (x - 0) * 9; py = 5 + (10 - y) * 9 (pixel y grows downward).
diff --git a/packages/core/test/settle-camera.test.ts b/packages/core/test/settle-camera.test.ts
index 3317d86..627e368 100644
--- a/packages/core/test/settle-camera.test.ts
+++ b/packages/core/test/settle-camera.test.ts
@@ -110,6 +110,18 @@ describe('settle camera', () => {
     expect(fitCalls(engine.cameraCalls).length).toBe(atCap);
   });
 
+  it('explicit pause cancels automatic follow even when a later config write re-arms frames', async () => {
+    const { h, engine } = await mounted();
+    for (let i = 0; i < 54; i++) engine.emitFrame();
+    const initialFits = fitCalls(engine.cameraCalls).length;
+    h.instance.pauseSimulation();
+    h.instance.applyHostUpdate({ simulation: { gravity: 0.26 } });
+    for (let i = 0; i < 100; i++) engine.emitFrame();
+    engine.injectSimulationEnd();
+    expect(fitCalls(engine.cameraCalls)).toHaveLength(initialFits);
+    h.instance.destroy();
+  });
+
   it('user camera input cancels the follow (public setViewport)', async () => {
     const { h, engine } = await mounted();
     const initialFits = fitCalls(engine.cameraCalls).length;
diff --git a/packages/data/README.md b/packages/data/README.md
new file mode 100644
index 0000000..002e516
--- /dev/null
+++ b/packages/data/README.md
@@ -0,0 +1,157 @@
+# @modernrelay/orbit-data
+
+Prepare supplied rows, CSV, JSON, Arrow, or Parquet for Orbit. This package does
+not fetch URLs or touch the DOM. The root entry includes rows/CSV/JSON; optional
+Arrow and Parquet parsers stay in their own entry points.
+
+## Import a graph
+
+```ts
+import { prepareGraphData } from '@modernrelay/orbit-data';
+
+const controller = new AbortController();
+const prepared = await prepareGraphData(
+  { nodes: nodeFile, edges: edgeFile }, // Blob/File, ArrayBuffer, or async byte streams
+  {
+    nodes: { id: 'person_id', includeFields: ['name', 'team'] },
+    edges: { id: 'relationship_id', source: 'from', target: 'to' },
+  },
+  {
+    datasetKey: 'relationships',
+    sourceRevision: 'upload-1', // change when the data changes
+    format: 'csv',
+    signal: controller.signal,
+    maxBytes: 128 * 1024 * 1024,
+    maxNodes: 100_000,
+    maxEdges: 250_000,
+    onProgress: ({ phase, bytes, nodes, edges }) => {
+      console.log(phase, bytes, nodes, edges);
+    },
+  },
+);
+// Pass prepared.snapshot to <Graph data={...}> or instance.applyHostUpdate.
+// prepared.summaries contains column profiles; mappingFingerprint identifies the mapping.
+```
+
+Use `{ edges, deriveNodes: true }` when only an edge table exists. Node IDs are
+derived in first endpoint occurrence order. Separate node/edge arrays and async
+row iterables use the same mappings with `format: 'rows'`. A JSON byte source uses
+`{ document }`, `format: 'json'`, and `mapping.documentPaths: { nodes: 'graph.nodes',
+edges: 'graph.edges' }`.
+
+Identity columns remain strings in CSV, preserving IDs such as `001`. Other
+CSV columns infer numeric values from the first 1,000 records; empty cells are
+absent. Explicit `includeFields` is an exact attribute allowlist; by default,
+all non-identity columns become attributes. Missing IDs and invalid mappings
+reject with row/column context. Duplicate IDs and dangling endpoints in object
+snapshots remain core's validation responsibility.
+
+For Arrow install `apache-arrow` and import `prepareArrowGraphData` from
+`@modernrelay/orbit-data/arrow`. It accepts Arrow tables or IPC bytes. For Parquet
+install `hyparquet` and import `prepareParquetGraphData` from
+`@modernrelay/orbit-data/parquet`; each node/edge source is a file's bytes. Both
+accept the same mapping and controls, without a `format` option.
+
+## Preview before choosing columns
+
+```ts
+import { previewCsv } from '@modernrelay/orbit-data';
+
+const preview = await previewCsv(file, {
+  signal: controller.signal,
+  maxRows: 5,           // default
+  maxBytes: 256 * 1024, // default examined-byte budget
+});
+// preview.columns -> mapping selectors
+// preview.rows -> raw strings, including quoted newlines and leading-zero IDs
+```
+
+Preview uses the same CSV record parser and closes its iterator once the sample
+is ready. `truncated: true` means the sample cap was reached; it does not inspect
+another row to determine whether the file ends there. A record that cannot be
+completed within the byte budget rejects. Bytes after the sample are not
+validated. Reopen single-use streams for the actual preparation.
+
+## Limits, progress, and cancellation
+
+- Limits are optional positive safe integers; omitting them preserves the
+  unrestricted default. `maxBytes` counts supplied byte chunks across **both**
+  inputs, including headers. Row objects and existing Arrow tables have no wire
+  bytes and report zero. `maxNodes`/`maxEdges` count admitted rows before core
+  validation; duplicates count, while derived nodes count unique endpoint IDs.
+- Limits reject with a `RangeError` naming the cap. They do not publish partial
+  graphs. Byte limits describe input size, **not** a JavaScript heap limit:
+  JSON parsing and Parquet decompression can require additional memory.
+- Progress reports cumulative `{ phase, bytes, nodes, edges }`, at most once per
+  100 ms plus a final `complete` event. Phases are `reading`, `preparing`, and
+  `complete`; not every phase must produce a callback on a short load.
+- Preparation yields tasks during row processing so browser input, cancellation,
+  and progress painting can run. Cancellation rejects with `AbortError`, including
+  cancellation during Parquet decoding. Synchronous parser calls cannot be
+  interrupted mid-call; cancellation is checked immediately afterward. Stalled
+  asynchronous reads stop being awaited, and their iterator is asked to close;
+  an uncooperative producer may finish its own pending I/O later.
+
+## Opt-in columnar output
+
+```ts
+const prepared = await prepareGraphData(input, mapping, {
+  datasetKey: 'relationships', sourceRevision: 'upload-1', output: 'columnar',
+}); // PreparedColumnarGraph; snapshot is ColumnarGraphSnapshot
+```
+
+All five formats support columnar output. The builder writes attribute columns
+without retaining object graph nodes/edges. Strings use dictionaries, numbers
+use Float64 arrays, and booleans use byte arrays. Missing, undefined, null, and
+non-finite numeric cells become explicit null bits; an all-null column uses a
+nullable Float64 array. Values keep their primitive type: a mixed string/number
+column is an error. Summaries and mapping fingerprints match the object lane.
+
+Nested arrays/objects, bigint attributes in raw row inputs, and `__proto__`
+attributes reject with a remedy to use `output: 'object'`. Arrow/Parquet integer
+normalization still applies before column construction. Unknown endpoints also
+reject because typed endpoint indices cannot represent them. Supply the missing
+nodes, derive nodes, or use the default object path for core's dangling-edge
+diagnostics. Synthesized edge IDs use the same canonical helper as core.
+
+Buffers and dictionaries are newly allocated. Inputs are never modified or
+detached; snapshots use `bufferOwnership: 'borrowed'` for repeatable admission.
+Callers may explicitly choose transfer ownership when handing a result to core.
+Core currently materializes columnar rows during acceptance, so a smaller
+prepared result does not imply a smaller final running graph or faster rendering.
+
+## Save and reuse object artifacts
+
+```ts
+import { serializePrepared, loadPrepared } from '@modernrelay/orbit-data';
+
+const bytes = serializePrepared(preparedObject);
+const restored = loadPrepared(bytes); // validates the v1 object artifact
+```
+
+The default object API and version-1 artifact format are unchanged. Columnar
+outputs are deliberately not accepted by the v1 serializer; keep their typed
+buffers in memory or prepare object output when an existing JSON artifact is
+required.
+
+## Measure preparation
+
+From the repository root run `node scripts/bench-data-preparation.mjs`. It runs
+three fresh processes for each output with identical 100K-node/250K-edge row
+streams and reports elapsed time, process peak RSS, and retained heap plus typed
+buffers after GC. These are CPU preparation measurements, not GPU qualification.
+The report explicitly evaluates whether columnar is faster and whether its
+retained memory is lower; neither result is assumed.
+
+One [recorded run](benchmarks/preparation-node24-darwin-arm64.json) on Node
+24.15.0/macOS arm64 measured these medians across three fresh processes:
+
+| Metric | Object | Columnar |
+|---|---:|---:|
+| Preparation | 628 ms | 702 ms |
+| Retained heap + typed buffers | 70.2 MiB | 18.5 MiB |
+| Process peak RSS | 277.0 MiB | 281.9 MiB |
+
+Retained result memory was about 74% lower, but preparation was slower and peak
+RSS did not improve. Timing varied (columnar 691–914 ms), so these are observations
+for this synthetic workload, not speed guarantees or end-to-end graph benchmarks.
diff --git a/packages/data/benchmarks/preparation-node24-darwin-arm64.json b/packages/data/benchmarks/preparation-node24-darwin-arm64.json
new file mode 100644
index 0000000..57aa1f5
--- /dev/null
+++ b/packages/data/benchmarks/preparation-node24-darwin-arm64.json
@@ -0,0 +1,114 @@
+{
+  "benchmark": "CPU-only prepared row streams",
+  "node": "v24.15.0",
+  "platform": "darwin",
+  "arch": "arm64",
+  "nodes": 100000,
+  "edges": 250000,
+  "runs": 3,
+  "qualification": "Not a GPU/render benchmark; core may materialize columnar output later.",
+  "verdict": {
+    "retainedMemoryLower": true,
+    "preparationFaster": false
+  },
+  "summary": {
+    "object": {
+      "elapsedMs": {
+        "min": 565.7480830000001,
+        "median": 627.672042,
+        "max": 636.950583
+      },
+      "peakRssBytes": {
+        "min": 289849344,
+        "median": 290406400,
+        "max": 290963456
+      },
+      "retainedHeapAndBuffersDelta": {
+        "min": 73319920,
+        "median": 73570200,
+        "max": 73613064
+      }
+    },
+    "columnar": {
+      "elapsedMs": {
+        "min": 691.352125,
+        "median": 701.807917,
+        "max": 914.170625
+      },
+      "peakRssBytes": {
+        "min": 294109184,
+        "median": 295567360,
+        "max": 297517056
+      },
+      "retainedHeapAndBuffersDelta": {
+        "min": 19174240,
+        "median": 19386640,
+        "max": 19388096
+      }
+    }
+  },
+  "samples": [
+    {
+      "output": "object",
+      "elapsedMs": 627.672042,
+      "peakRssBytes": 289849344,
+      "retainedHeapAndBuffersDelta": 73570200,
+      "baselineRssBytes": 55738368,
+      "nodes": 100000,
+      "edges": 250000,
+      "mappingFingerprint": "c10747e64218745a"
+    },
+    {
+      "output": "columnar",
+      "elapsedMs": 701.807917,
+      "peakRssBytes": 295567360,
+      "retainedHeapAndBuffersDelta": 19388096,
+      "baselineRssBytes": 56066048,
+      "nodes": 100000,
+      "edges": 250000,
+      "mappingFingerprint": "c10747e64218745a"
+    },
+    {
+      "output": "object",
+      "elapsedMs": 565.7480830000001,
+      "peakRssBytes": 290963456,
+      "retainedHeapAndBuffersDelta": 73319920,
+      "baselineRssBytes": 55787520,
+      "nodes": 100000,
+      "edges": 250000,
+      "mappingFingerprint": "c10747e64218745a"
+    },
+    {
+      "output": "columnar",
+      "elapsedMs": 691.352125,
+      "peakRssBytes": 294109184,
+      "retainedHeapAndBuffersDelta": 19386640,
+      "baselineRssBytes": 55640064,
+      "nodes": 100000,
+      "edges": 250000,
+      "mappingFingerprint": "c10747e64218745a"
+    },
+    {
+      "output": "object",
+      "elapsedMs": 636.950583,
+      "peakRssBytes": 290406400,
+      "retainedHeapAndBuffersDelta": 73613064,
+      "baselineRssBytes": 55803904,
+      "nodes": 100000,
+      "edges": 250000,
+      "mappingFingerprint": "c10747e64218745a"
+    },
+    {
+      "output": "columnar",
+      "elapsedMs": 914.170625,
+      "peakRssBytes": 297517056,
+      "retainedHeapAndBuffersDelta": 19174240,
+      "baselineRssBytes": 56262656,
+      "nodes": 100000,
+      "edges": 250000,
+      "mappingFingerprint": "c10747e64218745a"
+    }
+  ],
+  "measuredAt": "2026-10-24T16:45:58.023Z",
+  "cpu": "Apple M5 Pro"
+}
diff --git a/packages/data/src/arrow.ts b/packages/data/src/arrow.ts
index cc7b958..e845404 100644
--- a/packages/data/src/arrow.ts
+++ b/packages/data/src/arrow.ts
@@ -19,6 +19,7 @@
 
 import { normalizeJsonSafeValue } from './jsonSafe';
 
+import { PreparationControl } from './control';
 import { buildPrepared } from './builder';
 import { EMPTY_ROW_TABLE, type RowTable } from './rowTable';
 import { collectBytes, throwIfAborted } from './sources';
@@ -26,6 +27,9 @@ import type {
   GraphByteSource,
   GraphColumnMapping,
   GraphPrepareOptions,
+  GraphPrepareAnyOptions,
+  GraphPrepareColumnarOptions,
+  PreparedColumnarGraph,
   PreparedGraph,
 } from './types';
 
@@ -84,30 +88,41 @@ async function loadArrowModule(): Promise<ArrowModule> {
   };
 }
 
+export function prepareArrowGraphData<N = Record<string, unknown>, E = Record<string, unknown>>(
+  input: ArrowGraphPrepareInput, mapping: GraphColumnMapping, options: Omit<GraphPrepareColumnarOptions, 'format'>,
+): Promise<PreparedColumnarGraph<N, E>>;
+export function prepareArrowGraphData<N = Record<string, unknown>, E = Record<string, unknown>>(
+  input: ArrowGraphPrepareInput, mapping: GraphColumnMapping, options: Omit<GraphPrepareOptions, 'format'>,
+): Promise<PreparedGraph<N, E>>;
+export function prepareArrowGraphData<N = Record<string, unknown>, E = Record<string, unknown>>(
+  input: ArrowGraphPrepareInput, mapping: GraphColumnMapping, options: Omit<GraphPrepareAnyOptions, 'format'>,
+): Promise<PreparedGraph<N, E> | PreparedColumnarGraph<N, E>>;
 export async function prepareArrowGraphData<
   N = Record<string, unknown>,
   E = Record<string, unknown>,
 >(
   input: ArrowGraphPrepareInput,
   mapping: GraphColumnMapping,
-  options: Omit<GraphPrepareOptions, 'format'>,
-): Promise<PreparedGraph<N, E>> {
+  options: Omit<GraphPrepareAnyOptions, 'format'>,
+): Promise<PreparedGraph<N, E> | PreparedColumnarGraph<N, E>> {
+  const control = new PreparationControl(options as GraphPrepareAnyOptions);
   const signal = options.signal;
   throwIfAborted(signal);
   const arrow = await loadArrowModule();
   throwIfAborted(signal);
   const deriveNodes = 'deriveNodes' in input && input.deriveNodes === true;
-  const edgeTable = await arrowRowTable(input.edges, arrow, signal);
+  const edgeTable = await arrowRowTable(input.edges, arrow, signal, control);
   const nodeTable = deriveNodes
     ? null
-    : await arrowRowTable((input as { nodes: ArrowGraphSource }).nodes, arrow, signal);
+    : await arrowRowTable((input as { nodes: ArrowGraphSource }).nodes, arrow, signal, control);
   return (await buildPrepared({
     nodeTable,
     edgeTable,
     mapping,
     format: 'arrow',
-    options: { ...options, format: 'arrow' },
-  })) as PreparedGraph<N, E>;
+    options: { ...options, format: 'arrow' } as GraphPrepareAnyOptions,
+    control,
+  })) as PreparedGraph<N, E> | PreparedColumnarGraph<N, E>;
 }
 
 function isArrowTable(source: ArrowGraphSource): source is ArrowTableLike {
@@ -124,11 +139,12 @@ async function arrowRowTable(
   source: ArrowGraphSource,
   arrow: ArrowModule,
   signal: AbortSignal | undefined,
+  control: PreparationControl,
 ): Promise<RowTable> {
   throwIfAborted(signal);
   const table = isArrowTable(source)
     ? source
-    : arrow.tableFromIPC(await collectBytes(source as GraphByteSource, signal));
+    : arrow.tableFromIPC(await collectBytes(source as GraphByteSource, signal, control));
   throwIfAborted(signal);
   const columns = table.schema.fields.map((f) => f.name);
   if (columns.length === 0 && table.numRows === 0) return EMPTY_ROW_TABLE;
diff --git a/packages/data/src/artifact.ts b/packages/data/src/artifact.ts
index f6c8e9e..a02430b 100644
--- a/packages/data/src/artifact.ts
+++ b/packages/data/src/artifact.ts
@@ -37,6 +37,9 @@ interface PreparedArtifactEnvelopeV1 {
 
 export function serializePrepared(prepared: PreparedGraph<unknown, unknown>): Uint8Array {
   const snapshot = prepared.snapshot as GraphSnapshot;
+  if ((snapshot as { kind?: unknown }).kind === 'columnar') {
+    throw new TypeError("serializePrepared: v1 artifacts require output:'object'; columnar buffers are not a v1 JSON artifact");
+  }
   const envelope: PreparedArtifactEnvelopeV1 = {
     formatVersion: PREPARED_ARTIFACT_FORMAT_VERSION,
     datasetKey: snapshot.datasetKey,
diff --git a/packages/data/src/builder.ts b/packages/data/src/builder.ts
index 648d86c..45508d1 100644
--- a/packages/data/src/builder.ts
+++ b/packages/data/src/builder.ts
@@ -26,13 +26,16 @@
  */
 
 import type { GraphEdge, GraphNode, GraphSnapshot } from '@modernrelay/orbit-core';
+import { ColumnarBuilder } from './columnar';
+import type { PreparationControl } from './control';
 import { computeMappingFingerprint } from './fingerprint';
 import type { RowTable } from './rowTable';
 import { TableSummarizer } from './summaries';
 import type {
   GraphColumnMapping,
   GraphPrepareFormat,
-  GraphPrepareOptions,
+  GraphPrepareAnyOptions,
+  PreparedColumnarGraph,
   PreparedGraph,
 } from './types';
 import { validateMapping } from './validate';
@@ -47,14 +50,16 @@ export interface BuildArgs {
   mapping: GraphColumnMapping;
   /** Resolved lane label; part of the fingerprint. */
   format: GraphPrepareFormat;
-  options: GraphPrepareOptions;
+  options: GraphPrepareAnyOptions;
+  control: PreparationControl;
 }
 
-export async function buildPrepared(args: BuildArgs): Promise<PreparedGraph> {
-  const { nodeTable, edgeTable, mapping, format, options } = args;
+export async function buildPrepared(args: BuildArgs): Promise<PreparedGraph | PreparedColumnarGraph> {
+  const { nodeTable, edgeTable, mapping, format, options, control } = args;
   let failed = false;
   try {
-    validateOptions(options);
+    control.check();
+    const columnar = options.output === 'columnar' ? new ColumnarBuilder() : undefined;
     validateMapping({
       mapping,
       nodeColumns: nodeTable === null ? null : nodeTable.columns,
@@ -75,10 +80,13 @@ export async function buildPrepared(args: BuildArgs): Promise<PreparedGraph> {
       edgeSummarizer.seed(edgeAttrPick.seedColumns);
       for (const column of edgeAttrPick.seedColumns) edgeAttrPick.admitted.add(column);
     }
+    columnar?.edgeAttributes.seed(edgeAttrPick.seedColumns);
     const edges: GraphEdge[] = [];
     const endpointOrder = new Set<string>();
     let edgeOrdinal = 0;
     for await (const row of edgeTable.rows) {
+      await control.checkpoint();
+      control.admit('edges');
       const source = identityString(
         row[mapping.edges.source],
         'edge source',
@@ -93,20 +101,24 @@ export async function buildPrepared(args: BuildArgs): Promise<PreparedGraph> {
         mapping.edges.target,
         true,
       );
-      const edge: GraphEdge = { source, target };
+      let edgeId: string | undefined;
       if (mapping.edges.id !== undefined) {
         const raw = row[mapping.edges.id];
         if (raw !== undefined && raw !== null) {
-          edge.id = identityString(raw, 'edge id', edgeOrdinal, mapping.edges.id, true);
+          edgeId = identityString(raw, 'edge id', edgeOrdinal, mapping.edges.id, true);
         }
       }
       const attrs = edgeAttrPick.pick(row);
-      if (attrs !== undefined) edge.attrs = attrs;
       edgeSummarizer.addRow(attrs);
-      edges.push(edge);
+      if (columnar !== undefined) columnar.edge(source, target, edgeId, attrs);
+      else edges.push({ source, target, ...(edgeId === undefined ? {} : { id: edgeId }), ...(attrs === undefined ? {} : { attrs }) });
       if (nodeTable === null) {
-        endpointOrder.add(source);
-        endpointOrder.add(target);
+        for (const endpoint of [source, target]) {
+          if (!endpointOrder.has(endpoint)) {
+            control.admit('nodes');
+            endpointOrder.add(endpoint);
+          }
+        }
       }
       edgeOrdinal++;
     }
@@ -116,7 +128,11 @@ export async function buildPrepared(args: BuildArgs): Promise<PreparedGraph> {
     let nodeAdmitted: ReadonlySet<string> = new Set<string>();
     if (nodeTable === null) {
       // deriveNodes: ids only, first-occurrence order over edge endpoints.
-      for (const id of endpointOrder) nodes.push({ id });
+      for (const id of endpointOrder) {
+        await control.checkpoint();
+        if (columnar !== undefined) columnar.node(id);
+        else nodes.push({ id });
+      }
     } else {
       const nodeMapping = mapping.nodes!; // validated above
       const nodeIdentity = new Set<string>([nodeMapping.id]);
@@ -126,14 +142,16 @@ export async function buildPrepared(args: BuildArgs): Promise<PreparedGraph> {
         nodeSummarizer.seed(nodeAttrPick.seedColumns);
         for (const column of nodeAttrPick.seedColumns) nodeAttrPick.admitted.add(column);
       }
+      columnar?.nodeAttributes.seed(nodeAttrPick.seedColumns);
       let nodeOrdinal = 0;
       for await (const row of nodeTable.rows) {
+        await control.checkpoint();
+        control.admit('nodes');
         const id = identityString(row[nodeMapping.id], 'node id', nodeOrdinal, nodeMapping.id, true);
-        const node: GraphNode = { id };
         const attrs = nodeAttrPick.pick(row);
-        if (attrs !== undefined) node.attrs = attrs;
         nodeSummarizer.addRow(attrs);
-        nodes.push(node);
+        if (columnar !== undefined) columnar.node(id, attrs);
+        else nodes.push({ id, ...(attrs === undefined ? {} : { attrs }) });
         nodeOrdinal++;
       }
     }
@@ -146,17 +164,18 @@ export async function buildPrepared(args: BuildArgs): Promise<PreparedGraph> {
       edges: [...edgeAttrPick.admitted],
     });
 
-    const snapshot: GraphSnapshot = {
+    const snapshot = columnar !== undefined ? await columnar.finish(control) : {
       datasetKey: options.datasetKey,
       sourceRevision: options.sourceRevision,
       nodes,
       edges,
-    };
+    } satisfies GraphSnapshot;
+    control.report('complete');
     return {
       snapshot,
       summaries: { nodes: nodeSummarizer.finalize(), edges: edgeSummarizer.finalize() },
       mappingFingerprint,
-    };
+    } as PreparedGraph | PreparedColumnarGraph;
   } catch (cause) {
     failed = true;
     throw cause;
@@ -180,21 +199,6 @@ export async function buildPrepared(args: BuildArgs): Promise<PreparedGraph> {
   }
 }
 
-function validateOptions(options: GraphPrepareOptions): void {
-  if (typeof options.datasetKey !== 'string' || options.datasetKey === '') {
-    throw new TypeError('prepareGraphData: options.datasetKey must be a non-empty string');
-  }
-  const rev = options.sourceRevision;
-  if (
-    (typeof rev !== 'string' && typeof rev !== 'number') ||
-    (typeof rev === 'number' && !Number.isFinite(rev))
-  ) {
-    throw new TypeError(
-      'prepareGraphData: options.sourceRevision must be a string or finite number',
-    );
-  }
-}
-
 function identityString(
   value: unknown,
   role: string,
diff --git a/packages/data/src/columnar.ts b/packages/data/src/columnar.ts
new file mode 100644
index 0000000..13a49ea
--- /dev/null
+++ b/packages/data/src/columnar.ts
@@ -0,0 +1,160 @@
+import { nextSynthesizedEdgeId } from '@modernrelay/orbit-core';
+import type { Column, ColumnarGraphSnapshot, EdgePairCounters, StringColumn } from '@modernrelay/orbit-core';
+import type { PreparationControl } from './control';
+
+/** Grow typed storage geometrically; never retain a GraphNode/GraphEdge array. */
+class Values {
+  private kind: 'number' | 'boolean' | 'string' | undefined;
+  private data = new Float64Array(0);
+  private nulls = new Uint8Array(0);
+  private dictionary: string[] = [];
+  private codes = new Map<string, number>();
+
+  constructor(private readonly name: string) {}
+
+  set(index: number, raw: unknown): void {
+    const value = typeof raw === 'number' && !Number.isFinite(raw) ? null : raw;
+    if (value === null || value === undefined) return;
+    const kind = typeof value;
+    if (kind !== 'number' && kind !== 'boolean' && kind !== 'string') {
+      throw new TypeError(`prepareGraphData: columnar ${this.name} at row ${index} cannot represent ${kind}; use output:'object' for nested or non-primitive attributes`);
+    }
+    if (this.kind !== undefined && this.kind !== kind) {
+      throw new TypeError(`prepareGraphData: columnar ${this.name} mixes ${this.kind} and ${kind} at row ${index}; use output:'object'`);
+    }
+    this.kind = kind;
+    this.grow(index + 1);
+    this.nulls[index] = 0;
+    if (typeof value === 'string') {
+      let code = this.codes.get(value);
+      if (code === undefined) {
+        code = this.dictionary.length;
+        this.codes.set(value, code);
+        this.dictionary.push(value);
+      }
+      this.data[index] = code;
+    } else this.data[index] = typeof value === 'boolean' ? Number(value) : value as number;
+  }
+
+  private grow(length: number): void {
+    if (length <= this.data.length) return;
+    const capacity = Math.max(length, this.data.length * 2, 16);
+    const data = new Float64Array(capacity);
+    data.set(this.data);
+    const nulls = new Uint8Array(capacity).fill(1);
+    nulls.set(this.nulls);
+    this.data = data;
+    this.nulls = nulls;
+  }
+
+  finish(length: number): Column {
+    this.grow(length);
+    const mask = this.nulls.slice(0, length);
+    const nullable = mask.includes(1) ? { nulls: mask } : {};
+    if (this.kind === 'string') {
+      return { kind: 'string', dictionary: this.dictionary, codes: Uint32Array.from(this.data.subarray(0, length)), ...nullable };
+    }
+    if (this.kind === 'boolean') return { kind: 'bool', data: Uint8Array.from(this.data.subarray(0, length)), ...nullable };
+    return { kind: 'f64', data: this.data.slice(0, length), ...nullable };
+  }
+}
+
+class Attributes {
+  private columns = new Map<string, Values>();
+  constructor(private readonly role: string) {}
+
+  seed(names: readonly string[]): void {
+    for (const name of names) this.column(name);
+  }
+
+  private column(name: string): Values {
+    // Core currently materializes attributes using plain assignment. This
+    // special setter cannot faithfully survive that bridge; fail explicitly.
+    if (name === '__proto__') throw new TypeError("prepareGraphData: columnar __proto__ attributes require output:'object'");
+    let column = this.columns.get(name);
+    if (column === undefined) {
+      column = new Values(`${this.role}.${name}`);
+      this.columns.set(name, column);
+    }
+    return column;
+  }
+
+  add(attrs: Record<string, unknown> | undefined, row: number): void {
+    if (attrs === undefined) return;
+    for (const name of Object.keys(attrs)) this.column(name).set(row, attrs[name]);
+  }
+
+  finish(length: number): Record<string, Column> {
+    return Object.fromEntries([...this.columns].map(([name, column]) => [name, column.finish(length)]));
+  }
+}
+
+function ids(values: readonly string[]): StringColumn {
+  const dictionary: string[] = [];
+  const index = new Map<string, number>();
+  const codes = new Uint32Array(values.length);
+  for (let i = 0; i < values.length; i++) {
+    const value = values[i]!;
+    let code = index.get(value);
+    if (code === undefined) {
+      code = dictionary.length;
+      dictionary.push(value);
+      index.set(value, code);
+    }
+    codes[i] = code;
+  }
+  return { kind: 'string', dictionary, codes };
+}
+
+export class ColumnarBuilder {
+  private nodeIds: string[] = [];
+  private edgeIds: (string | undefined)[] = [];
+  private sources: string[] = [];
+  private targets: string[] = [];
+  readonly nodeAttributes = new Attributes('nodes');
+  readonly edgeAttributes = new Attributes('edges');
+
+  node(id: string, attrs?: Record<string, unknown>): void {
+    this.nodeAttributes.add(attrs, this.nodeIds.length);
+    this.nodeIds.push(id);
+  }
+
+  edge(source: string, target: string, id: string | undefined, attrs?: Record<string, unknown>): void {
+    this.edgeAttributes.add(attrs, this.edgeIds.length);
+    this.edgeIds.push(id);
+    this.sources.push(source);
+    this.targets.push(target);
+  }
+
+  async finish(control: PreparationControl): Promise<ColumnarGraphSnapshot> {
+    const nodeIndex = new Map<string, number>();
+    for (let i = 0; i < this.nodeIds.length; i++) {
+      if (!nodeIndex.has(this.nodeIds[i]!)) nodeIndex.set(this.nodeIds[i]!, i);
+    }
+    const source = new Uint32Array(this.edgeIds.length);
+    const target = new Uint32Array(this.edgeIds.length);
+    const edgeIds: string[] = [];
+    const counters: EdgePairCounters = new Map();
+    for (let i = 0; i < this.edgeIds.length; i++) {
+      await control.checkpoint();
+      const from = this.sources[i]!;
+      const to = this.targets[i]!;
+      const s = nodeIndex.get(from);
+      const t = nodeIndex.get(to);
+      if (s === undefined || t === undefined) {
+        throw new TypeError(`prepareGraphData: columnar edge ${i} has an unknown endpoint ${JSON.stringify(s === undefined ? from : to)}; supply its node or use output:'object' for core's dangling-edge diagnostics`);
+      }
+      source[i] = s;
+      target[i] = t;
+      edgeIds.push(this.edgeIds[i] ?? nextSynthesizedEdgeId(counters, from, to));
+    }
+    return {
+      kind: 'columnar',
+      datasetKey: control.options.datasetKey,
+      sourceRevision: control.options.sourceRevision,
+      bufferOwnership: 'borrowed',
+      nodes: { ids: ids(this.nodeIds), columns: this.nodeAttributes.finish(this.nodeIds.length), length: this.nodeIds.length },
+      edges: { ids: ids(edgeIds), source, target, columns: this.edgeAttributes.finish(edgeIds.length), length: edgeIds.length },
+    };
+  }
+}
diff --git a/packages/data/src/control.ts b/packages/data/src/control.ts
new file mode 100644
index 0000000..938b333
--- /dev/null
+++ b/packages/data/src/control.ts
@@ -0,0 +1,73 @@
+import { throwIfAborted } from './sources';
+import type { GraphPrepareAnyOptions, GraphPrepareProgress } from './types';
+
+/** One invocation owns all counters, including both node and edge sources. */
+export class PreparationControl {
+  private bytes = 0;
+  private nodes = 0;
+  private edges = 0;
+  private lastProgress = -Infinity;
+  private lastYield = Date.now();
+  private work = 0;
+
+  constructor(readonly options: GraphPrepareAnyOptions) {
+    if (typeof options.datasetKey !== 'string' || options.datasetKey === '') {
+      throw new TypeError('prepareGraphData: options.datasetKey must be a non-empty string');
+    }
+    if ((typeof options.sourceRevision !== 'string' && typeof options.sourceRevision !== 'number') ||
+        (typeof options.sourceRevision === 'number' && !Number.isFinite(options.sourceRevision))) {
+      throw new TypeError('prepareGraphData: options.sourceRevision must be a string or finite number');
+    }
+    for (const key of ['maxBytes', 'maxNodes', 'maxEdges'] as const) {
+      const limit = options[key];
+      if (limit !== undefined && (!Number.isSafeInteger(limit) || limit <= 0)) {
+        throw new TypeError(`prepareGraphData: ${key} must be a positive safe integer`);
+      }
+    }
+    if (options.output !== undefined && options.output !== 'object' && options.output !== 'columnar') {
+      throw new TypeError('prepareGraphData: output must be object or columnar');
+    }
+    this.check();
+  }
+
+  check(): void { throwIfAborted(this.options.signal); }
+
+  private bounded(next: number, key: 'maxBytes' | 'maxNodes' | 'maxEdges'): number {
+    this.check();
+    const limit = this.options[key];
+    if (!Number.isSafeInteger(next) || (limit !== undefined && next > limit)) {
+      throw new RangeError(`prepareGraphData: ${key} limit ${limit ?? Number.MAX_SAFE_INTEGER} exceeded (${next})`);
+    }
+    return next;
+  }
+
+  read(bytes: number): void {
+    this.bytes = this.bounded(this.bytes + bytes, 'maxBytes');
+    this.report('reading');
+  }
+
+  admit(role: 'nodes' | 'edges'): void {
+    if (role === 'nodes') this.nodes = this.bounded(this.nodes + 1, 'maxNodes');
+    else this.edges = this.bounded(this.edges + 1, 'maxEdges');
+    this.report('preparing');
+  }
+
+  /** Yield a task, not only a microtask, so browser cancellation can run. */
+  async checkpoint(): Promise<void> {
+    this.check();
+    if ((++this.work & 255) === 0 && Date.now() - this.lastYield >= 8) {
+      await new Promise<void>((resolve) => setTimeout(resolve, 0));
+      this.lastYield = Date.now();
+      this.check();
+    }
+  }
+
+  report(phase: GraphPrepareProgress['phase']): void {
+    this.check();
+    const now = Date.now();
+    if (phase !== 'complete' && now - this.lastProgress < 100) return;
+    this.lastProgress = now;
+    this.options.onProgress?.({ phase, bytes: this.bytes, nodes: this.nodes, edges: this.edges });
+    this.check();
+  }
+}
diff --git a/packages/data/src/csv.ts b/packages/data/src/csv.ts
index d655828..be4aa96 100644
--- a/packages/data/src/csv.ts
+++ b/packages/data/src/csv.ts
@@ -34,6 +34,7 @@ import { coerceNumeric } from '@modernrelay/orbit-core';
 import { EMPTY_ROW_TABLE, type RowTable } from './rowTable';
 import { byteChunks, throwIfAborted } from './sources';
 import type { GraphByteSource } from './types';
+import type { PreparationControl } from './control';
 
 export const SAMPLE_ROWS = 1000;
 
@@ -129,8 +130,9 @@ export async function csvTable(
   signal: AbortSignal | undefined,
   /** Columns exempt from numeric coercion (identity columns). */
   identityColumns: ReadonlySet<string>,
+  control?: PreparationControl,
 ): Promise<RowTable> {
-  const records = csvRecords(byteChunks(source, signal));
+  const records = csvRecords(byteChunks(source, signal, control));
   const iterator = records[Symbol.asyncIterator]();
   const head = await iterator.next();
   if (head.done) return EMPTY_ROW_TABLE;
@@ -142,6 +144,8 @@ export async function csvTable(
       const sample: (readonly string[])[] = [];
       let sampleDone = false;
       while (sample.length < SAMPLE_ROWS) {
+        await control?.checkpoint();
+        throwIfAborted(signal);
         const next = await iterator.next();
         if (next.done) {
           sampleDone = true;
@@ -183,6 +187,7 @@ export async function csvTable(
 
       // Pass 2: replay the sample, then keep streaming.
       for (const record of sample) {
+        throwIfAborted(signal);
         yield toRow(record);
       }
       if (!sampleDone) {
diff --git a/packages/data/src/document.ts b/packages/data/src/document.ts
index 8e3ded5..6498935 100644
--- a/packages/data/src/document.ts
+++ b/packages/data/src/document.ts
@@ -8,11 +8,13 @@
 import { EMPTY_ROW_TABLE, isPlainRowObject, type RowTable } from './rowTable';
 import { collectBytes } from './sources';
 import type { GraphByteSource, GraphColumnMapping } from './types';
+import type { PreparationControl } from './control';
 
 export async function documentTables(
   source: GraphByteSource,
   mapping: GraphColumnMapping,
   signal: AbortSignal | undefined,
+  control?: PreparationControl,
 ): Promise<{ nodes: RowTable; edges: RowTable }> {
   const paths = mapping.documentPaths;
   if (paths === undefined) {
@@ -21,7 +23,7 @@ export async function documentTables(
         '({ nodes, edges } dot-paths into the parsed object)',
     );
   }
-  const bytes = await collectBytes(source, signal);
+  const bytes = await collectBytes(source, signal, control);
   let parsed: unknown;
   try {
     parsed = JSON.parse(new TextDecoder().decode(bytes));
@@ -30,6 +32,7 @@ export async function documentTables(
       `prepareGraphData: document input is not valid JSON (${(cause as Error).message})`,
     );
   }
+  control?.check();
   if (!isPlainRowObject(parsed)) {
     throw new TypeError(
       'prepareGraphData: document input must parse to a single JSON object',
diff --git a/packages/data/src/index.ts b/packages/data/src/index.ts
index 2b8cda1..9c96d3c 100644
--- a/packages/data/src/index.ts
+++ b/packages/data/src/index.ts
@@ -13,6 +13,8 @@
  */
 
 export { prepareGraphData } from './prepare';
+export { previewCsv } from './preview';
+export type { CsvPreview, CsvPreviewOptions } from './preview';
 export {
   serializePrepared,
   loadPrepared,
@@ -28,7 +30,11 @@ export type {
   GraphColumnMapping,
   GraphPrepareFormat,
   GraphPrepareOptions,
+  GraphPrepareColumnarOptions,
+  GraphPrepareAnyOptions,
+  GraphPrepareProgress,
   ColumnSummary,
   PreparedGraph,
+  PreparedColumnarGraph,
   PreparedGraphSummaries,
 } from './types';
diff --git a/packages/data/src/parquet.ts b/packages/data/src/parquet.ts
index 1022dcc..e46345b 100644
--- a/packages/data/src/parquet.ts
+++ b/packages/data/src/parquet.ts
@@ -17,13 +17,17 @@
 
 import { normalizeJsonSafeValue } from './jsonSafe';
 
+import { PreparationControl } from './control';
 import { buildPrepared } from './builder';
 import { EMPTY_ROW_TABLE, isPlainRowObject, type RowTable } from './rowTable';
-import { collectBytes } from './sources';
+import { abortable, collectBytes, throwIfAborted } from './sources';
 import type {
   GraphByteSource,
   GraphColumnMapping,
   GraphPrepareOptions,
+  GraphPrepareAnyOptions,
+  GraphPrepareColumnarOptions,
+  PreparedColumnarGraph,
   PreparedGraph,
 } from './types';
 
@@ -61,39 +65,53 @@ async function loadHyparquetModule(): Promise<{ parquetReadObjects: ParquetReadO
   return { parquetReadObjects: parquetReadObjects as ParquetReadObjects };
 }
 
+export function prepareParquetGraphData<N = Record<string, unknown>, E = Record<string, unknown>>(
+  input: ParquetGraphPrepareInput, mapping: GraphColumnMapping, options: Omit<GraphPrepareColumnarOptions, 'format'>,
+): Promise<PreparedColumnarGraph<N, E>>;
+export function prepareParquetGraphData<N = Record<string, unknown>, E = Record<string, unknown>>(
+  input: ParquetGraphPrepareInput, mapping: GraphColumnMapping, options: Omit<GraphPrepareOptions, 'format'>,
+): Promise<PreparedGraph<N, E>>;
+export function prepareParquetGraphData<N = Record<string, unknown>, E = Record<string, unknown>>(
+  input: ParquetGraphPrepareInput, mapping: GraphColumnMapping, options: Omit<GraphPrepareAnyOptions, 'format'>,
+): Promise<PreparedGraph<N, E> | PreparedColumnarGraph<N, E>>;
 export async function prepareParquetGraphData<
   N = Record<string, unknown>,
   E = Record<string, unknown>,
 >(
   input: ParquetGraphPrepareInput,
   mapping: GraphColumnMapping,
-  options: Omit<GraphPrepareOptions, 'format'>,
-): Promise<PreparedGraph<N, E>> {
+  options: Omit<GraphPrepareAnyOptions, 'format'>,
+): Promise<PreparedGraph<N, E> | PreparedColumnarGraph<N, E>> {
+  const control = new PreparationControl(options as GraphPrepareAnyOptions);
   const hyparquet = await loadHyparquetModule();
   const signal = options.signal;
+  throwIfAborted(signal);
   const deriveNodes = 'deriveNodes' in input && input.deriveNodes === true;
-  const edgeTable = await parquetRowTable(input.edges, hyparquet, signal);
+  const edgeTable = await parquetRowTable(input.edges, hyparquet, signal, control);
   const nodeTable = deriveNodes
     ? null
-    : await parquetRowTable((input as { nodes: GraphByteSource }).nodes, hyparquet, signal);
+    : await parquetRowTable((input as { nodes: GraphByteSource }).nodes, hyparquet, signal, control);
   return (await buildPrepared({
     nodeTable,
     edgeTable,
     mapping,
     format: 'parquet',
-    options: { ...options, format: 'parquet' },
-  })) as PreparedGraph<N, E>;
+    options: { ...options, format: 'parquet' } as GraphPrepareAnyOptions,
+    control,
+  })) as PreparedGraph<N, E> | PreparedColumnarGraph<N, E>;
 }
 
 async function parquetRowTable(
   source: GraphByteSource,
   hyparquet: { parquetReadObjects: ParquetReadObjects },
   signal: AbortSignal | undefined,
+  control: PreparationControl,
 ): Promise<RowTable> {
-  const bytes = await collectBytes(source, signal);
+  const bytes = await collectBytes(source, signal, control);
   // collectBytes allocates an exact-size buffer, so `bytes.buffer` is the
   // whole file — the AsyncBuffer shape hyparquet expects.
-  const rows = await hyparquet.parquetReadObjects({ file: bytes.buffer as ArrayBuffer });
+  const rows = await abortable(hyparquet.parquetReadObjects({ file: bytes.buffer as ArrayBuffer }), signal);
+  throwIfAborted(signal);
   const first = rows[0];
   if (first === undefined) return EMPTY_ROW_TABLE;
   if (!isPlainRowObject(first)) {
@@ -106,6 +124,7 @@ async function parquetRowTable(
     columns,
     rows: (async function* () {
       for (const raw of rows) {
+        throwIfAborted(signal);
         const row: Record<string, unknown> = {};
         for (const key of Object.keys(raw)) {
           const value = raw[key];
@@ -118,6 +137,7 @@ async function parquetRowTable(
             configurable: true,
           });
         }
+        throwIfAborted(signal);
         yield row;
       }
     })(),
diff --git a/packages/data/src/prepare.ts b/packages/data/src/prepare.ts
index 00e729c..b627762 100644
--- a/packages/data/src/prepare.ts
+++ b/packages/data/src/prepare.ts
@@ -16,6 +16,7 @@
  * else 'csv' if any lane parsed CSV, else 'rows' (or 'json' for documents).
  */
 
+import { PreparationControl } from './control';
 import { buildPrepared } from './builder';
 import { csvTable } from './csv';
 import { documentTables } from './document';
@@ -26,18 +27,31 @@ import type {
   GraphColumnMapping,
   GraphPrepareInput,
   GraphPrepareOptions,
+  GraphPrepareAnyOptions,
+  GraphPrepareColumnarOptions,
+  PreparedColumnarGraph,
   GraphTabularSource,
   PreparedGraph,
 } from './types';
 
+export function prepareGraphData<N = Record<string, unknown>, E = Record<string, unknown>>(
+  input: GraphPrepareInput, mapping: GraphColumnMapping, options: GraphPrepareColumnarOptions,
+): Promise<PreparedColumnarGraph<N, E>>;
+export function prepareGraphData<N = Record<string, unknown>, E = Record<string, unknown>>(
+  input: GraphPrepareInput, mapping: GraphColumnMapping, options: GraphPrepareOptions,
+): Promise<PreparedGraph<N, E>>;
+export function prepareGraphData<N = Record<string, unknown>, E = Record<string, unknown>>(
+  input: GraphPrepareInput, mapping: GraphColumnMapping, options: GraphPrepareAnyOptions,
+): Promise<PreparedGraph<N, E> | PreparedColumnarGraph<N, E>>;
 export async function prepareGraphData<
   N = Record<string, unknown>,
   E = Record<string, unknown>,
 >(
   input: GraphPrepareInput,
   mapping: GraphColumnMapping,
-  options: GraphPrepareOptions,
-): Promise<PreparedGraph<N, E>> {
+  options: GraphPrepareAnyOptions,
+): Promise<PreparedGraph<N, E> | PreparedColumnarGraph<N, E>> {
+  const control = new PreparationControl(options);
   const { format, signal } = options;
   if (format === 'arrow' || format === 'parquet') {
     throw new TypeError(
@@ -53,14 +67,15 @@ export async function prepareGraphData<
         `prepareGraphData: a document input is valid only for JSON (got format '${format}')`,
       );
     }
-    const tables = await documentTables(input.document, mapping, signal);
+    const tables = await documentTables(input.document, mapping, signal, control);
     return (await buildPrepared({
       nodeTable: tables.nodes,
       edgeTable: tables.edges,
       mapping,
       format: 'json',
       options,
-    })) as PreparedGraph<N, E>;
+      control,
+    })) as PreparedGraph<N, E> | PreparedColumnarGraph<N, E>;
   }
   if (format === 'json') {
     throw new TypeError(
@@ -75,7 +90,7 @@ export async function prepareGraphData<
     ),
   );
   const lanes = { csv: false, rows: false };
-  const edgeTable = await resolveTabular(input.edges, options, edgeIdentity, 'edge', lanes);
+  const edgeTable = await resolveTabular(input.edges, options, edgeIdentity, 'edge', lanes, control);
   let nodeTable: RowTable | null = null;
   try {
     if (!deriveNodes) {
@@ -85,7 +100,7 @@ export async function prepareGraphData<
         );
       }
       const nodeIdentity = new Set(mapping.nodes === undefined ? [] : [mapping.nodes.id]);
-      nodeTable = await resolveTabular(input.nodes, options, nodeIdentity, 'node', lanes);
+      nodeTable = await resolveTabular(input.nodes, options, nodeIdentity, 'node', lanes, control);
     }
 
     const resolvedFormat = format ?? (lanes.csv ? 'csv' : 'rows');
@@ -95,7 +110,8 @@ export async function prepareGraphData<
       mapping,
       format: resolvedFormat,
       options,
-    })) as PreparedGraph<N, E>;
+      control,
+    })) as PreparedGraph<N, E> | PreparedColumnarGraph<N, E>;
   } catch (cause) {
     // The edge lane is opened first. If node-lane resolution fails before
     // buildPrepared takes ownership, release every already-peeked iterator.
@@ -111,10 +127,11 @@ export async function prepareGraphData<
 
 async function resolveTabular(
   source: GraphTabularSource,
-  options: GraphPrepareOptions,
+  options: GraphPrepareAnyOptions,
   identityColumns: ReadonlySet<string>,
   role: 'node' | 'edge',
   lanes: { csv: boolean; rows: boolean },
+  control: PreparationControl,
 ): Promise<RowTable> {
   const { format, signal } = options;
   if (Array.isArray(source)) {
@@ -133,23 +150,23 @@ async function resolveTabular(
       );
     }
     lanes.csv = true;
-    return csvTable(source, signal, identityColumns);
+    return csvTable(source, signal, identityColumns, control);
   }
   if (isAsyncIterable(source)) {
     if (format === 'csv') {
       lanes.csv = true;
-      return csvTable(source as AsyncIterable<Uint8Array>, signal, identityColumns);
+      return csvTable(source as AsyncIterable<Uint8Array>, signal, identityColumns, control);
     }
     if (format === 'rows') {
       lanes.rows = true;
       return rowsTable(source, signal, role);
     }
     // No format given: peek the first element to tell bytes from rows.
-    const { first, done, rest } = await peekAsyncIterable(source);
+    const { first, done, rest } = await peekAsyncIterable(source, signal);
     if (done) return EMPTY_ROW_TABLE;
     if (first instanceof Uint8Array) {
       lanes.csv = true;
-      return csvTable(rest as AsyncIterable<Uint8Array>, signal, identityColumns);
+      return csvTable(rest as AsyncIterable<Uint8Array>, signal, identityColumns, control);
     }
     lanes.rows = true;
     return rowsTable(rest, signal, role);
diff --git a/packages/data/src/preview.ts b/packages/data/src/preview.ts
new file mode 100644
index 0000000..22b5dac
--- /dev/null
+++ b/packages/data/src/preview.ts
@@ -0,0 +1,60 @@
+import { PreparationControl } from './control';
+import { csvRecords } from './csv';
+import { byteChunks } from './sources';
+import type { GraphByteSource } from './types';
+
+export interface CsvPreviewOptions {
+  signal?: AbortSignal;
+  /** Maximum bytes examined, default 256 KiB. A record exceeding it rejects. */
+  maxBytes?: number;
+  /** Maximum data records returned, default 5. */
+  maxRows?: number;
+}
+
+export interface CsvPreview {
+  columns: readonly string[];
+  /** Raw strings preserve identifiers and do not guess types from a short sample. */
+  rows: readonly Readonly<Record<string, string>>[];
+  /** True means the sample cap was reached; remaining input was not inspected. */
+  truncated: boolean;
+}
+
+export async function previewCsv(source: GraphByteSource, options: CsvPreviewOptions = {}): Promise<CsvPreview> {
+  const maxRows = options.maxRows ?? 5;
+  if (!Number.isSafeInteger(maxRows) || maxRows <= 0) throw new TypeError('previewCsv: maxRows must be a positive safe integer');
+  const maxBytes = options.maxBytes ?? 256 * 1024;
+  const control = new PreparationControl({ datasetKey: 'preview', sourceRevision: 0, maxBytes, ...(options.signal === undefined ? {} : { signal: options.signal }) });
+  // Subdivide large Blob/ArrayBuffer chunks before parsing. Stop as soon as
+  // the sample is ready instead of materializing an entire input chunk.
+  async function* chunks(): AsyncGenerator<Uint8Array> {
+    let read = 0;
+    for await (const chunk of byteChunks(source, options.signal)) {
+      for (let offset = 0; offset < chunk.byteLength;) {
+        const length = Math.min(chunk.byteLength - offset, 4096, Math.max(1, maxBytes - read));
+        control.read(length);
+        read += length;
+        yield chunk.subarray(offset, offset + length);
+        offset += length;
+      }
+    }
+  }
+  const records = csvRecords(chunks());
+  try {
+    const header = await records.next();
+    control.check();
+    if (header.done) return { columns: [], rows: [], truncated: false };
+    const columns = [...header.value];
+    const rows: Record<string, string>[] = [];
+    while (rows.length < maxRows) {
+      const record = await records.next();
+      control.check();
+      if (record.done) return { columns, rows, truncated: false };
+      rows.push(Object.fromEntries(columns.flatMap((name, index) =>
+        record.value[index] === undefined ? [] : [[name, record.value[index]!]],
+      )));
+    }
+    return { columns, rows, truncated: true };
+  } finally {
+    await records.return(undefined);
+  }
+}
diff --git a/packages/data/src/rows.ts b/packages/data/src/rows.ts
index 30d82d4..7d3deb8 100644
--- a/packages/data/src/rows.ts
+++ b/packages/data/src/rows.ts
@@ -14,7 +14,7 @@ export async function rowsTable(
   role: string,
 ): Promise<RowTable> {
   const stream = rowStream(source, signal);
-  const { first, done, rest, close } = await peekAsyncIterable(stream);
+  const { first, done, rest, close } = await peekAsyncIterable(stream, signal);
   if (done) return EMPTY_ROW_TABLE;
   if (!isPlainRowObject(first)) {
     // Close the underlying source before reporting: the replay
diff --git a/packages/data/src/sources.ts b/packages/data/src/sources.ts
index 9bd3dea..84e5b1b 100644
--- a/packages/data/src/sources.ts
+++ b/packages/data/src/sources.ts
@@ -11,13 +11,40 @@
  * pushed back, so adapters observe the full stream.
  */
 
+import type { PreparationControl } from './control';
+
 export function throwIfAborted(signal: AbortSignal | undefined): void {
   if (signal?.aborted) {
-    if (typeof signal.throwIfAborted === 'function') signal.throwIfAborted();
-    throw new Error('prepareGraphData: aborted');
+    if (signal.reason instanceof Error && signal.reason.name === 'AbortError') throw signal.reason;
+    throw new DOMException('prepareGraphData: aborted', 'AbortError');
   }
 }
 
+/** Stop waiting on caller I/O when cancelled; late settlement is still observed. */
+export async function abortable<T>(pending: PromiseLike<T>, signal: AbortSignal | undefined): Promise<T> {
+  if (signal === undefined) return pending;
+  return new Promise<T>((resolve, reject) => {
+    const cancel = (): void => {
+      signal.removeEventListener('abort', cancel);
+      try { throwIfAborted(signal); } catch (error) { reject(error); }
+    };
+    signal.addEventListener('abort', cancel, { once: true });
+    Promise.resolve(pending).then(
+      (value) => { signal.removeEventListener('abort', cancel); resolve(value); },
+      (error) => { signal.removeEventListener('abort', cancel); reject(error); },
+    );
+    if (signal.aborted) cancel();
+  });
+}
+
+async function closeAfterFailure(close: () => Promise<void>, signal?: AbortSignal): Promise<void> {
+  if (signal?.aborted) {
+    // An async generator can queue return() behind an uncooperative next().
+    // Request teardown but do not make cancellation wait for that foreign I/O.
+    void close().catch(() => {});
+  } else await close();
+}
+
 export function isBlob(value: unknown): value is Blob {
   return typeof Blob !== 'undefined' && value instanceof Blob;
 }
@@ -50,14 +77,15 @@ function iteratorCloseOnce<T>(iterator: AsyncIterator<T>): () => Promise<void> {
  * guarantees `return()` on early exit *and* when `next()` rejects. Native
  * `for await` does not close an iterator whose own `next()` rejects.
  */
-async function* closingIterable<T>(source: AsyncIterable<T>): AsyncGenerator<T> {
+async function* closingIterable<T>(source: AsyncIterable<T>, signal?: AbortSignal): AsyncGenerator<T> {
   const iterator = source[Symbol.asyncIterator]();
   const close = iteratorCloseOnce(iterator);
   let exhausted = false;
   let failed = false;
   try {
     while (true) {
-      const next = await iterator.next();
+      throwIfAborted(signal);
+      const next = await abortable(iterator.next(), signal);
       if (next.done) {
         exhausted = true;
         return;
@@ -70,7 +98,7 @@ async function* closingIterable<T>(source: AsyncIterable<T>): AsyncGenerator<T>
   } finally {
     if (!exhausted) {
       try {
-        await close();
+        await closeAfterFailure(close, signal);
       } catch (closeCause) {
         // A failed read/consumer operation is the useful outcome. Teardown
         // failure is surfaced only when there is no earlier failure to mask.
@@ -86,6 +114,7 @@ async function* closingIterable<T>(source: AsyncIterable<T>): AsyncGenerator<T>
  * of reporting malformed row zero. */
 export async function peekAsyncIterable(
   source: AsyncIterable<unknown>,
+  signal?: AbortSignal,
 ): Promise<{
   first: unknown | undefined;
   done: boolean;
@@ -99,10 +128,11 @@ export async function peekAsyncIterable(
   const close = iteratorCloseOnce(iterator);
   let head: IteratorResult<unknown>;
   try {
-    head = await iterator.next();
+    throwIfAborted(signal);
+    head = await abortable(iterator.next(), signal);
   } catch (cause) {
     try {
-      await close();
+      await closeAfterFailure(close, signal);
     } catch {
       // Preserve the iterator's read failure; teardown is best-effort here.
     }
@@ -116,7 +146,8 @@ export async function peekAsyncIterable(
       if (!head.done) yield head.value;
       // Delegate to the original iterator (not the iterable) so nothing is lost.
       while (true) {
-        const next = await iterator.next();
+        throwIfAborted(signal);
+        const next = await abortable(iterator.next(), signal);
         if (next.done) {
           exhausted = true;
           return;
@@ -132,7 +163,7 @@ export async function peekAsyncIterable(
       // return. A rejected next() also needs explicit teardown.
       if (!exhausted) {
         try {
-          await close();
+          await closeAfterFailure(close, signal);
         } catch (closeCause) {
           if (!failed) throw closeCause;
         }
@@ -151,34 +182,30 @@ export async function peekAsyncIterable(
 export function byteChunks(
   source: Blob | ArrayBuffer | AsyncIterable<Uint8Array>,
   signal: AbortSignal | undefined,
+  control?: PreparationControl,
 ): AsyncIterable<Uint8Array> {
-  if (source instanceof ArrayBuffer) {
-    const chunk = new Uint8Array(source);
-    return (async function* () {
-      throwIfAborted(signal);
-      yield chunk;
-    })();
-  }
-  if (isBlob(source)) {
-    return (async function* () {
-      // Blob.stream is a web ReadableStream; async-iterable in Node ≥18.
-      const stream = source.stream() as unknown as AsyncIterable<Uint8Array>;
-      for await (const chunk of closingIterable(stream)) {
-        throwIfAborted(signal);
-        yield chunk;
-      }
-    })();
+  async function* rawChunks(): AsyncGenerator<Uint8Array> {
+    throwIfAborted(signal);
+    if (source instanceof ArrayBuffer) { yield new Uint8Array(source); return; }
+    const stream = isBlob(source)
+      ? source.stream() as unknown as AsyncIterable<Uint8Array>
+      : source;
+    yield* closingIterable(stream, signal);
   }
   return (async function* () {
-    for await (const chunk of closingIterable(source)) {
+    for await (const chunk of rawChunks()) {
       throwIfAborted(signal);
-      if (!(chunk instanceof Uint8Array)) {
-        throw new TypeError(
-          'prepareGraphData: byte sources must yield Uint8Array chunks',
-        );
+      if (!(chunk instanceof Uint8Array)) throw new TypeError('prepareGraphData: byte sources must yield Uint8Array chunks');
+      // Cap parser work per chunk even for an already-resident ArrayBuffer.
+      for (let offset = 0; offset < chunk.byteLength; offset += 64 * 1024) {
+        throwIfAborted(signal);
+        const slice = chunk.subarray(offset, Math.min(chunk.byteLength, offset + 64 * 1024));
+        control?.read(slice.byteLength);
+        yield slice;
+        await control?.checkpoint();
       }
-      yield chunk;
     }
+    throwIfAborted(signal);
   })();
 }
 
@@ -186,13 +213,15 @@ export function byteChunks(
 export async function collectBytes(
   source: Blob | ArrayBuffer | AsyncIterable<Uint8Array>,
   signal: AbortSignal | undefined,
+  control?: PreparationControl,
 ): Promise<Uint8Array> {
   const chunks: Uint8Array[] = [];
   let total = 0;
-  for await (const chunk of byteChunks(source, signal)) {
+  for await (const chunk of byteChunks(source, signal, control)) {
     chunks.push(chunk);
     total += chunk.byteLength;
   }
+  throwIfAborted(signal);
   const out = new Uint8Array(total);
   let offset = 0;
   for (const chunk of chunks) {
@@ -218,7 +247,7 @@ export function rowStream(
   }
   if (isAsyncIterable(source)) {
     return (async function* () {
-      for await (const row of closingIterable(source)) {
+      for await (const row of closingIterable(source, signal)) {
         throwIfAborted(signal);
         yield row;
       }
diff --git a/packages/data/src/types.ts b/packages/data/src/types.ts
index ca7cb5d..b124d24 100644
--- a/packages/data/src/types.ts
+++ b/packages/data/src/types.ts
@@ -6,14 +6,11 @@
  * supplied bytes/streams, never fetches a URL, and remains Node-import-safe
  * without ambient browser globals.
  *
- * v0.9 TRIM (documented): core has no `ColumnarGraphSnapshot` yet — the
- * columnar lane remains separate, so the prepared artifact wraps an OBJECT
- * `GraphSnapshot` plus summaries and fingerprints. The serialized artifact
- * format is versioned (`formatVersion`, see artifact.ts) so the columnar
- * upgrade slots in without breaking stored artifacts.
+ * Object snapshots remain the default and the serialized v1 artifact format.
+ * Opt-in columnar preparation owns its buffers and uses core's columnar lane.
  */
 
-import type { GraphSnapshot } from '@modernrelay/orbit-core';
+import type { ColumnarGraphSnapshot, GraphSnapshot } from '@modernrelay/orbit-core';
 
 // ---------------------------------------------------------------------------
 // Input sources.
@@ -49,6 +46,34 @@ export interface GraphPrepareOptions {
   sourceRevision: string | number;
   format?: GraphPrepareFormat;
   signal?: AbortSignal;
+  /** Input bytes across byte sources; rows and existing Arrow tables have no wire bytes. */
+  maxBytes?: number;
+  /** Admitted rows, including derived unique nodes; duplicates count as rows. */
+  maxNodes?: number;
+  maxEdges?: number;
+  /** At most one notification per 100ms, plus the final completion. */
+  onProgress?: (progress: GraphPrepareProgress) => void;
+  output?: 'object';
+}
+
+export interface GraphPrepareProgress {
+  phase: 'reading' | 'preparing' | 'complete';
+  bytes: number;
+  nodes: number;
+  edges: number;
+}
+
+export interface GraphPrepareColumnarOptions extends Omit<GraphPrepareOptions, 'output'> {
+  output: 'columnar';
+}
+
+export type GraphPrepareAnyOptions = GraphPrepareOptions | GraphPrepareColumnarOptions;
+
+export interface PreparedColumnarGraph<N = Record<string, unknown>, E = Record<string, unknown>> {
+  /** Fresh owned buffers, marked borrowed for repeatable admission; inputs are never detached. */
+  snapshot: ColumnarGraphSnapshot<N, E>;
+  summaries: PreparedGraphSummaries;
+  mappingFingerprint: string;
 }
 
 // ---------------------------------------------------------------------------
@@ -93,7 +118,7 @@ export interface PreparedGraph<
   N = Record<string, unknown>,
   E = Record<string, unknown>,
 > {
-  /** v0.9 object-lane snapshot (see the trim note at the top of this file). */
+  /** Default object snapshot; accepted by the v1 artifact serializer. */
   snapshot: GraphSnapshot<N, E>;
   summaries: PreparedGraphSummaries;
   /** fnv-1a-64 hex over canonical-JSON(mapping) + format + the ADMITTED
diff --git a/packages/data/test/columnar-preparation.test.ts b/packages/data/test/columnar-preparation.test.ts
new file mode 100644
index 0000000..bec17e0
--- /dev/null
+++ b/packages/data/test/columnar-preparation.test.ts
@@ -0,0 +1,124 @@
+import { readFileSync } from 'node:fs';
+import { tableFromArrays, tableToIPC } from 'apache-arrow';
+import { describe, expect, expectTypeOf, it } from 'vitest';
+import { columnarArrayBuffers, materializeColumnarSnapshot, validateColumnarStructure, validateSnapshot } from '@modernrelay/orbit-core';
+import type { GraphSnapshot } from '@modernrelay/orbit-core';
+import { prepareGraphData, serializePrepared, loadPrepared } from '../src/index';
+import type { PreparedColumnarGraph, PreparedGraph } from '../src/index';
+import { prepareArrowGraphData } from '../src/arrow';
+import { prepareParquetGraphData } from '../src/parquet';
+import {
+  PARITY_MAPPING as mapping, PARITY_OPTIONS as options, PARITY_NODE_ROWS, PARITY_EDGE_ROWS,
+  PARITY_NODES_CSV, PARITY_EDGES_CSV, PARITY_DOCUMENT,
+} from './helpers';
+
+const bytes = (text: string): ArrayBuffer => new TextEncoder().encode(text).buffer as ArrayBuffer;
+
+/** Columnar null bits intentionally normalize absent attrs into explicit null. */
+function normalizedObject(prepared: PreparedGraph): GraphSnapshot {
+  const fill = (attrs: Record<string, unknown> | undefined, names: string[]) =>
+    Object.fromEntries(names.map((name) => [name, attrs?.[name] ?? null]));
+  return {
+    ...prepared.snapshot,
+    nodes: prepared.snapshot.nodes.map((row) => ({ ...row, attrs: fill(row.attrs, Object.keys(prepared.summaries.nodes)) })),
+    edges: prepared.snapshot.edges.map((row) => ({ ...row, attrs: fill(row.attrs, Object.keys(prepared.summaries.edges)) })),
+  };
+}
+
+function assertParity(object: PreparedGraph, columnar: PreparedColumnarGraph): void {
+  expect(validateColumnarStructure(columnar.snapshot)).toEqual([]);
+  const decoded = materializeColumnarSnapshot(columnar.snapshot);
+  const expected = validateSnapshot(normalizedObject(object));
+  const actual = validateSnapshot(decoded);
+  expect(actual.nodes).toEqual(expected.nodes);
+  expect(actual.edges).toEqual(expected.edges);
+  expect(columnar.summaries).toEqual(object.summaries);
+  expect(columnar.mappingFingerprint).toBe(object.mappingFingerprint);
+}
+
+describe('opt-in columnar preparation', () => {
+  it.each(['rows', 'csv', 'json'] as const)('matches object values, identities and summaries for %s', async (format) => {
+    const input = format === 'rows' ? { nodes: PARITY_NODE_ROWS, edges: PARITY_EDGE_ROWS }
+      : format === 'csv' ? { nodes: bytes(PARITY_NODES_CSV), edges: bytes(PARITY_EDGES_CSV) }
+      : { document: bytes(PARITY_DOCUMENT) };
+    const selected = { ...mapping, ...(format === 'json' ? { documentPaths: { nodes: 'graph.nodes', edges: 'graph.links' } } : {}) };
+    const object = await prepareGraphData(input, selected, { ...options, format });
+    const columnar = await prepareGraphData(input, selected, { ...options, format, output: 'columnar' });
+    expectTypeOf(object).toEqualTypeOf<PreparedGraph>();
+    expectTypeOf(columnar).toEqualTypeOf<PreparedColumnarGraph>();
+    assertParity(object, columnar);
+    expect(loadPrepared(serializePrepared(object))).toEqual(object);
+  });
+
+  it('supports real Arrow IPC and tables without borrowing or detaching source buffers', async () => {
+    const nodes = tableFromArrays({ id: ['a', 'b'], score: [1, 2], active: [true, false], empty: [null, null] });
+    const edgeTable = tableFromArrays({ source: ['a', 'b'], target: ['b', 'a'], kind: ['x', 'y'] });
+    const wire = tableToIPC(edgeTable);
+    const edgeBytes = wire.buffer.slice(wire.byteOffset, wire.byteOffset + wire.byteLength) as ArrayBuffer;
+    const input = { nodes, edges: edgeBytes };
+    const object = await prepareArrowGraphData(input, mapping, options);
+    const columnar = await prepareArrowGraphData(input, mapping, { ...options, output: 'columnar' });
+    assertParity(object, columnar);
+    expect(columnar.snapshot.bufferOwnership).toBe('borrowed');
+    const copied = structuredClone(columnar.snapshot, { transfer: columnarArrayBuffers(columnar.snapshot) });
+    expect(validateColumnarStructure(copied)).toEqual([]);
+    expect(edgeBytes.byteLength).toBe(wire.byteLength);
+    expect(nodes.getChild('score')?.get(0)).toBe(1);
+  });
+
+  it('supports real Parquet fixtures with the same summaries and synthesized edge IDs', async () => {
+    const fixture = (name: string) => {
+      const data = readFileSync(new URL(`./fixtures/parity-${name}.parquet`, import.meta.url));
+      return data.buffer.slice(data.byteOffset, data.byteOffset + data.byteLength) as ArrayBuffer;
+    };
+    const input = { nodes: fixture('nodes'), edges: fixture('edges') };
+    assertParity(await prepareParquetGraphData(input, mapping, options),
+      await prepareParquetGraphData(input, mapping, { ...options, output: 'columnar' }));
+  });
+
+  it('preserves collision-safe synthesized IDs, explicit IDs, parallel edges and duplicate node semantics', async () => {
+    const input = {
+      nodes: [{ id: 'a→b' }, { id: 'c#0' }, { id: 'a→b' }],
+      edges: [
+        { source: 'a→b', target: 'c#0' }, { source: 'a→b', target: 'c#0' },
+        { id: 'explicit', source: 'a→b', target: 'c#0' },
+      ],
+    };
+    assertParity(await prepareGraphData(input, mapping, options),
+      await prepareGraphData(input, mapping, { ...options, output: 'columnar' }));
+  });
+
+  it('handles derived nodes, empty inputs, late fields, null masks and selected attributes', async () => {
+    const input = { edges: [
+      { source: 'a', target: 'b', score: null },
+      { source: 'b', target: 'c', score: 3, later: true },
+      { source: 'c', target: 'a', score: null, later: false },
+    ], deriveNodes: true as const };
+    const selected = { edges: { source: 'source', target: 'target', includeFields: ['score', 'later'] } };
+    const result = await prepareGraphData(input, selected, { ...options, output: 'columnar' });
+    assertParity(await prepareGraphData(input, selected, options), result);
+    expect(result.snapshot.edges.columns.score).toMatchObject({ kind: 'f64', nulls: new Uint8Array([1, 0, 1]) });
+    expect(result.snapshot.edges.columns.later).toMatchObject({ kind: 'bool', data: new Uint8Array([0, 1, 0]), nulls: new Uint8Array([1, 0, 0]) });
+    const empty = await prepareGraphData({ nodes: [], edges: [] }, mapping, { ...options, output: 'columnar' });
+    expect(validateColumnarStructure(empty.snapshot)).toEqual([]);
+  });
+
+  it.each([
+    [{ id: 'a', attr: { nested: 1 } }], [{ id: 'a', attr: ['x'] }],
+    [{ id: 'a', attr: '1' }, { id: 'b', attr: 1 }],
+    [JSON.parse('{"id":"a","__proto__":3}') as Record<string, unknown>],
+  ].map((nodes) => ({ nodes })))('rejects unrepresentable attributes with an explicit object-output remedy', async ({ nodes }) => {
+    await expect(prepareGraphData({ nodes, edges: [] }, mapping, { ...options, output: 'columnar' })).rejects.toThrow(/output:'object'/);
+  });
+
+  it('rejects missing endpoints instead of emitting corrupt typed indices', async () => {
+    await expect(prepareGraphData({ nodes: [{ id: 'a' }], edges: [{ source: 'a', target: 'missing' }] }, mapping,
+      { ...options, output: 'columnar' })).rejects.toThrow(/unknown endpoint.*missing/);
+  });
+
+  it('rejects columnar data at the v1 artifact boundary for JavaScript callers too', async () => {
+    const prepared = await prepareGraphData({ nodes: [], edges: [] }, mapping, { ...options, output: 'columnar' });
+    // @ts-expect-error The v1 artifact API intentionally accepts object output only.
+    expect(() => serializePrepared(prepared)).toThrow(/v1 artifacts require output:'object'/);
+  });
+});
diff --git a/packages/data/test/load-control.test.ts b/packages/data/test/load-control.test.ts
new file mode 100644
index 0000000..5edc259
--- /dev/null
+++ b/packages/data/test/load-control.test.ts
@@ -0,0 +1,162 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { prepareGraphData, previewCsv } from '../src/index';
+import type { GraphPrepareProgress } from '../src/index';
+import { _internals, prepareParquetGraphData } from '../src/parquet';
+
+const mapping = { nodes: { id: 'id' }, edges: { source: 'source', target: 'target' } };
+const options = { datasetKey: 'control', sourceRevision: 1 };
+const bytes = (text: string): ArrayBuffer => new TextEncoder().encode(text).buffer as ArrayBuffer;
+const realImport = _internals.importHyparquet;
+afterEach(() => { _internals.importHyparquet = realImport; vi.restoreAllMocks(); });
+
+describe('preparation cancellation and budgets', () => {
+  it('rejects cancellation during Parquet decoding, including an empty decoded table', async () => {
+    for (const rows of [[], [{ source: 'a', target: 'b' }]]) {
+      const controller = new AbortController();
+      _internals.importHyparquet = async () => ({ parquetReadObjects: async () => {
+        controller.abort();
+        return rows;
+      } });
+      await expect(prepareParquetGraphData({ edges: new ArrayBuffer(0), deriveNodes: true }, mapping,
+        { ...options, signal: controller.signal })).rejects.toMatchObject({ name: 'AbortError' });
+    }
+  });
+
+  it('checks Parquet cancellation again while rows are normalized', async () => {
+    const controller = new AbortController();
+    let secondRead = false;
+    _internals.importHyparquet = async () => ({ parquetReadObjects: async () => [
+      { source: 'a', get target() { controller.abort('cancelled'); return 'b'; } },
+      { get source() { secondRead = true; return 'b'; }, target: 'c' },
+    ] });
+    await expect(prepareParquetGraphData({ edges: new ArrayBuffer(0), deriveNodes: true }, mapping,
+      { ...options, signal: controller.signal })).rejects.toMatchObject({ name: 'AbortError' });
+    expect(secondRead).toBe(false);
+  });
+
+  it('does not wait for a stalled decoder or source after cancellation', async () => {
+    const decoderController = new AbortController();
+    _internals.importHyparquet = async () => ({ parquetReadObjects: () => {
+      queueMicrotask(() => decoderController.abort());
+      return new Promise(() => {});
+    } });
+    await expect(prepareParquetGraphData({ edges: new ArrayBuffer(0), deriveNodes: true }, mapping,
+      { ...options, signal: decoderController.signal })).rejects.toMatchObject({ name: 'AbortError' });
+
+    const controller = new AbortController();
+    const close = vi.fn(async () => ({ done: true as const, value: undefined }));
+    const source: AsyncIterable<unknown> = { [Symbol.asyncIterator]: () => ({
+      next: () => {
+        queueMicrotask(() => controller.abort());
+        return new Promise(() => {});
+      },
+      return: close,
+    }) };
+    await expect(prepareGraphData({ edges: source, deriveNodes: true }, mapping,
+      { ...options, signal: controller.signal })).rejects.toMatchObject({ name: 'AbortError' });
+    expect(close).toHaveBeenCalledOnce();
+  });
+
+  it('yields a task so a timer can cancel resident row input and closes its iterator', async () => {
+    const controller = new AbortController();
+    let seen = 0;
+    let closed = false;
+    async function* edges() {
+      try {
+        for (let i = 0; i < 100_000; i++) { seen++; yield { source: 'a', target: 'b' }; }
+      } finally { closed = true; }
+    }
+    const timer = setTimeout(() => controller.abort(), 0);
+    try {
+      await expect(prepareGraphData({ edges: edges(), deriveNodes: true }, mapping,
+        { ...options, signal: controller.signal })).rejects.toMatchObject({ name: 'AbortError' });
+      expect(seen).toBeLessThan(100_000);
+      expect(closed).toBe(true);
+    } finally { clearTimeout(timer); }
+  });
+
+  it('enforces combined byte budgets and closes a source when the next chunk exceeds the cap', async () => {
+    let closed = false;
+    async function* edges() {
+      try { yield new Uint8Array(bytes('source,target\n')); yield new Uint8Array(bytes('a,b\n')); }
+      finally { closed = true; }
+    }
+    await expect(prepareGraphData({ edges: edges(), deriveNodes: true }, mapping,
+      { ...options, format: 'csv', maxBytes: 14 })).rejects.toThrow(/maxBytes.*exceeded/);
+    expect(closed).toBe(true);
+    await expect(prepareGraphData({ nodes: bytes('id\na\n'), edges: bytes('source,target\na,a\n') }, mapping,
+      { ...options, maxBytes: 20 })).rejects.toThrow(/maxBytes.*exceeded/);
+  });
+
+  it('counts derived unique nodes and actual edge rows before retaining an over-limit row', async () => {
+    const input = { edges: [{ source: 'a', target: 'b' }, { source: 'a', target: 'b' }], deriveNodes: true as const };
+    await expect(prepareGraphData(input, mapping, { ...options, maxNodes: 2, maxEdges: 2 })).resolves.toMatchObject({ snapshot: { nodes: [{ id: 'a' }, { id: 'b' }] } });
+    await expect(prepareGraphData(input, mapping, { ...options, maxNodes: 1 })).rejects.toThrow(/maxNodes/);
+    await expect(prepareGraphData(input, mapping, { ...options, maxEdges: 1 })).rejects.toThrow(/maxEdges/);
+    await expect(prepareGraphData({ nodes: [{ id: 'a' }, { id: 'a' }], edges: [] }, mapping,
+      { ...options, maxNodes: 1 })).rejects.toThrow(/maxNodes/);
+  });
+
+  it('validates budgets before opening an input', async () => {
+    const open = vi.fn();
+    const source = { [Symbol.asyncIterator]() { open(); throw new Error('opened'); } };
+    for (const maxBytes of [0, -1, Infinity, NaN, 1.5]) {
+      await expect(prepareGraphData({ edges: source, deriveNodes: true }, mapping,
+        { ...options, maxBytes })).rejects.toThrow(/positive safe integer/);
+    }
+    expect(open).not.toHaveBeenCalled();
+  });
+
+  it('throttles progress but always reports exact completed totals', async () => {
+    vi.spyOn(Date, 'now').mockReturnValue(1000);
+    const progress: GraphPrepareProgress[] = [];
+    const csv = 'source,target\n' + 'a,b\n'.repeat(2000);
+    await prepareGraphData({ edges: bytes(csv), deriveNodes: true }, mapping,
+      { ...options, onProgress: (p) => progress.push(p) });
+    expect(progress).toHaveLength(2);
+    expect(progress[0]?.phase).toBe('reading');
+    expect(progress[1]).toEqual({ phase: 'complete', bytes: new TextEncoder().encode(csv).byteLength, nodes: 2, edges: 2000 });
+  });
+
+  it('closes inputs when a progress callback cancels the operation', async () => {
+    const controller = new AbortController();
+    let closed = false;
+    async function* edges() { try { yield { source: 'a', target: 'b' }; } finally { closed = true; } }
+    await expect(prepareGraphData({ edges: edges(), deriveNodes: true }, mapping,
+      { ...options, signal: controller.signal, onProgress: () => controller.abort() })).rejects.toMatchObject({ name: 'AbortError' });
+    expect(closed).toBe(true);
+  });
+});
+
+describe('bounded CSV preview', () => {
+  it('reuses quoted CSV parsing, keeps raw identifiers and closes after the sample', async () => {
+    let readTail = false;
+    let closed = false;
+    async function* source() {
+      try {
+        yield new Uint8Array(bytes('source,target,label\n01,2,"line\nwith ""quote"""\n'));
+        readTail = true;
+        yield new Uint8Array(bytes('3,4,extra\n'));
+      } finally { closed = true; }
+    }
+    expect(await previewCsv(source(), { maxRows: 1 })).toEqual({
+      columns: ['source', 'target', 'label'],
+      rows: [{ source: '01', target: '2', label: 'line\nwith "quote"' }], truncated: true,
+    });
+    expect(readTail).toBe(false);
+    expect(closed).toBe(true);
+  });
+
+  it('previews the prefix of a large resident file without requiring its entire size budget', async () => {
+    const value = await previewCsv(bytes('s,t\na,b\n' + 'x,y\n'.repeat(100_000)), { maxRows: 1, maxBytes: 20 });
+    expect(value.rows).toEqual([{ s: 'a', t: 'b' }]);
+  });
+
+  it('rejects an over-budget quoted record and closes its source', async () => {
+    let closed = false;
+    async function* source() { try { yield new Uint8Array(bytes('a,b\n"' + 'x'.repeat(100) + '",b\n')); } finally { closed = true; } }
+    await expect(previewCsv(source(), { maxBytes: 10 })).rejects.toThrow(/maxBytes/);
+    expect(closed).toBe(true);
+    await expect(previewCsv(bytes('a,b\n"unfinished'))).rejects.toThrow(/unterminated/);
+  });
+});
diff --git a/packages/engine-cosmos/README.md b/packages/engine-cosmos/README.md
index 6190b93..179f266 100644
--- a/packages/engine-cosmos/README.md
+++ b/packages/engine-cosmos/README.md
@@ -40,7 +40,7 @@ readback timings are diagnostic, not a qualified performance comparison:
 | `link-picking` | ✅ pass | Native `onLinkClick`/`onLinkMouseOver` deliver correct link indices; ~4 px perpendicular tolerance on a 2 px link. **Flipped:** the adapter now reports `capabilities.linkPicking: true` and wires `onLinkClick`/`onLinkMouseOver`/`onLinkMouseOut` to the host events, backed by the headful probe. |
 | `nan-tombstones` | ✅ pass | NaN'd points escape hit-testing, incident links vanish, `fitView` ignores tombstoned slots. |
 | `native-pinning` | ✅ pass | `setPinnedPoints` excludes points from force integration; `[]`/repeat calls are idempotent. |
-| `tracked-positions` | ✅ semantics; ⚠️ timing diagnostic | Packing order and last-call-replaces semantics pass. The diagnostic run exceeded the probe's synchronous readback budget; no new performance claim is made without repeated, variance-qualified runs. Orbit keeps its existing label cadence and does not opt into the new nonblocking tracked-map API. |
+| `tracked-positions` | ✅ semantics; ⚠️ timing diagnostic | Packing order and last-call-replaces semantics pass. The diagnostic run exceeded the probe's synchronous readback budget; no new performance claim is made without repeated, variance-qualified runs. Orbit now uses the asynchronous full-position snapshot API for its bounded shared overlay cache; this does not change the synchronous tracked-map probe result. |
 | `position-snapshots` | ✅ pass | Flat `Float32Array` reads preserve NaN tombstones and remain independent across caller mutations, subsequent reads and roster replacement. |
 | `quiescence` | ✅ pass | On-demand rendering: 0 idle frames AND 0 rAF registrations per 750 ms at rest. Picking remains live at rest, drag release renders its final frame, and a `render()` + same-tick capture reads valid pixels (the stale-wake micro-cases). |
 | `context-loss` | ⚠️ fail (by design) | `lost`/`restored` events surface, but no combination of buffer/config replay revives rendering after `restoreContext()` — only a full `Graph` destroy + re-create recovers. This validates the adapter's recreate-on-restore protocol: `CosmosEngine` rebuilds the Graph in the same container and the core replays the scene. |
@@ -75,8 +75,31 @@ the intermediate boxed `number[]` and conversion back to `Float32Array`.
 Callers may overlay pinned coordinates without changing subsequent reads;
 later reads and roster updates leave earlier snapshots intact, and NaN
 tombstones remain NaN. The `position-snapshots` GPU probe checks that ownership
-contract against the real engine. The GPU read remains synchronous; this
-change does not introduce asynchronous readback or a new overlay scheduler.
+contract against the real engine. Event-time reads remain synchronous.
+
+`getPositionsAsync()` uses Cosmos 3.5.1's `getPointPositionsAsync()` without
+an output buffer and discards copies from a retired Graph or lost context.
+Core shares these snapshots between labels and the minimap. Scenes of at most
+10,000 nodes use async copies at most 10 Hz with labels enabled (2 Hz for an
+overview-only consumer), with one copy in flight while the simulation runs.
+Larger scenes retain the existing 2 Hz synchronous read path: repeated local
+L-tier profiling found the async staging/copy path added frame-time overhead,
+even at 2 Hz. The node threshold is a conservative readback budget, not a
+claim that the async path is faster on every smaller graph or GPU.
+Core checks the mount session, scene,
+desired/applied render revision, pins and position generation before admission;
+settle/drag/pause snapshots supersede older copies. Engines without the async
+method retain the bounded 2 Hz synchronous fallback. No sampling loop runs at
+rest, and no additional rAF scheduler is introduced. This is a cadence bound,
+not a measured frame-rate improvement; full readback still transfers O(n)
+positions and the CPU minimap raster remains O(n).
+
+The [2026-10-24 L-tier comparison](./benchmarks/position-cache-2026-10-24.json)
+records three headful runs per variant on Apple M5 Pro / Chromium 156. The
+final policy measured 42.11 ms frame p95 (1.0% CV), versus 41.81 ms on the
+previous commit; **both fail the existing 33 ms budget**. Async full-buffer
+reads at 10 Hz measured 56.56 ms, so that policy was rejected for large scenes.
+The final run recorded zero idle rAF registrations in all three parked windows.
 
 ## Overlay & toolbar surface
 
diff --git a/packages/engine-cosmos/benchmarks/position-cache-2026-10-24.json b/packages/engine-cosmos/benchmarks/position-cache-2026-10-24.json
new file mode 100644
index 0000000..011dee1
--- /dev/null
+++ b/packages/engine-cosmos/benchmarks/position-cache-2026-10-24.json
@@ -0,0 +1,276 @@
+{
+  "benchmark": "Live overlay position cache / L-tier frame-time comparison",
+  "baselineRevision": "d186a1f3f46dd907e1d2644d1c5df141bbbaf524",
+  "command": "node scripts/perf-lite.mjs --tier L --runs 3 --enforce",
+  "decision": "Keep 2 Hz synchronous full-buffer reads above 10,000 nodes; use async up to 10 Hz for labels at smaller sizes (2 Hz overview-only).",
+  "qualification": "Each listed run set is headful, real Apple M5 Pro GPU, 3 fresh browser contexts, variance-qualified. Headline p95 is the median of per-run p95s. This is one machine and one clustered fixture, not a universal speed guarantee.",
+  "verdict": "The existing 33 ms L-tier p95 budget fails on the baseline and every experiment. The selected large-scene policy avoids the marked async-transfer regression; it does not resolve the pre-existing frame-time budget failure.",
+  "variants": [
+    {
+      "name": "baseline",
+      "description": "Clean HEAD d186a1f; prior label-only 2 Hz synchronous sampling.",
+      "date": "2026-10-24T17:05:18.485Z",
+      "frameMs": {
+        "p50": 9.7,
+        "p95": 41.81,
+        "cvPct": 2.4,
+        "perRunP95": [
+          43.49,
+          41.7,
+          41.81
+        ]
+      },
+      "brushLatencyMsP95": 50.33,
+      "idleRafRegistrationsMax": 309,
+      "reArmedAllRuns": true,
+      "gate": {
+        "qualifying": true,
+        "disqualifiers": [],
+        "overall": "fail",
+        "verdicts": [
+          {
+            "metric": "frameMs.p95",
+            "target": 33,
+            "measured": 41.81,
+            "samples": 505,
+            "pass": false,
+            "note": null
+          },
+          {
+            "metric": "brushLatencyMs.p95",
+            "target": null,
+            "measured": 50.33,
+            "samples": 120,
+            "pass": null,
+            "note": "reported-only: names no numeric budget for this metric (no release gate yet)"
+          }
+        ]
+      }
+    },
+    {
+      "name": "current",
+      "description": "Initial shared cache: asynchronous reads at 10 Hz with labels on all scene sizes.",
+      "date": "2026-10-24T17:01:39.104Z",
+      "frameMs": {
+        "p50": 8.5,
+        "p95": 56.56,
+        "cvPct": 6.6,
+        "perRunP95": [
+          56.56,
+          58.1,
+          51.2
+        ]
+      },
+      "brushLatencyMsP95": 64.87,
+      "idleRafRegistrationsMax": 0,
+      "reArmedAllRuns": true,
+      "gate": {
+        "qualifying": true,
+        "disqualifiers": [],
+        "overall": "fail",
+        "verdicts": [
+          {
+            "metric": "frameMs.p95",
+            "target": 33,
+            "measured": 56.56,
+            "samples": 699,
+            "pass": false,
+            "note": null
+          },
+          {
+            "metric": "brushLatencyMs.p95",
+            "target": null,
+            "measured": 64.87,
+            "samples": 120,
+            "pass": null,
+            "note": "reported-only: names no numeric budget for this metric (no release gate yet)"
+          }
+        ]
+      }
+    },
+    {
+      "name": "nosampler",
+      "description": "Isolation only: current changes with periodic sampling disabled; event snapshots remain.",
+      "date": "2026-10-24T17:05:57.971Z",
+      "frameMs": {
+        "p50": 9.8,
+        "p95": 42.39,
+        "cvPct": 1.3,
+        "perRunP95": [
+          42.72,
+          41.67,
+          42.39
+        ]
+      },
+      "brushLatencyMsP95": 48.74,
+      "idleRafRegistrationsMax": 0,
+      "reArmedAllRuns": true,
+      "gate": {
+        "qualifying": true,
+        "disqualifiers": [],
+        "overall": "fail",
+        "verdicts": [
+          {
+            "metric": "frameMs.p95",
+            "target": 33,
+            "measured": 42.39,
+            "samples": 450,
+            "pass": false,
+            "note": null
+          },
+          {
+            "metric": "brushLatencyMs.p95",
+            "target": null,
+            "measured": 48.74,
+            "samples": 120,
+            "pass": null,
+            "note": "reported-only: names no numeric budget for this metric (no release gate yet)"
+          }
+        ]
+      }
+    },
+    {
+      "name": "adaptive",
+      "description": "Isolation only: async 10 Hz up to 10K nodes, async 2 Hz above 10K.",
+      "date": "2026-10-24T17:06:39.398Z",
+      "frameMs": {
+        "p50": 9.1,
+        "p95": 50.23,
+        "cvPct": 11.7,
+        "perRunP95": [
+          53.2,
+          50.23,
+          42.18
+        ]
+      },
+      "brushLatencyMsP95": 60.13,
+      "idleRafRegistrationsMax": 0,
+      "reArmedAllRuns": true,
+      "gate": {
+        "qualifying": true,
+        "disqualifiers": [],
+        "overall": "fail",
+        "verdicts": [
+          {
+            "metric": "frameMs.p95",
+            "target": 33,
+            "measured": 50.23,
+            "samples": 517,
+            "pass": false,
+            "note": null
+          },
+          {
+            "metric": "brushLatencyMs.p95",
+            "target": null,
+            "measured": 60.13,
+            "samples": 120,
+            "pass": null,
+            "note": "reported-only: names no numeric budget for this metric (no release gate yet)"
+          }
+        ]
+      }
+    },
+    {
+      "name": "sync",
+      "description": "Selected policy in isolated checkout: async up to 10K nodes, synchronous 2 Hz above 10K.",
+      "date": "2026-10-24T17:07:36.929Z",
+      "frameMs": {
+        "p50": 9.65,
+        "p95": 42.89,
+        "cvPct": 1.7,
+        "perRunP95": [
+          41.79,
+          43.15,
+          42.89
+        ]
+      },
+      "brushLatencyMsP95": 51.14,
+      "idleRafRegistrationsMax": 8,
+      "reArmedAllRuns": true,
+      "gate": {
+        "qualifying": true,
+        "disqualifiers": [],
+        "overall": "fail",
+        "verdicts": [
+          {
+            "metric": "frameMs.p95",
+            "target": 33,
+            "measured": 42.89,
+            "samples": 475,
+            "pass": false,
+            "note": null
+          },
+          {
+            "metric": "brushLatencyMs.p95",
+            "target": null,
+            "measured": 51.14,
+            "samples": 120,
+            "pass": null,
+            "note": "reported-only: names no numeric budget for this metric (no release gate yet)"
+          }
+        ]
+      }
+    },
+    {
+      "name": "final",
+      "description": "Final production source: async up to 10K nodes, synchronous 2 Hz above 10K.",
+      "date": "2026-10-24T18:57:27.125Z",
+      "frameMs": {
+        "p50": 9.6,
+        "p95": 42.11,
+        "cvPct": 1,
+        "perRunP95": [
+          42.61,
+          42.11,
+          41.8
+        ]
+      },
+      "brushLatencyMsP95": 50.13,
+      "idleRafRegistrationsMax": 0,
+      "reArmedAllRuns": true,
+      "gate": {
+        "qualifying": true,
+        "disqualifiers": [],
+        "overall": "fail",
+        "verdicts": [
+          {
+            "metric": "frameMs.p95",
+            "target": 33,
+            "measured": 42.11,
+            "samples": 471,
+            "pass": false,
+            "note": null
+          },
+          {
+            "metric": "brushLatencyMs.p95",
+            "target": null,
+            "measured": 50.13,
+            "samples": 120,
+            "pass": null,
+            "note": "reported-only: names no numeric budget for this metric (no release gate yet)"
+          }
+        ]
+      }
+    }
+  ],
+  "environment": {
+    "os": "darwin 25.5.0",
+    "arch": "arm64",
+    "machineClass": "Apple M5 Pro",
+    "node": "v24.15.0",
+    "browser": "chromium 156.0.8078.4",
+    "gpu": "ANGLE (Apple, ANGLE Metal Renderer: Apple M5 Pro, Unspecified Version)",
+    "headful": true,
+    "simulation": "running",
+    "runs": 3
+  },
+  "scenario": {
+    "tier": "L",
+    "family": "clustered",
+    "seed": 2026,
+    "nodes": 100000,
+    "edges": 250000,
+    "scrubSteps": 40
+  },
+  "idleObservation": "The isolated sync experiment observed at most 8 rAF registrations in the 2s parked window; the final production run observed 0 in each of its 3 runs. All runs re-armed after resume. No sampling timer or extra rAF scheduler was introduced."
+}
diff --git a/packages/engine-cosmos/src/CosmosEngine.ts b/packages/engine-cosmos/src/CosmosEngine.ts
index 1782026..2e585fd 100644
--- a/packages/engine-cosmos/src/CosmosEngine.ts
+++ b/packages/engine-cosmos/src/CosmosEngine.ts
@@ -596,6 +596,20 @@ export class CosmosEngine implements GraphEngine {
     return graph ? graph.getPointPositionsArray() : null;
   }
 
+  async getPositionsAsync(): Promise<Float32Array | null> {
+    const graph = this.activeGraph;
+    if (graph === null) return null;
+    try {
+      // No output reuse: each read owns its snapshot, including overlapping
+      // lifecycle generations. Cosmos may return an empty array on rebuild.
+      const positions = await graph.getPointPositionsAsync();
+      return this.activeGraph === graph && positions.length > 0 ? positions : null;
+    } catch {
+      // Context loss/disposal can reject an in-flight GPU copy.
+      return null;
+    }
+  }
+
   /**
    * Captures the cosmos canvas via the same-tick method (see module
    * header): one rAF is scheduled and, inside that tick, the WebGL canvas is
diff --git a/packages/engine-cosmos/test/cosmos-engine.test.ts b/packages/engine-cosmos/test/cosmos-engine.test.ts
index 33ac7a7..0fabb47 100644
--- a/packages/engine-cosmos/test/cosmos-engine.test.ts
+++ b/packages/engine-cosmos/test/cosmos-engine.test.ts
@@ -99,6 +99,9 @@ const h = vi.hoisted(() => {
     pointPositions: number[] = [1, 2, 3, 4];
     getPointPositions(): number[] { return this.pointPositions; }
     getPointPositionsArray(): Float32Array { return Float32Array.from(this.pointPositions); }
+    getPointPositionsAsync(): Promise<Float32Array> {
+      return Promise.resolve(Float32Array.from(this.pointPositions));
+    }
     /** Native fit uses destination positions while a position transition runs. */
     fitViewPositions: number[] | null = null;
     getFitViewPositions(): Float32Array {
@@ -1202,6 +1205,35 @@ describe('CosmosEngine', () => {
     expect(legacyRead).not.toHaveBeenCalled();
   });
 
+  it('delegates async snapshots without a synchronous read and retires disposed copies', async () => {
+    const { engine, graph } = await mounted();
+    const sync = vi.spyOn(graph, 'getPointPositionsArray');
+    expect(await engine.getPositionsAsync()).toEqual(Float32Array.of(1, 2, 3, 4));
+    expect(sync).not.toHaveBeenCalled();
+    let resolve!: (positions: Float32Array) => void;
+    vi.spyOn(graph, 'getPointPositionsAsync').mockReturnValue(new Promise((r) => { resolve = r; }));
+    const pending = engine.getPositionsAsync();
+    engine.destroy();
+    resolve(Float32Array.of(9, 8, 7, 6));
+    expect(await pending).toBeNull();
+    expect(await engine.getPositionsAsync()).toBeNull();
+  });
+
+  it('treats rejected or invalidated async GPU copies as unavailable', async () => {
+    const { engine, graph } = await mounted();
+    const read = vi.spyOn(graph, 'getPointPositionsAsync');
+    read.mockRejectedValueOnce(new Error('lost context'));
+    expect(await engine.getPositionsAsync()).toBeNull();
+    read.mockResolvedValueOnce(new Float32Array());
+    expect(await engine.getPositionsAsync()).toBeNull();
+    let resolve!: (positions: Float32Array) => void;
+    read.mockReturnValueOnce(new Promise((r) => { resolve = r; }));
+    const pending = engine.getPositionsAsync();
+    graph.canvas!.dispatchEvent(new Event('webglcontextlost', { cancelable: true }));
+    resolve(Float32Array.of(9, 8, 7, 6));
+    expect(await pending).toBeNull();
+  });
+
   // Real setViewport pan via setZoomTransformByPointPositions. The
   // derived formula (see the CosmosEngine module header): centering (x, y) at
   // zoom z is exactly setZoomTransformByPointPositions([x, y], duration, z);
diff --git a/packages/react/src/components/Minimap/index.tsx b/packages/react/src/components/Minimap/index.tsx
index 7cad039..2ecb5ff 100644
--- a/packages/react/src/components/Minimap/index.tsx
+++ b/packages/react/src/components/Minimap/index.tsx
@@ -1,44 +1,14 @@
 /**
- * `@modernrelay/orbit-react/components/Minimap` — `<GraphMinimap>`, the
- * whole-graph thumbnail + viewport rectangle.
- *
- * v0.9 is CPU-fallback-only (no engine exposes `capabilities.overviewPass`
- * cosmos matrix): the component owns an {@link OverviewController} and
- * blits its `rasterize` output into a small canvas via `putImageData`. The
- * three lanes stay strictly decoupled:
- *
- * 1. **Thumbnail refresh** — a 500 ms `setInterval` probes the controller's
- * `shouldRefresh(now, simulationRunning, epoch)` gate, so the effective
- * cadence is the controller's spec budget (≤ 2 Hz hot, ≤ 1 Hz idle, zero
- * work idle-with-unchanged-epoch) and each `true` is followed by exactly
- * one `rasterize` + blit. The interval — not a per-frame engine lane —
- * is the documented v0.9 cadence: the `onFrame` fan-out only reaches
- * React through the label lane, which is gated on labels being enabled,
- * so a plain timer is the correct always-on ≤ 2 Hz driver. The epoch is
- * `revisions.render` (a positions-bearing superset — over-approximate but
- * bounded by the same throttle).
- * 2. **Viewport rectangle** — an imperative store subscription writes the
- * rect's transform/size O(1) per `store.viewport` publication (CSS
- * transform on a ref; no React re-render, no re-rasterize).
- * 3. **Pan** — pointer down/drag maps minimap px → world via the
- * controller's `minimapToWorld` (exact inverse over the last rasterized
- * frame) and calls `instance.setViewport({x, y})` — real camera pans.
- *
- * Scene source (documented v0.9 trim): the instance does not yet expose the
- * posBuf mirror (reserved for the columnar lane), so the
- * component probes a pinned structural seam `getOverviewScene` first
- * (optional access — picked up automatically once core lands
- * it) and falls back to the DECLARED node positions (`GraphNode.x/y`) of the
- * current scene roster — exact for prepared/fixed-position datasets from
- * orbit-data, and empty for force layouts without a position mirror.
- * Position-less nodes rasterize as NaN tombstones (skipped); mask-hidden nodes draw dimmed
- * via `getVisible`.
+ * Whole-graph thumbnail + viewport rectangle. Core owns the shared live
+ * position cache; the CPU rasterizer paints at most 2 Hz hot / 1 Hz idle
+ * after a change. Cache notifications and a bounded timer drive thumbnail
+ * refresh; viewport changes move only the rectangle. No per-frame readback.
  */
 
 import { useEffect, useMemo, useRef } from 'react';
 import type { CSSProperties, PointerEvent as ReactPointerEvent, ReactElement } from 'react';
 import { OverviewController, OVERVIEW_HOT_INTERVAL_MS } from '@modernrelay/orbit-core';
-import type { NodeId, OverviewScene, ViewportState } from '@modernrelay/orbit-core';
+import type { NodeId, ViewportState } from '@modernrelay/orbit-core';
 import type { AnyGraphInstance } from '../../GraphProvider';
 import { cornerStyle, mergeStyle, useResolvedInstance } from '../shared';
 import type { GraphCorner } from '../shared';
@@ -51,13 +21,6 @@ const SIZE_DEFAULT = 200;
  * visible as a marker. */
 const MIN_RECT_PX = 6;
 
-/** Pinned structural seam: the instance-side
- * posBuf mirror read. Optional access until core lands it — this view
- * stays signature-compatible when the member becomes required. */
-interface OverviewSceneSurface {
-  getOverviewScene?(): OverviewScene | null;
-}
-
 export interface GraphMinimapProps {
   /** Explicit instance (multi-instance pages); ambient context otherwise. */
   instance?: AnyGraphInstance;
@@ -103,13 +66,6 @@ const RECT_STYLE: CSSProperties = {
   boxSizing: 'border-box',
 };
 
-/** Declared-position scene over the current roster, cached by the roster's
- * identity (`scene.idByIndex` is a stable reference per reconciled scene). */
-interface DeclaredSceneCache {
-  ids: readonly NodeId[];
-  scene: OverviewScene | null;
-}
-
 export function GraphMinimap(props: GraphMinimapProps): ReactElement {
   const instance = useResolvedInstance(props.instance, '<GraphMinimap>');
   const size = props.size ?? SIZE_DEFAULT;
@@ -120,7 +76,6 @@ export function GraphMinimap(props: GraphMinimapProps): ReactElement {
   /** Pointer that owns the current pan gesture. Other simultaneous pointers
    * cannot move or terminate it. */
   const draggingPointerRef = useRef<number | null>(null);
-  const declaredSceneRef = useRef<DeclaredSceneCache>({ ids: [], scene: null });
   /** mask lane for `getVisible`, recomputed once per refresh tick. */
   const visibleRef = useRef<{ ids: readonly NodeId[]; set: ReadonlySet<NodeId> | null }>({
     ids: [],
@@ -128,41 +83,13 @@ export function GraphMinimap(props: GraphMinimapProps): ReactElement {
   });
 
   const controller = useMemo(() => {
-    const getScene = (): OverviewScene | null => {
-      // 1. Pinned core seam: the posBuf mirror, once it lands.
-      const mirrored = (instance as unknown as OverviewSceneSurface).getOverviewScene?.();
-      if (mirrored !== undefined) return mirrored;
-      // 2. v0.9 fallback: declared node positions over the scene roster.
-      const ids = instance.getSceneNodeIds();
-      if (ids.length === 0) return null;
-      const cache = declaredSceneRef.current;
-      if (cache.ids === ids) return cache.scene;
-      const positions = new Float32Array(2 * ids.length);
-      let known = 0;
-      for (let i = 0; i < ids.length; i++) {
-        const node = instance.getNode(ids[i]!);
-        const x = node?.x;
-        const y = node?.y;
-        if (typeof x === 'number' && typeof y === 'number') {
-          positions[2 * i] = x;
-          positions[2 * i + 1] = y;
-          known++;
-        } else {
-          positions[2 * i] = NaN;
-          positions[2 * i + 1] = NaN;
-        }
-      }
-      const scene: OverviewScene | null = known > 0 ? { positions, count: ids.length } : null;
-      declaredSceneRef.current = { ids, scene };
-      return scene;
-    };
     const getVisible = (index: number): boolean => {
       const v = visibleRef.current;
       if (v.set === null) return true;
       const id = v.ids[index];
       return id === undefined ? true : v.set.has(id);
     };
-    return new OverviewController({ getScene, getVisible, size });
+    return new OverviewController({ getScene: () => instance.getOverviewScene(), getVisible, size });
   }, [instance, size]);
 
   /** O(1) rect update from the store viewport over the LAST rasterized frame.
@@ -227,19 +154,31 @@ export function GraphMinimap(props: GraphMinimapProps): ReactElement {
       // A fresh frame can move the world→minimap mapping: re-derive the rect.
       updateRect(instance.store.getState().viewport);
     };
+    let lastSnapshot = instance.getOverviewScene();
+    let lastRender = instance.store.getState().revisions.render;
+    let epoch = 0;
     const tick = (): void => {
       const state = instance.store.getState();
-      // `revisions.render` is the v0.9 positions epoch (see module JSDoc):
-      // idle with an unchanged render revision is provably position-stable.
-      if (!controller.shouldRefresh(Date.now(), state.simulationRunning, state.revisions.render)) {
+      const snapshot = instance.getOverviewScene();
+      // Position samples have their own epoch: a settle/drag need not commit
+      // a new render revision. Render changes also invalidate mask shading.
+      if (snapshot !== lastSnapshot || state.revisions.render !== lastRender) {
+        lastSnapshot = snapshot;
+        lastRender = state.revisions.render;
+        epoch += 1;
+      }
+      if (!controller.shouldRefresh(Date.now(), state.simulationRunning, epoch)) {
         return;
       }
       blit();
     };
-    tick(); // first paint without waiting a full interval
+    const unsubscribePositions = instance.subscribeOverview(tick); // includes first paint
+    const unsubscribeStore = instance.store.subscribe(tick);
     const timer = setInterval(tick, OVERVIEW_HOT_INTERVAL_MS);
     return () => {
       clearInterval(timer);
+      unsubscribePositions();
+      unsubscribeStore();
     };
     // updateRect is stable for each (instance, controller) pair — refs + controller
     // only — so it is deliberately not a dependency (this repo does not
diff --git a/packages/react/test/minimap.test.tsx b/packages/react/test/minimap.test.tsx
index 9384ddf..ed1ea93 100644
--- a/packages/react/test/minimap.test.tsx
+++ b/packages/react/test/minimap.test.tsx
@@ -110,6 +110,7 @@ function referenceController(size: number): OverviewController {
 
 afterEach(() => {
   cleanup();
+  vi.useRealTimers();
   vi.restoreAllMocks();
   vi.unstubAllGlobals();
   for (const instance of instances) instance.destroy();
@@ -142,7 +143,8 @@ describe('<GraphMinimap> thumbnail blit', () => {
     expect(ctx2d.putImageData.mock.calls[0]![2]).toBe(0);
   });
 
-  it('renders an empty thumbnail (no blit) when no node declares a position', async () => {
+  it('rasterizes live force positions when no node declares coordinates', async () => {
+    vi.useFakeTimers();
     const engine = new FakeEngine();
     const instance = createGraphInstance({ engine: () => engine });
     instances.push(instance);
@@ -163,8 +165,40 @@ describe('<GraphMinimap> thumbnail blit', () => {
         <GraphMinimap />
       </GraphProvider>,
     );
-    expect(ctx2d.putImageData).not.toHaveBeenCalled();
-    expect(ctx2d.clearRect).toHaveBeenCalled();
+    // The engine seeds/layouts the unpositioned roster; core shares its
+    // live positions even when labels are not configured.
+    engine.nudgePositions(50, 60);
+    engine.injectSimulationEnd();
+    await act(async () => { await vi.advanceTimersByTimeAsync(1000); });
+    expect(ctx2d.putImageData).toHaveBeenCalled();
+    expect([...instance.getOverviewScene()!.positions]).toEqual([50, 60, 60, 60]);
+    const image = ctx2d.putImageData.mock.lastCall![0] as ImageData;
+    expect(image.data.some((value, i) => i % 4 === 3 && value > 0)).toBe(true);
+  });
+
+  it('refreshes fixed-layout bounds after same-roster coordinate edits', async () => {
+    vi.useFakeTimers();
+    const rasterize = vi.spyOn(OverviewController.prototype, 'rasterize');
+    const { instance } = await setup(40);
+    act(() => { instance.applyHostUpdate({ layout: 'fixed', data: {
+      ...positionedSnapshot,
+      sourceRevision: 2,
+      nodes: positionedSnapshot.nodes.map((node) => ({ ...node, x: node.x! + 100, y: node.y! + 200 })),
+    } }); });
+    await act(async () => { await vi.advanceTimersByTimeAsync(1000); });
+    expect(rasterize.mock.results.at(-1)?.value?.bounds).toEqual({ minX: 100, maxX: 110, minY: 200, maxY: 210 });
+  });
+
+  it('refreshes settled bounds after a drag without a render revision', async () => {
+    vi.useFakeTimers();
+    const rasterize = vi.spyOn(OverviewController.prototype, 'rasterize');
+    const { instance, engine } = await setup(40);
+    act(() => { engine.injectSimulationEnd(); });
+    const render = instance.getRevisions().render;
+    act(() => { engine.injectDragEnd(0, -50, -60); });
+    expect(instance.getRevisions().render).toBe(render);
+    await act(async () => { await vi.advanceTimersByTimeAsync(1000); });
+    expect(rasterize.mock.results.at(-1)?.value?.bounds).toEqual({ minX: -50, maxX: 10, minY: -60, maxY: 10 });
   });
 });
 
diff --git a/scripts/bench-data-preparation.mjs b/scripts/bench-data-preparation.mjs
new file mode 100644
index 0000000..0de293c
--- /dev/null
+++ b/scripts/bench-data-preparation.mjs
@@ -0,0 +1,79 @@
+#!/usr/bin/env node
+/** CPU preparation comparison, not a GPU/render performance qualification.
+ * Run: node scripts/bench-data-preparation.mjs [--nodes 100000 --edges 250000 --runs 3]
+ * Each output uses identical generated row streams in a fresh --expose-gc process.
+ */
+import { spawnSync } from 'node:child_process';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { cpus, tmpdir } from 'node:os';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { performance } from 'node:perf_hooks';
+import { build } from 'esbuild';
+
+const self = fileURLToPath(import.meta.url);
+const root = path.resolve(path.dirname(self), '..');
+const args = process.argv.slice(2);
+const value = (flag, fallback) => {
+  const index = args.indexOf(flag);
+  const result = index < 0 ? fallback : Number(args[index + 1]);
+  if (!Number.isSafeInteger(result) || result <= 0) throw new Error(`${flag} must be a positive integer`);
+  return result;
+};
+const nodes = value('--nodes', 100_000);
+const edges = value('--edges', 250_000);
+const runs = value('--runs', 3);
+
+if (args.includes('--child')) {
+  const output = args[args.indexOf('--output') + 1];
+  const modulePath = args[args.indexOf('--module') + 1];
+  const { prepareGraphData } = await import(pathToFileURL(modulePath));
+  async function* nodeRows() {
+    for (let i = 0; i < nodes; i++) yield { id: `n${i}`, label: `Group ${i % 64}`, score: i % 1000, active: (i & 1) === 0 };
+  }
+  async function* edgeRows() {
+    for (let i = 0; i < edges; i++) yield { id: `e${i}`, source: `n${i % nodes}`, target: `n${(i + 1) % nodes}`, weight: (i % 10) / 10, kind: `kind${i % 4}` };
+  }
+  global.gc();
+  const before = process.memoryUsage();
+  const start = performance.now();
+  const prepared = await prepareGraphData({ nodes: nodeRows(), edges: edgeRows() }, {
+    nodes: { id: 'id' }, edges: { id: 'id', source: 'source', target: 'target' },
+  }, { datasetKey: 'benchmark', sourceRevision: 1, output });
+  const elapsedMs = performance.now() - start;
+  global.gc();
+  const after = process.memoryUsage();
+  const actualNodes = prepared.snapshot.nodes.length;
+  const actualEdges = prepared.snapshot.edges.length;
+  if (actualNodes !== nodes || actualEdges !== edges) throw new Error('Cardinality mismatch');
+  // Keep the result reachable through the final memory sample.
+  console.log(JSON.stringify({ output, elapsedMs, peakRssBytes: process.resourceUsage().maxRSS * 1024,
+    retainedHeapAndBuffersDelta: after.heapUsed + after.arrayBuffers - before.heapUsed - before.arrayBuffers,
+    baselineRssBytes: before.rss, nodes: actualNodes, edges: actualEdges, mappingFingerprint: prepared.mappingFingerprint }));
+} else {
+  const temp = mkdtempSync(path.join(tmpdir(), 'orbit-data-bench-'));
+  try {
+    const bundle = path.join(temp, 'data.mjs');
+    await build({ entryPoints: [path.join(root, 'packages/data/src/index.ts')], bundle: true, platform: 'node', format: 'esm', outfile: bundle });
+    const samples = [];
+    for (let i = 0; i < runs; i++) {
+      for (const output of ['object', 'columnar']) {
+        const child = spawnSync(process.execPath, ['--expose-gc', self, '--child', '--module', bundle,
+          '--nodes', String(nodes), '--edges', String(edges), '--output', output], { encoding: 'utf8' });
+        if (child.status !== 0) throw new Error(child.stderr || child.stdout || String(child.error));
+        samples.push(JSON.parse(child.stdout));
+      }
+    }
+    const median = (values) => values.sort((a, b) => a - b)[Math.floor(values.length / 2)];
+    const summary = Object.fromEntries(['object', 'columnar'].map((output) => {
+      const rows = samples.filter((s) => s.output === output);
+      return [output, Object.fromEntries(['elapsedMs', 'peakRssBytes', 'retainedHeapAndBuffersDelta'].map((key) =>
+        [key, { min: Math.min(...rows.map((r) => r[key])), median: median(rows.map((r) => r[key])), max: Math.max(...rows.map((r) => r[key])) }]))];
+    }));
+    console.log(JSON.stringify({ benchmark: 'CPU-only prepared row streams', measuredAt: new Date().toISOString(), cpu: cpus()[0]?.model, node: process.version,
+      platform: process.platform, arch: process.arch, nodes, edges, runs,
+      qualification: 'Not a GPU/render benchmark; core may materialize columnar output later.',
+      verdict: { retainedMemoryLower: summary.columnar.retainedHeapAndBuffersDelta.median < summary.object.retainedHeapAndBuffersDelta.median,
+        preparationFaster: summary.columnar.elapsedMs.median < summary.object.elapsedMs.median }, summary, samples }, null, 2));
+  } finally { rmSync(temp, { recursive: true, force: true }); }
+}
diff --git a/scripts/pack-smoke.mjs b/scripts/pack-smoke.mjs
index b2a8b69..5265db4 100644
--- a/scripts/pack-smoke.mjs
+++ b/scripts/pack-smoke.mjs
@@ -15,6 +15,7 @@
  * (i) `.smoke/report.json` summarizing every gate
  * (j) the packed inline worker asset is self-contained
  * (k) inferred consumer declarations use publicly accessible package types
+ * (l) the documented quickstart compiles, bundles, and runs as a consumer
  */
 import { execFileSync } from 'node:child_process';
 import {
@@ -31,6 +32,7 @@ import { tmpdir } from 'node:os';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import * as esbuild from 'esbuild';
+import { verifyQuickstart } from '../fixtures/quickstart/verify.mjs';
 
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 const SMOKE = path.join(ROOT, '.smoke');
@@ -175,6 +177,8 @@ try {
       'react',
       'react-dom',
       `@types/react@${pkgs.find((p) => p.name === '@modernrelay/orbit-react').manifest.devDependencies['@types/react']}`,
+      `@types/react-dom@${pkgs.find((p) => p.name === '@modernrelay/orbit-react').manifest.devDependencies['@types/react-dom']}`,
+      `jsdom@${pkgs.find((p) => p.name === '@modernrelay/orbit-react').manifest.devDependencies.jsdom}`,
     ],
     { cwd: consumerDir },
   );
@@ -223,6 +227,18 @@ try {
   fail('declarations:public-inferred-types', errText(err));
 }
 
+// ---------------------------------------------------- (l) documented quickstart
+try {
+  const detail = await verifyQuickstart({
+    root: ROOT,
+    consumerDir,
+    outdir: path.join(SMOKE, 'bundles', 'quickstart'),
+  });
+  pass('quickstart:documented-consumer', detail);
+} catch (err) {
+  fail('quickstart:documented-consumer', errText(err));
+}
+
 // ---------------------------------------------------------------- (f) publint
 for (const pkg of pkgs) {
   const gateName = `publint:${pkg.name}`;