@inventure71/paddockjs 3.0.0 → 4.1.0

package/docs/troubleshooting.md

@@ -0,0 +1,76 @@
+# Troubleshooting
+
+Use this when a host integration or package release check fails.
+
+## Raw Node Import Fails
+
+Do not use this as the main package check:
+
+```bash
+node -e "import('@inventure71/paddockjs')"
+```
+
+The root package is browser-oriented and imports CSS/assets. Use the browser-free subpaths in Node:
+
+```js
+import { createPaddockEnvironment } from '@inventure71/paddockjs/environment';
+import { DriverData } from '@inventure71/paddockjs/data';
+```
+
+## CSS Is Missing
+
+Import the package stylesheet from a browser entry when the host bundler does not extract it automatically:
+
+```js
+import '@inventure71/paddockjs/styles.css';
+```
+
+If styles are present but the simulator is squeezed or overlapping, check the host container size before changing package internals. PaddockJS supports roots at least `320px` wide and shows an `Unsupported size` placeholder below supported bounds.
+
+## Assets Do Not Resolve
+
+PaddockJS owns default simulator assets. Hosts should not copy them manually. In the package repo, verify publish contents with:
+
+```bash
+npm run pack:dry
+```
+
+In a host app, verify through the host's browser build rather than a raw Node import.
+
+## Simulator Looks Frozen
+
+Check whether browser expert mode is enabled:
+
+```js
+expert: { enabled: true, controlledDrivers: ['budget'] }
+```
+
+Expert mode intentionally waits for `simulator.expert.step(actions)`. Basic website mounts should omit `expert` unless they are playing back a model or debugging policy observations.
+
+## Policy Server Receives No Observations
+
+Policy Runner server mode uses protocol version `2`. `/policy/decide-batch`
+receives aligned compact arrays, not rich `observations`. Static specs,
+configuration, `previousActionFields`, and `metricFields` are sent once to
+`/policy/reset`, so servers should cache `observationSpec` and read model
+inputs from `body.vectors[index]` for `body.driverIds[index]` during decisions.
+
+## Theme Toggle Resets The Race
+
+Use runtime theme APIs instead of restarting:
+
+```js
+simulator.setThemeMode('dark');
+simulator.setTheme({ tokens: { primary: '#008c55' } });
+```
+
+`restart(nextOptions)` is for race/data/seed changes, not normal light/dark presentation sync.
+
+## 3.x Upgrade Symptoms
+
+- Remove host usage of `trackQueryIndex`; indexed track queries are package internals.
+- Replace old strict physics usage with `physicsMode: 'advanced'`, or omit `physicsMode` for the default `arcade` mode.
+- Use `@inventure71/paddockjs/environment` for headless simulation.
+- Use `@inventure71/paddockjs/data` for CSS-free data/tooling imports.
+
+See [Upgrading Hosts To PaddockJS 3.x](upgrading-hosts-to-3.md).

package/docs/upgrading-hosts-to-3.md

@@ -0,0 +1,42 @@
+# Upgrading Hosts To PaddockJS 4.x
+
+Use this checklist when moving a browser host website from 2.x-era PaddockJS usage to the 4.x package API.
+
+1. Install the 4.x package:
+
+   ```bash
+   npm install @inventure71/paddockjs@4
+   ```
+
+2. Import package CSS intentionally anywhere browser mounts are used:
+
+   ```js
+   import '@inventure71/paddockjs/styles.css';
+   ```
+
+   The stylesheet is scoped to PaddockJS roots and uses system fonts by default. Load any branded web fonts from the host app instead of relying on package-side remote font imports.
+
+3. Remove host usage of `trackQueryIndex`. Track query indexing is package-owned and internal in 4.x.
+
+4. Replace `physicsMode: 'simulator'` with `physicsMode: 'advanced'`, or omit `physicsMode` to keep the default `arcade` mode.
+
+5. Decide how the host should theme the simulator. Use mount-time `theme` for defaults, then use `simulator.setThemeMode(mode)` or `simulator.setTheme(theme)` for site light/dark toggles. Do not call `restart({ theme })` only to change presentation.
+
+6. Reuse public theme helpers instead of copying CSS variable names:
+
+   ```js
+   import {
+     PADDOCK_THEME_CSS_VARIABLES,
+     PADDOCK_THEME_TOKEN_KEYS,
+     applyPaddockTheme,
+     resolvePaddockTheme,
+   } from '@inventure71/paddockjs';
+   ```
+
+7. Decide whether the host should enable the driver camera with `ui.driverCamera: true` or `initialCameraMode: 'driver'`.
+
+8. Use `@inventure71/paddockjs/environment` for browser-free simulation/training imports.
+
+9. Use `@inventure71/paddockjs/data` for CSS-free data/helper imports such as `DriverData`, `normalizeSimulatorDrivers`, `createProceduralTrack`, and speed conversion helpers.
+
+10. Rebuild the host bundle and browser-smoke the host page, including theme toggles, selected-driver surfaces, and any composable mount roots.

package/examples/python/README.md

@@ -14,6 +14,8 @@ It is not a trainer and not a model/checkpoint format owner. It only shows trans
 - Preview latest-frame HTTP endpoint (for polling visualizers)
   - `http://127.0.0.1:8787/preview/frame`
 
+Policy HTTP uses protocol version `2`. `POST /policy/reset` receives static metadata (`actionSpec`, `observationSpec`, configuration) once per session. `POST /policy/decide-batch` is compact and receives `driverIds`, `vectors`, `previousActions`, `metrics`, and `events`; it does not receive rich observation objects, schemas, snapshots, or track metadata every decision.
+
 ## Run
 
 ```bash
@@ -55,6 +57,10 @@ Subclass `BasePolicyServer` and override:
 
 Use `broadcast_preview_frame(snapshot, observation, meta)` to push authoritative frames to the browser renderer.
 
+Inside `decide_batch(ctx)`, compact per-driver fields are aligned arrays:
+`ctx["vectors"][index]` belongs to `ctx["driverIds"][index]`. The base example's
+`compact_values_by_driver(ctx, "vectors")` helper maps them back to driver ids.
+
 ## Important Boundary
 
 - This server does not step the simulator by itself.

package/examples/python/base_policy_server.py

@@ -10,6 +10,9 @@ This file is intentionally minimal and transport-focused:
   - /preview (broadcasts {snapshot, observation, meta})
 
 Extend `BasePolicyServer` and override hook methods to plug your own model/runtime.
+Policy HTTP uses protocolVersion 2. Reset receives static specs/configuration;
+decide-batch receives compact per-driver vectors instead of rich observations.
+Compact per-driver fields are arrays aligned with driverIds.
 """
 
 from __future__ import annotations
@@ -33,6 +36,20 @@ def _zero_action() -> Dict[str, float]:
     }
 
 
+def compact_values_by_driver(context: Mapping[str, Any], field: str) -> Dict[str, Any]:
+    """Map a compact aligned field such as vectors/metrics back to driver ids."""
+    driver_ids = list(context.get("driverIds") or [])
+    values = context.get(field) or []
+    if isinstance(values, Mapping):
+        return {driver_id: values.get(driver_id) for driver_id in driver_ids}
+    if not isinstance(values, list):
+        return {driver_id: None for driver_id in driver_ids}
+    return {
+        driver_id: values[index] if index < len(values) else None
+        for index, driver_id in enumerate(driver_ids)
+    }
+
+
 @dataclass
 class ServerState:
     session_id: int = 0
@@ -70,6 +87,8 @@ class BasePolicyServer:
     async def decide_batch(self, context: Mapping[str, Any]) -> Dict[str, Dict[str, float]]:
         """Return per-driver controls for one batched policy step."""
         driver_ids = list(context.get("driverIds") or [])
+        vectors_by_driver = compact_values_by_driver(context, "vectors")
+        _ = vectors_by_driver
         return {driver_id: _zero_action() for driver_id in driver_ids}
 
     async def publish_preview_frame(self, frame: Mapping[str, Any]) -> None:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inventure71/paddockjs",
-  "version": "3.0.0",
+  "version": "4.1.0",
   "type": "module",
   "description": "A data-driven browser F1 simulator component for host websites.",
   "license": "Apache-2.0",
@@ -24,7 +24,8 @@
     "ui-component"
   ],
   "sideEffects": [
-    "./src/styles.css"
+    "./src/styles.css",
+    "./src/placeholder.css"
   ],
   "publishConfig": {
     "access": "public"
@@ -45,7 +46,18 @@
       "import": "./src/environment/index.js",
       "default": "./src/environment/index.js"
     },
-    "./styles.css": "./src/styles.css"
+    "./data": {
+      "types": "./src/data/index.d.ts",
+      "import": "./src/data/index.js",
+      "default": "./src/data/index.js"
+    },
+    "./placeholder": {
+      "types": "./src/placeholder/index.d.ts",
+      "import": "./src/placeholder/index.js",
+      "default": "./src/placeholder/index.js"
+    },
+    "./styles.css": "./src/styles.css",
+    "./placeholder.css": "./src/placeholder.css"
   },
   "files": [
     "CHANGELOG.md",
@@ -63,25 +75,29 @@
     "src/config",
     "src/data",
     "src/environment",
+    "src/placeholder",
     "src/rendering",
     "src/simulation",
     "src/ui",
     "src/index.d.ts",
     "src/index.js",
     "src/styles.css",
+    "src/placeholder.css",
     "README.md"
   ],
   "scripts": {
     "test": "node scripts/run-vitest.mjs --slow",
     "test:fast": "node scripts/run-vitest.mjs",
     "types:check": "tsc -p tsconfig.types.json --noEmit",
-    "check": "npm run test:fast && npm run types:check && npm run pack:dry && npm run consumer:smoke && npm run showcase:ci && npm run browser:smoke:quick -- --skip-build",
-    "check:release": "npm test && npm run types:check && npm run pack:dry && npm run consumer:smoke && npm run showcase:ci && npm run browser:smoke:full -- --skip-build",
+    "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 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 showcase:ci && npm run browser:smoke:full -- --skip-build",
     "pack:dry": "npm pack --dry-run",
     "consumer:smoke": "node scripts/consumer-package-smoke.mjs",
     "browser:smoke": "node smoke/browser-smoke.mjs",
     "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",

package/src/api/PaddockSimulatorController.js

@@ -22,6 +22,7 @@ import { applyPaddockThemeCssVariables, resolveF1SimulatorOptions } from '../con
 import { formatCssUrl } from '../config/cssValues.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)) {
@@ -29,10 +30,10 @@ function assertMountTarget(root, label) {
   }
 }
 
-function setPackageCssVariables(root, assets, theme) {
+function setPackageCssVariables(root, assets, theme, context = {}) {
   root.classList?.add?.('f1-sim-component');
   root.style?.setProperty?.('--broadcast-panel-surface', formatCssUrl(assets.broadcastPanel));
-  applyPaddockThemeCssVariables(root, theme);
+  applyPaddockThemeCssVariables(root, theme, context);
 }
 
 function createCompositeRoot(getRoots, getOptions) {
@@ -41,6 +42,9 @@ function createCompositeRoot(getRoots, getOptions) {
       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()) {
@@ -58,9 +62,9 @@ function createCompositeRoot(getRoots, getOptions) {
     removeAttribute(name) {
       getRoots().forEach((root) => root.removeAttribute?.(name));
     },
-    applyCssVariables() {
+    applyCssVariables(context = {}) {
       const options = getOptions();
-      getRoots().forEach((root) => setPackageCssVariables(root, options.assets, options.theme));
+      getRoots().forEach((root) => setPackageCssVariables(root, options.assets, options.theme, context));
     },
   };
 }
@@ -69,38 +73,41 @@ 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);
   }
 
-  mountComponent(root, key, markup) {
+  mountComponent(root, key, createMarkup) {
     assertMountTarget(root, `mount ${key}`);
     if (this.app) {
       throw new Error('Mount PaddockJS components before calling start().');
     }
-    root.innerHTML = markup;
+    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;
   }
 
   mountRaceControls(root) {
-    return this.mountComponent(root, 'race-controls', createRaceControlsMarkup(this.options));
+    return this.mountComponent(root, 'race-controls', () => createRaceControlsMarkup(this.options));
   }
 
   mountCameraControls(root) {
-    return this.mountComponent(root, 'camera-controls', createCameraControlsMarkup(this.options));
+    return this.mountComponent(root, 'camera-controls', () => createCameraControlsMarkup(this.options));
   }
 
   mountSafetyCarControl(root) {
-    return this.mountComponent(root, 'safety-car-control', createSafetyCarControlMarkup(this.options));
+    return this.mountComponent(root, 'safety-car-control', () => createSafetyCarControlMarkup(this.options));
   }
 
   mountTimingTower(root) {
-    return this.mountComponent(root, 'timing-tower', createTimingTowerMarkup(this.options));
+    return this.mountComponent(root, 'timing-tower', () => createTimingTowerMarkup(this.options));
   }
 
   mountRaceCanvas(root, {
@@ -110,7 +117,7 @@ export class PaddockSimulatorController {
     timingTowerVerticalFit,
     responsiveNarrowLayout,
   } = {}) {
-    return this.mountComponent(root, 'race-canvas', createRaceCanvasMarkup({
+    return this.mountComponent(root, 'race-canvas', () => createRaceCanvasMarkup({
       ...this.options,
       includeRaceDataPanel,
       includeTimingTower,
@@ -121,39 +128,39 @@ export class PaddockSimulatorController {
   }
 
   mountTelemetryPanel(root, { includeOverview } = {}) {
-    return this.mountComponent(root, 'telemetry-stack', createTelemetryPanelMarkup(this.options, { includeOverview }));
+    return this.mountComponent(root, 'telemetry-stack', () => createTelemetryPanelMarkup(this.options, { includeOverview }));
   }
 
   mountTelemetryCore(root) {
-    return this.mountComponent(root, 'telemetry-core', createTelemetryCoreMarkup(this.options));
+    return this.mountComponent(root, 'telemetry-core', () => createTelemetryCoreMarkup(this.options));
   }
 
   mountTelemetrySectors(root) {
-    return this.mountComponent(root, 'telemetry-sectors', createTelemetrySectorsMarkup(this.options));
+    return this.mountComponent(root, 'telemetry-sectors', () => createTelemetrySectorsMarkup(this.options));
   }
 
   mountTelemetryLapTimes(root) {
-    return this.mountComponent(root, 'telemetry-lap-times', createTelemetryLapTimesMarkup(this.options));
+    return this.mountComponent(root, 'telemetry-lap-times', () => createTelemetryLapTimesMarkup(this.options));
   }
 
   mountTelemetrySectorTimes(root) {
-    return this.mountComponent(root, 'telemetry-sector-times', createTelemetrySectorTimesMarkup(this.options));
+    return this.mountComponent(root, 'telemetry-sector-times', () => createTelemetrySectorTimesMarkup(this.options));
   }
 
   mountTelemetrySectorBanner(root) {
-    return this.mountComponent(root, 'telemetry-sector-banner', createTelemetrySectorBannerMarkup(this.options));
+    return this.mountComponent(root, 'telemetry-sector-banner', () => createTelemetrySectorBannerMarkup(this.options));
   }
 
   mountRaceTelemetryDrawer(root, options = {}) {
-    return this.mountComponent(root, 'race-telemetry-drawer', createRaceTelemetryDrawerMarkup(this.options, options));
+    return this.mountComponent(root, 'race-telemetry-drawer', () => createRaceTelemetryDrawerMarkup(this.options, options));
   }
 
   mountCarDriverOverview(root) {
-    return this.mountComponent(root, 'car-driver-overview', createCarDriverOverviewMarkup(this.options));
+    return this.mountComponent(root, 'car-driver-overview', () => createCarDriverOverviewMarkup(this.options));
   }
 
   mountRaceDataPanel(root) {
-    return this.mountComponent(root, 'race-data-panel', createRaceDataPanelMarkup({
+    return this.mountComponent(root, 'race-data-panel', () => createRaceDataPanelMarkup({
       ...this.options,
       standalone: true,
     }));
@@ -188,6 +195,17 @@ export class PaddockSimulatorController {
       root.innerHTML = '';
     });
     this.roots.clear();
+    this.mountRenderers.clear();
+  }
+
+  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));
+    });
   }
 
   syncOptionsFromRunningApp() {
@@ -207,12 +225,50 @@ export class PaddockSimulatorController {
     const currentOptions = this.app ? this.syncOptionsFromRunningApp() : this.options;
     const nextResolvedOptions = resolveF1SimulatorOptions(mergeRestartOptions(currentOptions, nextOptions));
     if (this.app) {
-      this.app.restart(nextResolvedOptions);
+      const previousOptions = this.options;
       this.options = nextResolvedOptions;
+      try {
+        this.app.restart(nextResolvedOptions);
+      } catch (error) {
+        this.options = previousOptions;
+        throw error;
+      }
       return;
     }
     this.options = nextResolvedOptions;
-    this.compositeRoot.applyCssVariables();
+    this.rerenderMountedComponents();
+  }
+
+  setTheme(themeInput = {}) {
+    const currentOptions = this.app ? this.syncOptionsFromRunningApp() : this.options;
+    const nextResolvedOptions = resolveRuntimeThemeOptions(currentOptions, themeInput);
+    this.options = nextResolvedOptions;
+    if (this.app?.setTheme) {
+      this.app.setTheme(nextResolvedOptions.theme);
+    } else {
+      this.compositeRoot.applyCssVariables();
+    }
+    return nextResolvedOptions.theme;
+  }
+
+  setThemeMode(mode) {
+    const currentOptions = this.app ? this.syncOptionsFromRunningApp() : this.options;
+    const nextResolvedOptions = resolveRuntimeThemeModeOptions(currentOptions, mode);
+    this.options = nextResolvedOptions;
+    if (this.app?.setTheme) {
+      this.app.setTheme(nextResolvedOptions.theme);
+    } else {
+      this.compositeRoot.applyCssVariables();
+    }
+    return nextResolvedOptions.theme;
+  }
+
+  getTheme() {
+    return this.options.theme;
+  }
+
+  syncThemeFrom(source, options = {}) {
+    return createThemeSync(this, source, options);
   }
 
   selectDriver(driverId) {

package/src/api/runtimeTheme.js

@@ -0,0 +1,59 @@
+import { resolveF1SimulatorOptions } from '../config/defaultOptions.js';
+import { mergeThemeInputs } from '../config/themeOptions.js';
+
+export function resolveRuntimeThemeOptions(currentOptions, themeInput = {}) {
+  return resolveF1SimulatorOptions({
+    ...currentOptions,
+    theme: mergeThemeInputs(currentOptions?.theme, themeInput),
+  });
+}
+
+export function resolveRuntimeThemeModeOptions(currentOptions, mode) {
+  return resolveRuntimeThemeOptions(currentOptions, { mode });
+}
+
+export function createThemeSync(simulator, source, {
+  attribute = 'data-theme',
+  map,
+} = {}) {
+  if (!source || typeof source !== 'object') {
+    throw new Error('syncThemeFrom requires a DOM element or attribute source.');
+  }
+
+  const readValue = () => {
+    const rawValue = typeof source.getAttribute === 'function'
+      ? source.getAttribute(attribute)
+      : source?.dataset?.[attributeToDatasetKey(attribute)];
+    if (map && Object.hasOwn(map, rawValue)) return map[rawValue];
+    return rawValue;
+  };
+
+  const sync = () => {
+    const value = readValue();
+    if (value && typeof value === 'object') {
+      simulator.setTheme(value);
+      return;
+    }
+    simulator.setThemeMode(typeof value === 'string' && value !== '' ? value : 'dark');
+  };
+
+  sync();
+
+  const Observer = globalThis.MutationObserver;
+  if (typeof Observer !== 'function' || typeof source.getAttribute !== 'function') {
+    return () => {};
+  }
+
+  const observer = new Observer(sync);
+  observer.observe(source, {
+    attributes: true,
+    attributeFilter: [attribute],
+  });
+  return () => observer.disconnect();
+}
+
+function attributeToDatasetKey(attribute) {
+  return String(attribute)
+    .replace(/^data-/, '')
+    .replace(/-([a-z])/g, (_, letter) => letter.toUpperCase());
+}

package/src/app/F1SimulatorApp.js

@@ -301,7 +301,8 @@ export class F1SimulatorApp {
       this.emitHostCallback('onReady', { snapshot });
       this.resizeHandler = () => {
         this.syncTimingPanelDisclosureState();
-        this.applyCamera(this.sim.snapshotRender?.() ?? this.sim.snapshot());
+        this.renderSourceSnapshotBuffer ??= {};
+        this.applyCamera(this.sim.snapshotRenderInto?.(this.renderSourceSnapshotBuffer) ?? this.sim.snapshotRender?.() ?? this.sim.snapshot());
       };
       window.addEventListener('resize', this.resizeHandler, { signal: this.abortController.signal });
       this.observeLayoutResize();
@@ -606,7 +607,8 @@ export class F1SimulatorApp {
 
   syncRendererToCurrentLayout({ render = false } = {}) {
     this.resizeRendererToCanvasHost();
-    const snapshot = this.sim?.snapshotRender?.() ?? this.sim?.snapshot?.();
+    this.renderSourceSnapshotBuffer ??= {};
+    const snapshot = this.sim?.snapshotRenderInto?.(this.renderSourceSnapshotBuffer) ?? this.sim?.snapshotRender?.() ?? this.sim?.snapshot?.();
     if (!snapshot) return;
     const renderSnapshot = interpolateRenderSnapshotInto(
       this.renderSnapshotBuffer,
@@ -1191,7 +1193,26 @@ export class F1SimulatorApp {
     const contextKey = selectedTeamId ?? '';
     if (this.lastThemeContextKey === contextKey) return;
     this.lastThemeContextKey = contextKey;
-    applyPaddockThemeCssVariables(this.root, this.options.theme, { selectedTeamId });
+    const context = { selectedTeamId };
+    if (typeof this.root?.applyCssVariables === 'function') {
+      this.root.applyCssVariables(context);
+      return;
+    }
+    applyPaddockThemeCssVariables(this.root, this.options.theme, context);
+  }
+
+  setTheme(theme) {
+    this.options = {
+      ...this.options,
+      theme,
+    };
+    this.lastThemeContextKey = null;
+    this.syncThemeContext(this.getSnapshot());
+    return this.options.theme;
+  }
+
+  getTheme() {
+    return this.options.theme;
   }
 
   getSelectedTeamId(snapshot = null) {