@inventure71/paddockjs 4.1.0 → 4.2.0

package/CHANGELOG.md

@@ -1,5 +1,47 @@
 # Changelog
 
+## 4.2.0
+
+### Minor Changes
+
+- Tighten the package boundary around supported simulator, environment, display, data, and Python policy-server example surfaces. Local JavaScript training experiments now live outside the published package surface, and release-facing docs no longer advertise the removed local starter trainer as packaged guidance.
+- Keep browser expert resets aligned with the resolved `physicsMode` and harden unsupported physics-mode handling so documented hosts continue to use only `arcade` or `advanced`.
+- Add stricter CLI validation for release and diagnostic scripts. Browser smoke, consumer smoke, bundle-boundary checks, runtime benchmarks, track-query benchmarks, and hotspot profiling now provide clean help output and reject unknown or conflicting arguments before running expensive work.
+- Clean up showcase/package-boundary examples so rendered snippets import only public package symbols and leave preview-local policy adapters as host-owned code.
+
+### Performance And Runtime
+
+- Reduce hot-loop allocations in built-in driver control by reusing racing-line profiles, traffic scan entries, lookahead sample objects, and target-point scratch while preserving the same steering/throttle/brake action contract.
+- Add allocation-light track sampling helpers and a prepared sample-index lookup table so repeated `pointAt`/heading/curvature queries avoid binary-search and temporary-object churn on the common simulation paths.
+- Reuse vehicle geometry, body AABB, swept AABB, and interpolated body-shape containers across collision and render paths instead of rebuilding geometry wrappers and axis objects every step.
+- Reuse participant-interaction serialization for render snapshots and avoid repeated spread/object reconstruction in participant interaction resolution.
+- Reduce per-step race/rules/timing churn by replacing transient race-order maps, steward review spreads, repeated inactive-steward state objects, and sector serialization maps with pooled or direct loop paths.
+- Keep advanced/simulator-mode checks behind one helper so browser expert resets, red-flag release, collision damping, driver stabilization, and external state placement stay aligned with the documented `physicsMode` contract.
+
+### Fixes And Hardening
+
+- Preserve the resolved advanced physics mode when the browser expert adapter resets its environment, so expert-controlled browser runs do not silently fall back to arcade behavior.
+- Keep unsupported browser and headless `physicsMode` values normalized to `arcade`, including explicit regression coverage for both surfaces.
+- Carry optional `driverModel` metadata from driver or vehicle input into runtime car state for host-owned model/controller bookkeeping without adding a package-owned model loader.
+- Tighten the environment performance characterization threshold for vector/object observation runs so ray-enabled physical-driver observations remain under the fixed local timing budget.
+
+### Showcase And Tooling
+
+- Add a playable-preview physics selector so the keyboard workbench can switch between arcade and advanced physics through the same documented query-parameter path as the rest of the preview.
+- Add the `scripts/profile-hotspots.mjs` local profiling helper for advanced-mode race hot spots, with validated `--steps`, `--help`, and extra-argument handling.
+- Split browser-smoke and runtime-benchmark argument parsing into focused helpers with direct unit coverage, and extend script coverage across consumer smoke, bundle-boundary, track-query benchmark, and profiler entrypoints.
+- Keep the packed release contents focused on published package assets, docs, Python policy-server examples, source modules, public styles, and placeholder assets.
+
+### Migration Notes
+
+- No breaking host migration is required from `4.1.0`.
+- Supported browser mounts, composable mounts, `@inventure71/paddockjs/environment`, `@inventure71/paddockjs/data`, and `@inventure71/paddockjs/placeholder` keep their documented public import contracts.
+- Hosts should not depend on removed repository-local JavaScript training scripts or preview-only policy helper names. Use the documented environment API, custom model controller guide, or Python policy-server bridge for external training and policy integration.
+
+### Verification Notes
+
+- The final release gate is `npm run check:release`.
+
 ## 4.1.0
 
 ### Minor Changes

package/INSTALL_AND_UPDATE.md

@@ -114,16 +114,22 @@ npm run check
 Install a specific version when the host needs a controlled upgrade:
 
 ```bash
-npm install @inventure71/paddockjs@4.1.0
+npm install @inventure71/paddockjs@4.2.0
 npm run check
 ```
 
 After updating, smoke-test the page that mounts the simulator. Browser behavior changes should be checked in the consuming host, because host CSS, container size, and route handling are outside the package.
 
+### 4.2.0 Migration Notes
+
+- No breaking host migration is required from `4.1.0`.
+- Browser mounts, composable mounts, `@inventure71/paddockjs/environment`, `@inventure71/paddockjs/data`, and `@inventure71/paddockjs/placeholder` keep their documented public import contracts.
+- Do not rely on repository-local JavaScript trainer scripts or preview-only policy helper names as package API. Local model experiments belong outside the package surface; production integrations should use the documented environment API, custom model controller guide, or Python policy-server bridge.
+
 ### 4.1.0 Migration Notes
 
 - No breaking host migration is required from `4.0.0`.
-- Hosts that want visible simulator startup UI before the full PaddockJS browser bundle downloads can render the new `@inventure71/paddockjs/placeholder` HTML helper with the optional `@inventure71/paddockjs/placeholder.css` stylesheet. This placeholder subpath is intentionally independent of PixiJS, simulator assets, root runtime CSS, and the browser mount.
+- Hosts that want visible simulator startup UI before the full PaddockJS browser bundle downloads can render the new `@inventure71/paddockjs/placeholder` HTML helper with the optional `@inventure71/paddockjs/placeholder.css` stylesheet. This placeholder subpath is intentionally independent of PixiJS, simulator assets, root runtime CSS, and the browser mount. Static HTML hosts should generate the placeholder HTML during their build and copy the CSS into their static output; see [Startup Loading](docs/loading.md).
 - Existing `mountF1Simulator()` and composable `mount*()` integrations keep their normal automatic package loading overlays after PaddockJS JavaScript starts.
 
 ### 4.0.0 Migration Notes
@@ -151,6 +157,7 @@ The package repo owns its release process:
 - `npm run check` runs docs checks, fast runtime tests, public type verification, dry-pack verification, packed-consumer install/build verification, the tracked showcase build, and a quick Chromium browser smoke test.
 - `npm run check:release` runs the exhaustive release gate, including slow characterization tests and the full Chromium browser smoke matrix.
 - `npm run consumer:smoke` packs the package, installs the tarball into a fresh temporary Vite app, and builds that app through public package imports.
+- `npm run consumer:bundle-boundaries` packs the package, installs the tarball into a fresh temporary Vite app, and verifies the root browser import remains the CSS/asset-owning simulator bundle while `/placeholder`, `/data`, and `/environment` stay CSS-free or lightweight according to their documented roles.
 - `npm run browser:smoke` builds `local-preview`, starts a local preview server, and checks desktop/mobile canvas rendering, overflow constraints, API buttons, and visual policy-runner stepping in Chromium. Use `npm run browser:smoke:quick` for the smaller local browser pass and `npm run browser:smoke:full` for the full matrix.
 - `npm run changeset` records the next version bump and changelog note.
 - `npm run version-packages` applies pending Changesets locally.

package/README.md

@@ -82,11 +82,12 @@ if ('requestIdleCallback' in window) {
 }
 ```
 
-`@inventure71/paddockjs/placeholder` does not import PixiJS, simulator assets, package runtime CSS, or the root browser mount. It is intended for the pre-JS/network gap. The full simulator mount replaces that placeholder and then uses the built-in package overlays while PixiJS and the race runtime finish booting.
+`@inventure71/paddockjs/placeholder` does not import PixiJS, simulator assets, package runtime CSS, or the root browser mount. It is intended for the pre-JS/network gap. The full simulator mount replaces that placeholder and then uses the built-in package overlays while PixiJS and the race runtime finish booting. Static HTML hosts should run the placeholder helper in their build step and copy `@inventure71/paddockjs/placeholder.css` into their static output instead of expecting a plain browser page to resolve bare npm imports.
 
 Start here:
 
 - [Getting Started](docs/getting-started.md): install, browser mount, CSS, assets, host responsibilities, and container sizing.
+- [Startup Loading](docs/loading.md): pre-JS placeholders, package loading overlays, and static-host build-time integration.
 - [Data Contract](docs/data_contract.md): driver, entry, callback, rules, and option shapes.
 - [Troubleshooting](docs/troubleshooting.md): common integration failures and supported checks.
 
@@ -176,11 +177,12 @@ npm run docs:check
 npm run check
 npm run check:release
 npm run consumer:smoke
+npm run consumer:bundle-boundaries
 npm run browser:smoke:quick -- --skip-build
 npm run showcase:dev
 ```
 
-`npm run check` is the normal local gate: docs checks, fast runtime tests, public declarations, dry package contents, packed-package consumption in a fresh Vite app, the showcase build, and a quick Chromium smoke against the showcase. `npm run check:release` adds slow characterization tests and the full browser smoke matrix.
+`npm run check` is the normal local gate: docs checks, fast runtime tests, public declarations, dry package contents, packed-package consumption in a fresh Vite app, packed subpath bundle-boundary checks, the showcase build, and a quick Chromium smoke against the showcase. `npm run check:release` adds slow characterization tests and the full browser smoke matrix.
 
 ## License
 

package/docs/architecture.md

@@ -281,6 +281,8 @@ Timing maintenance is also kept allocation-light now. Runtime timing writes in `
 
 `src/simulation/vehicle/vehicleState.js` owns external state mutation from simulator and environment reset APIs. It rejects non-finite numeric partial state and resynchronizes advanced-mode velocity from speed/heading when callers do not provide an explicit velocity vector, so scenario placement and `resetDrivers()` cannot leave stale physics velocity behind.
 
+Local model training experiments belong outside the committed package surface. The ignored `training-lab/` folder may hold local trainer scripts, checkpoints, model loaders, and research harnesses, but package modules, preview routes, public exports, published types, and consumer docs must stay focused on simulator/environment/display contracts.
+
 `src/simulation/rules/pitLaneSpeedingSteward.js` owns pit-speed-limit review. `raceSimulation.js` calls it after authoritative race-state recalculation so it reads the same pit-lane part classification as snapshots and track-limit stewarding. The steward only checks speed-limited pit-lane parts (`fast-lane`, `working-lane`, service areas, and garage boxes), leaving pit-entry and pit-exit connector roads legal but not speed-limited.
 
 Browser mounts generate a fresh procedural seed when `trackSeed` is omitted; explicit procedural track seeds are cached by seed plus resolved generation options so repeated mounts with the same procedural contract do not regenerate or rebuild the same model. The canonical generator owns both the default `race` profile and the smaller training profiles. Profile resolution lives beside the track model, merges `race` defaults, selected profile defaults, and explicit overrides, then feeds the same centerline, validation, start-straight, spatial-query, surface, and physics pipeline. Procedural generation starts from seeded connected coarse region masks, traces the outer boundary, smooths and warps the boundary into centerline controls, validates shape, clearance, local turn accumulation, length, and per-sample heading jumps, and retries with another region-derived control set instead of immediately falling back to an oval control ring when attempts fail.

package/docs/component_inventory.md

@@ -34,7 +34,7 @@ This inventory maps package-owned UI surfaces to their shared bases, owner modul
 | Telemetry sector times | `mountTelemetrySectorTimes()` and telemetry stack | `src/ui/telemetryTemplates.js` | Telemetry module class helper, loading overlay, unsupported overlay | `telemetryRenderer.js` | Last/best sector table only. |
 | Car/driver overview | `mountCarDriverOverview()` and optional telemetry stack embed | `src/ui/carOverviewTemplate.js` | Component surface frame helper, overview field slots, loading overlay, unsupported overlay | `domBindings.js` cached field bindings, `carOverviewRenderer.js` | Standalone and stack-embedded variants share identical markup. Runtime toggles vehicle vs driver fields without remounting and updates cached label/value bindings instead of querying each field during render. |
 | Race telemetry drawer | `mountRaceTelemetryDrawer()` and complete preview template | `src/ui/telemetryDrawerTemplate.js` | Component surface frame helper, loading overlay, camera controls, compact safety-car control, race canvas with timing/data panel, telemetry stack, unsupported overlay | `F1SimulatorApp.setTelemetryDrawerOpen()`, `controlStateRenderer.js`, normal race/telemetry renderers | Higher-level mixed template. It intentionally owns toolbar placement, drawer ids, open/closed inert state, and responsive narrow drawer behavior. |
-| Loading overlay | All public startup-capable mounted surfaces, including all-in-one shell children and composable roots | `src/ui/templateUtils.js` | `createLoadingMarkup(label)` | `F1SimulatorApp.completeComponentLoading()` | Removed after startup after the initial frame. Component labels remain surface-specific for accessibility. Pre-JS placeholders are host-owned, not package-owned. |
+| Loading overlay | All public startup-capable mounted surfaces, including all-in-one shell children and composable roots | `src/ui/templateUtils.js` | `createLoadingMarkup(label)` | `F1SimulatorApp.completeComponentLoading()` | Removed after startup after the initial frame. Component labels remain surface-specific for accessibility. Pre-JS placeholders are rendered by the host before package runtime starts, not by `F1SimulatorApp`. |
 | Pre-JS startup placeholder | `@inventure71/paddockjs/placeholder` and `@inventure71/paddockjs/placeholder.css` | `src/placeholder/index.js`, `src/placeholder.css` | Escaped inert HTML helper, optional tiny CSS start-light animation | Host page before root simulator import | Covers the network/import gap before the root package can render. It must stay independent of PixiJS, simulator assets, root runtime CSS, and app modules. |
 | Unsupported-size overlay | Public mount roots, shell, drawer, race/data/telemetry surfaces | `src/ui/templateUtils.js` | `createUnsupportedSizeMarkup(label)` | `installLayoutSupport()` | Display is driven by measured support state. Minimum size thresholds remain centralized in `layoutSupport.js`. |
 

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/index.md

@@ -7,6 +7,7 @@ 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.
 - [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 +26,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.

package/docs/loading.md

@@ -0,0 +1,141 @@
+# Startup Loading
+
+PaddockJS has two different startup loading surfaces. They solve different timing problems and should not be treated as interchangeable.
+
+## The Two Phases
+
+| Phase | When it can appear | Owner | Purpose |
+| --- | --- | --- | --- |
+| Pre-JS placeholder | Before the full PaddockJS browser bundle has downloaded, parsed, and imported | Host page, using the optional package placeholder helper/CSS | Give the user immediate lightweight visual feedback during the network/import gap |
+| Package loading overlays | After `mountF1Simulator()` or a composable `mount*()` call starts | PaddockJS runtime | Cover PixiJS setup, asset loading, control binding, simulation creation, readout initialization, and the first real frame |
+
+The pre-JS placeholder exists because PaddockJS cannot render anything before PaddockJS code exists on the page. The package loading overlays exist because, once the package has started, the runtime still needs time to build the simulator.
+
+## Phase 1: Pre-JS Placeholder
+
+Use the optional placeholder subpath when a host wants visible simulator UI before importing the full browser runtime:
+
+```js
+import { createPaddockLoadingPlaceholder } from '@inventure71/paddockjs/placeholder';
+import '@inventure71/paddockjs/placeholder.css';
+
+root.innerHTML = createPaddockLoadingPlaceholder({
+  label: 'Loading simulator',
+  detail: 'Preparing race control',
+});
+```
+
+`@inventure71/paddockjs/placeholder` is intentionally separate from the root package. It does not import PixiJS, simulator assets, package runtime CSS, `F1SimulatorApp`, or the browser mount. The stylesheet at `@inventure71/paddockjs/placeholder.css` is a tiny standalone stylesheet for the default start-light placeholder.
+
+The helper returns inert escaped HTML. It does not mount the simulator, register event listeners, fetch assets, or start any timers. The default `lights` variant uses CSS animation only.
+
+## Bundled Browser Hosts
+
+In Vite, Rollup, Webpack, or another browser bundler, render the placeholder first, then dynamically import the full simulator:
+
+```js
+import { createPaddockLoadingPlaceholder } from '@inventure71/paddockjs/placeholder';
+import '@inventure71/paddockjs/placeholder.css';
+
+const root = document.getElementById('f1-simulator-root');
+
+root.innerHTML = createPaddockLoadingPlaceholder({
+  label: 'Loading simulator',
+});
+
+const startSimulator = async () => {
+  const { mountF1Simulator } = await import('@inventure71/paddockjs');
+  await mountF1Simulator(root, { drivers, entries });
+};
+
+if ('requestIdleCallback' in window) {
+  window.requestIdleCallback(startSimulator);
+} else {
+  setTimeout(startSimulator, 0);
+}
+```
+
+The dynamic root import lets the page paint the placeholder before paying for the full browser simulator bundle. The full mount replaces the placeholder root content when PaddockJS starts.
+
+## Static HTML Hosts
+
+Plain static HTML pages cannot resolve bare npm imports such as `@inventure71/paddockjs/placeholder` directly in the browser unless the page also provides a bundler output or import map. Do not add a runtime bundling step only to render the placeholder.
+
+For static hosts with a build script, run the helper at build time and inject the generated HTML into the static page:
+
+```js
+import { copyFileSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname } from 'node:path';
+import { createPaddockLoadingPlaceholder } from '@inventure71/paddockjs/placeholder';
+
+const require = createRequire(import.meta.url);
+
+const placeholderHtml = createPaddockLoadingPlaceholder({
+  label: 'Loading simulator',
+  detail: 'Preparing race preview',
+});
+
+const cssSource = require.resolve('@inventure71/paddockjs/placeholder.css');
+const cssTarget = 'dist/f1-simulator/paddock-placeholder.css';
+
+mkdirSync(dirname(cssTarget), { recursive: true });
+copyFileSync(cssSource, cssTarget);
+
+const html = readFileSync('projects.html', 'utf8')
+  .replace('<!-- paddock-placeholder -->', placeholderHtml)
+  .replace(
+    '</head>',
+    '  <link rel="stylesheet" href="/f1-simulator/paddock-placeholder.css">\n</head>',
+  );
+
+writeFileSync('dist/projects.html', html);
+```
+
+That pattern keeps the first paint static and cheap while avoiding manual markup drift. The HTML still comes from the package helper, and the CSS still comes from the package stylesheet.
+
+If a static host cannot run the helper during its build, copying the generated placeholder markup contract is acceptable as a fallback, but it is weaker. Manual markup can drift if the package changes the placeholder structure in a later release.
+
+## Phase 2: Package Loading Overlays
+
+After PaddockJS JavaScript starts, `mountF1Simulator(root, options)` synchronously writes a lightweight package shell into the mount root. The shell includes package-owned loading overlays for startup-capable surfaces such as the race canvas, controls, timing tower, race-data panel, telemetry stack, and composable component roots.
+
+Composable hosts get the same behavior per mounted surface:
+
+```js
+const simulator = createPaddockSimulator(options);
+
+simulator.mountRaceCanvas(canvasRoot);
+simulator.mountTimingTower(timingRoot);
+simulator.mountTelemetryPanel(telemetryRoot);
+
+await simulator.start();
+```
+
+Each `mount*()` call writes 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.
+
+These overlays are automatic. Hosts should not recreate them, query them for simulator state, or patch package internals to hide them. If a host needs a different pre-PaddockJS first paint, use the phase-1 placeholder around or inside the same root before calling the package mount.
+
+## Replacement Flow
+
+A typical lazy startup flow is:
+
+1. Host HTML/CSS paints the page and optional pre-JS placeholder.
+2. Host code imports the full PaddockJS browser bundle.
+3. `mountF1Simulator()` or composable `mount*()` calls replace the placeholder with package startup markup.
+4. PaddockJS shows package loading overlays while runtime setup finishes.
+5. PaddockJS removes those overlays after the first real simulator frame is ready.
+
+The pre-JS placeholder and package overlays can look similar, but they are intentionally separate. The first is a host-rendered shell for the network/import gap. The second is package runtime UI for simulator boot.
+
+## What Not To Do
+
+- Do not expect a plain static HTML page to resolve `@inventure71/paddockjs/placeholder` as a browser import without a bundler or import map.
+- Do not eagerly import the root `@inventure71/paddockjs` package just to show a loading screen; that defeats the payload split.
+- Do not copy simulator assets or PixiJS into the pre-JS placeholder.
+- Do not manually maintain copied placeholder markup when the host has a build step that can call `createPaddockLoadingPlaceholder()`.
+- Do not style package runtime internals such as `.start-lights`, `.timing-list`, or `.race-data-panel` from host CSS. Size the host root and let PaddockJS own runtime layout.
+
+## Related Placeholders
+
+PaddockJS also shows an `Unsupported size` placeholder when a shell or component is constrained below its supported bounds. That is not a startup loader. It is a layout safety state that tells the host to fix the container size rather than letting package controls overlap or clip.

package/docs/system_specs.md

@@ -367,7 +367,7 @@ Full public race snapshots include `car.trackState` as the serialized car-center
 - `pixi.js` available through the package dependency graph.
 
 Raw Node imports of the package root are not a supported runtime check because the browser component entry imports CSS and image assets. The `@inventure71/paddockjs/environment` subpath is the supported browser-free import path for headless JavaScript training.
-The repository starter loop is executable with `node examples/train-basic-policy.mjs`. It imports the public environment subpath and self-contained example data from `examples/trainingData.mjs`. It is a dependency-free example that trains/evaluates a tiny policy against the environment contract; it is not a packaged Gymnasium bridge or a recommended final RL algorithm. The package exposes a JSON-serializable worker protocol wrapper so external processes can bridge to the JavaScript environment without PaddockJS choosing Python, Gymnasium, PettingZoo, model storage, or training infrastructure.
+The package exposes a JSON-serializable worker protocol wrapper so external processes can bridge to the JavaScript environment without PaddockJS choosing Python, Gymnasium, PettingZoo, model storage, training algorithms, checkpoint formats, or training infrastructure.
 
 ## Verification
 
@@ -382,9 +382,12 @@ Expected:
 - Fast Vitest tests pass in the normal local gate. Slow characterization tests run under `npm run check:release`.
 - `npm pack --dry-run` succeeds and includes source files plus bundled assets.
 - A packed tarball installs and builds inside a fresh temporary Vite consumer app.
+- Packed subpath bundle-boundary checks verify that the root import remains the CSS/asset-owning browser simulator bundle while `/placeholder`, `/data`, and `/environment` stay CSS-free or lightweight according to their documented roles.
 - The tracked showcase host builds.
 - The quick Chromium browser smoke verifies showcase canvas rendering, overflow constraints, one public API action, and live customization theme switching. The release browser smoke verifies the desktop/mobile matrix, package-panel overflow constraints, customization route interactions, public API buttons, and visual policy-runner stepping across generation and race configurations.
 
+Use [Testing Reliability Guide](testing-reliability-guide.md) to choose the smallest behavior-focused proof for a change before relying on the broad package gate. The guide is authoritative for mapping package/API, simulation, environment, browser, performance, and docs changes to focused tests and required broader verification.
+
 For internal runtime-efficiency development only, also run:
 
 ```bash

package/docs/testing-reliability-guide.md

@@ -0,0 +1,62 @@
+# Testing Reliability Guide
+
+PaddockJS reliability work is risk-driven. Do not add tests for coverage vanity. Add or change tests when they protect a package contract, a simulator state transition, a browser lifecycle path, or a performance invariant that can silently regress.
+
+## Confidence Model
+
+Use the smallest verification layer that proves the behavior, then run the broader gate before claiming package quality.
+
+- Unit tests in `src/__tests__/` prove deterministic simulation, data normalization, sensor math, controller loops, and focused UI rendering helpers.
+- Public type tests in `src/__tests__/publicApi.types.ts` prove the TypeScript consumer contract for root, `/data`, `/environment`, and `/placeholder` imports.
+- `npm run consumer:smoke` proves the packed tarball installs and builds in a fresh Vite consumer through public package imports.
+- `npm run consumer:bundle-boundaries` proves the packed root browser import remains the CSS/asset-owning simulator bundle while `/placeholder`, `/data`, and `/environment` stay CSS-free or lightweight according to their documented roles.
+- `npm run showcase:ci` proves the tracked browser showcase still builds.
+- `npm run browser:smoke:quick -- --skip-build` proves the built showcase can mount, paint a nonblank canvas, avoid key overflow regressions, exercise public controls, and keep live customization paths working.
+- `npm run browser:smoke:full -- --skip-build` is required for broad browser/showcase/layout behavior and release handoff.
+- `npm run benchmark:runtime -- --profile=standard --verify --json` proves simulation, sensor, rendering-data, snapshot, DOM-readout, and compact-transport performance contracts.
+
+## Change Matrix
+
+| Change area | Required focused proof | Required broader proof |
+| --- | --- | --- |
+| Public root, `/data`, `/environment`, or `/placeholder` API/types | `npm run types:check` plus a public API type assertion when the contract changes | `npm run check` |
+| Package install, exports, files, CSS/assets, subpath bundle boundaries, or build assumptions | `npm run pack:dry`, `npm run consumer:smoke`, or `npm run consumer:bundle-boundaries` | `npm run check` |
+| Race rules, ordering, DRS, starts, safety car, red flag, pits, penalties, collisions, or finish/classification | Focused Vitest file for the changed rule path | `npm run check`; use `npm run check:release` for broad behavior |
+| Track geometry, query index, wheel surfaces, runoff, contact patches, or sensor rays | Focused geometry/sensor tests plus benchmark verification when hot paths change | `npm run check`; benchmark command required for performance-sensitive edits |
+| Headless environment, controller loop, worker protocol, Policy Runner, observation/vector/schema contract | Focused environment/controller/transport tests and active observation contract assertions | `npm run check`; benchmark if compact/vector/snapshot cost changes |
+| Browser runtime, Pixi lifecycle, layout support, readouts, controls, theme, loading, or smoke pages | Focused DOM/render helper tests where possible | `npm run check`; full browser smoke for broad layout/showcase changes |
+| Docs-only consumer guidance | `npm run docs:check` | `npm run check` when docs describe package behavior changed in code |
+
+## Test Quality Rules
+
+- Test behavior through the production path whenever practical. Avoid tests that recreate private helper logic and only prove the helper still matches itself.
+- Include negative, stale-state, restart/remount, and partial-update cases for lifecycle code.
+- For deterministic simulation changes, fix the seed, track seed, drivers, entries, rules, and scenario inputs in the test.
+- For model-facing senses, assert the active observation/vector/schema contract. Debug overlays may have extra data, but no model-sense panel should display a recomputed or more precise value as model input.
+- For performance-sensitive paths, assert counters that explain the cost, such as fallback counts, allocation counters, or compact payload sizes. Do not rely only on elapsed time.
+- For package boundary work, prove public imports from the packed package, not internal relative paths.
+- For browser layout work, prove rendered behavior with browser smoke or a focused DOM/canvas check. Static markup snapshots are not enough when resize observers, canvas painting, or runtime CSS state are involved.
+
+## High-Risk Behaviors To Map In Audits
+
+- `mountF1Simulator()` and `createPaddockSimulator()` lifecycle: initial shell, loading overlays, start, restart, theme sync, destroy, and repeated mount behavior.
+- Public subpath boundaries: root imports browser/CSS runtime, `/environment` stays browser-free and CSS-free, `/data` stays CSS-free, `/placeholder` stays tiny and inert.
+- Determinism: same seed, track seed, drivers, entries, rules, and scenario produce stable simulation behavior.
+- Track query index propagation: built runtime tracks keep the internal non-enumerable index, while public JSON snapshots do not leak engine helpers.
+- Race state transitions: start sequence, safety car, red flag, pit-lane open/closed, pit stops, penalties, DNF, finish, and final classification.
+- Model-facing observations: object/vector/schema alignment, per-driver overrides, compact/vector-only outputs, reset-only observations, and external renderer frames.
+- Rendering and layout: nonblank canvas, timing tower constraints, unsupported-size placeholders, lower-third/timing clearance, theme variables, and composable roots.
+- Package consumption: dry pack contents, fresh consumer install/build, browser showcase build, and documented host update path.
+
+## Reporting Standard
+
+Every reliability audit should report:
+
+- current confidence: what is proven and what remains unproven;
+- findings ranked by user impact and regression likelihood;
+- exact files and behavior paths affected;
+- smallest test or verification change that would close each gap;
+- commands run, with the gate level they prove;
+- any rejected critique, with the technical reason it is not accepted.
+
+If a required command is blocked by the environment, report the command, failure text, retry state, and the exact proof still missing. Do not replace a broad required gate with a narrow check.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inventure71/paddockjs",
-  "version": "4.1.0",
+  "version": "4.2.0",
   "type": "module",
   "description": "A data-driven browser F1 simulator component for host websites.",
   "license": "Apache-2.0",
@@ -68,8 +68,6 @@
     "examples/python/README.md",
     "examples/python/base_policy_server.py",
     "examples/python/requirements.txt",
-    "examples/train-basic-policy.mjs",
-    "examples/trainingData.mjs",
     "src/api",
     "src/app",
     "src/config",
@@ -90,10 +88,11 @@
     "test:fast": "node scripts/run-vitest.mjs",
     "types:check": "tsc -p tsconfig.types.json --noEmit",
     "docs:check": "node scripts/docs-check.mjs",
-    "check": "npm run docs:check && npm run test:fast && npm run types:check && npm run pack:dry && npm run consumer:smoke && npm run 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",
+    "check": "npm run docs:check && npm run test:fast && npm run types:check && npm run pack:dry && npm run consumer:smoke && npm run consumer:bundle-boundaries && npm run showcase:ci && npm run browser:smoke:quick -- --skip-build",
+    "check:release": "npm run docs:check && npm test && npm run types:check && npm run pack:dry && npm run consumer:smoke && npm run consumer:bundle-boundaries && npm run showcase:ci && npm run browser:smoke:full -- --skip-build",
     "pack:dry": "npm pack --dry-run",
     "consumer:smoke": "node scripts/consumer-package-smoke.mjs",
+    "consumer:bundle-boundaries": "node scripts/consumer-bundle-boundaries.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",
@@ -104,8 +103,7 @@
     "showcase:ci": "npm --prefix local-preview ci && npm --prefix local-preview run build",
     "changeset": "changeset",
     "version-packages": "changeset version",
-    "release": "npm publish --provenance",
-    "example:train": "node examples/train-basic-policy.mjs"
+    "release": "npm publish --provenance"
   },
   "dependencies": {
     "pixi.js": "8.18.1"

package/src/data/index.d.ts

@@ -38,6 +38,69 @@ export interface PaddockProceduralTrackOptions {
   };
 }
 
+export interface PaddockTrackPoint {
+  x: number;
+  y: number;
+}
+
+export interface PaddockDrsZone {
+  id: string;
+  startRatio: number;
+  endRatio: number;
+}
+
+export interface PaddockResolvedProceduralTrackOptions {
+  profile: PaddockProceduralTrackProfile;
+  length: {
+    min: number;
+    max: number;
+  };
+  startStraight: {
+    grid: number;
+    exit: number;
+    blend: number;
+    lockExtra: number;
+  };
+  pitLane: {
+    enabled: boolean;
+  };
+  shape: {
+    scale: number;
+    cornerDensity: number;
+    variation: number;
+  };
+  validation: {
+    minClearanceMultiplier: number;
+    minShapeVariation: number;
+    minNonAdjacentArcDistance: number;
+    maxLocalTurnRadians: number;
+    maxSampleHeadingDeltaRadians: number;
+  };
+  attempts: {
+    primary: number;
+    fallback: number;
+  };
+  cacheKey: string;
+  [key: string]: unknown;
+}
+
+export interface PaddockProceduralTrack {
+  name: string;
+  width: number;
+  kerbWidth: number;
+  gravelWidth: number;
+  runoffWidth: number;
+  barrierWidth: number;
+  sampleCount: number;
+  seed?: number;
+  curveInterpolation?: string;
+  centerlineControls?: readonly PaddockTrackPoint[];
+  drsZones?: readonly PaddockDrsZone[] | null;
+  pitLane?: { enabled?: boolean } | null;
+  generationOptions?: PaddockResolvedProceduralTrackOptions;
+  [key: string]: unknown;
+}
+
 export interface CustomField {
   label: string;
   value: string;
@@ -207,6 +270,6 @@ export function normalizeSimulatorDrivers(
   drivers: SimulatorDriver[],
   options?: { entries?: ChampionshipEntryBlueprint[]; caller?: string },
 ): NormalizedSimulatorDriver[];
-export function createProceduralTrack(seed?: number | string, options?: PaddockProceduralTrackOptions): unknown;
+export function createProceduralTrack(seed?: number | string, options?: PaddockProceduralTrackOptions): PaddockProceduralTrack;
 export function kphToSimSpeed(kph: number): number;
 export function simSpeedToKph(simSpeed: number): number;