@inventure71/paddockjs 0.1.0

package/AGENTS.md

@@ -0,0 +1,86 @@
+# AGENTS.md
+
+## Project
+
+PaddockJS is an installable browser component package for an F1-style project race simulator.
+
+The package lives independently from the portfolio website. Host websites install it and mount it with:
+
+```js
+import { mountF1Simulator } from '@inventure71/paddockjs';
+```
+
+It can also be mounted as rearrangeable package-owned pieces with:
+
+```js
+import { createPaddockSimulator } from '@inventure71/paddockjs';
+```
+
+## What Is In This Repo
+
+- `src/index.js`: public package API.
+- `src/api/`: public composable mounting controller.
+- `src/app/`: browser runtime, DOM bindings, PixiJS app lifecycle, controls, readouts, and camera orchestration.
+- `src/config/`: default options and bundled default asset mapping.
+- `src/data/`: driver/project data normalization, driver/car pairing, rating conversion, and demo data.
+- `src/rendering/`: PixiJS track rendering helpers and render interpolation.
+- `src/simulation/`: race rules, driver AI, vehicle physics, track model, and math utilities.
+- `src/ui/`: generated markup for the all-in-one shell and individually mounted UI surfaces.
+- `src/__tests__/`: package tests.
+- `assets/`: simulator-owned default assets.
+- `docs/`: package specs and design documentation.
+- `INSTALL_AND_UPDATE.md`: install/update workflow.
+
+## Required Documentation Discipline
+
+When changing simulator behavior, update docs in the same change.
+
+Use this mapping:
+
+- Public API, lifecycle, install assumptions: update `docs/system_specs.md` and `README.md` if needed.
+- Race behavior, DRS, safety car, starts, physics, collisions: update `docs/rules.md`.
+- Vocabulary or domain model: update `docs/concepts.md`.
+- Driver/entry/options/assets callback shapes: update `docs/data_contract.md`.
+- Module ownership or data/control flow: update `docs/architecture.md`.
+- Local install/update workflow: update `INSTALL_AND_UPDATE.md`.
+
+Do not leave docs describing old behavior after code changes.
+
+## Linear Work Logging
+
+For any implementation that is more than a trivial/no-op change, log the work in the PaddockJS project on Linear.
+
+The Linear update must include:
+
+- what task was done
+- how it was solved
+- any important verification or remaining follow-up
+
+## Engineering Rules
+
+- Preserve the package boundary: PaddockJS should stay reusable and host-agnostic.
+- Host-specific routing belongs in `onDriverOpen(driver)`, not package internals.
+- Host-specific project data should be passed as `drivers` and `entries`, not hardcoded into the runtime.
+- The package should own default simulator assets so hosts do not need to copy them.
+- Treat the timing board width and broadcast proportions as package-owned. Do not resize or retune timing-board width as a casual fix; preserve its intended width and solve layout bugs through internal column/content constraints unless the user explicitly asks to redesign the timing board sizing.
+- Prefer small, focused modules when extracting from `F1SimulatorApp.js`.
+- Keep simulation logic deterministic for the same seed, track seed, drivers, entries, and rules.
+- Do not claim completion without running verification.
+
+## Verification
+
+Run before claiming package changes are complete:
+
+```bash
+npm run check
+```
+
+For portfolio integration changes, also run from the portfolio repo:
+
+```bash
+cd /Users/inventure71/VSProjects/Inventure71.github.io
+npm install ../PaddockJS
+npm run check
+```
+
+Browser behavior changes need a browser smoke test against the host page.

package/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The npm release workflow updates this changelog from committed Changesets.

package/LICENSE

@@ -0,0 +1,176 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS

package/README.md

@@ -0,0 +1,165 @@
+# PaddockJS
+
+This folder is the extractable F1 simulator component. It owns the simulator source, bundled simulator assets, CSS, demo data, and the public mount API.
+
+## Install
+
+From npm:
+
+```bash
+npm install @inventure71/paddockjs
+```
+
+For local sibling-repo development:
+
+```bash
+npm install ../PaddockJS
+```
+
+## Documentation
+
+Start with [docs/index.md](docs/index.md) for system specs, rules, concepts, data contracts, and architecture notes.
+
+## Package Workflow
+
+The repo now includes the full package-release boundary:
+
+- a tracked showcase host in `local-preview/`
+- public TypeScript declarations in `src/index.d.ts`
+- GitHub Actions CI in `.github/workflows/ci.yml`
+- Changesets release automation in `.github/workflows/release.yml`
+
+Useful commands:
+
+```bash
+npm run check
+npm run showcase:dev
+npm run showcase:build
+npm run changeset
+```
+
+`npm run check` verifies the runtime tests, public declaration file, dry package contents, and showcase build.
+
+## API
+
+All-in-one mount:
+
+```js
+import { mountF1Simulator } from '@inventure71/paddockjs';
+
+const simulator = await mountF1Simulator(document.getElementById('sim-root'), {
+  preset: 'timing-overlay',
+  drivers: [
+    {
+      id: 'budget',
+      name: 'Budget Buddy',
+      color: '#ff2d55',
+      link: '/project_details/project-budget-buddy.html',
+      raceData: ['AI finance coach', 'Python + LLM', 'Budget guardrails'],
+    },
+  ],
+  entries: [
+    {
+      driverId: 'budget',
+      driverNumber: 71,
+      timingName: 'Budget',
+      driver: { pace: 52, racecraft: 74, aggression: 38, riskTolerance: 47, patience: 81, consistency: 86 },
+      vehicle: { id: 'budget-bb01', name: 'BB-01 Ledger', power: 48, braking: 72, aero: 55, dragEfficiency: 66, mechanicalGrip: 63, weightControl: 58, tireCare: 82 },
+    },
+  ],
+  onDriverOpen(driver) {
+    window.location.href = driver.link;
+  },
+  onRaceFinish({ winner, classification }) {
+    console.log('Race winner:', winner.name, classification);
+  },
+});
+```
+
+Composable mount:
+
+```js
+import { createPaddockSimulator } from '@inventure71/paddockjs';
+
+const simulator = createPaddockSimulator({
+  drivers,
+  entries,
+  onDriverOpen(driver) {
+    window.location.href = driver.link;
+  },
+});
+
+simulator.mountRaceControls(document.getElementById('sim-controls'));
+simulator.mountCameraControls(document.getElementById('sim-camera-controls'));
+simulator.mountSafetyCarControl(document.getElementById('sim-safety-car'));
+simulator.mountTimingTower(document.getElementById('sim-timing'));
+simulator.mountRaceCanvas(document.getElementById('sim-race'), {
+  includeRaceDataPanel: true,
+});
+simulator.mountTelemetryPanel(document.getElementById('sim-telemetry'));
+simulator.mountCarDriverOverview(document.getElementById('sim-overview'));
+
+await simulator.start();
+```
+
+The race canvas can also own the timing tower when a host wants a single reusable race-window component:
+
+```js
+simulator.mountRaceCanvas(document.getElementById('sim-race'), {
+  includeTimingTower: true,
+  includeRaceDataPanel: true,
+  timingTowerVerticalFit: 'scroll',
+});
+```
+
+`drivers` is the host-owned project/pilot list. `entries` is the optional driver/car/team pairing sheet. The car/driver overview uses the existing driver and vehicle rating components from each entry. Driver and vehicle entries can also include `customFields` as extra label/value metadata. Entries can include `team: { id, name, color, icon }`; the timing tower uses the team icon and defaults team color to the car color when omitted. Assets, including the default car image and generic driver helmet, are bundled by default, so the host website does not need to provide simulator images or textures.
+
+The returned object supports:
+
+- `destroy()`
+- `restart(nextOptions)`
+- `selectDriver(driverId)`
+- `setSafetyCarDeployed(deployed)`
+- `callSafetyCar()`
+- `clearSafetyCar()`
+- `toggleSafetyCar()`
+- `getSnapshot()`
+
+Useful UI options:
+
+```js
+preset: 'timing-overlay',
+theme: {
+  accentColor: '#00ff84',
+  timingTowerMaxWidth: '360px',
+  raceViewMinHeight: '720px',
+},
+ui: {
+  layoutPreset: 'left-tower-overlay',
+  cameraControls: 'external',
+  showFps: false,
+  telemetryIncludesOverview: false,
+  raceDataBanners: {
+    initial: 'project',
+    enabled: ['project', 'radio'],
+  },
+  raceDataBannerSize: 'auto',
+  timingTowerVerticalFit: 'expand-race-view',
+}
+```
+
+`preset` is resolved before explicit host options. Available presets are `dashboard`, `timing-overlay`, `compact-race`, and `full-dashboard`; hosts can start from a preset and override any `ui` or `theme` field. `theme` maps to package CSS variables for the stable sizing/color contract: `accentColor`, `greenColor`, `yellowColor`, `timingTowerMaxWidth`, and `raceViewMinHeight`.
+
+If `trackSeed` is omitted, each mounted browser simulator creates a fresh procedural circuit. Passing `trackSeed` makes the track deterministic so multiple embeds can share the same generated circuit; repeated procedural seeds are cached within the page runtime.
+
+`layoutPreset: 'left-tower-overlay'` creates a left broadcast gutter inside the race view, frames the camera around the remaining race area, and places the timing tower in that gutter without covering camera controls. The project/radio lower-third stays inside the race window and can intentionally render over the timing sidebar instead of shrinking around it. Composable hosts should pass `{ includeRaceDataPanel: true }` to `mountRaceCanvas()` when they want that lower-third clipped and layered by the race window; `mountRaceDataPanel()` remains available for hosts that intentionally want the banner as a standalone surface. `includeTimingTower: true` embeds the timing tower directly inside the race canvas and reserves camera space from the measured tower gutter. `raceDataBanners.initial` selects the starting banner state (`'project'`, `'radio'`, or `'hidden'`), while `raceDataBanners.enabled` chooses which banner types may appear. `raceDataBannerSize: 'auto'` uses the race space to the right of the timing board when it is wide enough and falls back to the full lower-third overlap when it is not; `'custom'` preserves the default CSS-variable-driven lower-third size for hosts that want to tune their own banner geometry. `timingTowerVerticalFit: 'expand-race-view'` lets the race window grow tall enough for the tower; `'scroll'` keeps the race window height and scrolls the timing list inside the cropped tower. The same fit values can be passed to `mountRaceCanvas()` when `includeTimingTower` is enabled. Standalone timing towers are capped by `--timing-board-max-width` and fill their mount root height; placing the root in a fixed-height container makes only the timing entries scroll. Timing entries always stack from the top as fixed rows, so P1/P2 occupy the same vertical positions whether the race has 2 cars or 20. The timing tower includes an `Int`/`Gap` broadcast switch: `Int` shows the interval to the car ahead, while `Gap` shows total gap to the leader. `cameraControls: 'external'` moves view controls out of the canvas so hosts can mount them with `mountCameraControls()`. `showFps: false` hides the FPS readout. `telemetryIncludesOverview: false` keeps telemetry text-only so hosts can mount `mountCarDriverOverview()` separately.
+
+Mounted package surfaces include a lightweight red start-light loading overlay. The runtime removes each overlay after PixiJS, assets, controls, and the initial readouts are ready.
+
+The runtime also pauses its render ticker when the race canvas is offscreen or the browser tab is hidden. This keeps pages with multiple PaddockJS embeds responsive without requiring host code to manually start and stop each simulator.
+
+Lifecycle callbacks are optional and host-owned. PaddockJS emits `onLoadingChange`, `onReady`, `onError`, `onDriverSelect`, `onRaceEvent`, `onLapChange`, and `onRaceFinish`; callback errors are routed to `onError` when provided and do not stop the simulator loop. Race snapshots include per-car interval timing, leader-gap timing, calibrated `speedKph`, finish state, `raceControl.winner` after the first finisher, and final `raceControl.classification` only after the whole field finishes. The field then circulates in safety-car mode and the race canvas shows a package-owned winner banner.
+
+## License
+
+PaddockJS is released under `Apache-2.0`. See [LICENSE](LICENSE).

package/docs/architecture.md

@@ -0,0 +1,209 @@
+# Architecture
+
+## Package Boundary
+
+PaddockJS is the simulator package. A host website imports it and passes data.
+
+The package owns:
+
+- Simulator source.
+- Bundled assets.
+- CSS.
+- DOM shell generation.
+- PixiJS renderer.
+- Simulation rules and physics.
+- Demo data.
+- Tests.
+
+The host owns:
+
+- Project-specific driver data.
+- Navigation behavior.
+- Page placement.
+- Host build and deployment.
+
+## Main Flow
+
+All-in-one flow:
+
+```txt
+host page
+  -> mountF1Simulator(root, options)
+  -> resolveF1SimulatorOptions(options)
+  -> normalizeSimulatorDrivers(drivers, entries)
+  -> createF1SimulatorShell(options)
+  -> new F1SimulatorApp(shell, resolvedOptions)
+  -> createRaceSimulation(...)
+  -> PixiJS render loop + DOM readout updates
+```
+
+Composable flow:
+
+```txt
+host page
+  -> createPaddockSimulator(options)
+  -> resolveF1SimulatorOptions(options)
+  -> simulator.mountRaceControls(controlsRoot)
+  -> simulator.mountCameraControls(cameraControlsRoot)
+  -> simulator.mountSafetyCarControl(safetyCarRoot)
+  -> simulator.mountTimingTower(timingRoot)
+  -> simulator.mountRaceCanvas(canvasRoot, { includeRaceDataPanel })
+  -> simulator.mountTelemetryPanel(telemetryRoot)
+  -> simulator.mountRaceDataPanel(raceDataRoot) [optional standalone alternative]
+  -> simulator.start()
+  -> new F1SimulatorApp(compositeRoot, resolvedOptions)
+  -> PixiJS render loop + DOM readout updates
+```
+
+## Public Entry
+
+`src/index.js` is the public package entry.
+
+Responsibilities:
+
+- Import CSS.
+- Export package API and data helpers.
+- Validate the root element.
+- Resolve options.
+- Create the DOM shell.
+- Construct and initialize `F1SimulatorApp`.
+- Return the controller methods.
+- Re-export the composable mount API.
+
+`src/api/PaddockSimulatorController.js` owns composable mounting.
+
+Responsibilities:
+
+- Resolve host options once for component templates and runtime.
+- Render each independently mounted component into its host root.
+- Build a composite DOM query surface for `F1SimulatorApp`.
+- Initialize and control the shared simulator runtime through `start()`, `restart()`, `destroy()`, and state methods.
+- Expose explicit safety-car methods for callers that want to deploy or release the safety car without using package-rendered buttons.
+
+## Runtime App
+
+`src/app/F1SimulatorApp.js` owns browser runtime behavior.
+
+Responsibilities:
+
+- PixiJS application setup.
+- Asset loading.
+- Sprite creation.
+- Control event binding.
+- Fixed-step simulation pacing.
+- Viewport/document visibility throttling for the PixiJS ticker.
+- Camera modes.
+- Overlay-safe camera framing for the left timing-tower preset.
+- Timing tower rendering.
+- Telemetry rendering.
+- Race data panel rendering.
+- Safety car button.
+- Multiple package-rendered safety-car buttons bound to one simulation state.
+- Restart behavior.
+- Lifecycle cleanup.
+
+This file is still large. When changing it substantially, prefer extracting cohesive modules rather than adding unrelated responsibilities.
+
+`src/app/domBindings.js` owns DOM selector lookup and null-safe readout text writes for package-generated UI surfaces.
+
+## Simulation Core
+
+`src/simulation/raceSimulation.js` owns race state and rules.
+
+Responsibilities:
+
+- Race-control mode.
+- Start sequence.
+- Safety car.
+- Car creation.
+- Race ordering.
+- Lap calculation.
+- Timing history.
+- DRS eligibility.
+- Collision response.
+- Snapshot creation.
+
+`src/simulation/driverController.js` owns AI control decisions.
+
+`src/simulation/vehiclePhysics.js` owns vehicle integration and surface physics.
+
+`src/simulation/trackModel.js` owns track construction, procedural track generation, DRS zones, and nearest-track queries. Browser mounts generate a fresh procedural seed when `trackSeed` is omitted; explicit procedural track seeds are cached so repeated mounts with the same seed do not regenerate or rebuild the same model.
+
+`src/simulation/units.js` owns conversion between simulator units and public meter/km/h display values. Physics stays in simulator units; snapshots expose calibrated display fields such as `speedKph`, `distanceMeters`, and `gapMeters`.
+
+`src/rendering/renderSnapshot.js` owns interpolation for rendering.
+
+The app runtime pauses its PixiJS ticker when the race canvas is outside the viewport or the document is hidden, then resets the frame clock before resuming. This prevents host pages with several simulator embeds from running every race while only one is visible, and avoids a large simulation catch-up step when the canvas re-enters view. Camera safe-area layout measurements are cached and invalidated by resize observation so the 60 FPS render path does not force repeated DOM geometry reads. Long project-radio delays are also treated as stale schedule state instead of replaying every missed lower-third transition.
+
+## Data Layer
+
+`src/data/driverData.js` converts driver rating sheets into constructor arguments.
+
+`src/data/vehicleData.js` converts vehicle rating sheets into physical setup values.
+
+`src/data/championship.js` pairs drivers with entries and generates timing codes, numbers, team metadata, and converted constructor data.
+
+`src/data/normalizeDrivers.js` validates host driver data and invokes championship pairing.
+
+`src/data/demoDrivers.js` is demo/portfolio-flavored sample data. It should not become the only supported data path.
+
+## UI Shell
+
+`src/ui/componentTemplates.js` owns the generated markup for individual UI surfaces:
+
+- Race controls.
+- Camera controls.
+- Safety-car control.
+- Timing tower.
+- Race canvas.
+- Race-data panel.
+- Telemetry panel.
+- Car/driver overview panel.
+
+`src/ui/shellTemplate.js` composes those component templates into the default all-in-one simulator DOM and package-owned layout presets such as `left-tower-overlay`. The telemetry panel can embed the car/driver overview, but the overview is also a separately mountable package-owned component. The left-tower overlay preset is responsible for internal component placement and package-owned proportions; the project/radio lower-third remains owned by the race canvas so it can either use the race space beside the timing tower in `auto` sizing mode or overlap the tower when space is constrained. Composable hosts can also ask the race-canvas template to embed the timing tower directly with `includeTimingTower`, using the same expand-vs-scroll vertical fit contract. `F1SimulatorApp` measures the resulting timing-tower gutter when framing the PixiJS camera, whether the tower comes from the prebuilt shell or from an embedded composable race canvas. Hosts should not provide the internal simulator markup or tune preset internals with raw sizing options.
+
+`src/config/defaultOptions.js` owns preset resolution and the public theme contract. Presets are merged before host options; theme fields are applied as package CSS variables by the all-in-one app and composable controller. This keeps sizing/color customization explicit without turning internal layout ratios into public API.
+
+Race completion is owned by `src/simulation/raceSimulation.js`. The app layer reads `raceControl.finished`, `winner`, and `classification` from snapshots, renders the winner banner, and emits lifecycle callbacks. UI code must not infer finish state from lap text or timing rows.
+
+Composable hosts may choose where each package-owned component root is placed, but they still receive package-generated markup through the public mount functions. The controller marks each mounted root as an `f1-sim-component` styling scope so standalone pieces receive the same package variables as the all-in-one shell.
+
+`src/styles.css` styles the generated shell, imports package fonts, caps timing-tower width for readability, and owns the fixed-height timing-list scroll behavior. Timing rows are fixed grid rows stacked from the top, so rank positions do not stretch or redistribute when the number of entries changes. The timing tower owns its runtime interval-vs-leader-gap switch, while `F1SimulatorApp` reads both timing values from the race snapshot. Component templates include lightweight package-owned loading overlays; `F1SimulatorApp` removes them after startup initialization has completed.
+
+The host page should only provide:
+
+```html
+<div id="f1-simulator-root"></div>
+```
+
+## Assets
+
+`src/config/defaultAssets.js` imports bundled assets from `assets/` and exposes default asset resolution.
+
+Assets are bundled by the host build tool when the package is imported.
+
+## Tests
+
+Tests live in `src/__tests__/`.
+
+Current coverage includes:
+
+- Championship metadata.
+- Component API and callback behavior.
+- Driver controller behavior.
+- Procedural track rendering helpers.
+- Race simulation rules.
+- Render interpolation.
+- Track model behavior.
+
+Run:
+
+```bash
+npm test
+```
+
+## Design Rule
+
+Keep reusable simulator behavior in PaddockJS. Keep website-specific data and routing in the host.
+
+If a change adds portfolio-only behavior to package internals, move it to the host integration layer instead.