@inventure71/paddockjs 0.3.0 → 2.0.0

package/examples/python/base_policy_server.py

@@ -0,0 +1,191 @@
+#!/usr/bin/env python3
+"""Neutral PaddockJS policy server base example.
+
+This file is intentionally minimal and transport-focused:
+- HTTP policy endpoints:
+  - POST /policy/reset
+  - POST /policy/reset-state
+  - POST /policy/decide-batch
+- WebSocket preview endpoint:
+  - /preview (broadcasts {snapshot, observation, meta})
+
+Extend `BasePolicyServer` and override hook methods to plug your own model/runtime.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import time
+from dataclasses import dataclass, field
+from typing import Any, Dict, Iterable, List, Mapping, MutableMapping, Optional
+
+from fastapi import FastAPI, WebSocket, WebSocketDisconnect
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import JSONResponse
+import uvicorn
+
+
+def _zero_action() -> Dict[str, float]:
+    return {
+        "steering": 0.0,
+        "throttle": 0.0,
+        "brake": 0.0,
+    }
+
+
+@dataclass
+class ServerState:
+    session_id: int = 0
+    controlled_drivers: List[str] = field(default_factory=list)
+    connections: List[WebSocket] = field(default_factory=list)
+    latest_preview_frame: Optional[Dict[str, Any]] = None
+
+
+class BasePolicyServer:
+    """Base extension surface for custom policy/runtime integrations."""
+
+    def __init__(self) -> None:
+        self.app = FastAPI(title="PaddockJS Base Policy Server")
+        self.app.add_middleware(
+            CORSMiddleware,
+            allow_origins=["*"],
+            allow_methods=["*"],
+            allow_headers=["*"],
+        )
+        self.state = ServerState()
+        self._broadcast_lock = asyncio.Lock()
+        self._register_routes()
+
+    # ----- Extension hooks -------------------------------------------------
+
+    async def init_policy(self, context: Mapping[str, Any]) -> None:
+        """Initialize policy/runtime resources on full reset."""
+
+    async def reset_policy(self, context: Mapping[str, Any]) -> None:
+        """Reset all policy runtime state for a new run/session."""
+
+    async def reset_policy_state(self, driver_ids: Iterable[str]) -> None:
+        """Reset only selected driver-local model state."""
+
+    async def decide_batch(self, context: Mapping[str, Any]) -> Dict[str, Dict[str, float]]:
+        """Return per-driver controls for one batched policy step."""
+        driver_ids = list(context.get("driverIds") or [])
+        return {driver_id: _zero_action() for driver_id in driver_ids}
+
+    async def publish_preview_frame(self, frame: Mapping[str, Any]) -> None:
+        """Optional extension hook called before broadcasting preview frames."""
+
+    # ----- Public helpers --------------------------------------------------
+
+    async def broadcast_preview_frame(
+        self,
+        snapshot: Mapping[str, Any],
+        observation: Mapping[str, Any],
+        meta: Optional[Mapping[str, Any]] = None,
+    ) -> None:
+        """Broadcast one authoritative preview frame to websocket clients."""
+        frame = {
+            "type": "preview:snapshot",
+            "snapshot": dict(snapshot),
+            "observation": dict(observation),
+            "meta": dict(meta or {}),
+        }
+        self.state.latest_preview_frame = frame
+        await self.publish_preview_frame(frame)
+        payload = frame
+        async with self._broadcast_lock:
+            stale: List[WebSocket] = []
+            for ws in self.state.connections:
+                try:
+                    await ws.send_json(payload)
+                except Exception:
+                    stale.append(ws)
+            if stale:
+                self.state.connections = [ws for ws in self.state.connections if ws not in stale]
+
+    # ----- Internal routing ------------------------------------------------
+
+    def _register_routes(self) -> None:
+        @self.app.get("/preview/frame")
+        async def preview_frame() -> JSONResponse:
+            if self.state.latest_preview_frame:
+                return JSONResponse(self.state.latest_preview_frame)
+            return JSONResponse(
+                {
+                    "type": "preview:status",
+                    "status": "waiting-for-frame",
+                    "session": {"id": self.state.session_id},
+                }
+            )
+
+        @self.app.post("/policy/reset")
+        async def policy_reset(body: MutableMapping[str, Any]) -> JSONResponse:
+            self.state.session_id += 1
+            self.state.controlled_drivers = list(body.get("driverIds") or [])
+            await self.init_policy(body)
+            await self.reset_policy(body)
+            return JSONResponse(
+                {
+                    "ok": True,
+                    "session": {
+                        "id": self.state.session_id,
+                        "controlledDrivers": self.state.controlled_drivers,
+                    },
+                }
+            )
+
+        @self.app.post("/policy/reset-state")
+        async def policy_reset_state(body: MutableMapping[str, Any]) -> JSONResponse:
+            driver_ids = list(body.get("driverIds") or [])
+            await self.reset_policy_state(driver_ids)
+            return JSONResponse(
+                {
+                    "ok": True,
+                    "session": {"id": self.state.session_id},
+                    "resetDrivers": driver_ids,
+                }
+            )
+
+        @self.app.post("/policy/decide-batch")
+        async def policy_decide_batch(body: MutableMapping[str, Any]) -> JSONResponse:
+            actions = await self.decide_batch(body)
+            if not isinstance(actions, dict):
+                actions = {}
+            now_ms = int(time.time() * 1000)
+            return JSONResponse(
+                {
+                    "ok": True,
+                    "session": {"id": self.state.session_id},
+                    "actions": actions,
+                    "meta": {"serverTsMs": now_ms},
+                }
+            )
+
+        @self.app.websocket("/preview")
+        async def preview_stream(ws: WebSocket) -> None:
+            await ws.accept()
+            self.state.connections.append(ws)
+            try:
+                await ws.send_json(
+                    {
+                        "type": "preview:status",
+                        "status": "connected",
+                        "session": {"id": self.state.session_id},
+                    }
+                )
+                while True:
+                    # Keep connection alive; ignore client messages.
+                    await ws.receive_text()
+            except WebSocketDisconnect:
+                pass
+            finally:
+                self.state.connections = [conn for conn in self.state.connections if conn is not ws]
+
+
+def run(host: str = "127.0.0.1", port: int = 8787) -> None:
+    server = BasePolicyServer()
+    uvicorn.run(server.app, host=host, port=port, log_level="info")
+
+
+if __name__ == "__main__":
+    run()

package/examples/python/requirements.txt

@@ -0,0 +1,2 @@
+fastapi
+uvicorn

package/examples/train-basic-policy.mjs

@@ -1,8 +1,7 @@
 #!/usr/bin/env node
 
-import { createPaddockEnvironment, createProgressReward } from '../src/environment/index.js';
-import { CHAMPIONSHIP_ENTRY_BLUEPRINTS } from '../src/data/championship.js';
-import { DEMO_PROJECT_DRIVERS } from '../src/data/demoDrivers.js';
+import { createPaddockEnvironment, createProgressReward } from '@inventure71/paddockjs/environment';
+import { TRAINING_DEMO_DRIVERS, TRAINING_DEMO_ENTRIES } from './trainingData.mjs';
 
 const DEFAULT_OPTIONS = Object.freeze({
   generations: 4,
@@ -38,7 +37,7 @@ function main() {
     return;
   }
 
-  const driverId = DEMO_PROJECT_DRIVERS[0].id;
+  const driverId = TRAINING_DEMO_DRIVERS[0].id;
   const rng = createSeededRandom(options.seed);
   const reward = createProgressReward();
   const evaluate = (policy, seedOffset = 0) => evaluatePolicy({
@@ -122,10 +121,10 @@ function evaluatePolicy({ policy, driverId, reward, options, seedOffset = 0 }) {
 }
 
 function createTrainingEnvironment({ driverId, reward, options, episode, seedOffset }) {
-  const drivers = options.traffic ? DEMO_PROJECT_DRIVERS.slice(0, 8) : DEMO_PROJECT_DRIVERS.slice(0, 1);
+  const drivers = options.traffic ? TRAINING_DEMO_DRIVERS.slice(0, 8) : TRAINING_DEMO_DRIVERS.slice(0, 1);
   return createPaddockEnvironment({
     drivers,
-    entries: CHAMPIONSHIP_ENTRY_BLUEPRINTS,
+    entries: TRAINING_DEMO_ENTRIES,
     controlledDrivers: [driverId],
     seed: options.seed + seedOffset + episode,
     trackSeed: options.seed + 2026 + seedOffset + episode,

package/examples/trainingData.mjs

@@ -0,0 +1,133 @@
+export const TRAINING_DEMO_DRIVERS = [
+  {
+    id: 'budget',
+    code: 'BUD',
+    icon: 'BB',
+    name: 'Budget Buddy',
+    color: '#ff2d55',
+    tire: 'M',
+    raceData: ['AI finance coach', 'Python + LLM', 'Budget guardrails'],
+  },
+  {
+    id: 'noir',
+    code: 'NOI',
+    icon: 'NN',
+    name: 'Neural Noir',
+    color: '#ffb000',
+    tire: 'M',
+    raceData: ['Procedural mystery', 'Gemini storytelling', 'Unreal loop'],
+  },
+  {
+    id: 'vinyl',
+    code: 'HOL',
+    icon: 'HV',
+    name: 'HoloVinyl',
+    color: '#00c2a8',
+    tire: 'H',
+    raceData: ['Touchless DJ control', 'Computer vision', 'Hand tracking'],
+  },
+  {
+    id: 'drsorriso',
+    code: 'DRS',
+    icon: 'DR',
+    name: 'DrSorrisoDonations',
+    color: '#e10600',
+    tire: 'S',
+    raceData: ['Donation intake', 'Database workflow', 'Automation tool'],
+  },
+  {
+    id: 'victoria',
+    code: 'VIC',
+    icon: 'VI',
+    name: 'VictorIA',
+    color: '#00a3ff',
+    tire: 'M',
+    raceData: ['Game AI sandbox', 'Robotics ideas', 'Vision systems'],
+  },
+  {
+    id: 'reminderz',
+    code: 'REM',
+    icon: 'RZ',
+    name: 'ReminderZ',
+    color: '#a3e635',
+    tire: 'H',
+    raceData: ['Knowledge workflow', 'Personal graph', 'Capture tool'],
+  },
+  {
+    id: 'clipclop',
+    code: 'CLP',
+    icon: 'CC',
+    name: 'ClipClop',
+    color: '#f97316',
+    tire: 'S',
+    raceData: ['Mac + Android sync', 'Local clipboard', 'Productivity app'],
+  },
+  {
+    id: 'core',
+    code: 'COR',
+    icon: 'AI',
+    name: 'Core Conflict',
+    color: '#38bdf8',
+    tire: 'M',
+    raceData: ['Runtime AI agents', 'Multiplayer state', 'Game systems'],
+  },
+];
+
+export const TRAINING_DEMO_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 },
+  },
+  {
+    driverId: 'noir',
+    driverNumber: 13,
+    timingName: 'Noir',
+    driver: { pace: 68, racecraft: 83, aggression: 61, riskTolerance: 72, patience: 57, consistency: 64 },
+    vehicle: { id: 'noir-nn13', name: 'NN-13 Shadow', power: 64, braking: 60, aero: 73, dragEfficiency: 57, mechanicalGrip: 69, weightControl: 54, tireCare: 51 },
+  },
+  {
+    driverId: 'vinyl',
+    driverNumber: 33,
+    timingName: 'HoloVinyl',
+    driver: { pace: 71, racecraft: 66, aggression: 52, riskTolerance: 59, patience: 62, consistency: 58 },
+    vehicle: { id: 'vinyl-hv33', name: 'HV-33 Groove', power: 70, braking: 49, aero: 58, dragEfficiency: 74, mechanicalGrip: 52, weightControl: 68, tireCare: 46 },
+  },
+  {
+    driverId: 'drsorriso',
+    driverNumber: 55,
+    timingName: 'DrSorriso',
+    driver: { pace: 46, racecraft: 69, aggression: 44, riskTolerance: 43, patience: 76, consistency: 73 },
+    vehicle: { id: 'sorriso-ds55', name: 'DS-55 Intake', power: 54, braking: 67, aero: 62, dragEfficiency: 49, mechanicalGrip: 71, weightControl: 45, tireCare: 69 },
+  },
+  {
+    driverId: 'victoria',
+    driverNumber: 11,
+    timingName: 'VictorIA',
+    driver: { pace: 78, racecraft: 79, aggression: 58, riskTolerance: 65, patience: 55, consistency: 68 },
+    vehicle: { id: 'victoria-vi11', name: 'VI-11 Vector', power: 76, braking: 58, aero: 65, dragEfficiency: 63, mechanicalGrip: 61, weightControl: 60, tireCare: 48 },
+  },
+  {
+    driverId: 'reminderz',
+    driverNumber: 7,
+    timingName: 'ReminderZ',
+    driver: { pace: 41, racecraft: 61, aggression: 34, riskTolerance: 39, patience: 85, consistency: 80 },
+    vehicle: { id: 'reminderz-rz07', name: 'RZ-07 Recall', power: 42, braking: 76, aero: 50, dragEfficiency: 72, mechanicalGrip: 58, weightControl: 63, tireCare: 88 },
+  },
+  {
+    driverId: 'clipclop',
+    driverNumber: 14,
+    timingName: 'ClipClop',
+    driver: { pace: 73, racecraft: 88, aggression: 76, riskTolerance: 78, patience: 48, consistency: 61 },
+    vehicle: { id: 'clipclop-cc14', name: 'CC-14 Sync', power: 68, braking: 63, aero: 59, dragEfficiency: 61, mechanicalGrip: 78, weightControl: 56, tireCare: 44 },
+  },
+  {
+    driverId: 'core',
+    driverNumber: 91,
+    timingName: 'Core',
+    driver: { pace: 82, racecraft: 85, aggression: 67, riskTolerance: 74, patience: 53, consistency: 72 },
+    vehicle: { id: 'core-ai91', name: 'AI-91 Core', power: 80, braking: 61, aero: 72, dragEfficiency: 59, mechanicalGrip: 75, weightControl: 51, tireCare: 50 },
+  },
+];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inventure71/paddockjs",
-  "version": "0.3.0",
+  "version": "2.0.0",
   "type": "module",
   "description": "A data-driven browser F1 simulator component for host websites.",
   "license": "Apache-2.0",
@@ -53,7 +53,11 @@
     "LICENSE",
     "assets",
     "docs/*.md",
-    "examples",
+    "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",
@@ -68,10 +72,16 @@
     "README.md"
   ],
   "scripts": {
-    "test": "vitest run src",
+    "test": "node scripts/run-vitest.mjs --slow",
+    "test:fast": "node scripts/run-vitest.mjs",
     "types:check": "tsc -p tsconfig.types.json --noEmit",
-    "check": "npm test && npm run types:check && npm run pack:dry && npm run showcase:ci",
+    "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 test && npm run types:check && npm run pack:dry && npm run consumer:smoke && 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",
+    "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",
     "showcase:install": "npm --prefix local-preview ci",
     "showcase:dev": "npm --prefix local-preview run dev",
     "showcase:build": "npm --prefix local-preview run build",
@@ -86,6 +96,7 @@
   },
   "devDependencies": {
     "@changesets/cli": "2.29.7",
+    "playwright": "^1.57.0",
     "typescript": "5.9.3",
     "vitest": "4.1.5"
   }

package/src/api/PaddockSimulatorController.js

@@ -1,16 +1,18 @@
 import { F1SimulatorApp } from '../app/F1SimulatorApp.js';
+import {
+  createRaceDataPanelMarkup,
+  createTelemetrySectorBannerMarkup,
+} from '../ui/bannerTemplates.js';
 import {
   createCarDriverOverviewMarkup,
   createCameraControlsMarkup,
   createRaceCanvasMarkup,
   createRaceControlsMarkup,
-  createRaceDataPanelMarkup,
   createRaceTelemetryDrawerMarkup,
   createSafetyCarControlMarkup,
   createTelemetryCoreMarkup,
   createTelemetryLapTimesMarkup,
   createTelemetryPanelMarkup,
-  createTelemetrySectorBannerMarkup,
   createTelemetrySectorTimesMarkup,
   createTelemetrySectorsMarkup,
   createTimingTowerMarkup,
@@ -215,6 +217,14 @@ export class PaddockSimulatorController {
     this.app?.setSafetyCarDeployed(deployed);
   }
 
+  setRedFlagDeployed(deployed) {
+    this.app?.setRedFlagDeployed?.(deployed);
+  }
+
+  setPitLaneOpen(open) {
+    this.app?.setPitLaneOpen?.(open);
+  }
+
   callSafetyCar() {
     this.setSafetyCarDeployed(true);
   }
@@ -228,6 +238,30 @@ export class PaddockSimulatorController {
     this.setSafetyCarDeployed(!active);
   }
 
+  setPitIntent(driverId, intent, targetCompound) {
+    return this.app?.setPitIntent(driverId, intent, targetCompound) ?? false;
+  }
+
+  getPitIntent(driverId) {
+    return this.app?.getPitIntent(driverId) ?? 0;
+  }
+
+  getPitTargetCompound(driverId) {
+    return this.app?.getPitTargetCompound?.(driverId) ?? null;
+  }
+
+  getSimulationSpeed() {
+    return this.app?.simulationSpeed ?? 1;
+  }
+
+  servePenalty(penaltyId) {
+    return this.app?.servePenalty(penaltyId) ?? null;
+  }
+
+  cancelPenalty(penaltyId) {
+    return this.app?.cancelPenalty(penaltyId) ?? null;
+  }
+
   getSnapshot() {
     return this.app?.getSnapshot() ?? null;
   }