@inventure71/paddockjs 0.2.0 → 1.0.0

package/docs/training.md

@@ -0,0 +1,206 @@
+# Bring Your Own Model
+
+PaddockJS does not train models for you. It provides a simulator environment contract so users can train with any toolchain, then run the resulting policy in the visual simulator.
+
+## Boundary
+
+PaddockJS owns:
+
+- deterministic simulator stepping
+- observations
+- normalized actions
+- events
+- optional reward callback hooks
+- race-rule overrides for the existing simulator rules
+- browser expert stepping
+- sensor visualization
+
+Users own:
+
+- ML framework choice
+- training algorithm
+- model weights
+- model storage
+- model loading
+- reward design
+
+## Supported Now
+
+The current expert API is a JavaScript environment contract. It supports:
+
+- `createPaddockEnvironment()` from `@inventure71/paddockjs/environment`
+- explicit `controlledDrivers`
+- normalized actions: `steering`, `throttle`, `brake`, optional `pitIntent`, and optional `pitCompound`
+- manual stepping with optional `frameSkip`
+- object observations in real units plus a versioned numeric vector and schema, including rays, nearby cars, track lookahead/curvature, pit-lane surface, pit target compound, pit service state, pit-lane open state, and red-flag state
+- full simulator state under `result.state.snapshot`
+- global and per-controlled-driver events
+- optional host-owned `reward(context)` callbacks, or no reward
+- `getActionSpec()` and `getObservationSpec()`
+- scenarios with `participants: 'all'`, `'controlled-only'`, or an explicit driver-id list
+- reset-only scenario placement through `scenario.preset`, `scenario.placements`, and `scenario.traffic`
+- neutral rollout recording through `createRolloutRecorder()`
+- deterministic evaluation metrics through `runEnvironmentEvaluation()` and `createEvaluationTracker()`
+- a JSON-serializable worker protocol wrapper through `createEnvironmentWorkerProtocol()`
+- built-in AI for non-controlled cars
+- browser expert mode through `mountF1Simulator(..., { expert })`
+- opt-in browser ray visualization with `expert.visualizeSensors`
+
+The environment also accepts `rules` as a narrow override of the existing race rules, such as `standingStart: false` for training loops. Rule overrides change simulator behavior; keep them fixed when comparing policy runs.
+
+## Deferred
+
+These are not part of the current package API:
+
+- Python Gymnasium wrapper
+- static obstacle/ghost-car scenario modes
+- debug mutation APIs for arbitrary simulator state
+- assisted-control modes that blend model output with built-in AI
+- model loading, model storage, model registries, or trained policies
+
+Those features need separate design work because they change scenario ownership, reproducibility, and the safety boundary between user experiments and package internals. The worker protocol is intentionally only a message wrapper around the JavaScript environment; it is not a Gymnasium package and does not choose a Python RL stack.
+
+## Policy Shape
+
+Use this convention for browser playback:
+
+```js
+const policy = {
+  predict(observation) {
+    return {
+      steering: 0,
+      throttle: 1,
+      brake: 0,
+    };
+  },
+};
+```
+
+`predict()` receives one controlled driver's observation. It returns normalized controls:
+
+- `steering`: `-1` full left, `1` full right
+- `throttle`: `0` to `1`
+- `brake`: `0` to `1`
+- `pitIntent`: optional `0`, `1`, or `2`; `0` means no pit request and is accepted as a no-op even when pit stops are disabled, `1` means keep trying until a free-enough pit-entry window appears, and `2` means commit to entering at the next pit-entry window even if pit-lane capacity or gap checks would block mode `1`
+- `pitCompound`: optional tire target such as `'S'`, `'M'`, or `'H'`; it must be one of `rules.modules.tireStrategy.compounds`
+
+Controlled drivers do not receive tire-threshold automatic pit calls from the built-in strategy. A model must request a stop with `pitIntent`, and may choose the tire with `pitCompound`; then the simulator owns the pit entry, queue, service, penalty hold, tire change, and pit exit sequence until `pitStopStatus` returns to `completed`. For deterministic training, keep `rules.modules.pitStops.variability.enabled` false or set `rules.modules.pitStops.variability.perfect: true`; when variability is enabled without `perfect`, team `pitCrew` speed, consistency, and reliability affect service time from the same seeded simulation RNG.
+
+`observation.object.self.onTrack` follows the simulator's wheel-level legality rules: track, kerb, and legal pit-lane/box surfaces are on-track for reward/observation purposes, while gravel, grass, and barrier surfaces are off-track. Invalid `observation.lookaheadMeters` values fall back to `[20, 50, 100, 150]` so fixed observation schemas stay usable.
+
+## Headless Training Loop
+
+```js
+import { createPaddockEnvironment } from '@inventure71/paddockjs/environment';
+
+const env = createPaddockEnvironment({
+  drivers,
+  entries,
+  controlledDrivers: ['budget'],
+  frameSkip: 4,
+  rules: {
+    standingStart: false,
+  },
+  reward: myReward,
+});
+
+let result = env.reset();
+while (!result.done) {
+  const observation = result.observation.budget;
+  const action = policy.predict(observation);
+  result = env.step({ budget: action });
+}
+```
+
+## Scenario Reset Control
+
+Scenario placement belongs to environment reset, not to model control. It is useful for deterministic training or evaluation starts such as cornering, recovery, overtaking packs, and pit entry:
+
+```js
+const env = createPaddockEnvironment({
+  drivers,
+  entries,
+  controlledDrivers: ['budget'],
+  scenario: {
+    preset: 'off-track-recovery',
+    placements: {
+      budget: {
+        distanceMeters: 420,
+        offsetMeters: 16,
+        speedKph: 65,
+        headingErrorRadians: 0.4,
+      },
+    },
+    traffic: [
+      {
+        driverId: 'alpha',
+        relativeTo: 'budget',
+        deltaDistanceMeters: 24,
+        offsetMeters: -1.5,
+        speedKph: 68,
+      },
+    ],
+  },
+});
+```
+
+Supported fixed presets are `cornering`, `off-track-recovery`, `overtaking-pack`, and `pit-entry`. Explicit `placements` override preset placement for the same driver. `traffic` places cars relative to another placed or existing car. After reset, `step(actions)` still advances controlled cars only through the normal action contract.
+
+## Rollouts And Evaluation
+
+PaddockJS can export neutral transition data without owning a trainer:
+
+```js
+import { createRolloutRecorder } from '@inventure71/paddockjs/environment';
+
+const recorder = createRolloutRecorder();
+let result = env.reset();
+const action = { budget: policy.predict(result.observation.budget) };
+const next = env.step(action);
+recorder.recordStep(result, action, next);
+```
+
+Each transition has `{ observation, action, reward, nextObservation, terminated, truncated, info }`. If the environment has no reward callback, `reward` is still `null`; the recorder does not invent one.
+
+Deterministic evaluation helpers report simulator quality metrics such as distance, off-track steps, contacts, recovery success, pass count, and first lap time when available. They do not update a model or compute rewards.
+
+## Example Rewards
+
+`createProgressReward()` is exported for examples and quick smoke tests, but it is non-canonical demo code. It is not the official reward function and should not be treated as the recommended objective for every user. Real training code should pass a domain-specific `reward(context)` or omit rewards entirely when collecting observations or imitation data.
+
+## Visual Playback Loop
+
+```js
+import { mountF1Simulator } from '@inventure71/paddockjs';
+
+const simulator = await mountF1Simulator(root, {
+  drivers,
+  entries,
+  expert: {
+    enabled: true,
+    controlledDrivers: ['budget'],
+    frameSkip: 4,
+    visualizeSensors: { rays: true },
+  },
+});
+
+function frame() {
+  const observation = simulator.expert.getObservation().budget;
+  const action = policy.predict(observation);
+  simulator.expert.step({ budget: action });
+  requestAnimationFrame(frame);
+}
+
+frame();
+```
+
+## Specs
+
+Use specs to connect external training code without guessing:
+
+```js
+const actionSpec = env.getActionSpec();
+const observationSpec = env.getObservationSpec();
+```
+
+These specs describe the action ranges, controlled drivers, ray layout, nearby-car limits, and vector schema.

package/examples/train-basic-policy.mjs

@@ -0,0 +1,276 @@
+#!/usr/bin/env node
+
+import { createPaddockEnvironment, createProgressReward } from '@inventure71/paddockjs/environment';
+import { TRAINING_DEMO_DRIVERS, TRAINING_DEMO_ENTRIES } from './trainingData.mjs';
+
+const DEFAULT_OPTIONS = Object.freeze({
+  generations: 4,
+  candidates: 5,
+  episodes: 1,
+  steps: 240,
+  frameSkip: 4,
+  seed: 71,
+  traffic: false,
+  evalOnly: false,
+});
+
+const INITIAL_POLICY = Object.freeze({
+  steeringHeading: -1.2,
+  steeringOffset: -0.35,
+  steeringRayBalance: 0.45,
+  throttleBias: 0.72,
+  throttleFrontClearance: 0.28,
+  throttleSpeedDamping: 0.18,
+  brakeBias: 0,
+  brakeFrontDanger: 0.65,
+  brakeOffTrack: 0.2,
+});
+
+const POLICY_KEYS = Object.keys(INITIAL_POLICY);
+
+main();
+
+function main() {
+  const options = parseCliArgs(process.argv.slice(2));
+  if (options.help) {
+    printHelp();
+    return;
+  }
+
+  const driverId = TRAINING_DEMO_DRIVERS[0].id;
+  const rng = createSeededRandom(options.seed);
+  const reward = createProgressReward();
+  const evaluate = (policy, seedOffset = 0) => evaluatePolicy({
+    policy,
+    driverId,
+    reward,
+    options,
+    seedOffset,
+  });
+
+  if (options.evalOnly) {
+    const baseline = evaluate(INITIAL_POLICY);
+    printSummary({ options, driverId, bestPolicy: INITIAL_POLICY, best: baseline });
+    return;
+  }
+
+  let bestPolicy = { ...INITIAL_POLICY };
+  let best = evaluate(bestPolicy);
+
+  console.log(formatGenerationLine(0, best));
+
+  for (let generation = 1; generation <= options.generations; generation += 1) {
+    const mutationScale = 0.45 / Math.sqrt(generation);
+    const candidates = [{ policy: bestPolicy, scoreSeedOffset: generation * 1000 }];
+
+    for (let index = 1; index < options.candidates; index += 1) {
+      candidates.push({
+        policy: mutatePolicy(bestPolicy, rng, mutationScale),
+        scoreSeedOffset: generation * 1000 + index * 100,
+      });
+    }
+
+    for (const candidate of candidates) {
+      const score = evaluate(candidate.policy, candidate.scoreSeedOffset);
+      if (score.averageReward > best.averageReward) {
+        best = score;
+        bestPolicy = candidate.policy;
+      }
+    }
+
+    console.log(formatGenerationLine(generation, best));
+  }
+
+  printSummary({ options, driverId, bestPolicy, best });
+}
+
+function evaluatePolicy({ policy, driverId, reward, options, seedOffset = 0 }) {
+  let totalReward = 0;
+  let totalDistanceMeters = 0;
+  let totalCollisions = 0;
+  let totalOffTrackSteps = 0;
+  let completedEpisodes = 0;
+
+  for (let episode = 0; episode < options.episodes; episode += 1) {
+    const env = createTrainingEnvironment({ driverId, reward, options, episode, seedOffset });
+    let result = env.reset();
+    let episodeReward = 0;
+
+    for (let step = 0; step < options.steps && !result.done; step += 1) {
+      const observation = result.observation[driverId];
+      const action = chooseAction(policy, observation);
+      result = env.step({ [driverId]: action });
+      episodeReward += result.reward?.[driverId] ?? 0;
+      totalCollisions += result.events.filter((event) => event.type === 'collision').length;
+      if (result.observation[driverId]?.object?.self?.onTrack === false) totalOffTrackSteps += 1;
+    }
+
+    const car = result.state.snapshot.cars.find((entry) => entry.id === driverId);
+    totalReward += episodeReward;
+    totalDistanceMeters += Number(car?.distanceMeters ?? 0);
+    completedEpisodes += 1;
+    env.destroy();
+  }
+
+  return {
+    averageReward: totalReward / Math.max(1, completedEpisodes),
+    averageDistanceMeters: totalDistanceMeters / Math.max(1, completedEpisodes),
+    collisions: totalCollisions,
+    offTrackSteps: totalOffTrackSteps,
+  };
+}
+
+function createTrainingEnvironment({ driverId, reward, options, episode, seedOffset }) {
+  const drivers = options.traffic ? TRAINING_DEMO_DRIVERS.slice(0, 8) : TRAINING_DEMO_DRIVERS.slice(0, 1);
+  return createPaddockEnvironment({
+    drivers,
+    entries: TRAINING_DEMO_ENTRIES,
+    controlledDrivers: [driverId],
+    seed: options.seed + seedOffset + episode,
+    trackSeed: options.seed + 2026 + seedOffset + episode,
+    totalLaps: 3,
+    frameSkip: options.frameSkip,
+    scenario: {
+      participants: options.traffic ? 'all' : 'controlled-only',
+      nonControlled: 'ai',
+    },
+    episode: {
+      maxSteps: options.steps,
+      endOnRaceFinish: true,
+    },
+    rules: {
+      standingStart: false,
+    },
+    reward,
+  });
+}
+
+function chooseAction(policy, observation) {
+  const self = observation.object.self;
+  const frontRay = getRayDistance(observation, 0);
+  const leftRay = getRayDistance(observation, -60);
+  const rightRay = getRayDistance(observation, 60);
+  const frontDanger = clamp01((35 - frontRay) / 35);
+  const rayBalanceMeters = rightRay - leftRay;
+
+  const steering = clamp(
+    policy.steeringHeading * self.trackHeadingErrorRadians +
+      policy.steeringOffset * (self.trackOffsetMeters / 12) +
+      policy.steeringRayBalance * (rayBalanceMeters / 120),
+    -1,
+    1,
+  );
+  const throttle = clamp01(
+    policy.throttleBias +
+      policy.throttleFrontClearance * (frontRay / 120) -
+      policy.throttleSpeedDamping * (self.speedKph / 320) -
+      (self.onTrack ? 0 : 0.35),
+  );
+  const brake = clamp01(
+    policy.brakeBias +
+      policy.brakeFrontDanger * frontDanger +
+      (self.onTrack ? 0 : policy.brakeOffTrack),
+  );
+
+  return { steering, throttle, brake };
+}
+
+function getRayDistance(observation, angleDegrees) {
+  const ray = observation.object.rays.find((entry) => entry.angleDegrees === angleDegrees);
+  return Number(ray?.track?.distanceMeters ?? ray?.lengthMeters ?? 120);
+}
+
+function mutatePolicy(policy, rng, scale) {
+  return Object.fromEntries(POLICY_KEYS.map((key) => [
+    key,
+    policy[key] + randomNormal(rng) * scale,
+  ]));
+}
+
+function parseCliArgs(argv) {
+  const options = { ...DEFAULT_OPTIONS };
+
+  for (const arg of argv) {
+    const [name, rawValue] = arg.split('=');
+    if (name === '--help' || name === '-h') options.help = true;
+    else if (name === '--eval-only') options.evalOnly = true;
+    else if (name === '--traffic') options.traffic = true;
+    else if (name === '--no-traffic') options.traffic = false;
+    else if (name === '--generations') options.generations = parsePositiveInt(rawValue, name);
+    else if (name === '--candidates') options.candidates = parsePositiveInt(rawValue, name);
+    else if (name === '--episodes') options.episodes = parsePositiveInt(rawValue, name);
+    else if (name === '--steps') options.steps = parsePositiveInt(rawValue, name);
+    else if (name === '--frame-skip') options.frameSkip = parsePositiveInt(rawValue, name);
+    else if (name === '--seed') options.seed = parsePositiveInt(rawValue, name);
+    else throw new Error(`Unknown option: ${name}`);
+  }
+
+  return options;
+}
+
+function parsePositiveInt(value, optionName) {
+  const parsed = Number.parseInt(value, 10);
+  if (!Number.isFinite(parsed) || parsed <= 0) {
+    throw new Error(`${optionName} requires a positive integer value.`);
+  }
+  return parsed;
+}
+
+function createSeededRandom(seed) {
+  let state = seed >>> 0;
+  return function random() {
+    state += 0x6D2B79F5;
+    let value = state;
+    value = Math.imul(value ^ (value >>> 15), value | 1);
+    value ^= value + Math.imul(value ^ (value >>> 7), value | 61);
+    return ((value ^ (value >>> 14)) >>> 0) / 4294967296;
+  };
+}
+
+function randomNormal(rng) {
+  const a = Math.max(Number.EPSILON, rng());
+  const b = Math.max(Number.EPSILON, rng());
+  return Math.sqrt(-2 * Math.log(a)) * Math.cos(2 * Math.PI * b);
+}
+
+function clamp(value, min, max) {
+  return Math.min(max, Math.max(min, value));
+}
+
+function clamp01(value) {
+  return clamp(value, 0, 1);
+}
+
+function formatGenerationLine(generation, score) {
+  return [
+    `generation=${generation}`,
+    `reward=${score.averageReward.toFixed(2)}`,
+    `distanceMeters=${score.averageDistanceMeters.toFixed(1)}`,
+    `collisions=${score.collisions}`,
+    `offTrackSteps=${score.offTrackSteps}`,
+  ].join(' ');
+}
+
+function printSummary({ options, driverId, bestPolicy, best }) {
+  console.log(JSON.stringify({
+    driverId,
+    options,
+    best,
+    bestPolicy,
+  }, null, 2));
+}
+
+function printHelp() {
+  console.log(`Usage: node examples/train-basic-policy.mjs [options]
+
+Options:
+  --generations=N   Random-search generations. Default: ${DEFAULT_OPTIONS.generations}
+  --candidates=N    Candidate policies per generation. Default: ${DEFAULT_OPTIONS.candidates}
+  --episodes=N      Episodes per policy evaluation. Default: ${DEFAULT_OPTIONS.episodes}
+  --steps=N         Maximum manual environment steps per episode. Default: ${DEFAULT_OPTIONS.steps}
+  --frame-skip=N    Simulator frames advanced by each step(action). Default: ${DEFAULT_OPTIONS.frameSkip}
+  --seed=N          Deterministic random seed. Default: ${DEFAULT_OPTIONS.seed}
+  --traffic         Keep built-in AI traffic on track during training.
+  --eval-only       Evaluate the starter policy without training.
+`);
+}

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,8 +1,8 @@
 {
   "name": "@inventure71/paddockjs",
-  "version": "0.2.0",
+  "version": "1.0.0",
   "type": "module",
-  "description": "A data-driven browser F1 simulator component for project portfolios.",
+  "description": "A data-driven browser F1 simulator component for host websites.",
   "license": "Apache-2.0",
   "author": "Matteo Giorgetti",
   "homepage": "https://github.com/Inventure71/PaddockJS#readme",
@@ -30,7 +30,7 @@
     "access": "public"
   },
   "engines": {
-    "node": ">=20"
+    "node": ">=20.19.0"
   },
   "main": "src/index.js",
   "types": "src/index.d.ts",
@@ -40,45 +40,55 @@
       "import": "./src/index.js",
       "default": "./src/index.js"
     },
+    "./environment": {
+      "types": "./src/environment/index.d.ts",
+      "import": "./src/environment/index.js",
+      "default": "./src/environment/index.js"
+    },
     "./styles.css": "./src/styles.css"
   },
   "files": [
-    "AGENTS.md",
     "CHANGELOG.md",
+    "INSTALL_AND_UPDATE.md",
     "LICENSE",
     "assets",
-    "docs",
+    "docs/*.md",
+    "examples",
     "src/api",
     "src/app",
     "src/config",
     "src/data",
+    "src/environment",
     "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",
+    "check": "npm test && npm run types:check && npm run pack:dry && npm run consumer:smoke && npm run showcase:ci && npm run browser:smoke",
     "pack:dry": "npm pack --dry-run",
+    "consumer:smoke": "node scripts/consumer-package-smoke.mjs",
+    "browser:smoke": "node smoke/browser-smoke.mjs",
     "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"
+    "release": "npm publish --provenance",
+    "example:train": "node examples/train-basic-policy.mjs"
   },
   "dependencies": {
     "pixi.js": "8.18.1"
   },
   "devDependencies": {
     "@changesets/cli": "2.29.7",
+    "playwright": "^1.57.0",
     "typescript": "5.9.3",
     "vitest": "4.1.5"
   }