@inventure71/paddockjs 0.2.0 → 1.0.0

package/src/environment/sensors.js

@@ -0,0 +1,367 @@
+import { nearestTrackState } from '../simulation/trackModel.js';
+import { metersToSimUnits, simUnitsToMeters } from '../simulation/units.js';
+import { VEHICLE_GEOMETRY } from '../simulation/vehicleGeometry.js';
+
+const TRACK_RAY_STEP_METERS = 1;
+const TRACK_RAY_REFINE_STEPS = 12;
+const ANALYTIC_TRACK_RAY_MAX_CURVATURE = 0.00005;
+const PIT_CONNECTOR_RAY_FALLBACK_METERS = 55;
+export const DEFAULT_RAY_ANGLES_DEGREES = [-135, -60, -20, 0, 20, 60, 135, 180];
+
+export function buildNearbyCars(car, snapshot, { maxCars = 6, radiusMeters = 150 } = {}) {
+  const limit = Math.max(0, Math.floor(maxCars));
+  if (limit === 0) return [];
+  const radius = metersToSimUnits(radiusMeters);
+  const radiusSquared = radius * radius;
+  const forwardX = Math.cos(car.heading);
+  const forwardY = Math.sin(car.heading);
+  const rightX = -Math.sin(car.heading);
+  const rightY = Math.cos(car.heading);
+  const nearest = [];
+
+  snapshot.cars.forEach((other, order) => {
+    if (other.id === car.id) return;
+    const dx = other.x - car.x;
+    const dy = other.y - car.y;
+    const distanceSquared = dx * dx + dy * dy;
+    if (distanceSquared > radiusSquared) return;
+
+    const forward = forwardX * dx + forwardY * dy;
+    const right = rightX * dx + rightY * dy;
+    const entry = {
+      id: other.id,
+      relativeForwardMeters: simUnitsToMeters(forward),
+      relativeRightMeters: simUnitsToMeters(right),
+      relativeDistanceMeters: simUnitsToMeters(Math.sqrt(distanceSquared)),
+      relativeSpeedKph: other.speedKph - car.speedKph,
+      relativeHeadingRadians: normalizeRelativeHeading(other.heading - car.heading),
+      ahead: forward > 0,
+      sameLap: other.lap === car.lap,
+      distanceSquared,
+      order,
+    };
+    insertNearestCar(nearest, entry, limit);
+  });
+
+  return nearest.map(({ distanceSquared, order, ...entry }) => entry);
+}
+
+export function buildRaySensors(car, snapshot, rayOptions = {}) {
+  const angles = rayOptions.anglesDegrees ?? DEFAULT_RAY_ANGLES_DEGREES;
+  const lengthMeters = rayOptions.lengthMeters ?? 120;
+  const origin = getCarRayOrigin(car);
+  const trackContext = rayOptions.detectTrack === false
+    ? null
+    : createTrackRayContext(car, snapshot, origin);
+
+  return angles.map((angleDegrees) => ({
+    angleDegrees,
+    angleRadians: degreesToRadians(angleDegrees),
+    lengthMeters,
+    track: rayOptions.detectTrack === false
+      ? createTrackMiss(lengthMeters)
+      : estimateTrackHit(car, snapshot, angleDegrees, lengthMeters, trackContext),
+    car: rayOptions.detectCars === false
+      ? { hit: false, distanceMeters: lengthMeters, driverId: null, relativeSpeedKph: 0 }
+      : estimateCarHit(car, snapshot, angleDegrees, lengthMeters, origin),
+  }));
+}
+
+function createTrackRayContext(car, snapshot, origin) {
+  if (!Array.isArray(snapshot.track?.samples) || snapshot.track.samples.length === 0) {
+    return { origin, originState: null };
+  }
+  return {
+    origin,
+    originState: nearestTrackState(snapshot.track, origin, car.progress),
+  };
+}
+
+function estimateTrackHit(car, snapshot, angleDegrees, lengthMeters, context = null) {
+  if (!Array.isArray(snapshot.track?.samples) || snapshot.track.samples.length === 0) {
+    return estimateLocalTrackHit(car, snapshot, angleDegrees, lengthMeters);
+  }
+
+  const origin = context?.origin ?? getCarRayOrigin(car);
+  const ray = getCarRayVector(car, angleDegrees);
+  const maxDistance = metersToSimUnits(lengthMeters);
+  const step = metersToSimUnits(TRACK_RAY_STEP_METERS);
+  const originState = context?.originState ?? nearestTrackState(snapshot.track, origin, car.progress);
+  const includePitLane = Boolean(car.inPitLane || car.pitLanePart || originState.inPitLane);
+  const analyticHit = estimateAnalyticMainTrackHit({
+    car,
+    track: snapshot.track,
+    originState,
+    ray,
+    lengthMeters,
+    includePitLane,
+  });
+  if (analyticHit) return analyticHit;
+  let previousDistance = 0;
+  let previousInside = null;
+
+  for (let distance = 0; distance <= maxDistance; distance += step) {
+    const state = nearestTrackState(snapshot.track, pointOnRay(origin, ray, distance), car.progress);
+    const inside = isInsideTrackBorder(state, snapshot.track, includePitLane);
+    if (previousInside == null) {
+      previousInside = inside;
+      previousDistance = distance;
+      continue;
+    }
+
+    if (inside !== previousInside) {
+      const kind = previousInside ? 'exit' : 'entry';
+      const hitDistance = refineTrackTransitionDistance(
+        snapshot.track,
+        origin,
+        ray,
+        car.progress,
+        previousDistance,
+        distance,
+        kind,
+        includePitLane,
+      );
+      return {
+        hit: true,
+        distanceMeters: simUnitsToMeters(hitDistance),
+        kind,
+      };
+    }
+    previousDistance = distance;
+    previousInside = inside;
+  }
+
+  return createTrackMiss(lengthMeters);
+}
+
+function insertNearestCar(nearest, entry, limit) {
+  let insertAt = nearest.findIndex((candidate) => (
+    entry.distanceSquared < candidate.distanceSquared ||
+    (entry.distanceSquared === candidate.distanceSquared && entry.order < candidate.order)
+  ));
+  if (insertAt < 0) insertAt = nearest.length;
+  if (insertAt >= limit) return;
+  nearest.splice(insertAt, 0, entry);
+  if (nearest.length > limit) nearest.pop();
+}
+
+function estimateAnalyticMainTrackHit({ car, track, originState, ray, lengthMeters, includePitLane }) {
+  if (includePitLane || isNearPitConnector(track, originState)) return null;
+  if (Math.abs(originState.curvature ?? 0) > ANALYTIC_TRACK_RAY_MAX_CURVATURE) return null;
+
+  const lateral = ray.x * originState.normalX + ray.y * originState.normalY;
+  if (Math.abs(lateral) < 0.08) return createTrackMiss(lengthMeters);
+
+  const trackHalfWidth = track.width / 2;
+  const offset = originState.signedOffset ?? car.signedOffset ?? 0;
+  const inside = Math.abs(offset) <= trackHalfWidth;
+  const targetEdge = getLocalTrackTransitionTarget({
+    inside,
+    offsetMeters: offset,
+    lateral,
+    trackHalfWidthMeters: trackHalfWidth,
+  });
+  if (targetEdge == null) return createTrackMiss(lengthMeters);
+
+  const distance = (targetEdge - offset) / lateral;
+  const maxDistance = metersToSimUnits(lengthMeters);
+  if (distance < 0 || distance > maxDistance) return createTrackMiss(lengthMeters);
+
+  return {
+    hit: true,
+    distanceMeters: simUnitsToMeters(distance),
+    kind: inside ? 'exit' : 'entry',
+  };
+}
+
+function isNearPitConnector(track, state) {
+  const pitLane = track.pitLane;
+  if (!pitLane?.enabled || !Number.isFinite(state?.distance)) return false;
+  const window = metersToSimUnits(PIT_CONNECTOR_RAY_FALLBACK_METERS);
+  const entryDistance = pitLane.entry?.trackDistance ?? pitLane.entry?.distanceFromStart;
+  const exitDistance = pitLane.exit?.trackDistance ?? pitLane.exit?.distanceFromStart;
+  return wrappedTrackDistance(state.distance, entryDistance, track.length) <= window ||
+    wrappedTrackDistance(state.distance, exitDistance, track.length) <= window;
+}
+
+function wrappedTrackDistance(first, second, totalLength) {
+  if (!Number.isFinite(first) || !Number.isFinite(second) || !Number.isFinite(totalLength) || totalLength <= 0) {
+    return Infinity;
+  }
+  const delta = Math.abs(first - second);
+  return Math.min(delta, totalLength - delta);
+}
+
+function estimateLocalTrackHit(car, snapshot, angleDegrees, lengthMeters) {
+  const trackHalfWidthMeters = simUnitsToMeters(snapshot.track.width / 2);
+  const offsetMeters = simUnitsToMeters(car.signedOffset ?? 0);
+  const lateral = Math.sin(degreesToRadians(angleDegrees));
+  if (Math.abs(lateral) < 0.08) {
+    return createTrackMiss(lengthMeters);
+  }
+
+  const inside = Math.abs(offsetMeters) <= trackHalfWidthMeters;
+  const targetEdge = getLocalTrackTransitionTarget({ inside, offsetMeters, lateral, trackHalfWidthMeters });
+  if (targetEdge == null) return createTrackMiss(lengthMeters);
+
+  const distanceMeters = (targetEdge - offsetMeters) / lateral;
+  if (distanceMeters < 0 || distanceMeters > lengthMeters) return createTrackMiss(lengthMeters);
+
+  return {
+    hit: true,
+    distanceMeters,
+    kind: inside ? 'exit' : 'entry',
+  };
+}
+
+function getLocalTrackTransitionTarget({ inside, offsetMeters, lateral, trackHalfWidthMeters }) {
+  if (inside) return lateral > 0 ? trackHalfWidthMeters : -trackHalfWidthMeters;
+  if (offsetMeters > trackHalfWidthMeters) return lateral < 0 ? trackHalfWidthMeters : null;
+  if (offsetMeters < -trackHalfWidthMeters) return lateral > 0 ? -trackHalfWidthMeters : null;
+  return null;
+}
+
+function refineTrackTransitionDistance(track, origin, ray, progressHint, lowDistance, highDistance, kind, includePitLane = true) {
+  let low = lowDistance;
+  let high = highDistance;
+  for (let index = 0; index < TRACK_RAY_REFINE_STEPS; index += 1) {
+    const middle = (low + high) / 2;
+    const state = nearestTrackState(track, pointOnRay(origin, ray, middle), progressHint);
+    const inside = isInsideTrackBorder(state, track, includePitLane);
+    if (kind === 'entry') {
+      if (inside) high = middle;
+      else low = middle;
+    } else if (inside) {
+      low = middle;
+    } else {
+      high = middle;
+    }
+  }
+  return high;
+}
+
+function isInsideTrackBorder(state, track, includePitLane = true) {
+  if (includePitLane && state.inPitLane) return true;
+  return state.crossTrackError <= track.width / 2;
+}
+
+function createTrackMiss(lengthMeters) {
+  return {
+    hit: false,
+    distanceMeters: lengthMeters,
+    kind: null,
+  };
+}
+
+function estimateCarHit(car, snapshot, angleDegrees, lengthMeters, origin = getCarRayOrigin(car)) {
+  const ray = getCarRayVector(car, angleDegrees);
+  const maxDistance = metersToSimUnits(lengthMeters);
+  let closest = null;
+  snapshot.cars.forEach((other) => {
+    if (other.id === car.id) return;
+    if (!carRayBroadphaseHit(origin, ray, maxDistance, other)) return;
+    const hitDistance = intersectCarFootprint(origin, ray, other);
+    if (hitDistance == null || hitDistance > maxDistance) return;
+    const distanceMeters = simUnitsToMeters(hitDistance);
+    if (!closest || hitDistance < closest.distanceSimUnits) {
+      closest = {
+        hit: true,
+        distanceSimUnits: hitDistance,
+        distanceMeters,
+        driverId: other.id,
+        relativeSpeedKph: other.speedKph - car.speedKph,
+      };
+    }
+  });
+  if (!closest) return { hit: false, distanceMeters: lengthMeters, driverId: null, relativeSpeedKph: 0 };
+  const { distanceSimUnits, ...publicHit } = closest;
+  return publicHit;
+}
+
+function carRayBroadphaseHit(origin, ray, maxDistance, other) {
+  const dx = other.x - origin.x;
+  const dy = other.y - origin.y;
+  const projection = dx * ray.x + dy * ray.y;
+  const radius = Math.hypot(VEHICLE_GEOMETRY.bodyLength, VEHICLE_GEOMETRY.bodyWidth) / 2;
+  if (projection < -radius || projection > maxDistance + radius) return false;
+  const perpendicularSquared = Math.max(0, dx * dx + dy * dy - projection * projection);
+  return perpendicularSquared <= radius * radius;
+}
+
+export function getCarRayOrigin(car) {
+  return {
+    x: car.x,
+    y: car.y,
+  };
+}
+
+export function getCarRayVector(car, angleDegrees) {
+  const angle = car.heading + degreesToRadians(angleDegrees);
+  return {
+    x: Math.cos(angle),
+    y: Math.sin(angle),
+  };
+}
+
+function pointOnRay(origin, ray, distance) {
+  return {
+    x: origin.x + ray.x * distance,
+    y: origin.y + ray.y * distance,
+  };
+}
+
+function intersectCarFootprint(origin, ray, other) {
+  const forward = { x: Math.cos(other.heading), y: Math.sin(other.heading) };
+  const right = { x: -Math.sin(other.heading), y: Math.cos(other.heading) };
+  const delta = { x: origin.x - other.x, y: origin.y - other.y };
+  const localOrigin = {
+    x: dot(delta, forward),
+    y: dot(delta, right),
+  };
+  const localRay = {
+    x: dot(ray, forward),
+    y: dot(ray, right),
+  };
+  const halfLength = VEHICLE_GEOMETRY.bodyLength / 2;
+  const halfWidth = VEHICLE_GEOMETRY.bodyWidth / 2;
+  return intersectAxisAlignedBoxRay(localOrigin, localRay, halfLength, halfWidth);
+}
+
+function intersectAxisAlignedBoxRay(origin, ray, halfLength, halfWidth) {
+  let tMin = -Infinity;
+  let tMax = Infinity;
+  const xRange = intersectSlab(origin.x, ray.x, -halfLength, halfLength);
+  const yRange = intersectSlab(origin.y, ray.y, -halfWidth, halfWidth);
+  if (!xRange || !yRange) return null;
+  tMin = Math.max(tMin, xRange.min, yRange.min);
+  tMax = Math.min(tMax, xRange.max, yRange.max);
+  if (tMax < 0 || tMin > tMax) return null;
+  return Math.max(0, tMin);
+}
+
+function intersectSlab(origin, direction, min, max) {
+  if (Math.abs(direction) < 1e-9) {
+    return origin >= min && origin <= max ? { min: -Infinity, max: Infinity } : null;
+  }
+  const first = (min - origin) / direction;
+  const second = (max - origin) / direction;
+  return {
+    min: Math.min(first, second),
+    max: Math.max(first, second),
+  };
+}
+
+function dot(a, b) {
+  return a.x * b.x + a.y * b.y;
+}
+
+function degreesToRadians(degrees) {
+  return (degrees * Math.PI) / 180;
+}
+
+function normalizeRelativeHeading(angle) {
+  let value = angle;
+  while (value > Math.PI) value -= Math.PI * 2;
+  while (value < -Math.PI) value += Math.PI * 2;
+  return value;
+}

package/src/environment/specs.js

@@ -0,0 +1,163 @@
+import { normalizeLookaheadMeters } from './observationOptions.js';
+
+export function buildActionSpec(options) {
+  const compounds = Array.isArray(options.rules?.modules?.tireStrategy?.compounds) &&
+    options.rules.modules.tireStrategy.compounds.length
+    ? [...options.rules.modules.tireStrategy.compounds]
+    : ['S', 'M', 'H'];
+  return {
+    version: 1,
+    controlledDrivers: [...options.controlledDrivers],
+    action: {
+      type: 'continuous',
+      perDriver: {
+        steering: { min: -1, max: 1, unit: 'normalized' },
+        throttle: { min: 0, max: 1, unit: 'normalized' },
+        brake: { min: 0, max: 1, unit: 'normalized' },
+        pitIntent: { values: [0, 1, 2], unit: 'request', optional: true },
+        pitCompound: { values: compounds, unit: 'compound', optional: true },
+      },
+    },
+  };
+}
+
+export function buildObservationSpec(options) {
+  const rayOptions = options.sensors.rays;
+  const nearbyOptions = options.sensors.nearbyCars;
+  const lookaheadMeters = normalizeLookaheadMeters(options.observation?.lookaheadMeters);
+  return {
+    version: 2,
+    controlledDrivers: [...options.controlledDrivers],
+    object: {
+      self: [
+        { name: 'id', unit: 'id' },
+        { name: 'speedKph', unit: 'kph' },
+        { name: 'speedMetersPerSecond', unit: 'm/s' },
+        { name: 'headingRadians', unit: 'rad' },
+        { name: 'steeringAngleRadians', unit: 'rad' },
+        { name: 'throttle', unit: 'normalized' },
+        { name: 'brake', unit: 'normalized' },
+        { name: 'lap', unit: 'count' },
+        { name: 'completedLaps', unit: 'count' },
+        { name: 'lapProgressMeters', unit: 'm' },
+        { name: 'trackOffsetMeters', unit: 'm' },
+        { name: 'trackHeadingErrorRadians', unit: 'rad' },
+        { name: 'onTrack', unit: 'boolean' },
+        { name: 'surface', unit: 'label' },
+        { name: 'inPitLane', unit: 'boolean' },
+        { name: 'pitLanePart', unit: 'nullable:label' },
+        { name: 'pitBoxId', unit: 'nullable:id' },
+        { name: 'tireEnergy', unit: 'nullable:number' },
+        { name: 'pitIntent', unit: '0:none|1:if-free|2:committed' },
+        { name: 'pitTargetCompound', unit: 'nullable:compound' },
+        { name: 'pitStopStatus', unit: 'nullable:label' },
+        { name: 'pitStopPhase', unit: 'nullable:label' },
+        { name: 'pitStopServiceRemainingSeconds', unit: 'nullable:seconds' },
+        { name: 'pitStopPenaltyServiceRemainingSeconds', unit: 'nullable:seconds' },
+        { name: 'pitStopsCompleted', unit: 'count' },
+      ],
+      race: [
+        { name: 'position', unit: 'rank' },
+        { name: 'totalCars', unit: 'count' },
+        { name: 'raceMode', unit: 'label' },
+        { name: 'pitLaneOpen', unit: 'boolean' },
+        { name: 'redFlag', unit: 'boolean' },
+        { name: 'totalLaps', unit: 'count' },
+      ],
+      rays: {
+        enabled: Boolean(rayOptions.enabled),
+        anglesDegrees: [...rayOptions.anglesDegrees],
+        lengthMeters: rayOptions.lengthMeters,
+        track: {
+          distanceMeters: { unit: 'm', noHitValue: rayOptions.lengthMeters },
+          hit: { unit: 'boolean' },
+          kind: { values: ['exit', 'entry', null] },
+        },
+        car: {
+          distanceMeters: { unit: 'm', noHitValue: rayOptions.lengthMeters },
+          hit: { unit: 'boolean' },
+          driverId: { nullable: true },
+          relativeSpeedKph: { unit: 'kph' },
+        },
+      },
+      nearbyCars: {
+        enabled: Boolean(nearbyOptions.enabled),
+        maxCars: nearbyOptions.maxCars,
+        radiusMeters: nearbyOptions.radiusMeters,
+      },
+      track: {
+        lengthMeters: { unit: 'm' },
+        widthMeters: { unit: 'm' },
+        curvature: { unit: '1/sim-unit' },
+        lookaheadMeters: [...lookaheadMeters],
+        lookahead: {
+          distanceMeters: { unit: 'm' },
+          curvature: { unit: '1/sim-unit' },
+          headingDeltaRadians: { unit: 'rad' },
+        },
+      },
+      events: { type: 'array' },
+    },
+    vector: {
+      schema: buildVectorSchema({ rayOptions, nearbyOptions, lookaheadMeters }),
+    },
+  };
+}
+
+function buildVectorSchema({ rayOptions, nearbyOptions, lookaheadMeters }) {
+  const schema = [
+    { name: 'self.speedKph', unit: 'kph', scale: 'fixed:400' },
+    { name: 'self.speedMetersPerSecond', unit: 'm/s', scale: 'fixed:120' },
+    { name: 'self.steeringAngleRadians', unit: 'rad', scale: 'fixed:pi' },
+    { name: 'self.throttle', scale: '0..1' },
+    { name: 'self.brake', scale: '0..1' },
+    { name: 'self.lapProgressRatio', scale: '0..1' },
+    { name: 'self.trackOffsetMeters', unit: 'm', scale: 'fixed:meters' },
+    { name: 'self.trackHeadingErrorRadians', unit: 'rad', scale: 'fixed:pi' },
+    { name: 'self.onTrack', scale: 'boolean' },
+    { name: 'self.inPitLane', scale: 'boolean' },
+    { name: 'self.tireEnergy', scale: '0..100' },
+    { name: 'self.pitIntent', scale: '0..2' },
+    { name: 'self.pitStopActive', scale: 'boolean' },
+    { name: 'race.positionNormalized', scale: '0..1' },
+    { name: 'race.raceModeGreen', scale: 'boolean' },
+    { name: 'race.raceModeSafetyCar', scale: 'boolean' },
+    { name: 'race.redFlag', scale: 'boolean' },
+    { name: 'race.pitLaneOpen', scale: 'boolean' },
+    { name: 'track.curvature', scale: 'track-curvature' },
+  ];
+  lookaheadMeters.forEach((_, index) => {
+    schema.push(
+      { name: `track.lookahead[${index}].curvature`, scale: 'track-curvature' },
+      { name: `track.lookahead[${index}].headingDeltaRadians`, unit: 'rad', scale: 'fixed:pi' },
+    );
+  });
+  if (rayOptions.enabled) {
+    rayOptions.anglesDegrees.forEach((_, index) => {
+      schema.push(
+        { name: `rays[${index}].track.distanceRatio`, scale: '0..1' },
+        { name: `rays[${index}].track.hit`, scale: 'boolean' },
+        { name: `rays[${index}].track.kindExit`, scale: 'boolean' },
+        { name: `rays[${index}].track.kindEntry`, scale: 'boolean' },
+        { name: `rays[${index}].car.distanceRatio`, scale: '0..1' },
+        { name: `rays[${index}].car.hit`, scale: 'boolean' },
+        { name: `rays[${index}].car.relativeSpeedKph`, unit: 'kph', scale: 'fixed:200' },
+      );
+    });
+  }
+  if (nearbyOptions.enabled) {
+    for (let index = 0; index < nearbyOptions.maxCars; index += 1) {
+      schema.push(
+        { name: `nearbyCars[${index}].present`, scale: 'boolean' },
+        { name: `nearbyCars[${index}].relativeForwardRatio`, scale: '-1..1' },
+        { name: `nearbyCars[${index}].relativeRightRatio`, scale: '-1..1' },
+        { name: `nearbyCars[${index}].relativeDistanceRatio`, scale: '0..1' },
+        { name: `nearbyCars[${index}].relativeSpeedKph`, unit: 'kph', scale: 'fixed:200' },
+        { name: `nearbyCars[${index}].relativeHeadingRadians`, unit: 'rad', scale: 'fixed:pi' },
+        { name: `nearbyCars[${index}].ahead`, scale: 'boolean' },
+        { name: `nearbyCars[${index}].sameLap`, scale: 'boolean' },
+      );
+    }
+  }
+  return schema;
+}

package/src/environment/workerProtocol.js

@@ -0,0 +1,52 @@
+export function createEnvironmentWorkerProtocol(env) {
+  return {
+    handle(message = {}) {
+      try {
+        return handleEnvironmentMessage(env, message);
+      } catch (error) {
+        return createErrorResponse(message, error);
+      }
+    },
+  };
+}
+
+export function handleEnvironmentMessage(env, message = {}) {
+  const id = message.id ?? null;
+  switch (message.type) {
+    case 'reset':
+      return createSuccessResponse(id, 'reset:result', env.reset(message.options ?? {}));
+    case 'step':
+      return createSuccessResponse(id, 'step:result', env.step(message.actions ?? {}));
+    case 'getActionSpec':
+      return createSuccessResponse(id, 'getActionSpec:result', env.getActionSpec());
+    case 'getObservationSpec':
+      return createSuccessResponse(id, 'getObservationSpec:result', env.getObservationSpec());
+    case 'getObservation':
+      return createSuccessResponse(id, 'getObservation:result', env.getObservation());
+    case 'getState':
+      return createSuccessResponse(id, 'getState:result', env.getState());
+    case 'destroy':
+      env.destroy();
+      return createSuccessResponse(id, 'destroy:result', null);
+    default:
+      throw new Error(`Unsupported PaddockJS environment worker message type: ${message.type}`);
+  }
+}
+
+function createSuccessResponse(id, type, result) {
+  return {
+    id,
+    ok: true,
+    type,
+    result,
+  };
+}
+
+function createErrorResponse(message, error) {
+  return {
+    id: message?.id ?? null,
+    ok: false,
+    type: 'error',
+    error: error instanceof Error ? error.message : String(error),
+  };
+}