@inventure71/paddockjs 4.2.0 → 4.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inventure71/paddockjs",
-  "version": "4.2.0",
+  "version": "4.3.0",
   "type": "module",
   "description": "A data-driven browser F1 simulator component for host websites.",
   "license": "Apache-2.0",
@@ -88,8 +88,10 @@
     "test:fast": "node scripts/run-vitest.mjs",
     "types:check": "tsc -p tsconfig.types.json --noEmit",
     "docs:check": "node scripts/docs-check.mjs",
-    "check": "npm run docs:check && npm run test:fast && npm run types:check && npm run pack:dry && npm run consumer:smoke && npm run consumer:bundle-boundaries && npm run showcase:ci && npm run browser:smoke:quick -- --skip-build",
-    "check:release": "npm run docs:check && npm test && npm run types:check && npm run pack:dry && npm run consumer:smoke && npm run consumer:bundle-boundaries && npm run showcase:ci && npm run browser:smoke:full -- --skip-build",
+    "check": "npm run docs:check && npm run test:fast && npm run types:check && npm run pack:dry && npm run consumer:smoke && npm run consumer:bundle-boundaries && npm run site:ci && npm run browser:smoke:quick -- --skip-build && npm run demo:smoke -- --skip-build",
+    "check:release": "npm run docs:check && npm run audit:release && npm test && npm run types:check && npm run pack:dry && npm run consumer:smoke && npm run consumer:bundle-boundaries && npm run site:ci && npm run browser:smoke:full -- --skip-build && npm run demo:smoke -- --skip-build",
+    "audit:release": "npm run tools:release:ci && npm audit --audit-level=high && npm --prefix site audit --audit-level=high && npm --prefix tools/release audit --audit-level=high",
+    "tools:release:ci": "npm --prefix tools/release ci",
     "pack:dry": "npm pack --dry-run",
     "consumer:smoke": "node scripts/consumer-package-smoke.mjs",
     "consumer:bundle-boundaries": "node scripts/consumer-bundle-boundaries.mjs",
@@ -97,21 +99,29 @@
     "browser:smoke:quick": "node smoke/browser-smoke.mjs --quick",
     "browser:smoke:full": "node smoke/browser-smoke.mjs --full",
     "benchmark:runtime": "node scripts/benchmark-runtime-efficiency.mjs",
-    "showcase:install": "npm --prefix local-preview ci",
-    "showcase:dev": "npm --prefix local-preview run dev",
-    "showcase:build": "npm --prefix local-preview run build",
-    "showcase:ci": "npm --prefix local-preview ci && npm --prefix local-preview run build",
-    "changeset": "changeset",
-    "version-packages": "changeset version",
-    "release": "npm publish --provenance"
+    "showcase:install": "npm run site:install",
+    "showcase:dev": "npm run site:dev",
+    "showcase:build": "npm run site:build",
+    "showcase:ci": "npm run site:ci",
+    "demo:install": "npm run site:install",
+    "demo:dev": "npm run site:dev",
+    "demo:build": "npm run site:build",
+    "demo:ci": "npm run site:ci",
+    "demo:smoke": "node smoke/demo-smoke.mjs",
+    "changeset": "node scripts/run-changeset.mjs",
+    "version-packages": "node scripts/run-changeset.mjs version",
+    "release": "npm publish --provenance",
+    "site:install": "npm --prefix site ci",
+    "site:dev": "npm --prefix site run dev",
+    "site:build": "npm --prefix site run check",
+    "site:ci": "npm --prefix site ci && npm --prefix site run check"
   },
   "dependencies": {
-    "pixi.js": "8.18.1"
+    "pixi.js": "8.20.1"
   },
   "devDependencies": {
-    "@changesets/cli": "2.29.7",
     "playwright": "^1.57.0",
     "typescript": "5.9.3",
-    "vitest": "4.1.5"
+    "vitest": "4.1.12"
   }
 }

package/src/api/MountedSimulatorComponents.js

@@ -0,0 +1,101 @@
+import { installLayoutSupport } from '../app/layoutSupport.js';
+import { applyPaddockThemeCssVariables } from '../config/defaultOptions.js';
+import { formatCssUrl } from '../config/cssValues.js';
+
+function assertMountTarget(root, label) {
+  if (!root || typeof root !== 'object' || !('innerHTML' in root)) {
+    throw new Error(`${label} requires a DOM element root.`);
+  }
+}
+
+function setPackageCssVariables(root, assets, theme, context = {}) {
+  root.classList?.add?.('f1-sim-component');
+  root.style?.setProperty?.('--broadcast-panel-surface', formatCssUrl(assets.broadcastPanel));
+  applyPaddockThemeCssVariables(root, theme, context);
+}
+
+function createCompositeRoot(getRoots, getOptions) {
+  return {
+    style: {
+      setProperty(name, value) {
+        getRoots().forEach((root) => root.style?.setProperty?.(name, value));
+      },
+      removeProperty(name) {
+        getRoots().forEach((root) => root.style?.removeProperty?.(name));
+      },
+    },
+    querySelector(selector) {
+      for (const root of getRoots()) {
+        const match = root.querySelector?.(selector);
+        if (match) return match;
+      }
+      return null;
+    },
+    querySelectorAll(selector) {
+      return getRoots().flatMap((root) => [...(root.querySelectorAll?.(selector) ?? [])]);
+    },
+    setAttribute(name, value) {
+      getRoots().forEach((root) => root.setAttribute?.(name, value));
+    },
+    removeAttribute(name) {
+      getRoots().forEach((root) => root.removeAttribute?.(name));
+    },
+    applyCssVariables(context = {}) {
+      const options = getOptions();
+      getRoots().forEach((root) => setPackageCssVariables(root, options.assets, options.theme, context));
+    },
+  };
+}
+
+// Owns mounted DOM surfaces, layout-support lifetimes and their composite query
+// root. The simulator controller supplies runtime availability and options.
+export class MountedSimulatorComponents {
+  constructor({ getOptions, canMount }) {
+    this.getOptions = getOptions;
+    this.canMount = canMount;
+    this.roots = new Map();
+    this.mountRenderers = new Map();
+    this.layoutSupportCleanups = new Map();
+    this.compositeRoot = createCompositeRoot(() => [...this.roots.values()], getOptions);
+  }
+
+  mount(root, key, createMarkup) {
+    assertMountTarget(root, `mount ${key}`);
+    if (!this.canMount()) {
+      throw new Error('Mount PaddockJS components before calling start().');
+    }
+    const occupiedEntry = [...this.roots.entries()]
+      .find(([mountedKey, mountedRoot]) => mountedKey !== key && mountedRoot === root);
+    if (occupiedEntry) {
+      throw new Error(`Mount ${key} requires its own root; this root already hosts ${occupiedEntry[0]}.`);
+    }
+    const render = typeof createMarkup === 'function' ? createMarkup : () => createMarkup;
+    const previousRoot = this.roots.get(key);
+    this.layoutSupportCleanups.get(key)?.();
+    if (previousRoot && previousRoot !== root) previousRoot.innerHTML = '';
+    root.innerHTML = render();
+    setPackageCssVariables(root, this.getOptions().assets, this.getOptions().theme);
+    this.layoutSupportCleanups.set(key, installLayoutSupport(root));
+    this.roots.set(key, root);
+    this.mountRenderers.set(key, render);
+    return root;
+  }
+
+  rerender() {
+    this.roots.forEach((root, key) => {
+      const render = this.mountRenderers.get(key);
+      if (render) root.innerHTML = render();
+      setPackageCssVariables(root, this.getOptions().assets, this.getOptions().theme);
+      this.layoutSupportCleanups.get(key)?.();
+      this.layoutSupportCleanups.set(key, installLayoutSupport(root));
+    });
+  }
+
+  destroy() {
+    this.layoutSupportCleanups.forEach((cleanup) => cleanup());
+    this.layoutSupportCleanups.clear();
+    this.roots.forEach((root) => { root.innerHTML = ''; });
+    this.roots.clear();
+    this.mountRenderers.clear();
+  }
+}

package/src/api/PaddockSimulatorController.js

@@ -1,5 +1,6 @@
+import { createViewControlsMarkup } from '../ui/viewControlsTemplate.js';
 import { F1SimulatorApp } from '../app/F1SimulatorApp.js';
-import { installLayoutSupport } from '../app/layoutSupport.js';
+import { MountedSimulatorComponents } from './MountedSimulatorComponents.js';
 import {
   createRaceDataPanelMarkup,
   createTelemetrySectorBannerMarkup,
@@ -18,80 +19,27 @@ import {
   createTelemetrySectorsMarkup,
   createTimingTowerMarkup,
 } from '../ui/componentTemplates.js';
-import { applyPaddockThemeCssVariables, resolveF1SimulatorOptions } from '../config/defaultOptions.js';
-import { formatCssUrl } from '../config/cssValues.js';
+import { resolveF1SimulatorOptions } from '../config/defaultOptions.js';
 import { mergeRestartOptions } from '../config/restartOptions.js';
 import { getNextTimingGapMode, normalizeTimingGapMode } from '../config/timingGapMode.js';
 import { createThemeSync, resolveRuntimeThemeModeOptions, resolveRuntimeThemeOptions } from './runtimeTheme.js';
 
-function assertMountTarget(root, label) {
-  if (!root || typeof root !== 'object' || !('innerHTML' in root)) {
-    throw new Error(`${label} requires a DOM element root.`);
-  }
-}
-
-function setPackageCssVariables(root, assets, theme, context = {}) {
-  root.classList?.add?.('f1-sim-component');
-  root.style?.setProperty?.('--broadcast-panel-surface', formatCssUrl(assets.broadcastPanel));
-  applyPaddockThemeCssVariables(root, theme, context);
-}
-
-function createCompositeRoot(getRoots, getOptions) {
-  return {
-    style: {
-      setProperty(name, value) {
-        getRoots().forEach((root) => root.style?.setProperty?.(name, value));
-      },
-      removeProperty(name) {
-        getRoots().forEach((root) => root.style?.removeProperty?.(name));
-      },
-    },
-    querySelector(selector) {
-      for (const root of getRoots()) {
-        const match = root.querySelector?.(selector);
-        if (match) return match;
-      }
-      return null;
-    },
-    querySelectorAll(selector) {
-      return getRoots().flatMap((root) => [...(root.querySelectorAll?.(selector) ?? [])]);
-    },
-    setAttribute(name, value) {
-      getRoots().forEach((root) => root.setAttribute?.(name, value));
-    },
-    removeAttribute(name) {
-      getRoots().forEach((root) => root.removeAttribute?.(name));
-    },
-    applyCssVariables(context = {}) {
-      const options = getOptions();
-      getRoots().forEach((root) => setPackageCssVariables(root, options.assets, options.theme, context));
-    },
-  };
-}
-
 export class PaddockSimulatorController {
   constructor(options = {}) {
     this.options = resolveF1SimulatorOptions(options);
-    this.roots = new Map();
-    this.mountRenderers = new Map();
-    this.layoutSupportCleanups = new Map();
     this.app = null;
-    this.compositeRoot = createCompositeRoot(() => [...this.roots.values()], () => this.options);
+    this.initializingApp = null;
+    this.startPromise = null;
+    this.components = new MountedSimulatorComponents({
+      getOptions: () => this.options,
+      canMount: () => !this.app && !this.startPromise,
+    });
+    this.roots = this.components.roots;
+    this.compositeRoot = this.components.compositeRoot;
   }
 
   mountComponent(root, key, createMarkup) {
-    assertMountTarget(root, `mount ${key}`);
-    if (this.app) {
-      throw new Error('Mount PaddockJS components before calling start().');
-    }
-    const render = typeof createMarkup === 'function' ? createMarkup : () => createMarkup;
-    root.innerHTML = render();
-    setPackageCssVariables(root, this.options.assets, this.options.theme);
-    this.layoutSupportCleanups.get(key)?.();
-    this.layoutSupportCleanups.set(key, installLayoutSupport(root));
-    this.roots.set(key, root);
-    this.mountRenderers.set(key, render);
-    return root;
+    return this.components.mount(root, key, createMarkup);
   }
 
   mountRaceControls(root) {
@@ -102,6 +50,10 @@ export class PaddockSimulatorController {
     return this.mountComponent(root, 'camera-controls', () => createCameraControlsMarkup(this.options));
   }
 
+  mountViewControls(root) {
+    return this.mountComponent(root, 'view-controls', () => createViewControlsMarkup(this.options));
+  }
+
   mountSafetyCarControl(root) {
     return this.mountComponent(root, 'safety-car-control', () => createSafetyCarControlMarkup(this.options));
   }
@@ -176,10 +128,31 @@ export class PaddockSimulatorController {
 
   async start() {
     if (this.app) return this;
+    if (this.startPromise) return this.startPromise;
     this.compositeRoot.applyCssVariables();
-    this.app = new F1SimulatorApp(this.compositeRoot, this.options);
-    await this.app.init();
-    return this;
+    const app = new F1SimulatorApp(this.compositeRoot, this.options);
+    this.initializingApp = app;
+    const startPromise = (async () => {
+      try {
+        await app.init();
+        if (this.initializingApp !== app) {
+          throw new Error('PaddockJS start() was cancelled before initialization completed.');
+        }
+        this.app = app;
+        this.initializingApp = null;
+        return this;
+      } catch (error) {
+        app.destroy();
+        throw error;
+      }
+    })();
+    this.startPromise = startPromise;
+    try {
+      return await startPromise;
+    } finally {
+      if (this.startPromise === startPromise) this.startPromise = null;
+      if (this.initializingApp === app) this.initializingApp = null;
+    }
   }
 
   get expert() {
@@ -187,25 +160,16 @@ export class PaddockSimulatorController {
   }
 
   destroy() {
+    const initializingApp = this.initializingApp;
+    this.initializingApp = null;
+    initializingApp?.destroy();
     this.app?.destroy();
     this.app = null;
-    this.layoutSupportCleanups.forEach((cleanup) => cleanup());
-    this.layoutSupportCleanups.clear();
-    this.roots.forEach((root) => {
-      root.innerHTML = '';
-    });
-    this.roots.clear();
-    this.mountRenderers.clear();
+    this.components.destroy();
   }
 
   rerenderMountedComponents() {
-    this.roots.forEach((root, key) => {
-      const render = this.mountRenderers.get(key);
-      if (render) root.innerHTML = render();
-      setPackageCssVariables(root, this.options.assets, this.options.theme);
-      this.layoutSupportCleanups.get(key)?.();
-      this.layoutSupportCleanups.set(key, installLayoutSupport(root));
-    });
+    this.components.rerender();
   }
 
   syncOptionsFromRunningApp() {
@@ -222,6 +186,9 @@ export class PaddockSimulatorController {
   }
 
   restart(nextOptions = {}) {
+    if (this.startPromise || this.initializingApp) {
+      throw new Error('Cannot restart PaddockJS while start() is initializing. Await start() before restarting.');
+    }
     const currentOptions = this.app ? this.syncOptionsFromRunningApp() : this.options;
     const nextResolvedOptions = resolveF1SimulatorOptions(mergeRestartOptions(currentOptions, nextOptions));
     if (this.app) {
@@ -275,6 +242,10 @@ export class PaddockSimulatorController {
     this.app?.selectCar(driverId, { focus: true });
   }
 
+  setView(view) { return this.app?.setView(view) ?? false; }
+
+  getView() { return this.app?.getView() ?? (this.options.gridWalk.enabled ? this.options.gridWalk.initialView : 'race'); }
+
   setSafetyCarDeployed(deployed) {
     this.app?.setSafetyCarDeployed(deployed);
   }
@@ -374,6 +345,10 @@ export function mountCameraControls(root, simulator) {
   return simulator.mountCameraControls(root);
 }
 
+export function mountViewControls(root, simulator) {
+  return simulator.mountViewControls(root);
+}
+
 export function mountCarDriverOverview(root, simulator) {
   return simulator.mountCarDriverOverview(root);
 }

package/src/app/BrowserExpertAdapter.js

@@ -40,12 +40,6 @@ export function createBrowserExpertAdapter(app, expertOptions = {}) {
     });
   }
 
-  function initialResolvedOptions() {
-    return resolveBrowserExpertOptions(app.options, expertOptions);
-  }
-
-  resolvedOptions = initialResolvedOptions();
-
   const runtime = createEnvironmentRuntime({
     getSimulation: () => app.sim,
     setSimulation(nextSim) {

package/src/app/BrowserExpertExternalRenderer.js

@@ -1,3 +1,4 @@
+import { createExternalTrackSnapshotDecoder } from './ExternalTrackSnapshot.js';
 import { renderTrackSurface } from './rendering/trackRenderer.js';
 
 export function createBrowserExpertExternalRendererBridge(app) {
@@ -7,8 +8,11 @@ export function createBrowserExpertExternalRendererBridge(app) {
   let lastFrameAt = null;
   let lastError = null;
   let driverIdMap = new Map();
-  let trackFingerprint = null;
+  let renderedTrack = null;
+  let renderedFingerprint = null;
   let appliedTrackSurface = false;
+  let attachmentGeneration = 0;
+  const trackDecoder = createExternalTrackSnapshotDecoder();
 
   function localDriverRecords() {
     const source = Array.isArray(app.drivers) && app.drivers.length > 0
@@ -37,14 +41,16 @@ export function createBrowserExpertExternalRendererBridge(app) {
     const knownLocalIdSet = new Set(knownLocalIds);
 
     const activeRawIds = new Set();
-    const usedLocalIds = new Set();
+    // Reserve exact identities before allocating unknown external IDs. A
+    // leading unknown car must not steal a later car's existing local slot.
+    const usedLocalIds = new Set(snapshot.cars.map((car) => car?.id).filter((id) => knownLocalIdSet.has(id)));
 
     snapshot.cars.forEach((car, index) => {
       const rawId = typeof car?.id === 'string' && car.id.length > 0
         ? car.id
         : `external-${String(index)}`;
       activeRawIds.add(rawId);
-      if (knownLocalIdSet.has(rawId) && !usedLocalIds.has(rawId)) {
+      if (knownLocalIdSet.has(rawId)) {
         driverIdMap.set(rawId, rawId);
         usedLocalIds.add(rawId);
         return;
@@ -95,6 +101,7 @@ export function createBrowserExpertExternalRendererBridge(app) {
     const mappedEvents = Array.isArray(snapshot.events)
       ? snapshot.events.map((event) => ({
         ...event,
+        driverId: mapId(event?.driverId),
         carId: mapId(event?.carId),
         otherCarId: mapId(event?.otherCarId),
         winnerId: mapId(event?.winnerId),
@@ -194,18 +201,23 @@ export function createBrowserExpertExternalRendererBridge(app) {
 
   function syncTrackSurface(snapshot) {
     if (!snapshot || typeof snapshot !== 'object') return;
-    const nextFingerprint = fingerprintTrack(snapshot);
-    if (!nextFingerprint) return;
-    if (nextFingerprint === trackFingerprint) return;
+    const track = snapshot.track;
+    if (!track || typeof track !== 'object') return;
+    const fingerprint = fingerprintTrack(snapshot);
+    if (track === renderedTrack && fingerprint === renderedFingerprint) return;
     if (
       !app.trackAsset ||
       !app.drsLayer ||
       !app.sensorLayer ||
       !app.pitLaneStatusLayer
     ) {
-      trackFingerprint = nextFingerprint;
+      renderedTrack = track;
+      renderedFingerprint = fingerprint;
       return;
     }
+    // Drawing clears layers before it can fail. Own restoration from this
+    // point, including partial drawing failures on the first external packet.
+    appliedTrackSurface = true;
     app.pitLaneStatusRenderer?.reset?.();
     app.cameraController?.invalidateTrackCaches?.();
     renderTrackSurface({
@@ -215,8 +227,8 @@ export function createBrowserExpertExternalRendererBridge(app) {
       trackAsset: app.trackAsset,
       snapshot,
     });
-    trackFingerprint = nextFingerprint;
-    appliedTrackSurface = true;
+    renderedTrack = track;
+    renderedFingerprint = fingerprint;
   }
 
   function assertDetached(method) {
@@ -225,25 +237,26 @@ export function createBrowserExpertExternalRendererBridge(app) {
   }
 
   function detach() {
-    if (typeof unsubscribeExternalRenderer === 'function') {
-      try {
-        unsubscribeExternalRenderer();
-      } catch (error) {
-        lastError = error instanceof Error ? error.message : String(error);
-      }
-    }
+    // Clear ownership before cleanup: unsubscribe may flush a queued packet or
+    // reentrantly install its successor. Neither can revive this attachment.
+    const generation = ++attachmentGeneration;
+    const unsubscribe = unsubscribeExternalRenderer;
+    const restoreTrack = appliedTrackSurface;
     unsubscribeExternalRenderer = null;
     attached = false;
     driverIdMap = new Map();
-    if (appliedTrackSurface && typeof app.renderTrack === 'function') {
-      try {
-        app.renderTrack();
-      } catch (error) {
-        lastError = error instanceof Error ? error.message : String(error);
-      }
-    }
-    trackFingerprint = null;
+    renderedTrack = null;
+    renderedFingerprint = null;
     appliedTrackSurface = false;
+    trackDecoder.reset();
+    if (restoreTrack && typeof app.renderTrack === 'function') {
+      try { app.renderTrack(); }
+      catch (error) { if (generation === attachmentGeneration) lastError = error instanceof Error ? error.message : String(error); }
+    }
+    if (typeof unsubscribe === 'function') {
+      try { unsubscribe(); }
+      catch (error) { if (generation === attachmentGeneration) lastError = error instanceof Error ? error.message : String(error); }
+    }
   }
 
   function attach(source) {
@@ -252,33 +265,42 @@ export function createBrowserExpertExternalRendererBridge(app) {
     }
     detach();
     lastError = null;
-    const unsubscribe = source.subscribe((frame) => {
-      if (!frame || typeof frame !== 'object') {
-        lastError = 'Invalid external frame payload.';
-        return;
-      }
-      const rewrittenFrame = rewriteFrame(frame);
-      const snapshot = rewrittenFrame.snapshot;
-      if (!snapshot || typeof snapshot !== 'object') {
-        lastError = 'External frame is missing snapshot.';
-        return;
-      }
-      try {
-        syncTrackSurface(snapshot);
-        app.renderExpertFrame(snapshot, {
-          forceDomUpdate: true,
-          observation: rewrittenFrame.observation && typeof rewrittenFrame.observation === 'object'
-            ? rewrittenFrame.observation
-            : {},
-        });
-        lastMeta = rewrittenFrame.meta ?? null;
-        lastFrameAt = Date.now();
-        lastError = null;
-      } catch (error) {
-        lastError = error instanceof Error ? error.message : String(error);
-      }
-    });
+    const generation = attachmentGeneration;
+    const isCurrent = () => generation === attachmentGeneration;
+    let unsubscribe;
+    try {
+      unsubscribe = source.subscribe((frame) => {
+        if (!isCurrent()) return;
+        if (!frame || typeof frame !== 'object') {
+          lastError = 'Invalid external frame payload.';
+          return;
+        }
+        try {
+          const rewrittenFrame = rewriteFrame(frame);
+          const snapshot = trackDecoder.decode(rewrittenFrame.snapshot);
+          if (!snapshot || typeof snapshot !== 'object') {
+            lastError = 'External frame is missing snapshot.';
+            return;
+          }
+          syncTrackSurface(snapshot);
+          app.renderExpertFrame(snapshot, {
+            forceDomUpdate: true,
+            observation: rewrittenFrame.observation && typeof rewrittenFrame.observation === 'object'
+              ? rewrittenFrame.observation
+              : {},
+          });
+          if (!isCurrent()) return;
+          lastMeta = rewrittenFrame.meta ?? null;
+          lastFrameAt = Date.now();
+          lastError = null;
+        } catch (error) {
+          if (isCurrent()) lastError = error instanceof Error ? error.message : String(error);
+        }
+      });
+    } catch (error) { if (isCurrent()) detach(); throw error; }
+    if (!isCurrent()) { if (typeof unsubscribe === 'function') unsubscribe(); return; }
     if (typeof unsubscribe !== 'function') {
+      detach();
       throw new Error('attachExternalRenderer(source) subscribe(onFrame) must return an unsubscribe function.');
     }
     unsubscribeExternalRenderer = unsubscribe;

package/src/app/ExternalTrackSnapshot.js

@@ -0,0 +1,50 @@
+import { attachTrackQueryIndex, createTrackQueryIndex } from '../simulation/track/trackQueryConstruction.js';
+import { prepareSampleIndexLut } from '../simulation/track/spatialQueries.js';
+import { createPitBoxBounds, createPitConnectorBounds, createPitLaneBounds } from '../simulation/track/pitLaneLayout.js';
+
+const SAMPLE_FIELDS = ['x', 'y', 'distance', 'heading', 'normalX', 'normalY', 'curvature'];
+
+// JSON snapshots deliberately omit runtime indexes and compact sample objects
+// into a schema/table. Restore only display query infrastructure around that
+// supplied geometry. Never generate another track or reconstruct model senses.
+export function createExternalTrackSnapshotDecoder() {
+  let lastKey = null, lastTrack = null;
+  return {
+    decode(snapshot) {
+      const track = snapshot?.track;
+      if (!track || track.queryIndex || !Array.isArray(track.samples)) return snapshot;
+      const key = JSON.stringify(track);
+      if (key !== lastKey) {
+        const decoded = decodeTrack(track);
+        lastTrack = decoded;
+        lastKey = key;
+      }
+      return { ...snapshot, track: lastTrack };
+    },
+    reset() { lastKey = null; lastTrack = null; },
+  };
+}
+
+function decodeTrack(track) {
+  const schema = track.sampleSchema;
+  const samples = track.samples?.map((sample) => Array.isArray(sample) && Array.isArray(schema)
+    ? Object.fromEntries(schema.map((field, index) => [field, sample[index]]))
+    : { ...sample });
+  if (!Array.isArray(samples) || samples.length < 2 ||
+    !Number.isFinite(track.length) || track.length <= 0 ||
+    !Number.isFinite(track.width) || track.width <= 0 ||
+    samples.some((sample) => SAMPLE_FIELDS.some((field) => !Number.isFinite(sample[field])))) {
+    throw new Error('External track requires finite sample geometry, length and width.');
+  }
+  const decoded = { ...track, samples };
+  if (track.pitLane?.enabled) {
+    const pitLane = { ...track.pitLane };
+    pitLane.bounds ??= createPitLaneBounds(pitLane);
+    pitLane.boxBounds ??= createPitBoxBounds(pitLane);
+    pitLane.connectorBounds ??= createPitConnectorBounds(pitLane);
+    decoded.pitLane = pitLane;
+  }
+  attachTrackQueryIndex(decoded, createTrackQueryIndex(decoded));
+  prepareSampleIndexLut(decoded);
+  return decoded;
+}