Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 12 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,17 @@
# Changelog

## 4.4.0

### Minor Changes

- cd5f46c: Add optional Grid Walk initialPosition: 'start-line' to align the actual start/finish line near the right or top scene edge. Preserve selected-entry centering by default. Measure framing in local canvas coordinates through host loading-scale transitions and refresh late overlay measurements so first interaction does not change a stale camera frame.

Break browser startup into cancellation-aware tasks during procedural generation and track drawing, preserve automatic Grid Walk, and render one complete initial frame. Keep synchronous generation/restart APIs and deterministic geometry unchanged.

### Patch Changes

- ff900fd: Preserve configured drivers across environment participant resets and browser restarts, and keep active state intact when replacement simulation creation fails. Make composable controllers available to ready callbacks, share reentrant startup calls, and stop obsolete restart rendering after callback teardown. Record near-line and exact floating-point sector/lap crossings, carry rounded telemetry times across minute boundaries, and render accepted CSS driver colors consistently on the canvas.

## 4.3.2

### Patch Changes
Expand Down
9 changes: 8 additions & 1 deletion INSTALL_AND_UPDATE.md
Original file line number Diff line number Diff line change
Expand Up @@ -116,12 +116,19 @@ npm run check
Install a specific version when the host needs a controlled upgrade:

```bash
npm install @inventure71/paddockjs@4.3.0
npm install @inventure71/paddockjs@4.4.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.4.0 Migration Notes

- No breaking host migration is required from `4.3.x`. Rebuild the host bundle to receive the startup and lifecycle fixes.
- Browser startup now yields during track generation and drawing while preserving automatic Grid Walk, cancellation and ready callbacks. Local measurements show shorter blocking tasks with a modest increase in elapsed initialization time; see [Browser Startup Responsiveness](docs/browser_startup.md).
- Set `gridWalk: { enabled: true, initialPosition: 'start-line' }` to place the actual start/finish line near the safe right edge in wide hosts or top edge in tall hosts. The default `'selected'` retains initial-entry centering. Grid Walk also keeps its camera framing stable through host loading-scale transitions and late overlay resizing.
- Participant resets/restarts retain configured drivers, ready callbacks can operate the published controller, and timing/color rendering includes reliability fixes. Existing public import paths and synchronous generation/restart APIs are preserved.

### 4.3.0 Migration Notes

- Existing browser and composable mounts retain Race as their default view. Enable Grid Walk with `gridWalk: { enabled: true, initialView: 'grid-walk' }`. Choose `ui: { viewControls: 'toggle' }` for the green Start race / red Stop race button; the default is the two-button switch. See [Grid Walk](docs/grid_walk.md) for host metadata, external controls, camera sizing and paused-progress behavior.
Expand Down
2 changes: 2 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -206,6 +206,8 @@ npm run demo:smoke

Pass `gridWalk: { enabled: true }` to either mounting API to explore the starting grid before racing. Supply entry `presentation` metadata for full names, summaries and ordinary links in the same bottom project banner used by Race. The arrow selector sits centered at the top, with centered entry text; Grid Walk adds no separate project details panel.

Add `gridWalk: { enabled: true, initialPosition: 'start-line' }` to start with the start/finish line near the right edge in a wide host or the top edge in a tall host. The default `'selected'` centers the initially selected entry.

Its package-styled Grid Walk / Race switch lives outside the scene: mount `simulator.mountViewControls(viewControlsRoot)` before `start()` alongside a composable `mountRaceCanvas()`, or use the equivalent `mountViewControls(viewControlsRoot, simulator)` helper. The all-in-one shell and race telemetry drawer include these controls above the scene automatically. Choose `ui: { viewControls: 'toggle' }` for one green **Start race** / red **Stop race** button instead of the default two-button switch. Stop pauses the race and returns to its original display grid; Start resumes saved progress. The main demo demonstrates this single-button option.

`setView('grid-walk' | 'race')` switches presentation without resetting progress; the same grid camera rotates for actual component dimensions and supports drag, touch and wheel browsing. Browser-native scrolling drives that camera and hands scrolling to the host page at the grid's ends. Race wheel zoom uses continuous scroll distance, yields at its limits and preserves native page touch gestures. Neither mode registers a canceling wheel listener or locks body/document scrolling; Ctrl/Meta wheel retains browser zoom. This avoids the nonpassive wheel-listener path implicated in macOS Gecko scroll freezes; it does not patch the browser itself. Grid Walk reuses race controls and panels, with varied preparation crews and a continuous flow of visitors entering and leaving beyond the camera bounds. Existing consumers retain Race defaults. See [Grid Walk](docs/grid_walk.md) for the API, lifecycle and example, or open `/guide/grid-walk.html` on the website. The main demo also starts with Grid Walk.
Expand Down
10 changes: 10 additions & 0 deletions docs/architecture.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,13 @@
# Architecture

## Cooperative browser startup

`src/app/runtime/browserSimulationStartup.js` prewarms immutable geometry cooperatively before invoking the existing simulation factory. `startupTasks.js` owns time budgeting, real task yields and cancellation checks. `src/rendering/track/trackRenderSteps.js` drains shared synchronous/asynchronous drawing generators; kerb/border safety loops expose bounded work checkpoints. Partial scene objects remain owned by the stopped Pixi stage throughout startup. Grid Walk sync can prepare layout without rendering; its scene/input availability becomes active immediately before the single complete initial render. See [Browser startup responsiveness](browser_startup.md).

## Grid Walk presentation boundary

Grid Walk measures chrome in the canvas's local CSS coordinate space, normalizing shared host scaling before calculating camera frames. The layout owner observes overlay size changes and cancels pending layout work on destruction. Initial start-line positioning uses the track's actual zero-distance point; after pan/focus the camera retains its longitudinal world position.

`src/app/gridWalk/` owns optional Grid Walk presentation. `GridWalkController` composes the lifecycle and scene without owning UI action handlers. `GridWalkSession` captures assigned display poses and transition state without changing or stepping the race. `GridWalkCamera` retains one longitudinal world position and a fixed grid axis; `GridWalkNavigation` normalizes pointer and keyboard input into that single camera action; shared native-scroll controls own wheel browsing. `GridWalkControls` owns in-scene entry-selector actions, `GridWalkLabels` owns measured, collision-free label lanes and focus restoration, `GridWalkProjectBanner` composes the shared race banner template/presenter and enabled/muted policy, and `GridWalkLayout` measures chrome/safe scene bounds and restores covered Race UI. Camera framing and label visibility use the same path after selection and manual browsing. Car taps select on release; staging snaps display headings while Race retains smoothing. `GridWalkCrew` creates varied per-car mechanic groups and visitor geometry once, animates transforms with cosmetic randomness independent of the race, and maintains continuous coverage with irregular visitor spacing, varied lateral paths and bounded individual pace/sway, and extends paths beyond the full permitted camera envelope by filling only new offscreen coverage without repositioning existing visitors. `src/ui/gridWalkTemplate.js` composes the semantic surfaces; `src/data/entryPresentation.js` normalizes host metadata/URLs. Runtime visibility, ticker, resize and cleanup paths remain shared. Race, physics and environment modules do not depend on Grid Walk.

`src/ui/viewControlsTemplate.js` and `src/app/controls/SimulatorViewControls.js` own the external Grid Walk / Race component, its startup availability and synchronized active state. `ui.viewControls` selects either the default two-button switch or the single Start race / Stop race action, including on restart; both variants delegate to the same view lifecycle. The composable controller exposes `mountViewControls()`; shell and telemetry-drawer templates compose it above their scenes. A standalone race canvas owns no mode-switch markup. The shared scroll controller directs native scrolling to the Grid Walk camera while active and to Race zoom otherwise. Native boundaries hand scrolling to the host page, and browser modifier zoom remains native. See [Grid Walk](grid_walk.md).
Expand Down Expand Up @@ -120,6 +126,10 @@ training script

The environment runtime consumes per-step events directly from the simulation during `frameSkip` and builds the full public snapshot once for the returned result. This keeps `reset()` / `step()` semantics unchanged while avoiding repeated full car, wheel, penalty, and track serialization inside one environment action.

Resolved environment options retain an internal `configuredDrivers` roster separately from the participating `drivers` used to create a simulation. Reset merging uses the full roster unless the caller replaces `drivers`, allowing previously excluded drivers to participate again. The runtime creates a replacement simulation before committing its options; browser expert hosts likewise defer visual option/driver updates until simulation creation succeeds. Public snapshots, observations, and specs do not expose the internal roster.

Composable startup records its pending promise before initialization can invoke host code. After full renderer/control/ticker setup, an internal initialization hook publishes the running app before ready callbacks. Cancellation during earlier initialization still prevents publication and late ready delivery.

Browser expert mode reuses the same environment runtime around the visual app's existing `RaceSimulation` instance. When `expert.enabled` is true, the visual ticker does not advance simulation time automatically; `simulator.expert.reset()` and `simulator.expert.step(actions)` are the only simulation-advance entry points.

## Shared Data and Presentation Rules
Expand Down
28 changes: 28 additions & 0 deletions docs/browser_startup.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,28 @@
# Browser startup responsiveness

Browser mounting prepares track geometry and draws the scene cooperatively. Automatic Grid Walk starts without a host interaction. Public mount/start promises, ready callbacks, synchronous restart and `createProceduralTrack()` contracts are unchanged.

## Task boundaries and ownership

`src/app/runtime/startupTasks.js` supplies cancellation-aware checkpoints with an 8 ms work budget and real timer-task yields. Microtasks alone cannot release the main thread for input or painting. Track generation yields between candidate construction and validation, and before publishing immutable cached geometry. The existing simulation factory retains ownership of warmup, RNG and mutable race state. Synchronous and asynchronous generation share candidate order, mathematics and cache behavior.

`ProceduralTrackAsset.renderAsync()` consumes the same drawing steps as synchronous rendering. Kerb and border safety queries yield within expensive loops. Every partially built Graphics object is attached to the owned scene before a pause, so destruction releases it. The scene remains non-renderable, its ticker stopped, and its Grid Walk controls inert until construction finishes. Startup renders one complete initial frame before clearing loading state and delivering ready callbacks. Cancellation is checked at task resumptions and before publishing the prepared simulation; a disposed startup cannot restore resources or deliver ready.

## Measured portfolio workload

Measured on 2026-11-12 using an isolated copy of the portfolio Projects page and its real automatic loader, seven F1 entries, simulation seed 71 and track seed 7110. The browser used Apple M4 Pro hardware through ANGLE Metal, viewport 1280×800, DPR 2, with no CPU throttling. Each variant used three fresh page navigations. Diagnostic builds recorded function spans, Long Tasks API entries and an 8 ms timer heartbeat; asynchronous span durations include time yielded to the browser. Baseline and candidate runs were grouped rather than alternated, so these are local ranges, not a general device guarantee.

| Metric | Before | After |
| --- | ---: | ---: |
| Longest startup main-thread task | 597–627 ms | 62–71 ms |
| Longest heartbeat interval | 607–634 ms | 78–86 ms |
| Worst scheduled navbar-handler delay | 598–625 ms | 64–76 ms |
| Initialization until ready | 918–978 ms | 1243–1372 ms |

The baseline spent 224–240 ms in simulation preparation and 537–555 ms drawing the track, predominantly borders (407–418 ms) and kerbs (124–130 ms). Individual geometry candidates took roughly 30–54 ms. Texture loading included asynchronous waits; the candidate first render took 47–50 ms. Initial DOM readouts took about 2 ms, so deferring unused UI was not justified. Cooperative scheduling increases elapsed startup time by roughly 0.3–0.4 seconds while substantially reducing individual stalls. No worker or texture-preparation rewrite was needed for this measured workload. GPU initialization and individual geometry candidates can still exceed the 8 ms scheduling budget because checkpoints cannot preempt an atomic operation.

A separate real navbar click at 768×900 occurred while both initialization and track drawing were pending. The unrelated navbar expanded before startup completed; its First Input entry reported 1.3 ms processing delay and 8 ms duration. This real input measurement is separate from the scheduled-handler comparison above. Baseline and candidate initial simulation snapshots had identical SHA-256 hashes for the fixed workload.

## Regression verification

`startupTasks.test.js`, `runtimeStartup.test.js`, `proceduralTrackAsync.test.js` and `proceduralTrackAsset.test.js` cover real task turns, sync/async parity, cancellation before cache commit and during scene construction, destruction at promise completion, partial resource cleanup and retry. Grid Walk browser smoke covers automatic startup, loading-scale transitions, late overlay resizing, both start-line orientations, input and remounting. Run the package release gate and runtime benchmark for changes to these paths. Repeat host profiling with the real stylesheet/loader, a fixed workload and recorded renderer metadata; distinguish elapsed preparation from blocking task duration.
Loading
Loading