@inventure71/paddockjs 2.0.1 → 4.0.0

package/docs/training.md

@@ -46,6 +46,7 @@ The current expert API is a JavaScript environment contract. It supports:
 - reset-only scenario placement through `scenario.preset`, `scenario.placements`, `scenario.traffic`, and episode-boundary `resetDrivers(placements)`
 - multi-car interaction profiles through `participantInteractions`, including no-collision training cars that are hidden from other cars' ray and nearby-car sensors by default
 - per-driver episode state and neutral step metrics for batched training loops
+- `episode.maxSteps` as a controlled-driver episode safety horizon; the default is high for browser/expert usability, so training and evaluation loops should set an explicit smaller value
 - neutral rollout recording through `createRolloutRecorder()`
 - deterministic evaluation metrics through `runEnvironmentEvaluation()` and `createEvaluationTracker()`
 - a JSON-serializable worker protocol wrapper through `createEnvironmentWorkerProtocol()`
@@ -93,7 +94,7 @@ Use a user-owned controller for browser playback and JavaScript training-style l
 ```js
 import {
   createPaddockDriverControllerLoop,
-} from '@inventure71/paddockjs';
+} from '@inventure71/paddockjs/environment';
 
 const controller = {
   async init(ctx) {
@@ -155,15 +156,15 @@ built-in driver applied. This is intended for audits or clean local imitation
 datasets; it does not blend built-in AI with a model during normal controlled
 stepping.
 
-For model training, prefer `physicsMode: 'simulator'` so the policy learns against the same grip, yaw-rate, contact-patch, kerb, and runoff behavior exposed by those senses. Arcade physics can still be useful as a debugging baseline, but it should not be treated as the main training target for realistic driver policies.
+For model training, prefer `physicsMode: 'advanced'` so the policy learns against the same grip, yaw-rate, contact-patch, kerb, and runoff behavior exposed by those senses. Arcade physics can still be useful as a debugging baseline, but it should not be treated as the main training target for realistic driver policies.
 
-Surface-aware rays are opt-in because they are more expensive than the default road-edge/car channels. The environment normalizes both the legacy compact ray shape and the newer per-ray layout:
+Surface-aware rays are opt-in because they are more expensive than the default road-edge/car channels. The environment normalizes both the compact ray shape and the newer per-ray layout:
 
 ```js
 const env = createPaddockEnvironment({
   drivers,
   controlledDrivers: ['budget'],
-  physicsMode: 'simulator',
+  physicsMode: 'advanced',
   observation: { profile: 'physical-driver' },
   sensors: {
     rays: {
@@ -181,13 +182,15 @@ const env = createPaddockEnvironment({
 
 Only requested ray channels are computed. The default compact config still computes the existing road-edge and car readings, so existing policy vectors keep their current shape unless the profile or sensor config opts into richer fields. Barrier walls are not a ray channel; they are visible track geometry and a terminal destruction condition in both physics modes. Active ray objects, vectors, schemas, and visualizations must not expose barrier ray fields.
 
-`precision: 'driver'` is the default and the recommended model-facing ray contract. It returns the normal sampled driver-sensor distances without extra refinement. `precision: 'debug'` exists only for clearly labeled diagnostics with additional edge refinement. If the Policy Runner or expert visualization is showing model senses, it must render the active observation values exactly and must not replace them with debug-precision readings.
+`precision: 'driver'` is the default and the recommended model-facing ray contract. Safe main-track road-edge, kerb, and illegal-surface rays use direct indexed boundary intersections against the same surface bands used by wheel surfaces and rendering. Normal driver rays validate direct candidates against driver-precision track state; the `batch-training` profile keeps the accelerated direct indexed contract for safe main-track rays. Surface-only batch-training rays also reuse same-pose `progress`/`signedOffset` origin-state synthesis plus shared surface-hit and track-band boundary scratch, so kerb/illegal-surface vector batches avoid nearest-track origin classification and per-ray hit-object replacement. Recovery rays can also use the direct path when the indexed boundary is validated against driver-precision track state, including barrier-to-runoff illegal-surface recovery and off-track road/kerb re-entry. Low-curvature recovery and validation samples may reuse the origin segment to stay off generic nearest-track classification, while curved ambiguous recovery, pit-connector, and pit-lane-origin rays stay inside the ray-band tracer and use one bounded sampled validation pass for all requested road/surface channels instead of falling back to separate legacy road and surface scans. `precision: 'debug'` uses the same tracer-owned path with additional sampled refinement for clearly labeled diagnostics; only missing-index cases use the older sampled fallback path. If the Policy Runner or expert visualization is showing model senses, it must render the active observation values exactly and must not replace them with debug-precision readings.
+
+Scratch-backed driver ray batches keep requested-channel dispatch in reusable scalar channel flags rather than rebuilding channel `Set` containers per ray. The indexed boundary traversal also reuses one query-index sample point across ray-grid steps instead of allocating temporary points. The runtime benchmark gate enforces zero channel-set allocations, stable channel-flag containers, and sample-point reuse for the common direct ray path.
 
 When a full observation includes both `object` and `vector`, Policy Runner model inputs that need ray geometry use the observation object's actual `angleDegrees` and `lengthMeters`. Compact vector schemas intentionally carry ray channel values, not out-of-band ray geometry, so consumers with per-driver sensor overrides must read the active object observation or the exact per-driver spec instead of reconstructing layout from a default preset.
 
 The model-facing sense proof boundary is documented in [Model Sense Contract](sense_contract.md). The executable contract test compares object observations against independent simulator-snapshot oracles, decodes vector entries by schema name, and checks compact vector-only output against full output for the same deterministic state. New model-facing sense fields must extend that oracle instead of relying only on snapshot or shape tests.
 
-Track-position, wheel-surface, pit-lane, and ray fallback queries can be backed by an internal startup-built track query index. Browser/expert mounts, headless environments, and direct race-simulation construction now default to indexed queries and can opt out with `trackQueryIndex: false` for comparison runs. Compact vector-only, schema-free, no-state environment runs enable that index on the environment-owned simulation, and `batch-training` ray runs keep it enabled even when full state output is returned for inspection. Internal benchmarks can explicitly compare indexed and legacy-disabled modes. This does not change the observation shape. For normal driver interactions, ray `precision: 'driver'` keeps sampled road-edge, kerb, and illegal-surface distances with or without the index, preserving zero-distance origin surface hits and avoiding debug-only precision in policy inputs. The `batch-training` participant profile keeps its indexed recovery-ray path as a separate high-throughput training contract with characterization coverage. Indexed ray-boundary shortcuts remain available to non-driver/debug precision paths.
+Track-position, wheel-surface, pit-lane, and ray queries use the internal startup-built track query index. Browser/expert mounts, headless environments, direct race-simulation construction, compact vector-only training loops, and `batch-training` ray runs all use that canonical indexed path. Indexed pit-road state resolution reuses route candidate buckets, one polyline projection result, and index-owned cumulative route distance tables for entry, fast-lane, working-lane, and exit classification; connector-adjacent direct pit-entry/pit-exit shortcut checks reuse that same projection target and route metadata. Endpoint-progress shortcut checks use precomputed route endpoint segment windows, while mid-connector points use bounded indexed route candidates without becoming full pit-lane queries. The runtime track-query benchmark explicitly probes those pit-road routes and requires direct connector scratch reuse, positive endpoint-window connector projections, zero connector full-route projection scans, grid hits, scratch reuse, precomputed route distances, zero cumulative-distance rebuilds, zero road-grid misses, and zero pit fallbacks. This does not change the observation shape. Ray `precision: 'driver'` uses indexed projection plus driver-precision validation for road-edge, kerb, and illegal-surface distances, preserving zero-distance origin surface hits and avoiding debug-only refinement in policy inputs. The internal ray-band tracer reports whether a ray used the pure `direct` path or bounded `sampled` recovery so benchmarks can catch regressions without changing public ray objects or vectors. Debug precision remains available only for explicitly labeled diagnostics.
 
 `resetDrivers()` is part of episode control, not policy action. After reset placement, the environment immediately reclassifies the selected cars against the same runoff/barrier rules used during stepping before building observations. Recovery starts inside the legal recovery band remain normal physical starts. Placements that are already inside the barrier destruction boundary return a terminal per-driver episode state and miss-valued rays, so a batch loop can assign its own negative reward and reset that driver without paying for far-out ray geometry. In multi-driver batches, top-level `done` is true once every reported controlled driver is terminal, including mixed states where one driver is terminated and another is max-step truncated; per-driver `info.drivers[driverId]` keeps the distinct reason.
 
@@ -287,6 +290,8 @@ Use that override deliberately. The default no-collision training profile is sen
 
 Compact vector mode is intended for high-throughput loops. `env.getObservationSpec()` remains the canonical schema source, so external code can request `output: 'vector'` and `includeSchema: false` without serializing object observations and schema data on every step. If `sensorsByDriver` changes ray or nearby-car shape for specific drivers, read `observationSpec.perDriver[driverId].vector.schema` for that driver's exact compact schema. JavaScript training loops can also request `vectorType: 'float32'` for typed numeric buffers. Keep the default array output for JSON-only bridges unless the bridge explicitly packs typed arrays.
 
+The HTTP Policy Runner server path uses this compact convention by default. `/policy/reset` sends `protocolVersion: 2` plus static metadata, `previousActionFields`, and `metricFields` once, and `/policy/decide-batch` sends only `driverIds` plus aligned `vectors`, `previousActions`, `metrics`, and `events` arrays. Servers should read model inputs from `body.vectors[index]` where `body.driverIds[index]` is the driver being evaluated; `previousActions[index]` is a `[steering, throttle, brake]` tuple for the same driver, and `metrics[index]` follows the reset-time `metricFields` order. Rich observation objects and schemas are no longer repeated on every decision. This is a breaking transport contract for policy-server integrations. There is no rich per-decision fallback in Policy Runner server mode; use object/full observation output only in local JavaScript, headless, debug, or explicit state/export flows.
+
 Use `result.stateOutput` to avoid returning more state than the loop needs:
 
 ```js
@@ -304,19 +309,23 @@ const env = createPaddockEnvironment({
 
 `stateOutput: 'minimal'` returns the lean public observation snapshot. `stateOutput: 'none'` returns `state: null`. The default is still `full` for existing callers. `resetDriversObservationScope: 'reset'` also scopes `info.controlledDrivers` to the drivers present in that reset result's `observation` and `metrics`; use `info.drivers` if you need all configured drivers' episode bookkeeping. When `stateOutput: 'none'`, `observation.output: 'vector'`, and `includeSchema: false`, the environment uses an internal compact training snapshot before building observations and metrics. That optimization is not exposed as policy state. Reward callbacks still receive the documented reward context on `step(actions)`, and reset/read calls remain reward-neutral.
 
-Simulator-mode velocity senses are authoritative only when the simulator owns a real world velocity. Arcade snapshots intentionally expose `velocityX/Y` as `null`. When simulator-mode cars are terminal or held by race control, grid logic, or pit queue logic, the environment freezes scalar speed and `velocityX/Y` together at zero instead of carrying old motion into observations or recorded transitions.
+Advanced-mode velocity senses are authoritative only when the simulator owns a real world velocity. Arcade snapshots intentionally expose `velocityX/Y` as `null`. When advanced-mode cars are terminal or held by race control, grid logic, or pit queue logic, the environment freezes scalar speed and `velocityX/Y` together at zero instead of carrying old motion into observations or recorded transitions.
 
-On the local 20-car batch-training benchmark used for this package work (`physicsMode: 'simulator'`, `frameSkip: 4`, `physical-driver`, `driver-front-heavy` rays), the measured environment action cost after compact output and indexed track queries was approximately:
+On the local 3.0.0-to-4.0.0 comparison runs (`physicsMode: 'advanced'`, `physical-driver`, `driver-front-heavy` rays, procedural worst-seed checks, and vector observations), the current engine-style paths measured as a net runtime improvement in real environment stepping:
 
 ```txt
-nearest track states                   1.52x faster than legacy-disabled
-pit lane states                        2.02x faster than legacy-disabled
-sampled high-curvature off-track rays  14.81x faster than legacy-disabled
-wheel surface near pit connector       1.12x faster than legacy-disabled
-20-car batch recovery environment      1.03x faster than legacy-disabled
+20-car race step                       4.67x faster than 3.0.0
+normal env, seed 104729                4.05x faster than 3.0.0
+normal env, seed 4101                  1.45x faster than 3.0.0
+normal env, seed 47                    5.07x faster than 3.0.0
+batch-training env, worst seeds        1.32x-1.39x faster than 3.0.0
+wheel surface near pit connector       89.27x faster than 3.0.0
+snapshot JSON, 20 cars                 4.21x faster than 3.0.0
 ```
 
-These numbers are hardware- and track-dependent, but the relative result is the useful guidance: compact state/observation output reduces serialization/allocation overhead, and indexed track queries prevent off-track recovery rays from becoming the dominant cost center.
+Those numbers are hardware- and track-dependent, but the relative result is the useful guidance: compact state/observation output reduces serialization/allocation overhead, indexed track queries prevent off-track recovery rays from becoming the dominant cost center in real environment loops, and direct indexed ray-band intersections keep common driver-precision road/surface rays off the expensive sampled nearest-query path. The high-volume seed sweep covered 69 procedural seeds, 447,120 ray builds, 3,129,840 individual rays, 149,040 wheel-surface classifications, and 1,380 environment steps with zero invalid ray payloads, zero invalid environment observations, zero invalid wheel classifications, and zero nearest/pit fallbacks.
+
+There is one deliberate microbenchmark caveat: adversarial standalone `buildRaySensors()` sweeps that force normal-profile rays from kerb, gravel, and runoff poses on complex generated tracks can be slower than 3.0.0 because the current path performs more bounded indexed exact validation to preserve driver-precision surface semantics. On the worst checked seeds, real environment stepping still measured faster than 3.0.0. Treat the standalone ray torture case as a precision/diagnostic stress test, not the expected training-loop cost.
 
 ## Scenario Reset Control
 
@@ -404,7 +413,7 @@ recorder.recordStep(result, action, next);
 
 Each transition has `{ observation, action, reward, nextObservation, terminated, truncated, info }`. If the environment has no reward callback, `reward` is still `null`; the recorder does not invent one. Recorded transitions snapshot arrays, typed vectors, actions, observations, rewards, and info at record time, so later policy-loop mutations do not rewrite previous rollout rows.
 
-Environment step results also include reward-neutral `metrics[driverId]` facts such as progress delta, legal progress delta, kerb use, illegal/off-track state, severe cuts, destruction state, under-30-kph state, spin/backwards/instability state, lap completion, lap time, and contact count. `spinOrBackwards` is true for large heading-error backwards cases and for active simulator instability labels such as `spin-risk`, `understeer`, `oversteer`, and `destroyed`. `contactCount` counts each normalized physical contact event once per involved driver even when the event carries both legacy `carId`/`otherCarId` fields and normalized `driverIds`. These metrics are facts for logging, evaluation, and user-defined reward functions; PaddockJS does not turn them into a built-in objective. If a car touches the rendered barrier wall's inner face in either physics mode, that driver receives `metrics[driverId].destroyed: true` and `info.drivers[driverId].endReason: 'destroyed'`; external training code should assign any super-negative crash reward itself and then call `resetDrivers()` for the next episode. If opt-in `rules.modules.stalledDnf.enabled: true` retires a controlled car for being stuck off legal surfaces, the episode terminates with `endReason: 'stalled-off-track'` while `metrics[driverId].destroyed` stays `false`.
+Environment step results also include reward-neutral `metrics[driverId]` facts such as progress delta, legal progress delta, kerb use, illegal/off-track state, severe cuts, destruction state, under-30-kph state, spin/backwards/instability state, lap completion, lap time, and contact count. `spinOrBackwards` is true for large heading-error backwards cases and for active simulator instability labels such as `spin-risk`, `understeer`, `oversteer`, and `destroyed`. `contactCount` counts each normalized physical contact event once per involved driver even when the event carries older `carId`/`otherCarId` fields and normalized `driverIds`. These metrics are facts for logging, evaluation, and user-defined reward functions; PaddockJS does not turn them into a built-in objective. If a car touches the rendered barrier wall's inner face in either physics mode, that driver receives `metrics[driverId].destroyed: true` and `info.drivers[driverId].endReason: 'destroyed'`; external training code should assign any super-negative crash reward itself and then call `resetDrivers()` for the next episode. If opt-in `rules.modules.stalledDnf.enabled: true` retires a controlled car for being stuck off legal surfaces, the episode terminates with `endReason: 'stalled-off-track'` while `metrics[driverId].destroyed` stays `false`.
 
 Deterministic evaluation helpers report simulator quality metrics such as distance, off-track steps, contacts, recovery success, pass count, and first lap time when available. They use the same wheel-level legal-surface and contact-event semantics as environment metrics. `runEnvironmentEvaluation()` can accept compact base options with `result.stateOutput: 'none'`; it internally requests the minimal snapshot needed for evaluation bookkeeping. Direct `createEvaluationTracker(result)` calls require a result with `state.snapshot`, so use `stateOutput: 'minimal'` or `full` for manual tracker wiring. Evaluation helpers do not update a model or compute rewards.
 
@@ -415,10 +424,8 @@ Deterministic evaluation helpers report simulator quality metrics such as distan
 ## Visual Playback Loop
 
 ```js
-import {
-  createPaddockDriverControllerLoop,
-  mountF1Simulator,
-} from '@inventure71/paddockjs';
+import { createPaddockDriverControllerLoop } from '@inventure71/paddockjs/environment';
+import { mountF1Simulator } from '@inventure71/paddockjs';
 
 const simulator = await mountF1Simulator(root, {
   drivers,

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": "2.0.1",
+  "version": "4.0.0",
   "type": "module",
   "description": "A data-driven browser F1 simulator component for host websites.",
   "license": "Apache-2.0",
@@ -45,6 +45,11 @@
       "import": "./src/environment/index.js",
       "default": "./src/environment/index.js"
     },
+    "./data": {
+      "types": "./src/data/index.d.ts",
+      "import": "./src/data/index.js",
+      "default": "./src/data/index.js"
+    },
     "./styles.css": "./src/styles.css"
   },
   "files": [
@@ -75,13 +80,15 @@
     "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",