@inventure71/paddockjs 0.1.0

package/docs/index.md

@@ -0,0 +1,15 @@
+# PaddockJS Documentation
+
+PaddockJS is a browser-mounted, data-driven F1-style race simulator component. It is designed to live as its own package and be installed into host websites such as the portfolio site.
+
+Use these docs as the package source of truth:
+
+- [System Specs](system_specs.md): expected package behavior, public API, runtime guarantees, and verification standards.
+- [Rules](rules.md): race-control behavior, DRS, safety car, starts, ordering, contact handling, and simulation rules.
+- [Concepts](concepts.md): vocabulary used by the simulator.
+- [Data Contract](data_contract.md): shape of host-provided drivers, car pairings, ratings, assets, and callbacks.
+- [Architecture](architecture.md): module ownership and data/control flow.
+- [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.
+
+When simulator behavior changes, update the relevant doc in this folder in the same change.

package/docs/learnings.md

@@ -0,0 +1,47 @@
+# Learnings
+
+This file records implementation lessons that should influence future PaddockJS changes.
+
+## Overlay Layouts Need Internal Safe Areas
+
+When a package-owned preset overlays one component on top of another, the preset must reserve a safe area for every affected layer:
+
+- The visual overlay itself.
+- Canvas camera framing.
+- Canvas-hosted controls.
+- Start lights.
+- Lower-third and radio banners, unless the intended broadcast treatment is to overlay them across the full combined grid.
+- Any internal rows, headers, grids, or readouts inside the overlay.
+
+The left timing-tower overlay exposed this risk. Shrinking the tower container was not enough, because the timing rows still used the wider default timing-column grid. The result was a horizontal scrollbar inside the tower entries even though the outer tower size was package-controlled.
+
+The rule is: do not only constrain the outer component. Also verify that all child grids and fixed-width pieces can compress within the new preset.
+
+## Presets Own Their Internal Ratios
+
+For all-in-one layout presets, hosts may scale the full mounted simulator through the container. Hosts should not be given raw width, max-width, or horizontal-ratio options for internal preset pieces.
+
+If a host needs full layout ownership, it should use the composable API and mount package-owned pieces separately:
+
+```js
+const simulator = createPaddockSimulator(options);
+simulator.mountRaceCanvas(canvasRoot, { includeRaceDataPanel: true });
+simulator.mountTimingTower(timingRoot);
+await simulator.start();
+```
+
+Avoid adding public options like `timingTowerWidth`, `timingTowerMaxWidth`, or arbitrary column ratios. Prefer named package-owned variants if a second layout is genuinely needed.
+
+When the race-data lower-third must overlay the timing tower while staying clipped inside the race window, keep it inside the race canvas with `includeRaceDataPanel: true`. Mounting it as a sibling root gives the host responsibility for stacking contexts and can put the banner underneath the timing tower.
+
+## Layout Verification Standard
+
+For visual layout changes, verify more than the happy path screenshot:
+
+- Desktop, tablet, and narrow mobile widths.
+- Standard and overlay presets.
+- `scrollWidth <= clientWidth` for shell, canvas panel, timing tower, timing list, timing rows, column header, race-data panel, telemetry, car overview, camera controls, and topbar controls.
+- Overlay safe-area geometry: camera controls must start to the right of the overlay tower, while race-data banners are allowed to overlay the tower but must remain centered and clipped inside the race window.
+- Browser smoke against an installed/bundled host, not only string-based unit tests.
+
+Unit tests should cover the contract, but browser geometry checks catch CSS interactions that tests can miss.

package/docs/rules.md

@@ -0,0 +1,181 @@
+# Race Rules
+
+This file documents the rules currently implemented by the simulator. If the race engine changes, update this file with the behavior change.
+
+## Default Race Rules
+
+Default rules are defined in `src/simulation/raceSimulation.js` as `DEFAULT_RULES`:
+
+- DRS detection gap: `1` second.
+- Safety car speed: `46` world units per second.
+- Safety car lead distance: `122` world units.
+- Safety car queue gap: `128` world units.
+- Collision restitution: `0.18`.
+- Standing start enabled by default.
+- Start lights: `5`.
+- Start light interval: `0.72` seconds.
+- Lights-out hold: `0.78` seconds.
+
+## Race Modes
+
+The simulator has three race-control modes:
+
+- `pre-start`: cars are grid locked while start lights run.
+- `green`: normal racing.
+- `safety-car`: order is frozen and cars queue behind the safety car.
+
+Safety car deployment is ignored during `pre-start`.
+
+## Standing Start
+
+When standing start is enabled:
+
+- Cars begin in staggered grid slots.
+- Cars stay locked until the start-light sequence releases them.
+- Start lights increment over time.
+- When lights go out, cars release and race mode becomes `green`.
+
+When standing start is disabled through rules, race mode starts as `green`.
+
+## Ordering And Timing
+
+Race order is based on `raceDistance`, descending. Ties fall back to original driver index.
+
+During safety car, order is frozen at deployment time. That prevents passing from reshuffling the timing tower while the safety car is active.
+
+Timing history is sampled per car and used to estimate:
+
+- Interval to the car ahead as `intervalAheadSeconds` / `gapAheadSeconds`.
+- Cumulative gap to the leader as `leaderGapSeconds`.
+- DRS detection timing.
+
+The timing tower can switch at runtime between `Int` mode, which displays interval to the car ahead, and `Gap` mode, which displays cumulative gap to the leader. Timing continues to be calculated during pre-start, safety-car, and post-finish states even when the UI shows state labels such as `Grid`, `SC`, or `FIN`.
+
+## Units
+
+The race engine uses simulator units internally. `src/simulation/units.js` converts simulator distance and speed to public meter and km/h values. The current speed calibration maps the simulation maximum speed to an F1-like `330 km/h`; rendered car sprite dimensions are a visual scale and are not used as the physical distance scale.
+
+## Laps
+
+Lap is computed from each car's cumulative race distance over the track length. Total laps are provided by mount options and default to `10`.
+
+Each car is marked `finished` when it reaches `track.length * totalLaps`. The first finisher becomes `winner`, receives classified rank `1`, and emits a `car-finish` event, but the race keeps running until every car has crossed the finish distance.
+
+When all cars have finished, the simulator records `finishedAt` and final `classification`, emits a `race-finish` event, freezes order to the classified result, deploys the safety car, and switches race mode to `safety-car`. Finished cars keep circulating under safety-car behavior instead of hard-stopping. The current implementation does not yet implement pit stops, penalties, or championship scoring.
+
+## DRS
+
+DRS behavior:
+
+- DRS is disabled during safety car.
+- Each track has DRS zones.
+- A car latches into a DRS zone when it crosses that zone start.
+- A car becomes DRS eligible if it was close enough to the car ahead at the relevant detection crossing.
+- The current detection window is controlled by `drsDetectionSeconds`.
+- When eligible inside the latched zone, `drsActive` becomes true.
+
+Physics effect:
+
+- Active DRS reduces drag through `src/simulation/vehiclePhysics.js`.
+- The current drag multiplier is `0.42`.
+
+Visual effect:
+
+- Active DRS creates cyan trail segments behind the car in `src/app/F1SimulatorApp.js`.
+
+## Safety Car
+
+Safety car behavior:
+
+- Deployment switches race mode to `safety-car`.
+- Race order freezes.
+- DRS state is cleared for all cars.
+- Driver aggression is reduced.
+- Cars target a queue slot behind the safety car.
+- Timing values continue to be calculated, but gaps in the timing tower display as `SC` for non-leaders.
+
+When safety car is cleared:
+
+- Race mode returns to `green`.
+- Frozen order is removed.
+- Normal DRS and attacking behavior can resume.
+
+## Driver AI
+
+Driver control decisions live in `src/simulation/driverController.js`.
+
+The AI has separate behavior for:
+
+- Grid lock.
+- Green-flag racing.
+- Off-track rejoin.
+- Safety-car queueing.
+
+Green-flag behavior uses:
+
+- Driver aggression.
+- Racecraft.
+- Risk tolerance.
+- Patience.
+- Current tire energy.
+- Track curvature.
+- Nearby traffic.
+- Preferred and available lane offsets.
+
+## Vehicle Physics
+
+Vehicle physics live in `src/simulation/vehiclePhysics.js`.
+
+The model includes:
+
+- Steering target and steering rate.
+- Engine force.
+- Brake force.
+- Drag force.
+- Rolling resistance.
+- Surface grip.
+- Downforce grip.
+- Tire condition.
+- Yaw-rate saturation.
+- Tire energy wear.
+
+This is a browser simulation with physically grounded approximations. It is not exact F1 telemetry or a professional motorsport dynamics model.
+
+## Surfaces
+
+Track state can classify a car as on:
+
+- `track`
+- `kerb`
+- `gravel`
+- `grass`
+- `barrier`
+
+Surface affects grip, drag, and rolling resistance.
+
+## Contact And Collision Handling
+
+Collision handling uses:
+
+- Oriented bounding-box overlap checks.
+- Longitudinal spacing checks.
+- Limited position correction.
+- Contact velocity response.
+- Yaw nudges.
+- Contact cooldown.
+
+The goal is believable traffic spacing and visible contact response, not full rigid-body simulation.
+
+## Known Non-Goals For Now
+
+These are not currently implemented:
+
+- Pit stops.
+- Tire compound strategy.
+- Fuel load strategy.
+- Weather.
+- Penalties.
+- Mechanical failures.
+- Race finish ceremony.
+- Multiplayer controls.
+- Official timing rules, licensing, or real-world team identities.

package/docs/system_specs.md

@@ -0,0 +1,211 @@
+# System Specs
+
+## Purpose
+
+PaddockJS mounts an interactive F1-style race simulator into a host webpage. The package owns the simulator UI, PixiJS renderer, bundled simulator assets, simulation core, default demo data, and public mount API.
+
+The host website owns only:
+
+- The root DOM element where the simulator mounts.
+- The driver/project list.
+- Optional driver/car pairing entries.
+- Optional display/config overrides.
+- `onDriverOpen(driver)` navigation behavior.
+
+## Public API
+
+Main import:
+
+```js
+import {
+  createPaddockSimulator,
+  mountF1Simulator,
+} from '@inventure71/paddockjs';
+```
+
+All-in-one mount call:
+
+```js
+const simulator = await mountF1Simulator(root, {
+  drivers,
+  entries,
+  onDriverOpen,
+  seed,
+  trackSeed,
+  totalLaps,
+  initialCameraMode,
+  preset,
+  title,
+  kicker,
+  backLinkHref,
+  backLinkLabel,
+  showBackLink,
+  ui,
+  theme,
+  assets,
+  onLoadingChange,
+  onReady,
+  onError,
+  onDriverSelect,
+  onRaceEvent,
+  onLapChange,
+  onRaceFinish,
+});
+```
+
+Composable mount call:
+
+```js
+const simulator = createPaddockSimulator({
+  drivers,
+  entries,
+  onDriverOpen,
+  seed,
+  trackSeed,
+  totalLaps,
+  initialCameraMode,
+});
+
+simulator.mountRaceControls(controlsRoot);
+simulator.mountCameraControls(cameraControlsRoot);
+simulator.mountSafetyCarControl(safetyCarRoot);
+simulator.mountTimingTower(timingRoot);
+simulator.mountRaceCanvas(canvasRoot, {
+  includeRaceDataPanel: true,
+  includeTimingTower: true,
+  timingTowerVerticalFit: 'scroll',
+});
+simulator.mountTelemetryPanel(telemetryRoot);
+
+await simulator.start();
+```
+
+Standalone helper functions are also exported for host code that prefers function calls:
+
+```js
+mountRaceControls(root, simulator);
+mountTimingTower(root, simulator);
+mountRaceCanvas(root, simulator, {
+  includeRaceDataPanel: true,
+  includeTimingTower: true,
+  timingTowerVerticalFit: 'scroll',
+});
+mountTelemetryPanel(root, simulator);
+mountRaceDataPanel(root, simulator);
+```
+
+Returned controller:
+
+```js
+{
+  // Included on composable controllers only:
+  mountRaceControls(root),
+  mountCameraControls(root),
+  mountSafetyCarControl(root),
+  mountTimingTower(root),
+  mountRaceCanvas(root, { includeRaceDataPanel, includeTimingTower, timingTowerVerticalFit }),
+  mountTelemetryPanel(root),
+  mountRaceDataPanel(root),
+  start(),
+
+  // Included on both APIs:
+  destroy(),
+  restart(nextOptions),
+  selectDriver(driverId),
+  setSafetyCarDeployed(deployed),
+  callSafetyCar(),
+  clearSafetyCar(),
+  toggleSafetyCar(),
+  getSnapshot(),
+}
+```
+
+## Required Behavior
+
+- Mounting creates the simulator shell inside the provided root.
+- Composable mounting can place controls, timing tower, canvas, telemetry, car/driver overview, and race-data panels into separate host roots.
+- Composable mounting can also place camera controls and a safety-car button into separate host roots while keeping package-owned markup.
+- Composable mounting can embed the timing tower directly inside the race canvas with `mountRaceCanvas(root, { includeTimingTower: true })`.
+- The race canvas is required before `start()` because PixiJS needs a canvas host.
+- Timing tower, telemetry, controls, and race-data panels are optional from a runtime safety perspective; omitted panels simply do not render their readouts.
+- Timing tower entries are fixed rows stacked from the top of the timing list. Row vertical position must be based on rank/index, never distributed by available height or total entry count.
+- Timing tower entries display team icons. The tower can switch at runtime between interval-to-car-ahead timing and cumulative gap-to-leader timing.
+- Snapshots expose calibrated display units through `speedKph`, `distanceMeters`, and `gapMeters`; internal physics remains in simulator units.
+- Entries can include optional `team` metadata. Team color defaults to car color when omitted.
+- Mounted package surfaces show a package-owned red start-light loading overlay until `start()` finishes PixiJS, asset, control, and initial readout initialization.
+- `preset` is a preset-first API. Presets are resolved before explicit host overrides so hosts can use `dashboard`, `timing-overlay`, `compact-race`, or `full-dashboard` as a starting point and still override specific `ui` or `theme` fields.
+- `theme` is the public sizing/color contract. It maps to package CSS variables for `accentColor`, `greenColor`, `yellowColor`, `timingTowerMaxWidth`, and `raceViewMinHeight`.
+- Camera controls can be embedded in the race canvas, externally mounted, or omitted by `ui.cameraControls`.
+- Telemetry can include the car/driver overview directly or stay text-only through `ui.telemetryIncludesOverview` / `mountTelemetryPanel(root, { includeOverview: false })`.
+- The FPS readout can be shown or hidden with `ui.showFps`.
+- `ui.layoutPreset: 'left-tower-overlay'` is a package-owned preset that creates a left broadcast gutter inside the race view, places the timing tower there at the same width as the default timing-board column, frames the PixiJS camera around the remaining usable race area, and keeps camera controls and start lights out of the tower area. In the combined shell, project and radio lower-thirds stay inside the race window while being allowed to cover the timing sidebar.
+- `ui.raceDataBanners.initial` controls the starting lower-third (`'project'`, `'radio'`, or `'hidden'`), and `ui.raceDataBanners.enabled` controls which lower-third types can appear.
+- `ui.raceDataBannerSize` controls lower-third sizing: `'custom'` keeps the default CSS-variable-driven banner size for host tuning, while `'auto'` uses the race space to the right of the timing board when wide enough and overlaps the timing board only when space is constrained.
+- `ui.timingTowerVerticalFit` controls vertical tower behavior in the combined overlay preset: `'expand-race-view'` grows the race window to fit the tower, while `'scroll'` crops the tower area and scrolls timing rows inside it. The same values are accepted as `mountRaceCanvas()` options when `includeTimingTower` embeds the tower in the race canvas.
+- Hosts may scale the whole mounted simulator through the container. The horizontal proportions inside package-owned presets are not public API and should not be configurable through raw width or ratio options. The camera reads the current canvas dimensions so wider or taller host windows reveal more of the race view without needing host-owned camera math. The timing tower has a package-owned max width because overly wide timing boards degrade readability; standalone hosts can constrain vertical height through the mount container and let the timing entries scroll internally.
+- The host does not need to provide simulator assets.
+- The host passes data, not internal DOM.
+- `onDriverOpen(driver)` is the navigation boundary.
+- Lifecycle callbacks are optional: `onLoadingChange`, `onReady`, `onError`, `onDriverSelect`, `onRaceEvent`, `onLapChange`, and `onRaceFinish`. Host callback failures are routed to `onError` when possible and must not stop the simulator loop.
+- Race completion is part of the simulation snapshot. Cars receive individual `finished`, `finishTime`, and `classifiedRank` values as they cross the finish distance. The first finisher sets `raceControl.winner`; final `raceControl.classification` and `raceControl.finished` are set only after every car finishes. At that point race control switches to `safety-car`, the final order freezes, and the field keeps circulating under safety-car behavior.
+- The simulator must stay interactive after being installed through `npm install ../PaddockJS`.
+- The package must build correctly through a browser bundler that supports JavaScript modules, CSS imports, and image imports.
+- The simulation should remain deterministic for the same seed, track seed, drivers, entries, and rules.
+- When `trackSeed` is omitted in a browser mount, the simulator creates a fresh procedural circuit for that mount. Explicit `trackSeed` values are deterministic and cached by seed for repeated mounts.
+- The renderer should target a paced 60 FPS simulation/render loop.
+- The render loop should pause while the race canvas is offscreen or the document is hidden, then resume without catching up the elapsed hidden time. Layout measurements needed for overlay camera safe areas should be cached between resize/layout invalidations.
+
+## Current Visible Features
+
+- Timing tower with position, team icon, timing code, interval/gap switch, and tire compound.
+- Race canvas rendered with PixiJS.
+- Procedural track rendering with asphalt texture and DRS overlays.
+- Driver selection from cars and timing tower rows.
+- Camera modes: overview, leader, selected, show all.
+  Overview is a closer static circuit view centered on the world; show all is the mode that dynamically fits the active pack.
+- Zoom controls.
+- FPS readout.
+- Start lights.
+- Safety car toggle.
+- External safety-car control through controller methods and optional mounted button.
+- Restart button.
+- Selected-car text telemetry.
+- Car/driver overview panel with a center visual, linked stat cells, and a Car/Driver toggle.
+- Project/race data lower-third.
+- Intermittent project radio quotes.
+- Race-finish winner banner and final top-three classification.
+- `Open project` button driven by `onDriverOpen(driver)`.
+
+## Runtime Requirements
+
+- Browser environment with DOM APIs.
+- A host build tool that handles CSS and image imports. Vite is the currently verified bundler.
+- `pixi.js` available through the package dependency graph.
+
+Raw Node imports are not a supported runtime check because the package imports CSS and image assets. Verify through a browser bundler and host page instead.
+
+## Verification
+
+Run from this package:
+
+```bash
+npm run check
+```
+
+Expected:
+
+- All Vitest tests pass.
+- `npm pack --dry-run` succeeds and includes source files plus bundled assets.
+
+Run from the portfolio host:
+
+```bash
+npm install ../PaddockJS
+npm run check
+```
+
+Expected:
+
+- PaddockJS tests pass through the host script.
+- The host F1 bundle builds.
+- Browser smoke shows shell, canvas, driver rows, FPS readout, and working `Open project` navigation.

package/package.json

@@ -0,0 +1,85 @@
+{
+  "name": "@inventure71/paddockjs",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "A data-driven browser F1 simulator component for project portfolios.",
+  "license": "Apache-2.0",
+  "author": "Matteo Giorgetti",
+  "homepage": "https://github.com/Inventure71/PaddockJS#readme",
+  "bugs": {
+    "url": "https://github.com/Inventure71/PaddockJS/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Inventure71/PaddockJS.git"
+  },
+  "keywords": [
+    "f1",
+    "formula-1",
+    "motorsport",
+    "racing",
+    "simulator",
+    "timing-tower",
+    "pixijs",
+    "ui-component"
+  ],
+  "sideEffects": [
+    "./src/styles.css"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "main": "src/index.js",
+  "types": "src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "import": "./src/index.js",
+      "default": "./src/index.js"
+    },
+    "./styles.css": "./src/styles.css"
+  },
+  "files": [
+    "AGENTS.md",
+    "CHANGELOG.md",
+    "LICENSE",
+    "assets",
+    "docs",
+    "src/api",
+    "src/app",
+    "src/config",
+    "src/data",
+    "src/rendering",
+    "src/simulation",
+    "src/ui",
+    "src/index.d.ts",
+    "src/index.js",
+    "src/standalone.js",
+    "src/styles.css",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "vitest run src",
+    "types:check": "tsc -p tsconfig.types.json --noEmit",
+    "check": "npm test && npm run types:check && npm run pack:dry && npm run showcase:ci",
+    "pack:dry": "npm pack --dry-run",
+    "showcase:install": "npm --prefix local-preview ci",
+    "showcase:dev": "npm --prefix local-preview run dev",
+    "showcase:build": "npm --prefix local-preview run build",
+    "showcase:ci": "npm --prefix local-preview ci && npm --prefix local-preview run build",
+    "changeset": "changeset",
+    "version-packages": "changeset version",
+    "release": "npm publish --provenance"
+  },
+  "dependencies": {
+    "pixi.js": "8.18.1"
+  },
+  "devDependencies": {
+    "@changesets/cli": "2.29.7",
+    "typescript": "5.9.3",
+    "vitest": "4.1.5"
+  }
+}