@inventure71/paddockjs 0.2.0 → 1.0.0

package/src/ui/bannerTemplates.js

@@ -0,0 +1,69 @@
+import { createLoadingMarkup } from './templateUtils.js';
+
+export function createStewardMessageMarkup() {
+  return `
+      <div class="steward-message is-hidden" data-paddock-component="steward-message" data-steward-message aria-live="polite">
+        <span class="steward-message__kicker" data-steward-message-kicker>Race control</span>
+        <strong data-steward-message-title>--</strong>
+        <span data-steward-message-detail>--</span>
+      </div>
+  `;
+}
+
+export function createRaceDataPanelMarkup({ ui = {} } = {}) {
+  const sizeMode = ui.raceDataBannerSize === 'auto' ? 'auto' : 'custom';
+  const telemetryDetail = Boolean(ui.raceDataTelemetryDetail);
+  const classNames = ['race-data-panel', `race-data-panel--${sizeMode}`];
+  if (telemetryDetail) classNames.push('race-data-panel--with-telemetry');
+  return `
+    <div class="${classNames.join(' ')}" data-paddock-component="race-data-panel" data-race-data-panel aria-live="polite">
+      <button class="race-data-dismiss" type="button" data-race-data-dismiss aria-label="Close race data pill">x</button>
+      <div class="race-data-copy">
+        <span class="race-data-kicker" data-race-data-kicker>Project</span>
+        <strong data-race-data-title>Select driver</strong>
+        <span class="race-data-subtitle" data-race-data-subtitle>Race entry</span>
+      </div>
+      ${telemetryDetail ? createRaceDataTelemetryMarkup() : ''}
+      <strong class="race-data-number" data-race-data-number>--</strong>
+      <button class="race-data-link" type="button" data-race-data-open>Open project</button>
+      ${createLoadingMarkup('Race data')}
+    </div>
+  `;
+}
+
+function createRaceDataTelemetryMarkup() {
+  return `
+      <div class="race-data-telemetry" data-race-data-telemetry aria-label="Project sector telemetry">
+        <span class="race-data-telemetry__label">Sectors</span>
+        <div class="race-data-telemetry__bars">
+          ${[1, 2, 3].map((sector) => `
+          <div class="telemetry-sector-bar race-data-sector-bar" data-telemetry-sector-bar="${sector}" style="--sector-fill: 0%">
+            <span>S${sector}</span>
+            <strong data-telemetry-sector-time="${sector}">--</strong>
+          </div>
+          `).join('')}
+        </div>
+      </div>
+  `;
+}
+
+export function createTelemetrySectorBannerMarkup() {
+  return `
+      <section class="telemetry-sector-banner" data-paddock-component="telemetry-sector-banner" data-telemetry-sector-banner aria-label="Broadcast sector telemetry">
+        <div class="telemetry-sector-banner__copy">
+          <span><b data-selected-code>--</b> sector telemetry</span>
+          <strong data-selected-name>Select driver</strong>
+          <em data-telemetry-current-sector>S1</em>
+        </div>
+        <div class="telemetry-sector-banner__bars">
+          ${[1, 2, 3].map((sector) => `
+          <div class="telemetry-sector-bar" data-telemetry-sector-bar="${sector}" style="--sector-fill: 0%">
+            <span>S${sector}</span>
+            <strong data-telemetry-sector-time="${sector}">--</strong>
+          </div>
+          `).join('')}
+        </div>
+        ${createLoadingMarkup('Sector banner')}
+      </section>
+  `;
+}

package/src/ui/componentTemplates.js

@@ -1,3 +1,18 @@
+import {
+  createRaceDataPanelMarkup,
+  createStewardMessageMarkup,
+  createTelemetrySectorBannerMarkup,
+} from './bannerTemplates.js';
+import { createRaceControlStatusBannerMarkup } from './raceControlStatusBanner.js';
+import { createLoadingMarkup, escapeHtml } from './templateUtils.js';
+
+export {
+  createRaceDataPanelMarkup,
+  createStewardMessageMarkup,
+  createTelemetrySectorBannerMarkup,
+} from './bannerTemplates.js';
+export { escapeHtml } from './templateUtils.js';
+
 function buttonHiddenAttribute(isVisible) {
   return isVisible ? '' : ' hidden';
 }
@@ -9,30 +24,6 @@ function createTelemetryDrawerId() {
   return `paddock-telemetry-drawer-${telemetryDrawerIdSequence}`;
 }
 
-function createLoadingMarkup(label = 'Loading') {
-  return `
-      <div class="paddock-loading" data-paddock-loading aria-label="${escapeHtml(label)} loading">
-        <div class="paddock-loading__lights" aria-hidden="true">
-          <span></span>
-          <span></span>
-          <span></span>
-          <span></span>
-          <span></span>
-        </div>
-        <span class="paddock-loading__label">${escapeHtml(label)}</span>
-      </div>
-  `;
-}
-
-export function escapeHtml(value) {
-  return String(value ?? '')
-    .replaceAll('&', '&amp;')
-    .replaceAll('<', '&lt;')
-    .replaceAll('>', '&gt;')
-    .replaceAll('"', '&quot;')
-    .replaceAll("'", '&#39;');
-}
-
 export function createRaceControlsMarkup({
   title,
   kicker,
@@ -81,10 +72,7 @@ export function createTimingTowerMarkup({ totalLaps, assets }) {
           <button type="button" data-timing-gap-mode="interval" aria-pressed="true">Int</button>
           <button type="button" data-timing-gap-mode="leader" aria-pressed="false">Gap</button>
         </div>
-        <div class="broadcast-safety-banner" data-tower-safety-banner>
-          <span>FIA</span>
-          <strong>Safety Car</strong>
-        </div>
+        ${createRaceControlStatusBannerMarkup()}
         <div class="broadcast-column-head" aria-hidden="true">
           <span>Pos</span>
           <span>Team</span>
@@ -99,16 +87,20 @@ export function createTimingTowerMarkup({ totalLaps, assets }) {
   `;
 }
 
-export function createCameraControlsMarkup({ embedded = false } = {}) {
+export function createCameraControlsMarkup({ embedded = false, showSimulationSpeed = false, ui = {} } = {}) {
   const className = embedded ? 'camera-controls' : 'camera-controls camera-controls--external';
+  const showSpeedControl = showSimulationSpeed || ui.simulationSpeedControl === true;
   return `
       <div class="${className}" data-paddock-component="camera-controls" aria-label="Camera controls">
         <button type="button" data-camera-mode="overview" aria-pressed="false">Overview</button>
         <button type="button" data-camera-mode="leader" aria-pressed="true">Leader</button>
         <button type="button" data-camera-mode="selected" aria-pressed="false">Selected</button>
         <button type="button" data-camera-mode="show-all" aria-pressed="false">Show all</button>
+        <button type="button" data-camera-mode="pit" aria-pressed="false">Pits</button>
         <button type="button" data-zoom-out aria-label="Zoom out">-</button>
         <button type="button" data-zoom-in aria-label="Zoom in">+</button>
+        ${showSpeedControl ? '<button type="button" data-simulation-speed aria-label="Simulation speed">1x</button>' : ''}
+        <button type="button" data-race-data-banners-muted aria-pressed="false">Mute banners</button>
         ${createLoadingMarkup('Camera controls')}
       </div>
   `;
@@ -124,7 +116,7 @@ export function createRaceCanvasMarkup({
   ui = {},
 } = {}) {
   const showFps = ui.showFps !== false;
-  const showEmbeddedCameraControls = ui.cameraControls !== 'external' && ui.cameraControls !== false;
+  const showEmbeddedCameraControls = ui.cameraControls === 'embedded';
   const timingFit = (timingTowerVerticalFit ?? ui.timingTowerVerticalFit) === 'scroll'
     ? 'scroll'
     : 'expand-race-view';
@@ -153,7 +145,8 @@ export function createRaceCanvasMarkup({
           <span></span>
         </div>
       </div>
-      ${showEmbeddedCameraControls ? createCameraControlsMarkup({ embedded: true }) : ''}
+      ${createStewardMessageMarkup()}
+      ${showEmbeddedCameraControls ? createCameraControlsMarkup({ embedded: true, ui }) : ''}
       ${includeRaceDataPanel ? createRaceDataPanelMarkup({ assets, ui }) : ''}
       ${includeTelemetrySectorBanner ? createTelemetrySectorBannerMarkup({ ui }) : ''}
       <div class="race-finish-panel" data-race-finish-panel hidden aria-live="polite">
@@ -166,22 +159,6 @@ export function createRaceCanvasMarkup({
   `;
 }
 
-export function createRaceDataPanelMarkup({ ui = {} } = {}) {
-  const sizeMode = ui.raceDataBannerSize === 'auto' ? 'auto' : 'custom';
-  return `
-    <div class="race-data-panel race-data-panel--${sizeMode}" data-paddock-component="race-data-panel" data-race-data-panel aria-live="polite">
-      <div class="race-data-copy">
-        <span class="race-data-kicker" data-race-data-kicker>Project</span>
-        <strong data-race-data-title>Select driver</strong>
-        <span class="race-data-subtitle" data-race-data-subtitle>Race entry</span>
-      </div>
-      <strong class="race-data-number" data-race-data-number>--</strong>
-      <button class="race-data-link" type="button" data-race-data-open>Open project</button>
-      ${createLoadingMarkup('Race data')}
-    </div>
-  `;
-}
-
 export function createCarDriverOverviewMarkup({ assets }) {
   const cells = Array.from({ length: 7 }, (_, index) => `
           <div class="car-overview-cell car-overview-cell--slot-${index + 1}" data-overview-field data-overview-slot="${index}">
@@ -280,27 +257,6 @@ export function createTelemetrySectorsMarkup() {
   `;
 }
 
-export function createTelemetrySectorBannerMarkup() {
-  return `
-      <section class="telemetry-sector-banner" data-paddock-component="telemetry-sector-banner" data-telemetry-sector-banner aria-label="Broadcast sector telemetry">
-        <div class="telemetry-sector-banner__copy">
-          <span><b data-selected-code>--</b> sector telemetry</span>
-          <strong data-selected-name>Select driver</strong>
-          <em data-telemetry-current-sector>S1</em>
-        </div>
-        <div class="telemetry-sector-banner__bars">
-          ${[1, 2, 3].map((sector) => `
-          <div class="telemetry-sector-bar" data-telemetry-sector-bar="${sector}" style="--sector-fill: 0%">
-            <span>S${sector}</span>
-            <strong data-telemetry-sector-time="${sector}">--</strong>
-          </div>
-          `).join('')}
-        </div>
-        ${createLoadingMarkup('Sector banner')}
-      </section>
-  `;
-}
-
 export function createTelemetryLapTimesMarkup() {
   return `
       <section class="${getTelemetryModuleClass('lap-times')} telemetry-lap-module" data-paddock-component="telemetry-lap-times" aria-label="Lap timing">
@@ -368,33 +324,41 @@ export function createTelemetryPanelMarkup(options, { includeOverview = options.
 export function createRaceTelemetryDrawerMarkup(options, {
   timingTowerVerticalFit,
   drawerInitiallyOpen = false,
+  raceDataTelemetryDetail = options.ui?.raceDataTelemetryDetail,
 } = {}) {
   const openClass = drawerInitiallyOpen ? ' is-telemetry-open' : '';
   const drawerId = createTelemetryDrawerId();
+  const drawerOptions = {
+    ...options,
+    ui: {
+      ...(options.ui ?? {}),
+      cameraControls: false,
+      raceDataTelemetryDetail: Boolean(raceDataTelemetryDetail),
+    },
+  };
+  const showCameraControls = options.ui?.cameraControls !== false;
   return `
     <section class="race-telemetry-drawer${openClass}" data-paddock-component="race-telemetry-drawer" data-race-telemetry-drawer aria-label="Race view with telemetry drawer">
+      <div class="race-telemetry-drawer__toolbar" aria-label="Race workbench controls">
+        ${showCameraControls ? createCameraControlsMarkup({ showSimulationSpeed: true, ui: options.ui }) : ''}
+        <div class="race-telemetry-drawer__controls">
+          ${createSafetyCarControlMarkup({ compact: true })}
+          <button class="telemetry-drawer-toggle" type="button" data-telemetry-drawer-toggle aria-expanded="${drawerInitiallyOpen ? 'true' : 'false'}" aria-controls="${drawerId}">
+            ${drawerInitiallyOpen ? 'Close telemetry' : 'Telemetry'}
+          </button>
+        </div>
+      </div>
       <div class="race-telemetry-drawer__race">
         ${createRaceCanvasMarkup({
-          ...options,
+          ...drawerOptions,
           includeRaceDataPanel: true,
           includeTimingTower: true,
-          includeTelemetrySectorBanner: true,
           timingTowerVerticalFit,
         })}
       </div>
-      <div class="race-telemetry-drawer__controls" aria-label="Race workbench controls">
-        ${createSafetyCarControlMarkup({ compact: true })}
-        <button class="telemetry-drawer-toggle" type="button" data-telemetry-drawer-toggle aria-expanded="${drawerInitiallyOpen ? 'true' : 'false'}" aria-controls="${drawerId}">
-          ${drawerInitiallyOpen ? 'Close telemetry' : 'Telemetry'}
-        </button>
-      </div>
       <aside id="${drawerId}" class="telemetry-drawer" data-telemetry-drawer aria-label="Telemetry drawer" aria-hidden="${drawerInitiallyOpen ? 'false' : 'true'}"${drawerInitiallyOpen ? '' : ' inert'}>
-        <div class="telemetry-drawer__header">
-          <span>Live telemetry</span>
-          <button type="button" data-telemetry-drawer-close>Close</button>
-        </div>
         <div class="telemetry-drawer__content">
-          ${createTelemetryComponentMarkup(options)}
+          ${createTelemetryPanelMarkup(options, { includeOverview: false })}
         </div>
       </aside>
     </section>

package/src/ui/raceControlStatusBanner.js

@@ -0,0 +1,39 @@
+import { escapeHtml } from './templateUtils.js';
+
+export const RACE_CONTROL_STATUS_BANNERS = {
+  'safety-car': {
+    status: 'safety-car',
+    className: 'is-safety-car',
+    kicker: 'FIA',
+    title: 'Safety Car',
+  },
+  'red-flag': {
+    status: 'red-flag',
+    className: 'is-red-flag',
+    kicker: 'FIA',
+    title: 'Red Flag',
+  },
+};
+
+export function getRaceControlStatusBanner(mode) {
+  return RACE_CONTROL_STATUS_BANNERS[mode] ?? null;
+}
+
+export function createRaceControlStatusBannerMarkup({ status = null } = {}) {
+  const banner = getRaceControlStatusBanner(status);
+  const className = [
+    'broadcast-race-control-banner',
+    banner?.className,
+  ].filter(Boolean).join(' ');
+  const hiddenAttribute = banner ? '' : ' hidden';
+  const statusAttribute = banner ? ` data-race-control-status="${escapeHtml(banner.status)}"` : '';
+  const kicker = banner?.kicker ?? 'FIA';
+  const title = banner?.title ?? 'Race Control';
+
+  return `
+        <div class="${className}" data-tower-race-control-banner${statusAttribute}${hiddenAttribute}>
+          <span data-tower-race-control-kicker>${escapeHtml(kicker)}</span>
+          <strong data-tower-race-control-title>${escapeHtml(title)}</strong>
+        </div>
+  `;
+}

package/src/ui/shellTemplate.js

@@ -24,7 +24,7 @@ export function createF1SimulatorShell({
   shellClasses.push(`sim-shell--timing-${timingFit}`);
   shellClasses.push(`sim-shell--race-data-${raceDataBannerSize}`);
   const cameraControls = ui.cameraControls === 'external'
-    ? `<div class="sim-external-camera-controls">${createCameraControlsMarkup()}</div>`
+    ? `<div class="sim-external-camera-controls">${createCameraControlsMarkup({ ui })}</div>`
     : '';
 
   return `

package/src/ui/templateUtils.js

@@ -0,0 +1,23 @@
+export function escapeHtml(value) {
+  return String(value ?? '')
+    .replaceAll('&', '&')
+    .replaceAll('<', '&lt;')
+    .replaceAll('>', '&gt;')
+    .replaceAll('"', '&quot;')
+    .replaceAll("'", '&#39;');
+}
+
+export function createLoadingMarkup(label = 'Loading') {
+  return `
+      <div class="paddock-loading" data-paddock-loading aria-label="${escapeHtml(label)} loading">
+        <div class="paddock-loading__lights" aria-hidden="true">
+          <span></span>
+          <span></span>
+          <span></span>
+          <span></span>
+          <span></span>
+        </div>
+        <span class="paddock-loading__label">${escapeHtml(label)}</span>
+      </div>
+  `;
+}

package/AGENTS.md

@@ -1,86 +0,0 @@
-# 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/src/standalone.js

@@ -1,15 +0,0 @@
-import { DEMO_PROJECT_DRIVERS, mountF1Simulator } from './index.js';
-
-const root = document.getElementById('f1-simulator-root');
-
-if (root) {
-  mountF1Simulator(root, {
-    drivers: DEMO_PROJECT_DRIVERS,
-    onDriverOpen(driver) {
-      if (driver.link) window.location.href = driver.link;
-    },
-  }).catch((error) => {
-    root.dataset.simulatorState = 'error';
-    console.error('F1 simulator failed to initialize.', error);
-  });
-}