@inventure71/paddockjs 4.1.0 → 4.3.0

package/docs/data_contract.md

@@ -2,6 +2,10 @@
 
 This file documents the data that host websites pass into PaddockJS.
 
+`gridWalk?: { enabled?: boolean, initialView?: 'grid-walk' | 'race', ambientMotion?: boolean }` enables [Grid Walk](grid_walk.md). Defaults are disabled, Grid Walk initial view when enabled, and ambient motion enabled. `SimulatorDriver` and `ChampionshipEntryBlueprint` accept `presentation?: EntryPresentation` with optional `name`, `summary`, `technologies: string[]`, `details: string[]`, `image: { src, alt? }`, `href` and `linkLabel`. Matching entry metadata overrides driver metadata. Full driver names, legacy `raceData` and `link` are compatible fallbacks. URLs are normalized and text is escaped; Grid Walk links are anchors independent of `onDriverOpen`. Its shared race banner displays name/summary/link content only; technologies, details and image remain accepted metadata but are not rendered in an extra inspector.
+
+Grid Walk mode controls are a separate presentation surface: `simulator.mountViewControls(controlsRoot)` or `mountViewControls(controlsRoot, simulator)`. Mount it before `start()` alongside a standalone race canvas; the all-in-one shell and race telemetry drawer compose it automatically above the scene. Its buttons share the controller's `getView()` / `setView()` state, stay disabled during startup and hide when Grid Walk is disabled. `ui.viewControls: 'switch' | 'toggle'` chooses the default two-button switch or a single Start race / Stop race action. Stop pauses exact race progress and shows the original starting grid using display poses; Start resumes saved progress. Both variants use the same mounting API, including after restart. No host-specific routing is required.
+
 ## Mount Options
 
 All-in-one API:
@@ -136,7 +140,7 @@ result = env.step({
 `controlledDrivers` is required. It supports one or many externally controlled cars. Non-controlled participants use the built-in driver AI in the stable 1.0 environment API.
 `externalRenderer` is optional and observer-only. It can be a function or `{ onFrame(frame) }`, and receives `{ snapshot, observation, meta }` on `reset`, `step`, and `resetDrivers`. The hook does not mutate simulation state and hook failures are isolated so stepping continues.
 `warmup` is optional and enabled by default. It primes a disposable runtime during load/reset creation and caches by configuration fingerprint so repeated identical resets skip warmup. Use `warmup: { enabled, policy: 'config-change' | 'always' | 'never', steps }` or `warmup: false` to disable.
-`physicsMode` is optional and accepts `'arcade'` or `'advanced'`. Invalid values, including the removed old `'simulator'` name, fall back to `'arcade'`, which is the default compatibility mode. `'advanced'` keeps the same public action contract but uses stricter 2D velocity/yaw dynamics and exposes additional telemetry fields on snapshots and observations: `velocityX`, `velocityY`, `lateralG`, `longitudinalG`, `gripUsage`, `slipAngleRadians`, `tractionLimited`, and `stabilityState`. In advanced mode, `slipAngleRadians` is derived from the car heading versus actual velocity direction, and mixed wheel surfaces are averaged for physics while wheel snapshots still report each contact patch. Terminal and race-control-held advanced-mode cars publish `velocityX: 0` and `velocityY: 0` whenever scalar `speed` is zero, so training loops do not see stale pre-DNF, pre-grid, pre-red-flag, or pre-queue motion. Arcade snapshots publish `velocityX` and `velocityY` as `null`; consumers that need a heading-aligned arcade velocity should derive it from `heading` and `speed`.
+`physicsMode` is optional and accepts `'arcade'` or `'advanced'`. Invalid values, including the removed old `'simulator'` name, fall back to `'arcade'`, which is the default compatibility mode. `'advanced'` keeps the same public action contract but uses four-contact force and yaw-inertia dynamics and exposes additional telemetry fields on snapshots and observations: `velocityX`, `velocityY`, `lateralG`, `longitudinalG`, `gripUsage`, `slipAngleRadians`, `tractionLimited`, and `stabilityState`. In advanced mode, `slipAngleRadians` is derived from the car heading versus actual velocity direction, and each wheel contributes forces from its own surface and normal load; wheel snapshots retain their existing contact-patch shape. `gripUsage` is the maximum requested combined force divided by adhesion over the four contacts; it can exceed one. `tractionLimited` flags this demand threshold, while `stabilityState` distinguishes front/rear demand imbalance and large body slip. Acceleration telemetry is the velocity change over the caller step, projected into the body axes at the start of that step, in m/s²; G divides it by 9.80665. Tire slip at a contact is internal and must not be substituted for the public body `slipAngleRadians`. Terminal and race-control-held advanced-mode cars publish `velocityX: 0` and `velocityY: 0` whenever scalar `speed` is zero, so training loops do not see stale pre-DNF, pre-grid, pre-red-flag, or pre-queue motion. Arcade snapshots publish `velocityX` and `velocityY` as `null`; consumers that need a heading-aligned arcade velocity should derive it from `heading` and `speed`. The rebuilt advanced model intentionally changes trajectories and grip-response distributions; controllers/checkpoints trained on the previous advanced dynamics need reevaluation or retraining. Action shapes and observation schema remain unchanged.
 `rules` is an optional override object for the race rules documented in [rules.md](rules.md). Flat keys such as `standingStart: false` still work for existing behavior. Advanced systems live under `rules.modules` so hosts can choose a preset and then override individual modules:
 
 ```js
@@ -301,6 +305,8 @@ Operationally this is one architecture with two modes:
 - local expert mode: browser owns stepping
 - external render mode: browser only renders authoritative external frames
 
+Browser external-renderer frames accept live indexed track models and JSON snapshot geometry, including the package's compact `sampleSchema` / sample-table form. The browser restores display-only query infrastructure and omitted pit bounds, caches unchanged received geometry, and reports malformed geometry through external-renderer state. It does not regenerate the track or compute replacement model senses. Frame `observation` remains the authoritative model-facing data; detaching clears live senses and invalidates queued callbacks.
+
 Policy Runner maps this directly through supported controller modes: `Distilled policy` and `Policy server` for browser-owned stepping, and `Live preview stream` for external render-only frames. The browser-owned HTTP policy-server transport uses protocol version `2`: `/policy/reset` receives static metadata such as `actionSpec`, `observationSpec`, configuration, `previousActionFields`, and `metricFields` once per session, while `/policy/decide-batch` receives only `driverIds` plus parallel compact `vectors`, `previousActions`, `metrics`, and `events` arrays aligned by driver index. Per-decision payloads intentionally do not include full observation objects, schemas, snapshots, or track/static metadata. Server integrations must treat the reset payload as the place to cache specs/configuration and tuple field order; Policy Runner server mode does not expose a legacy rich-observation transport option.
 
 `steering` is an absolute steering-wheel target: `-1` points at the maximum left steering limit, `0` points at center, `1` points at the maximum right steering limit, and intermediate values are percentages of that limit. The vehicle physics moves the steering angle toward that target through the configured steering-rate limit, so centering is physical rather than an instantaneous snap. `throttle` and `brake` are clamped from `0` to `1`. `steering`, `throttle`, and `brake` are required on every controlled-driver action; missing or non-finite values fail action validation instead of defaulting to zero.
@@ -455,6 +461,8 @@ recorder.recordStep(previous, action, next);
 
 Each recorded transition has `{ observation, action, reward, nextObservation, terminated, truncated, info }`. Recorded transitions are cloned at record time, including numeric arrays and typed vectors, so later mutation of a policy action object or observation buffer cannot change already-recorded samples. This is data export only; it does not train or update a model.
 
+Controller hooks (`init`, `reset`, `decideBatch`, `onStep`) receive an optional typed `context.signal`; Paddock-owned loops always supply an AbortSignal for the current generation. Forward it to cancellable I/O. Stop, full reset and partial reset abort prior work, then future operations receive a fresh signal. Obsolete completions and abort rejections cannot apply stale actions or overwrite the resumed loop's error/running state. Custom callers constructing contexts may omit the field.
+
 Deterministic evaluation helpers run fixed seeds/scenarios and report environment quality metrics:
 
 ```js
@@ -468,7 +476,7 @@ const report = runEnvironmentEvaluation({
 });
 ```
 
-Evaluation reports include distance, lap progress, off-track step count, contact count, recovery success, pass count, and first lap time when available. They follow the same wheel-level legal-surface and contact-event definitions 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)` usage requires `state.snapshot`, so use `stateOutput: 'minimal'` or `full` when wiring the tracker manually. These metrics are not rewards.
+Evaluation reports include distance, lap progress, off-track step count, contact count, recovery success, pass count, and a recorded completed-lap duration when available. They follow the same wheel-level legal-surface and contact-event definitions as environment metrics and starter contact rewards. `createEvaluationTracker(result, { lapScope })` and `runEnvironmentEvaluation({ ..., lapScope })` accept `'since-start'` (default) or `'include-history'`. Since-start ignores laps already complete at tracker creation and captures the first subsequently observed completion with a valid `lapTelemetry.lastLapTime`. Include-history may initialize from the latest valid recorded lap in the initial snapshot. Snapshots do not contain a multi-lap history here; unavailable, negative or nonfinite durations stay `null`. Neither mode substitutes total elapsed time or best-lap time. `runEnvironmentEvaluation()` can accept compact base options with `result.stateOutput: 'none'`; it internally requests the minimal snapshot needed for evaluation bookkeeping. Direct tracker usage requires `state.snapshot`, so use `stateOutput: 'minimal'` or `full`. Evaluation metrics are not rewards.
 
 `step(actions)` returns a JavaScript object designed for environment loops:
 
@@ -634,9 +642,11 @@ sensors: {
 }
 ```
 
-Ray precision defaults to `driver`. Driver precision is the active model-facing sensor contract and uses the normal sampled ray step without extra refinement. `precision: 'debug'` is available for clearly labeled diagnostics with additional edge refinement, but debug precision must not be displayed as model senses unless the policy is also running with that exact sensor config.
+Global rays and `sensorsByDriver` overrides use the same normalization for observations, compact vectors, and specs. Partial `env.reset()` overrides preserve explicitly supplied per-ray lengths; `lengthMeters` / `defaultLengthMeters` changes affect rays that inherit a default length. Supplying a new `layout` or `anglesDegrees` replaces the inherited generated ray arrangement unless explicit `rays` are supplied in that override. Explicit angles also replace an inherited preset layout.
 
-Surface channels are computed only when requested. `kerb` is legal racing surface. `illegalSurface` reports the first grass or gravel surface crossed by the ray. Requested surface-ray channels are part of the active object observation and compact vector schema for both default and physical-driver profiles. `precision: 'driver'` road-edge, kerb, and illegal-surface channels use the canonical indexed track projection path with driver-precision validation, preserving zero-distance origin surface hits and avoiding debug-only refinement in policy inputs. Requested surface channels preserve an origin hit at `distanceMeters: 0` even if another requested channel has no visible boundary. Barrier-origin recovery rays stay on direct indexed band results whenever the tracer can already prove the misses and the first non-barrier illegal-surface entry; ambiguous pit-connector, pit-lane-origin, and remaining unusual geometry cases may still use sampled validation internally, but the returned ray object shape is unchanged. Barrier walls are not exposed as a model-facing ray target; active ray objects, vectors, schemas, and visualizations must not expose a `barrier` ray channel. Barrier contact is enforced as a shared destruction boundary in both physics modes at the rendered wall's inner face and reported through events, snapshots, metrics, and per-driver episode state.
+Ray precision defaults to `driver`. Driver precision is the active model-facing sensor contract and uses the indexed geometry and bounded sampled recovery described below, without debug-only refinement. `precision: 'debug'` is available for clearly labeled diagnostics with additional edge refinement, but debug precision must not be displayed as model senses unless the policy is also running with that exact sensor config.
+
+Surface channels are computed only when requested. `kerb` is legal racing surface. `illegalSurface` reports the first grass or gravel surface crossed by the ray. Requested surface-ray channels are part of the active object observation and compact vector schema for both default and physical-driver profiles. Vector surface fields always follow `kerb`, then `illegalSurface` when enabled, irrespective of the channel array order; this also applies to per-driver overrides and schema-free array/Float32 output. `precision: 'driver'` road-edge, kerb, and illegal-surface channels use the canonical indexed track projection path with driver-precision validation, preserving zero-distance origin surface hits and avoiding debug-only refinement in policy inputs. Requested surface channels preserve an origin hit at `distanceMeters: 0` even if another requested channel has no visible boundary. Barrier-origin recovery rays stay on direct indexed band results whenever the tracer can already prove the misses and the first non-barrier illegal-surface entry; ambiguous pit-connector, pit-lane-origin, and remaining unusual geometry cases may still use sampled validation internally, but the returned ray object shape is unchanged. Barrier walls are not exposed as a model-facing ray target; active ray objects, vectors, schemas, and visualizations must not expose a `barrier` ray channel. Barrier contact is enforced as a shared destruction boundary in both physics modes at the rendered wall's inner face and reported through events, snapshots, metrics, and per-driver episode state.
 
 Nearby-car observations are car-relative. When advanced-mode velocity fields are present, `closingRateMetersPerSecond` and `timeToContactSeconds` use the actual 2D velocity vector instead of assuming the car is moving in its heading direction, so slip and recovery states remain physically accurate:
 
@@ -722,7 +732,7 @@ Each `car.lapTelemetry` snapshot includes current/last/best lap and sector timin
 
 `totalLaps` is optional. Values are normalized to a finite positive integer, with invalid or non-positive input falling back to a one-lap race.
 
-`trackSeed` is optional. If omitted, each mounted browser simulator creates a fresh procedural circuit. Passing a `trackSeed` makes the track deterministic; repeated procedural seeds are cached so multiple mounts can reuse the same immutable generated track definition when the resolved generation options also match. Callers should treat `createProceduralTrack(seed, options)` results as read-only. Calling `restart({ trackSeed })` rebuilds the simulation on the deterministic circuit for that seed.
+`trackSeed` is optional. If omitted, each mounted browser simulator creates a fresh procedural circuit. Passing a `trackSeed` makes the track deterministic; repeated procedural contracts use a bounded eight-entry least-recently-used cache so multiple mounts can reuse the same immutable generated track definition when the resolved generation options also match, while evicted contracts regenerate deterministically. Callers should treat `createProceduralTrack(seed, options)` results as read-only. Calling `restart({ trackSeed })` rebuilds the simulation on the deterministic circuit for that seed.
 
 `trackGeneration` is optional and applies only when a procedural `trackSeed` is used. It accepts profile presets plus explicit overrides:
 
@@ -771,6 +781,7 @@ Each driver must have:
   customFields: {
     Specialty: 'Late braking',
   },
+  driverModel: { id: 'host-policy-v2' },
 }
 ```
 
@@ -785,6 +796,7 @@ Fields:
 - `tire`: `S`, `M`, or `H`.
 - `raceData`: short project/radio lines shown in the UI.
 - `customFields`: optional driver overview fields. Use an object or an array of `{ label, value }`.
+- `driverModel`: optional opaque host metadata. PaddockJS preserves the value on normalized driver data and internal car state for host/controller bookkeeping, but does not interpret it or include it in model observations.
 
 ## Entry Shape
 
@@ -805,6 +817,7 @@ Entries are optional. If omitted, defaults are used.
     customFields: {
       Style: 'Patient race manager',
     },
+    driverModel: { id: 'driver-policy-v2' },
   },
   vehicle: {
     id: 'budget-bb01',
@@ -820,6 +833,7 @@ Entries are optional. If omitted, defaults are used.
       { label: 'Aero kit', value: 'Low drag' },
       { label: 'Battery map', value: 'Conservative' },
     ],
+    driverModel: { id: 'vehicle-policy-v2' },
   },
   team: {
     id: 'ledger-racing',
@@ -836,7 +850,7 @@ Entries are optional. If omitted, defaults are used.
 }
 ```
 
-Entries match drivers by `driverId`. Entry `driverId` values must be unique. `driverNumber` is optional; if omitted, PaddockJS falls back to stable grid order. When `driverNumber` is provided, values must be unique.
+Entries match drivers by `driverId`. Entry `driverId` values must be unique. `driverNumber` is optional; if omitted, PaddockJS falls back to stable grid order. All resolved numbers must be unique, including explicit numbers colliding with stable grid-order fallbacks. A collision rejects normalization/mounting with the number and conflicting driver IDs; PaddockJS does not silently renumber entries. Opaque `driverModel` metadata may be supplied on the top-level driver, entry driver blueprint, or entry vehicle blueprint; precedence is top-level driver, then entry driver, then entry vehicle.
 The car/driver overview primarily renders the existing driver and vehicle rating components from `driver` and `vehicle`. `team` is optional team-level metadata for race identity and pit behavior; `color` defaults to the driver/car color, and `icon` defaults from the team name or timing code. `team.pitCrew` may define `speed`, `consistency`, and `reliability` from `0` to `1`; these values affect optional pit-stop variability when `rules.modules.pitStops.variability.enabled` is true. The timing tower uses the team icon in the car/team column. `driver.customFields`, `vehicle.customFields`, and top-level driver `customFields` are accepted as extra metadata after those defined components.
 
 ## Rating Rules
@@ -852,6 +866,8 @@ Rating conversion lives in:
 - `src/data/driverData.js`
 - `src/data/vehicleData.js`
 
+The built-in racing policy consumes existing driver ratings. `pace` and `racecraft` affect ability, `consistency` affects line and speed judgement precision, and `aggression` plus `riskTolerance` affect willingness to use smaller margins. `patience` remains part of traffic decisions. Normalized consistency is retained in internal vehicle state; missing legacy consistency defaults to the neutral constructor value `0.75`. No new host option, action, snapshot or environment-observation field is introduced. Existing legacy vehicle fallbacks remain: when explicit vehicle coefficients are omitted, car creation derives power from pace and grip partly from racecraft. Use explicit vehicle entries for comparisons that must hold the car identical across skills. Explicit vehicle ratings determine the same physical setup across driver skill levels.
+
 ## Callback Contract
 
 PaddockJS does not directly own host navigation. The host should provide:
@@ -880,6 +896,8 @@ Optional lifecycle callbacks:
 
 `onRaceEvent` receives simulation events such as `contact`, `penalty`, `track-limits`, `pit-lane-speeding`, `car-dnf`, `safety-car`, `green-flag`, `start-lights-out`, and `race-finish`. `car-dnf` currently reports stalled off-track retirements with `reason: 'stalled-off-track'`. `contact` events include metadata from the production body collision solver: `firstShapeId`, `secondShapeId`, `contactType`, `depth`, and `timeOfImpact`. Lifecycle callback errors are caught; if `onError` exists, it receives `{ callback: name }` context for callback failures.
 
+Normal browser ticker frames and expert-driven frames use the same lifecycle path. `onLapChange` and `onRaceFinish` therefore run in either mode, duplicate delivery of one simulation event is suppressed, and separate same-time events remain distinct when their stable event, penalty, driver, car, or sequence identifiers differ.
+
 Race snapshots include a top-level `penalties` array. Each penalty entry includes `id`, `type`, `driverId`, `strictness`, `status`, `penaltySeconds`, `pendingPenaltySeconds`, `serviceType`, `serviceRequired`, `serviceServedAt`, `appliedAt`, `cancelledAt`, `unserved`, `positionDrop`, `gridDrop`, `disqualified`, `consequences`, `lap`, `at`, and rule-specific context such as `otherCarId`, `aheadDriverId`, `atFaultDriverId`, `sharedFault`, and `impactSpeedKph` for collision penalties or `speedKph`, `speedLimitKph`, `excessKph`, and `pitLanePart` for pit-lane speeding penalties. Clear rear contact has one at-fault driver; unclear meaningful contact records one shared-fault penalty per involved driver. Multiple time penalties for the same driver are summed into the car snapshot's `penaltySeconds` and adjusted finish/classification time.
 
 Each full public car snapshot includes `trackState` for the car-center track classification used by runtime readouts and environment surfaces. Its stable public fields are `distance`, `signedOffset`, `crossTrackError`, `surface`, `inPitLane`, `pitLanePart`, `pitBoxId`, `curvature`, and `heading`. `pitLanePart` and `pitBoxId` are `null` when the car is not classified on a pit-lane part or pit box. The existing flat `signedOffset`, `crossTrackError`, `surface`, `inPitLane`, `pitLanePart`, and `pitBoxId` fields remain as convenience mirrors for common UI and host checks.
@@ -931,6 +949,7 @@ Current UI options:
 ui: {
   layoutPreset: 'standard',
   cameraControls: 'external',
+  viewControls: 'switch',
   showFps: true,
   showTimingTower: true,
   showTelemetry: true,
@@ -960,6 +979,7 @@ debug: {
 
 - `layoutPreset`: `'standard'` or `'left-tower-overlay'`. The overlay preset creates a left broadcast gutter inside the race canvas, places the timing tower in that gutter at the same width as the default timing-board column, and frames the camera around the remaining race-view area. Camera controls are external by default. In the combined shell, the project/radio lower-third stays inside the race window and can render over the timing sidebar.
 - `cameraControls`: `'embedded'`, `'external'`, or `false`. The default is external so camera controls do not cover the race view. Embedded controls render inside the race canvas only when explicitly requested. External controls are mounted with `mountCameraControls(root)` or included in package-owned workbench templates. The generated controls include mode buttons, zoom buttons, and a `Mute banners` toggle that temporarily disables project/radio lower-thirds while active. `ui.driverCamera: true` adds the opt-in `driver` camera button; it is omitted from generated controls by default. A browser-playback speed button is optional for normal camera controls through `ui.simulationSpeedControl: true`; the complete race workbench enables it by default and cycles `1x`, `2x`, `3x`, `4x`, `5x`, `10x`, then back to `1x`. `false` leaves camera controls unrendered, though callers can still drive selection through controller methods.
+- `viewControls`: `'switch'` (default) or `'toggle'`. Controls the separately mounted Grid Walk view surface and built-in compositions: either Grid Walk / Race buttons or one Start race / Stop race button. Start enters or resumes Race; Stop pauses it and returns to the original display grid without resetting race state. Unknown values normalize to `'switch'`; `restart({ ui: { viewControls: ... } })` updates the mounted variant. Grid Walk must be enabled for either variant to appear.
 - `showFps`: controls whether the race canvas renders the FPS readout.
 - `showRaceDataPanel`: controls whether the precombined shell includes the project/radio lower-third inside the race window.
 - `showTimingTower`, `showTelemetry`: reserved component visibility flags for host layout decisions.
@@ -1074,7 +1094,7 @@ After every car completes `totalLaps`, `getSnapshot()` returns:
 
 Cars also include `team`, `speedKph`, `distanceMeters`, `gapAheadMeters`, `gapAheadSeconds`, `intervalAheadSeconds`, `leaderGapSeconds`, `gapAheadLaps`, `intervalAheadLaps`, `leaderGapLaps`, `finished`, `finishTime`, `finishRank`, `status`, `raceStatus`, `wavedFlag`, `destroyed`, `destroyReason`, `destroyedAt`, `dnf`, `dnfReason`, `dnfAt`, `dnfOrder`, `penaltySeconds`, `adjustedFinishTime`, `classifiedRank`, and `lapTelemetry`. A car that has crossed the finish before the whole race is complete exposes `status: 'waved-flag'`, `raceStatus: 'waved-flag'`, and `wavedFlag: true`; the timing order keeps those cars frozen by provisional `finishRank` until final classification is available, and later barrier contact or stalled-off-track detection does not convert that result into DNF. A destroyed/out-of-race car exposes `dnf: true`, keeps compatibility `raceStatus: 'destroyed'`, shows `DNF` in the timing tower, renders faded/gray in the race canvas, and is ordered below running cars by `dnfOrder`. Stalled off-track DNFs use `dnfReason: 'stalled-off-track'` and `destroyed: false`; barrier DNFs keep `destroyed: true`. Classification entries also expose `gapLaps`, `intervalLaps`, `positionDrop`, `disqualified`, and DNF metadata. `gapAheadSeconds` and `intervalAheadSeconds` are the interval to the car directly ahead when both cars are on the same lead-lap cycle; `gapAheadLaps` and `intervalAheadLaps` are the whole-lap deficit to that car when it is at least one lap ahead. `leaderGapSeconds` is the same-lead-lap gap to P1. `leaderGapLaps` is the whole-lap deficit to P1. Seconds gaps are measured from the timestamp difference when both cars crossed the same hidden timing line, with fallback interpolation only when no shared timing line exists yet. The timing tower prefers lap labels such as `+1` over seconds when the relevant lap gap is positive, shows `WAVED` for a finished car before full race classification, and shows `DNF` for retired cars. The first car to finish sets a provisional `raceControl.winner` and receives a `car-finish` event, but the race keeps running until every race participant has finished or is DNF. A DNF car restored before final classification re-enters live timing and must finish; after final classification, resurrection does not reopen the race. Final `raceControl.classification` sorts finishers by `finishTime + penaltySeconds` after converting unserved drive-through and stop-go penalties, applies position-drop and disqualification consequences, then appends DNF entries after finishers.
 
-When `rules.modules.pitStops.enabled` is true, cars also expose `pitIntent`, `pitStop`, and `usedTireCompounds`. `pitIntent` and `pitStop.intent` use `0` for no request, `1` for an opportunistic request that stays active until a free-enough entry window appears, and `2` for a committed request that enters at the next pit-entry window even if pit capacity or gap checks would block mode `1`. `pitStop.status` is one of `pending`, `entering`, `queued`, `servicing`, `exiting`, or `completed`; `pitStop.phase` may be `entry`, `queue`, `queue-release`, `penalty`, `service`, `exit`, or `null`. It also includes the assigned shared service `boxId`/`boxIndex`, the driver's `garageBoxId`/`garageBoxIndex`, optional team id/color, planned pit-call race distance, physical pit-entry race distance, service seconds remaining, `penaltyServiceRemainingSeconds`, `penaltyServiceTotalSeconds`, `servingPenaltyIds`, target tire, optional `serviceProfile`, queue flag, and completed stop count. Host APIs and expert actions can choose the target tire compound with `setPitIntent(driverId, intent, targetCompound)` or `pitCompound`; invalid compounds are rejected. Automatic pit calls can share the same entry lap, but a pending mode `1` car only joins when the active pit-lane population is below `maxConcurrentPitLaneCars` and the nearest active pit-lane car is at least `minimumPitLaneGapMeters` ahead; mode `2` bypasses that opportunistic-capacity gate and commits to the automatic pit-entry route. Team-mates share one service area; every car enters through the working-lane queue point first. If the service area is free, the queue point behaves as a rolling gate and the car immediately follows a short `queue-release` route into service without exposing `queued`; if the area is occupied, the car exposes `status: queued` until servicing, queue-release, and just-exiting cars have physically cleared the active spot. Completed stops can be re-armed by later tire condition or host intent, so `stopsCompleted` can increase beyond one during longer races. `pitLaneSpeedLimitKph` applies only while the automatic route is inside the straight main pit lane/working lane; entry and exit connector roads remain legal pit surfaces but are not limiter zones. The automatic route brakes before the main lane start, travels along the main fast lane, and crosses into the team service area only near the assigned stop. If `phase` is `penalty`, the car is stationary before tire service and the browser renderer shows a red `+Ns` countdown above the car; if `phase` is `service`, it shows a yellow `Ns` countdown for the normal pit-service time. Optional pit-stop variability records the resolved `serviceProfile`; `pitStops.variability.perfect: true` forces the configured default service time for deterministic training. `usedTireCompounds` starts with the initial tire and receives the tire selected by completed automatic pit stops.
+When `rules.modules.pitStops.enabled` is true, cars also expose `pitIntent`, `pitStop`, and `usedTireCompounds`. `pitIntent` and `pitStop.intent` use `0` for no request, `1` for an opportunistic request that stays active until a free-enough entry window appears, and `2` for a committed request that enters at the next pit-entry window even if pit capacity or gap checks would block mode `1`. `pitStop.status` is one of `pending`, `entering`, `queued`, `servicing`, `exiting`, or `completed`; `pitStop.phase` may be `entry`, `queue`, `queue-release`, `penalty`, `service`, `exit`, or `null`. It also includes the assigned shared service `boxId`/`boxIndex`, the driver's `garageBoxId`/`garageBoxIndex`, optional team id/color, planned pit-call race distance, physical pit-entry race distance, service seconds remaining, `penaltyServiceRemainingSeconds`, `penaltyServiceTotalSeconds`, `servingPenaltyIds`, target tire, optional `serviceProfile`, queue flag, and completed stop count. Host APIs and expert actions can choose the target tire compound with `setPitIntent(driverId, intent, targetCompound)` or `pitCompound`; invalid compounds are rejected. Automatic pit calls can share the same entry lap, but a pending mode `1` car only joins when the active pit-lane population is below `maxConcurrentPitLaneCars` and the nearest active pit-lane car is at least `minimumPitLaneGapMeters` ahead; mode `2` bypasses that opportunistic-capacity gate and commits to the automatic pit-entry route. Team-mates share one service area; every car enters through the working-lane queue point first. If the service area is free, the queue point behaves as a rolling gate and the car immediately follows a short `queue-release` route into service without exposing `queued`; if the area is occupied, the car exposes `status: queued` until servicing, queue-release, and just-exiting cars have physically cleared the active spot. Completed stops can be re-armed by later tire condition or host intent, so `stopsCompleted` can increase beyond one during longer races. Automatic tire-condition rearming chooses another available compound rather than silently targeting the current tire again; explicit host/model target compounds are preserved. `pitLaneSpeedLimitKph` applies only while the automatic route is inside the straight main pit lane/working lane; entry and exit connector roads remain legal pit surfaces but are not limiter zones. The automatic route brakes before the main lane start, travels along the main fast lane, and crosses into the team service area only near the assigned stop. If `phase` is `penalty`, the car is stationary before tire service and the browser renderer shows a red `+Ns` countdown above the car; if `phase` is `service`, it shows a yellow `Ns` countdown for the normal pit-service time. Optional pit-stop variability records the resolved `serviceProfile`; `pitStops.variability.perfect: true` forces the configured default service time for deterministic training. `usedTireCompounds` starts with the initial tire and receives the tire selected by completed automatic pit stops.
 
 Car snapshots expose `surface`, `signedOffset`, `crossTrackError`, `inPitLane`, `pitLanePart`, `pitBoxId`, and `pitLaneCrossTrackError` so hosts can distinguish main-circuit running from pit entry, fast lane, working lane, pit exit, and service-box states without recalculating geometry. `surface` is the worst current wheel/contact-patch surface, not only the center point. Each car also exposes `wheels`, with one entry per contact patch:
 
@@ -1094,6 +1114,8 @@ Car snapshots expose `surface`, `signedOffset`, `crossTrackError`, `inPitLane`,
 
 Use `wheels` when a host needs exact debug overlays, per-wheel surface labels, or track-limit state. A car is track-limit illegal only when all four wheel contact patches are fully outside the same white line; a mixed state such as one wheel on gravel and one wheel still inside the white line reports the worse physics surface but does not count as a track-limit violation.
 
+Supported mutable snapshot metadata is caller-owned: penalty `consequences` entries, `usedCompounds`, and `wheelOffsets`; car team `pitCrew` and `pitCrewStats`; and pit-stop `serviceProfile.pitCrew` are copied. Mutating them does not change live enforcement or service behavior, and later live changes do not alter prior snapshots. Optional fields remain absent or undefined as supplied; no crew defaults are added by serialization. The live track reference described below is an explicit exception.
+
 ## Track And Lap Telemetry Snapshot
 
 Every built track is automatically divided into three equal sectors. `snapshot.track.sectors` exposes:
@@ -1165,7 +1187,7 @@ const simulator = await mountF1Simulator(root, options);
 
 Controller methods:
 
-- `destroy()`: removes listeners, destroys PixiJS runtime, clears the host root.
+- `destroy()`: removes listeners, destroys PixiJS runtime, clears the host root, and releases that root for a future mount. A live all-in-one root rejects a second mount; failed initialization clears and releases it automatically.
 - `restart(nextOptions)`: restarts the simulation with merged non-asset options. Use `destroy()` and mount a new simulator to change bundled or host-provided asset URLs.
 - `selectDriver(driverId)`: selects and focuses a driver.
 - `setSafetyCarDeployed(deployed)`: toggles safety car state.
@@ -1195,15 +1217,16 @@ Composable controllers additionally expose the canonical composable mounting API
 - `mountTelemetryPanel(root, { includeOverview })`: renders the package-owned telemetry stack template. The stack is only a composition of detached telemetry surfaces, owns vertical scrolling when its host is shorter than its contents, and includes the car/driver overview by default unless `includeOverview: false` is passed or `ui.telemetryIncludesOverview` is `false`.
 - `mountTelemetryCore(root)`: renders selected-car scalar telemetry only.
 - `mountTelemetrySectors(root)`: renders the live sector progress graph only.
+- `mountTelemetrySectorBanner(root)`: renders the selected driver's compact sector-progress lower-third only.
 - `mountTelemetryLapTimes(root)`: renders current, last, and best lap timing only.
 - `mountTelemetrySectorTimes(root)`: renders last and best sector timing only.
 - `mountRaceTelemetryDrawer(root, { timingTowerVerticalFit, drawerInitiallyOpen, raceDataTelemetryDetail, responsiveNarrowLayout })`: renders a template that combines an external top control row, race canvas, embedded timing tower, the project/radio lower-third, top steward message, safety-car control, and a right-side telemetry drawer. The control row contains camera controls, the `1x..10x` simulation-speed toggle, banner mute, the safety-car button, and the telemetry toggle so those controls do not cover the race view. Pass `raceDataTelemetryDetail: true` when this template should put compact S1/S2/S3 detail in the project lower-third instead of mounting a second sector popup. The drawer embeds the same package-owned telemetry stack used by `mountTelemetryPanel()` and takes layout space from the race window when opened on wide containers; narrow drawer reveal behavior is enabled by default, stacks the top workbench controls into readable full-width rows, and can be disabled with `responsiveNarrowLayout: false`.
 - `mountCarDriverOverview(root)`: renders the package-owned car/driver overview as a separate component with a Car/Driver toggle, center visual, and linked stat cells from the existing driver/vehicle rating components.
 - `mountRaceDataPanel(root)`: renders the project/race-data lower-third as a separate component for hosts that intentionally want it outside the race canvas.
 - `querySelector(selector)` / `querySelectorAll(selector)`: search across the mounted package-owned composable roots. These exist for integration tests and advanced host glue; ordinary hosts should prefer explicit controller methods and mounted component roots.
-- `start()`: initializes PixiJS, binds mounted controls, and starts the simulation loop.
+- `start()`: initializes PixiJS, binds mounted controls, and starts the simulation loop. Concurrent callers await the same initialization. If initialization fails, partial runtime state is destroyed and a later call may retry.
 
-Mount component roots before calling `start()`. If a component is not mounted, the runtime skips that UI surface instead of requiring hidden placeholder DOM. Every public mounted surface renders lightweight static package markup and a surface-specific `data-paddock-loading` overlay immediately. `start()` removes those overlays only after PixiJS, assets, controls, initial DOM readouts, and the first frame have initialized. If `restart(nextOptions)` is called before `start()`, mounted component markup is refreshed from the new resolved options so copy, component visibility, driver data, and theme changes do not leave stale pre-start HTML behind.
+Mount component roots before calling `start()`. Each surface key owns one root: remounting that surface into another root clears the prior root, and different surfaces cannot share one root. If a component is not mounted, the runtime skips that UI surface instead of requiring hidden placeholder DOM. Every public mounted surface renders lightweight static package markup and a surface-specific `data-paddock-loading` overlay immediately. `start()` removes those overlays only after PixiJS, assets, controls, initial DOM readouts, and the first frame have initialized. If `restart(nextOptions)` is called before `start()`, mounted component markup is refreshed from the new resolved options so copy, component visibility, driver data, and theme changes do not leave stale pre-start HTML behind.
 
 This loading overlay is the package's client-side startup state. It begins after the PaddockJS JavaScript bundle has executed and a mount function has run. Hosts that need an instant placeholder before package JavaScript loads should render host-owned fallback HTML/CSS around or inside the mount root, then let `mountF1Simulator()` or the composable `mount*()` calls replace that root content when the package starts.
 

package/docs/data_model.md

@@ -10,7 +10,7 @@ The race loop does not read raw rating numbers directly. It receives constructor
 
 ## Rating Scale
 
-Driver and vehicle stats use a `0-100` rating scale.
+Driver and vehicle stats use a `0-100` rating scale. The common bounds, numeric validation, clamping, and conversion live in `src/data/ratingScale.js`; each data class owns its stat definitions and error labels.
 
 - `50` is neutral.
 - Values above `50` add to the class default.
@@ -55,6 +55,7 @@ Driver stats:
 ```js
 {
   ratings,
+  customFields,
   pace,
   racecraft,
   consistency,
@@ -94,7 +95,7 @@ Vehicle stats:
 - `dragEfficiency`: Converts inversely to `dragCoefficient`; higher rating means less drag.
 - `mechanicalGrip`: Converts to `tireGrip`.
 - `weightControl`: Converts inversely to `mass`; higher rating means lower mass.
-- `tireCare`: Converts to `tireCare`, reserved for tire behavior tuning.
+- `tireCare`: Converts to the tire-wear divisor used by both vehicle physics modes; higher values reduce tire-energy loss when tire degradation is enabled.
 
 `VehicleData.toConstructorArgs()` returns:
 
@@ -103,6 +104,7 @@ Vehicle stats:
   id,
   name,
   ratings,
+  customFields,
   powerNewtons,
   brakeNewtons,
   downforceCoefficient,

package/docs/efficiency_cleanup_2026-10-13.md

@@ -0,0 +1,80 @@
+# Efficiency and maintainability follow-up — 2026-10-13
+
+This continues the isolated v11 improvement pass after the user requested sustained hardware-browser measurements and a broader cleanup audit. The starting point includes the earlier AI, lifecycle and motion fixes, not untouched v11. Source, scripts and both built consumers were preserved under `/tmp/paddock-v11-efficiency-20261013-pass2/` before edits. Work remains uncommitted on `v11-improvements`; original v11 is preserved and no Git/GitHub mutation is part of this pass.
+
+## Checkable scope
+
+- [x] Inspect live branch/worktree state, current ownership, existing cleanup records and test contracts.
+- [x] Scan package/runtime/environment/data/config/UI/rendering and both consumers for large modules, duplication and unused paths; deeply inspect concrete candidates and callsites.
+- [x] Preserve the exact starting source and builds and identify the native GPU.
+- [x] Implement bounded work reduction and ownership cleanup with focused tests and exact-output comparisons.
+- [x] Complete matched hardware frame-time, CPU and retained-memory measurements.
+- [x] Run standard performance contracts and both package gates against the final candidate.
+- [x] Verify final interactions, update Linear and record remaining limits.
+
+This is an audit of the full module map and demonstrated risks, not a claim that every line is optimal. Historical [cleanup coverage](cleanup_coverage.md) and [the September audit](maintainability_audit_2026-09-08.md) informed candidate selection; their old evidence was not treated as current proof. Supported compatibility barrels remain intact. Large geometry/surface kernels retain their current boundaries because splitting them by line count would add numerical/invalidation risk without a demonstrated benefit.
+
+## Findings and target ownership
+
+| Finding | Change | Proof |
+| --- | --- | --- |
+| Overlay synchronization observes the class/style attributes it writes, risking observer → RAF feedback | Compare current values before writing/removing clearance state; retain geometry and timing-board width | Modeled observer convergence plus native-browser idle follow-up |
+| Replay halos rebuild fixed Graphics geometry each frame | Cache tint/effective opacity, keeping all pose and sprite/label updates | 120 moving frames produce zero additional halo rebuilds; changed appearance and removal/recreation covered |
+| Timing refreshes rewrite unchanged attributes/classes/styles and append every existing row | Guard writes against DOM values and reconcile keyed positions only when order changes | Gap-only updates produce one text write, no row moves and preserve focus; insertion, removal, order and penalty changes covered |
+| Pooled render snapshots still build rank-wrapper/order collections | Direct ranked-then-index-sorted writer with per-target weak scratch | Real-simulation order/identity tests and exact baseline/current frames including excluded participants, DNF and classification |
+| Nearby projections and radar lookup are rebuilt per controlled driver | Lazy preparation shared within one observation build; fresh returned records | Multi-driver flags, retained results, limits, ties, car/ghost IDs and direct-vector equivalence |
+| Nearby candidates allocate complete payloads before losing the shortlist | Admit by squared distance/order first | Crowded fields, exact radius boundaries, stable ties and zero limits |
+| Advanced braking previews repeatedly query identical capacity endpoints | Decision-local lazy reuse of speed-zero and maximum-speed endpoints | Exact controls/trajectories on four tracks; tire/DRS/surface mutation tests; measured query count reduction |
+| Display destruction policy is duplicated between app and track layers | `src/rendering/displayLifecycle.js` owns child destruction, preserving shared textures | Real Pixi nested destruction and repeated cleanup |
+| Workbench DOM mechanics and sense presentation expand broad entrypoints | Focused controls/disclosure modules and Policy Runner `senseReadout.js` | Existing lifecycle/control suites, focused missing/vector/physical sense cases and full browser smoke |
+| Two driver constants and a now-obsolete internal sensor wrapper have no consumers | Remove only proven internal dead declarations after named/import/export screening | Public types, import graph and package gates; no public barrel removal |
+
+The app retains race state, selection, options, camera invalidation and layout orchestration. Control modules accept explicit DOM references, signal and command callbacks, not the whole mutable runtime. Sense presentation reads the active observation only. Snapshot scratch adds no public fields and releases participant references; nearby contexts never persist across builds or mutable snapshots.
+
+`F1SimulatorApp.js` decreases from 1,347 to 1,275 lines; the showcase entrypoint decreases from 3,211 to 3,069. These reductions describe responsibility placement, not a performance metric. Numerical kernels and supported facades are not removed merely to improve counts.
+
+## Semantic and work-reduction evidence
+
+The first serializer/sensor cleanup preserves **5,558,802 serialized bytes** exactly across 160 retained environment results, eight resets, 50 render frames and 50 ghost observations. SHA-256: `ac2bd02e4de2d52498e500f03b5d3d4960a86f0ddd8f4ae2250a739731e4845a`.
+
+Advanced endpoint reuse preserves exact controls and trajectory/observation hashes on the canonical track and procedural seeds 12, 7110 and 7203, each with 1,200 steps and eight advanced cars, including changes to tires, DRS and wheel surfaces between decisions. Lateral-capacity queries fall **1,273,206 → 637,075 (49.96%)**. One real driver decision falls **53 → 14**, with the interior query sequence unchanged. Counting instrumentation is confined to temporary copies; actual tire-force kernels are unchanged.
+
+Three alternating fresh-process runs of the same 10,000-step, 20-car advanced workload report baseline totals 2,290.6 / 2,222.9 / 2,243.6 ms and candidate totals 1,873.5 / 1,869.6 / 1,909.9 ms. Median falls 2,243.6 → 1,873.5 ms, about **16.5%**. This is a measured result for this workload on this machine, not a universal CPU/FPS speedup. Other desktop development activity remains a timing-noise source.
+
+## Hardware-browser measurements
+
+An isolated headed Chrome 154 session reports `ANGLE Metal Renderer: Apple M4 Pro`. Sampling uses a 1,280 × 800 viewport and device/canvas density 2, the built complete workbench, fixed race/track seeds, 60-second intervals, and real Pixi draw callbacks. Each case starts after exactly 600 fixed simulation steps, with matching car-state SHA-256 across sources. Typed arrays bound instrumentation; hooks and observers are restored afterward. Update-work samples measure the runtime callback, while CDP metrics cover broader page task/style/layout costs. Heap samples request GC outside frame-timing intervals.
+
+| Mode | Baseline → final FPS | Draw p95 ms | Draw p99 ms | Gaps over 50 ms | Mean update work ms |
+| --- | --- | --- | --- | --- | --- |
+| Arcade 1x | 58.57 → 58.51 | 23.0 → 23.7 | 25.5 → 25.5 | 0 → 0 | 0.412 → 0.808 |
+| Advanced 1x | 58.53 → 58.53 | 23.7 → 23.4 | 25.6 → 25.5 | 0 → 0 | 0.512 → 0.825 |
+| Advanced 10x | 58.57 → 58.60 | 23.5 → 22.8 | 26.3 → 26.3 | 0 → 0 | 1.775 → 1.993 |
+
+Frame pacing is maintained; these data do not establish a browser CPU or FPS improvement. Average callback work rises in these samples even as exact operation counts fall. Broader page task time is mixed: estimated task CPU is 22.09% → 24.82% arcade, 23.18% → 24.36% advanced and 27.71% → 27.12% advanced 10x. This is page task duration divided by elapsed time, not total process, device or GPU utilization. The final arcade sample overlapped the end of the demo smoke gate; a separate baseline/final repeat is retained to examine the variation rather than silently dropping results.
+
+A subsequent arcade pair, without the package gate running, reports FPS 58.60 → 58.49, p95 22.8 → 19.3 ms, p99 25.5 → 25.4 ms, callback mean 0.444 → 0.697 ms and page task CPU 24.16% → 24.70%. The final repeat contains two gaps over 50 ms. The higher callback cost is therefore retained as a measured limitation, not dismissed as a single overlapping-gate artifact or hidden behind the simulation speedup.
+
+An earlier uncontrolled 10x baseline had one 368 ms gap; its raw record remains in the evidence. A diagnostic sample that changed browser density after mounting is excluded because the Pixi canvas retained its old density. Neither sample is used to claim a speedup. The collaborative preview's SwiftShader results do not establish hardware performance.
+
+A canonical stopped-runtime probe observes the complete panel for three seconds after settling: baseline performs **360 class writes**, the final candidate performs **zero class/style writes**, with the private ticker stopped and timing tower still **255 px** wide. This isolates the overlay observer feedback loop from normal racing activity.
+
+## Verification and remaining limits
+
+Focused control/startup/lifecycle, replay/disposal, observer, render-order, nearby and advanced pace tests pass. Independent review finds no ordering, aliasing, stale-cache or precision issue in the current simulation/environment changes. A nearby configuration with `maxCars: 0` still prepares one context; this minor overhead is retained to avoid widening the change.
+
+`npm run check` passes **75 files, 1,195 fast tests**, with 93 intentionally deferred slow cases, public types, dry pack, fresh packed-consumer install/build, bundle boundaries, both consumer builds, quick Chromium smoke and complete demo smoke. The final standard runtime benchmark validates all **23 cases**. Three earlier alternating baseline/candidate runs also preserve every non-timing contract across all 23 cases; timing-valued diagnostic fields are explicitly excluded from equality checks. `npm run check:release` passes all **75 exhaustive batches / 1,288 tests**, four dependency audits with zero vulnerabilities, types/pack/consumers/builds, the full Chromium showcase matrix and complete demo smoke. Source changes preceded both final gates; subsequent changes only document evidence.
+
+Native focus acceptance updates one actual timing gap text node with zero row moves and the same focused button. This guarantee concerns unchanged ordering; actual reordering can still blur a moved row and remains a preexisting interaction limitation. Native interaction at **390 × 844** additionally exercises telemetry open/close, timing reveal, Budget Buddy selection, interval-to-leader gap switching and Overview camera; document width remains 390 px with all ten rows present. The painted native screenshot is `output/playwright/final-narrow.png`.
+
+After two warm-up mounts, **ten native GPU mount/destroy cycles** leave nodes **3,131 → 3,131**, listeners **94 → 94**, documents **1 → 1** and the existing page canvas count **2**. Post-GC heap rises 99.94 → 100.86 MB, so this does not claim zero heap growth. Each temporary controller mounted one hardware-rendered canvas and removed it on destroy. Private GPU/driver allocation retention is not quantified by these JavaScript/CDP metrics.
+
+The final **five-minute, eleven-sample** advanced-mode soak performs ten seeded restarts with alternating driver selection and drawer state. Nodes remain within **3,131–3,135** and finish at **3,131**; listeners **94**, documents **1**, and canvases **2** are constant throughout. Heap starts at 74.32 MB immediately after restart, warms to 102.18 MB, briefly reaches 129.29 MB, then returns to 103.10 MB. Samples three through ten stay within **102.99–103.36 MB**; final heap is **103.36 MB**. This supports bounded retention over the measured window, not a guarantee for unlimited runtimes or all GPU allocations. The exhaustive package gate runs in parallel with the retention probe; it is excluded from native frame-time repeat measurements.
+
+ All temporary comparisons, raw profiles, browser records and inventory are under `/tmp/paddock-v11-efficiency-20261013-pass2/`; CLI probes live in ignored `output/playwright/`.
+
+The broader numerical geometry/surface kernels remain large; the pass does not claim complete architectural decomposition. No new browser CPU/FPS gain is claimed, and the callback-cost increase remains a useful profiling follow-up. Existing release-only publishing/lock synchronization items in `v11_improvements.md` remain outside this optimization task. Original v11 stays clean at the approved starting commit, while all candidate changes remain uncommitted without an upstream.
+
+The PaddockJS Linear project document was updated with task, implementation, verification and remaining limits: [v11 improvement pass](https://linear.app/mgiorgetti/document/v11-improvement-pass-racecraft-render-cost-and-lifecycle-reliability-b6c4a20b8501). Temporary browser/profiling servers are closed; the candidate demo remains available at `http://127.0.0.1:4181/`.
+
+Subsequent skill-dependent physical-envelope tuning, timing-line boundary repair and measured limitations are documented in [limit driving, 2026-10-14](limit_driving_2026-10-14.md). Earlier results above describe their recorded candidate.

package/docs/getting-started.md

@@ -68,6 +68,8 @@ await mountF1Simulator(root, { drivers, entries });
 
 That placeholder covers the time before the full PaddockJS bundle executes. Once the bundle runs, PaddockJS owns the root markup and shows its package loading overlays until the first real simulator frame is ready.
 
+Plain static HTML pages cannot resolve bare npm imports such as `@inventure71/paddockjs/placeholder` directly in the browser without a bundler or import map. Static hosts should run `createPaddockLoadingPlaceholder()` in the site build script, inject the generated HTML into the static page, and copy `@inventure71/paddockjs/placeholder.css` into the static output. See [Startup Loading](loading.md) for the bundled and static-host patterns.
+
 ## CSS
 
 Most browser bundlers consume the root package stylesheet automatically. If your host build does not, import the stylesheet explicitly from a browser entry:
@@ -100,6 +102,7 @@ If a package surface is constrained below its supported size, PaddockJS shows an
 ## Where To Go Next
 
 - Use [Composable Layouts](composable-layouts.md) when the host needs separate package-owned surfaces.
+- Use [Startup Loading](loading.md) when the host needs instant first paint, static HTML integration, or a clearer split between placeholders and runtime overlays.
 - Use [Theming](theming.md) for runtime light/dark sync and token customization.
 - Use [Data Contract](data_contract.md) for full driver, entry, rule, UI, callback, and asset option shapes.
 - Use [Troubleshooting](troubleshooting.md) when a host build or browser smoke fails.

package/docs/grid_walk.md

@@ -0,0 +1,80 @@
+# Grid Walk
+
+Grid Walk is an opt-in browser presentation around the existing race. It stages the same cars on the same track, adds preparing crew, visitors walking along the grid and readable entry labels, and reuses the race project banner at the bottom. Both mounting APIs support it. Existing consumers continue to start in Race without Grid Walk UI.
+
+```js
+import { createPaddockSimulator } from '@inventure71/paddockjs';
+
+const simulator = createPaddockSimulator({
+  drivers: [{ id: 'surveyor', name: 'Surveyor', color: '#f05060' }],
+  entries: [{
+    driverId: 'surveyor',
+    presentation: {
+      name: 'Surveyor Field Workspace',
+      summary: 'Map field observations in a shared workspace.',
+      href: '/projects/surveyor',
+      linkLabel: 'View project',
+    },
+  }],
+  gridWalk: { enabled: true, initialView: 'grid-walk', ambientMotion: true },
+  ui: { viewControls: 'toggle' }, // Omit for the two-button Grid Walk / Race switch.
+});
+simulator.mountViewControls(document.getElementById('sim-view-controls'));
+simulator.mountRaceCanvas(document.getElementById('sim-race'));
+await simulator.start();
+simulator.setView('race');
+```
+
+## Host composition
+
+The Grid Walk / Race switch is a separately mountable package component. Place `simulator.mountViewControls(controlsRoot)` outside the scene alongside `mountRaceCanvas(canvasRoot)`, before `await simulator.start()`. The equivalent function-style helper is `mountViewControls(controlsRoot, simulator)`, imported from the browser package. It uses the package's control styling and calls the same `setView()` API; it does not create another simulator. `ui.viewControls` selects `'switch'` (the default Grid Walk / Race buttons) or `'toggle'` (one ordinary action button). The toggle reads **Start race** in Grid Walk with a green fill and **Stop race** in Race with a red fill, using the semantic `theme.colors.greenFlag` / `redFlag` colors in both themes. Stop pauses exact progress and presents the original display grid; Start resumes it through the same lifecycle below, without restarting the race. Invalid option values fall back to `'switch'`. Both variants use the same `mountViewControls()` API and remain synchronized after `restart({ ui: { viewControls: ... } })`.
+
+A standalone race canvas does not insert a mode switch. Composable hosts must mount the switch explicitly or provide their own buttons calling `setView()`. The all-in-one shell and `mountRaceTelemetryDrawer()` already compose the package switch above the scene when Grid Walk is enabled. Mounted switches share the active view, remain disabled until runtime startup completes, and hide when Grid Walk is disabled, including after a restart. The top entry selector and bottom project banner remain part of the scene. The selector is horizontally centered with centered entry text. The external workbench camera controls fill their available row, and action controls reserve the wider of their labels so Start/Stop or Telemetry/Close changes do not shift neighboring controls.
+
+## Lifecycle and state
+
+- `gridWalk.enabled` defaults to `false`. When enabled, `initialView` defaults to `'grid-walk'`; use `'race'` to begin playback with Grid Walk available afterward. `ambientMotion` defaults to `true`.
+- `getView()` returns `'grid-walk'` or `'race'`. `setView(view)` returns `true` for an accepted change and `false` for an unchanged/invalid view, disabled Grid Walk, or a composable controller that has not started. View changes do not call `restart()`.
+- Before the first departure from Grid Walk, the simulation clock and lights are held. Choosing Race clears the crew over 650 ms of visible activity, then starts the existing deterministic lights sequence. With reduced motion or `ambientMotion: false`, clearing is immediate. Returning during clearing cancels the transition.
+- Returning after playback has begun pauses the exact live race and shows its original starting grid using display poses only. Race resumes saved time, laps, order, tires, pit state, selected entry and fractional fixed-step remainder. The simulation object, RNG, entries and track are not recreated or changed by browsing or resizing. Project banner selection/open state survives a mode switch.
+- Standing starts use actual assigned grid distances and offsets, including penalties present when the presentation is captured. With `rules.standingStart: false`, staging uses display-only staggered slots; Race resumes the existing rolling-start state without adding a lights sequence.
+- Explicit `restart()` still creates a new race, captures its grid and applies the configured initial view. Nested Grid Walk options merge on restart. Resizing and mode switches never implicitly restart.
+- Grid Walk is excluded from `expert.enabled`: expert/reset/step callers own their separate lifecycle. Combining these opt-ins throws during option resolution.
+
+## Entry content and links
+
+`presentation` may be supplied on a driver or its matching entry. The entry's presentation takes precedence. `name` falls back to the driver's full name and `summary` to its first legacy `raceData` item. The bottom banner uses the same project name, driver number, position/code, summary and project link fields as the race banner. It initially shows the selected entry; clicking a car/label or changing the top selector updates it. Rich metadata fields (`technologies`, `details`, `image`) remain accepted for host compatibility but are not displayed. There is no separate inspector or expanded information. Content is rendered as text, not HTML.
+
+`href` falls back to the driver's `link`. Navigation is an ordinary anchor supporting browser open/copy/modifier behavior; Grid Walk does not route through `onDriverOpen`. That existing callback remains available on the legacy race banner. Hosts supply all destinations. URLs accept relative, hash, HTTP and HTTPS URLs through the package's URL normalization; script, data and protocol-relative URLs are excluded.
+
+The external mode switch and in-scene entry selector reuse the race camera-control styling. Project details reuse the actual race banner template, renderer and compact variant; only navigation uses an ordinary anchor in Grid Walk. Appearance follows existing package theme tokens for text, surfaces, borders, primary and focus colors. No host-specific names, categories or routing are embedded in the runtime.
+
+## Camera and accessibility
+
+The measured canvas host's width and height choose composition, independent of viewport, device or user-agent. Wide starts horizontal, tall starts vertical. A retained orientation uses a ratio band of 0.92–1.08 near square to avoid flapping. The camera rotates and frames the same world. The grid and entries are never rebuilt or reordered for another orientation.
+
+The camera measures the wrapping top controls and shared bottom banner to reserve a safe scene area. It keeps a stable scale for that area and a single world position along the original grid axis. Selecting an on-screen car changes the project without resetting the camera, zoom or other labels. Previous/next and the native selector bring offscreen entries into view; Home explicitly recenters the selected entry. Resizing, rotation and mode switches preserve the browsing position.
+
+Drag the canvas or an entry label with a mouse or touch to move along the grid. All camera input uses the same axis: horizontal composition accepts left/right dragging and arrow keys, vertical composition accepts up/down. Diagonal drags and scroll cannot move across that axis. A vertical wheel travels front to rear in both compositions; horizontal trackpad input is accepted only in horizontal composition. Browsing is bounded near the grid. The canvas consumes wheel input only while it moves the grid camera; continuing past an end scrolls the host page. Race zoom does not handle wheel input while Grid Walk owns the scene. Ctrl/Meta wheel remains available to browser zoom, and scrolling outside the canvas keeps normal host behavior. Host-handled and non-cancelable wheel events are left alone; modified keyboard navigation such as Ctrl/Cmd+Home keeps its browser behavior. Race releases wheel events at zoom limits and restores native touch scrolling. Only active Grid Walk applies `touch-action: none` to its canvas/entry drag targets; it never changes body/document overflow. A drag starting on a car or label does not select it; a click or tap does, including a gesture that moves only in the forbidden direction.
+
+HTML labels follow the actual car poses in two lanes, with connector lines if space requires displacement. Labels are packed as a group, preserving spatial order and preventing collisions with other labels, controls or the banner. When a lane cannot fit all visible cars at readable size, it keeps the entries nearest the camera center. This decision uses geometry, never selection. Every entry remains reachable through the selector and camera. Short scenes use single-line labels so readable entry targets still fit between the controls and banner in either orientation. Full accessible names and native titles remain available when constrained text is truncated. Label surfaces are opaque in both themes.
+
+In constrained all-in-one embeds, the opt-in shell also uses its container width for the existing stacked timing/telemetry composition. Overlapping timing towers clear the Grid Walk scene and return in Race; outboard towers retain their layout. Timing-board width tokens are unchanged.
+
+Controls are keyboard-operable. Selection focuses the project banner title; Escape or Close restores the selected visible label, or the selector if it has been panned offscreen. Dismissal preserves camera position and zoom. The banner follows `ui.raceDataBannerSize`, `ui.showRaceDataPanel`, enabled banner types and the Race mute state; with project banners disabled, selection focuses the entry label instead. Grid Walk keeps project-only content even when Race telemetry detail is enabled. Links keep ordinary browser behavior. Focus is not trapped because the grid remains available.
+
+There is no motion button. Hosts can set `ambientMotion: false` for a static presentation. `prefers-reduced-motion` freezes visitors and crew, disables banner transitions and makes clearing immediate; live changes are respected. Each car has two to five mechanics with varied, stable preparation positions and poses. Visitors have varied clothing and stride and walk from front to rear in a continuous, spatially distributed flow along each side lane. Visitors use deliberately irregular longitudinal spacing, varied lateral paths and individual pace changes and sideways sway. Broad cosmetic offsets hide the underlying coverage cells; bounded movement preserves continuous traffic without drifting into long empty stretches. Their paths extend beyond the full canvas at both ends throughout the permitted camera range, including after resizing, so visitors enter and leave offscreen rather than appearing at a visible spawn point. Camera changes extend the path by filling only newly exposed offscreen coverage without moving existing visitors to new positions. Their cosmetic randomness is independent of the race RNG. People geometry is created once and only transforms change during animation. Camera gestures redraw without reallocating an unchanged renderer. A live reduced-motion preference is also checked by the frame loop so delayed media events cannot leave the ticker running. Existing visibility/activity handling pauses unnecessary rendering when hidden. Static Grid Walk stops the ticker and draws only for interaction/layout changes. Race logic and simulation updates are skipped while browsing.
+
+Very small containers retain the package's minimum-size limits. Provide at least 320 px width and enough height for the scene and controls. Browser checks exercise 320 × 460, 390 × 360, 390 × 760, 640 × 640, 720 × 460, 1120 × 620 and 1400 × 400 hosts. In short containers the shared banner bounds its height and allows its own content to scroll. The project banner retains the race component's text truncation and compact layout.
+
+## Startup, failure and recovery
+
+A successful `restart()` completes loading for any newly created Grid Walk surfaces before rendering the replacement session. Restarted project banners must show their entry content rather than stale startup placeholders.
+
+Grid Walk shares existing renderer/asset startup and teardown ownership. A failed `mountF1Simulator()` rejects and releases its root; invoke the mount function again to retry. For a composable controller, await the rejected `start()` and call `start()` again on the mounted components. If `destroy()` cancelled a pending start, await settlement, remount required surfaces and then call `start()`.
+
+Hosts must restore Retry in a `finally` block and explicitly call their mount/start operation. Importing a cached module does not execute its side effects again. That host-loader wiring is outside this package. Test unpublished changes in the package showcase or a temporary packed consumer.
+
+## Verification surface
+
+Run `npm run site:dev` and open `/guide/grid-walk.html`, or use Grid Walk in the main demo at `/`. The main demo uses the single Start/Stop button; the Guide retains the default two-button switch. Host size controls change actual component dimensions without replacing the simulation. Normal and full browser gates exercise keyboard focus, canvas mouse/touch selection and dragging, diagonal wheel and cross-axis keyboard input, label overlap and selection continuity, opaque light surfaces, every entry, live resizing, state preservation, reduced motion, shared banner content/links and destroy/remount with cached assets. Focused tests cover deterministic progress equivalence, display-only staging and camera hysteresis.

package/docs/index.md

@@ -7,6 +7,8 @@ Code snippets in the documentation are illustrative host integration fragments u
 Start with the consumer task docs:
 
 - [Getting Started](getting-started.md): install, browser mount, package CSS, bundled assets, host responsibilities, and container sizing.
+- [Startup Loading](loading.md): pre-JS placeholders, package loading overlays, static-host build-time integration, and unsupported-size placeholders.
+- [Grid Walk](grid_walk.md): opt-in starting-grid discovery, camera-based resizing, entry selection and race pause/resume.
 - [Composable Layouts](composable-layouts.md): building host layouts from package-owned simulator surfaces.
 - [Headless Environment](headless-environment.md): browser-free environment imports, expert-mode boundary, and basic stepping.
 - [Data Helpers](data-helpers.md): CSS-free data/tooling imports and procedural track helpers.
@@ -25,16 +27,17 @@ Reference docs:
 - [Custom Model Controller Guide](custom_model_controller.md): how to wrap a trained model as a batched driver controller for browser playback or headless loops.
 - [Architecture](architecture.md): module ownership and data/control flow.
 - [Component Inventory](component_inventory.md): package-owned UI surfaces, shared bases, derived/mixed variants, and remaining intentional duplication.
+- [Testing Reliability Guide](testing-reliability-guide.md): risk-driven test selection, behavior maps, required gates, and audit reporting standards.
 - [Data Model Notes](data_model.md): lower-level simulator data model notes kept with package docs.
 - [Learnings](learnings.md): implementation lessons and layout verification rules learned from simulator integration issues.
 
 Common paths:
 
-- Installing PaddockJS into a browser host: read [Getting Started](getting-started.md), then [Data Contract](data_contract.md) for full option shapes.
+- Installing PaddockJS into a browser host: read [Getting Started](getting-started.md), [Startup Loading](loading.md), then [Data Contract](data_contract.md) for full option shapes.
 - Upgrading an existing browser host from 2.x-era usage: read [Upgrading Hosts to 4.x](upgrading-hosts-to-3.md), then [Troubleshooting](troubleshooting.md) if the host build fails.
 - Building a package-owned composable layout: read [Composable Layouts](composable-layouts.md), then the sizing and UI options in [Data Contract](data_contract.md).
 - Enabling pits, penalties, tire requirements, safety car, or stalled off-track DNF: read [Rules](rules.md) first. Pit stops require `rules.modules.pitStops.enabled`; `tireStrategy` alone only controls compounds, tire-requirement stewarding, and pit target choices.
 - Connecting a trained model: read [Headless Environment](headless-environment.md), [Bring Your Own Model](training.md), then [Custom Model Controller Guide](custom_model_controller.md). PaddockJS owns observations, actions, specs, scenarios, and browser playback; the host owns the model, reward, storage, and training framework.
-- Changing internals: read [Architecture](architecture.md) before editing source so new code lands in the feature-owned module instead of a facade or compatibility barrel.
+- Changing internals: read [Architecture](architecture.md) before editing source so new code lands in the feature-owned module instead of a facade or compatibility barrel. Read [Testing Reliability Guide](testing-reliability-guide.md) before adding or changing tests.
 
 When simulator behavior changes, update the relevant doc in this folder in the same change.