@inventure71/paddockjs 1.0.0 → 2.0.1

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inventure71/paddockjs",
-  "version": "1.0.0",
+  "version": "2.0.1",
   "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,12 +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 consumer:smoke && npm run showcase:ci && npm run browser:smoke",
+    "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",

package/src/api/PaddockSimulatorController.js

@@ -18,6 +18,7 @@ import {
   createTimingTowerMarkup,
 } from '../ui/componentTemplates.js';
 import { applyPaddockThemeCssVariables, resolveF1SimulatorOptions } from '../config/defaultOptions.js';
+import { mergeRestartOptions } from '../config/restartOptions.js';
 
 function assertMountTarget(root, label) {
   if (!root || typeof root !== 'object' || !('innerHTML' in root)) {
@@ -31,38 +32,6 @@ function setPackageCssVariables(root, assets, theme) {
   applyPaddockThemeCssVariables(root, theme);
 }
 
-function mergeResolvedOptions(previousOptions, nextOptions) {
-  const resetFromPreset = Object.hasOwn(nextOptions, 'preset');
-  const previousUi = resetFromPreset ? {} : previousOptions.ui;
-  const previousTheme = resetFromPreset ? {} : previousOptions.theme;
-  return {
-    ...previousOptions,
-    ...nextOptions,
-    ui: {
-      ...previousUi,
-      ...(nextOptions.ui ?? {}),
-      raceDataBanners: {
-        ...(previousUi.raceDataBanners ?? {}),
-        ...(nextOptions.ui?.raceDataBanners ?? {}),
-      },
-    },
-    theme: {
-      ...previousTheme,
-      ...(nextOptions.theme ?? {}),
-    },
-    assets: {
-      ...previousOptions.assets,
-      ...(nextOptions.assets ?? {}),
-      trackTextures: {
-        ...previousOptions.assets.trackTextures,
-        ...(nextOptions.assets?.trackTextures ?? {}),
-      },
-    },
-    drivers: nextOptions.drivers ?? previousOptions.drivers,
-    entries: nextOptions.entries ?? previousOptions.entries,
-  };
-}
-
 function createCompositeRoot(getRoots, getOptions) {
   return {
     style: {
@@ -203,7 +172,7 @@ export class PaddockSimulatorController {
   }
 
   restart(nextOptions = {}) {
-    const nextResolvedOptions = resolveF1SimulatorOptions(mergeResolvedOptions(this.options, nextOptions));
+    const nextResolvedOptions = resolveF1SimulatorOptions(mergeRestartOptions(this.options, nextOptions));
     this.app?.restart(nextResolvedOptions);
     this.options = nextResolvedOptions;
     this.compositeRoot.applyCssVariables();
@@ -250,6 +219,10 @@ export class PaddockSimulatorController {
     return this.app?.getPitTargetCompound?.(driverId) ?? null;
   }
 
+  getSimulationSpeed() {
+    return this.app?.simulationSpeed ?? 1;
+  }
+
   servePenalty(penaltyId) {
     return this.app?.servePenalty(penaltyId) ?? null;
   }

package/src/app/BrowserExpertAdapter.js

@@ -1,14 +1,52 @@
 import { createEnvironmentRuntime } from '../environment/runtime.js';
 import { resolveEnvironmentOptions } from '../environment/options.js';
+import { createBrowserExpertExternalRendererBridge } from './BrowserExpertExternalRenderer.js';
 
 export function createBrowserExpertAdapter(app, expertOptions = {}) {
-  let resolvedOptions = resolveEnvironmentOptions({
-    ...app.options,
-    ...expertOptions,
-    controlledDrivers: expertOptions.controlledDrivers,
-  });
+  let resolvedOptions = resolveBrowserExpertOptions(app.options, expertOptions);
+  let frameRenderSuppressed = false;
+  const externalRenderer = createBrowserExpertExternalRendererBridge(app);
+
+  function resolveBrowserExpertOptions(appOptions, nextExpertOptions = {}) {
+    const options = resolveEnvironmentOptions({
+      ...appOptions,
+      ...nextExpertOptions,
+      controlledDrivers: nextExpertOptions.controlledDrivers,
+    });
+    if (options.result.stateOutput !== 'none') return options;
+    return {
+      ...options,
+      result: {
+        ...options.result,
+        stateOutput: 'minimal',
+      },
+    };
+  }
+
+  function renderableSnapshot(result) {
+    return result?.state?.snapshot ?? app.sim?.snapshotObservation?.() ?? app.sim?.snapshot?.() ?? null;
+  }
+
+  /*
+   * Browser expert mode is a visual adapter. Compact headless options may ask for
+   * no state payload, but the canvas still needs a snapshot to render.
+   */
+  function renderExpertResult(result, renderOptions = {}) {
+    const snapshot = renderableSnapshot(result);
+    if (!snapshot) return;
+    app.renderExpertFrame(snapshot, {
+      ...renderOptions,
+      observation: result?.observation,
+    });
+  }
+
+  function initialResolvedOptions() {
+    return resolveBrowserExpertOptions(app.options, expertOptions);
+  }
+
+  resolvedOptions = initialResolvedOptions();
 
-  return createEnvironmentRuntime({
+  const runtime = createEnvironmentRuntime({
     getSimulation: () => app.sim,
     setSimulation(nextSim) {
       app.sim = nextSim;
@@ -19,14 +57,43 @@ export function createBrowserExpertAdapter(app, expertOptions = {}) {
     },
     getOptions: () => resolvedOptions,
     setOptions(nextOptions) {
-      resolvedOptions = nextOptions;
+      resolvedOptions = nextOptions.result?.stateOutput === 'none'
+        ? { ...nextOptions, result: { ...nextOptions.result, stateOutput: 'minimal' } }
+        : nextOptions;
     },
     afterReset(result) {
       app.renderTrack();
-      app.renderExpertFrame(result.state.snapshot, { observation: result.observation });
+      renderExpertResult(result, { forceDomUpdate: true });
     },
     afterStep(result) {
-      app.renderExpertFrame(result.state.snapshot, { observation: result.observation });
+      if (frameRenderSuppressed) return;
+      renderExpertResult(result);
     },
   });
+
+  return {
+    ...runtime,
+    reset(options = {}) {
+      externalRenderer.assertDetached('reset');
+      return runtime.reset(options);
+    },
+    step(actions = {}) {
+      externalRenderer.assertDetached('step');
+      return runtime.step(actions);
+    },
+    resetDrivers(placements = {}, resultOptions = {}) {
+      externalRenderer.assertDetached('resetDrivers');
+      return runtime.resetDrivers(placements, resultOptions);
+    },
+    destroy() {
+      externalRenderer.detach();
+      runtime.destroy();
+    },
+    setFrameRenderSuppressed(suppressed) {
+      frameRenderSuppressed = Boolean(suppressed);
+    },
+    attachExternalRenderer: externalRenderer.attach,
+    detachExternalRenderer: externalRenderer.detach,
+    getExternalRendererState: externalRenderer.getState,
+  };
 }