Merge pull request 'v0.16.1 — ISS-007 smooth client-side sim clock with per-snapshot re-sync' (#18 ) from feat/smooth-sim-clock into master

test: fix ISS-007 clock parse — replace only fixed the first space
feat: v0.16.1 — ISS-007 smooth client-side sim clock with per-snapshot re-sync
2026-09-19 16:27:21 +02:00 · 2026-09-19 14:20:34 +00:00 · 2026-09-19 14:00:47 +00:00 · 2026-09-19 15:44:09 +02:00 · 2026-09-19 13:36:27 +00:00 · 2026-09-19 13:00:06 +00:00
25 changed files with 879 additions and 93 deletions
@@ -1,5 +1,36 @@
 # Changelog
 ## v0.16.1 — 2026-09-19 14:00
 - **Smooth client-side sim clock with per-snapshot re-sync (ISS-007).** The left-pane "Time" display used to jump once per 1 s poll because it rendered the snapshot's `clockMs` verbatim. It now ticks smoothly on the client between polls: new hook `lib/useSimClock.ts` keeps an anchor `{clockMs, at, timeScale, paused}` and re-derives the display clock every ~100 ms as `anchor.clockMs + (now − at) × timeScale` — exactly the server's own tick model (`tickOnce`: real-time × timeScale), so client extrapolation mirrors authoritative game time. Every new snapshot re-anchors to server truth, bounding any drift by network latency only; while paused the display is frozen at the anchor value (advance 0). The pure core `advanceSimClock(anchor, nowMs)` is exported and unit-tested in node
 - **LeftPane consumes it for the `sim-clock` paragraph ONLY** (`components/LeftPane.tsx`): fed with EFFECTIVE controls `{timeScale: pendingScale ?? snapshot scale, paused}` so a slider drag or pause click takes effect on click/drag without waiting for a confirming snapshot; the `(paused)` suffix keeps coming from the effective paused flag. Right-pane deadline/penalty previews are untouched — they stay computed from the snapshot's `clockMs` (deterministic against server truth)
 - No server or OpenAPI changes — display-only client work
 - Tests: unit — new suite in `lib/useSimClock.test.ts` pins the extrapolation math (exact elapsed × scale advance, frozen while paused at any scale, zero-elapsed identity, clock-skew clamp never goes backwards, mirrors the tickOnce formula under the 2 s clamp). e2e (`panes.spec.ts`) — new test: at scale 1000 sample `sim-clock` three times ~1.3 s apart real time and assert the displayed clock strictly advances between CONSECUTIVE samples (with poll-only rendering a pair could straddle zero snapshots and not change), plus format check and a total-advance sanity bound
 - Verified: `tsc --noEmit` clean; unit suite green locally; e2e not run locally by design — CI verifies against an isolated stack
 ## v0.16.0 — 2026-09-19 12:18
 - **Weight-proportional fuel burn (ISS-005, part A).** Fuel no longer burns at a constant L/km — the instantaneous rate is proportional to total weight, `r(F) = k·(We + ρF)` L/km with We the empty weight and ρ = 0.8 kg/L (Jet-A1), so a heavier plane burns more per km and a tank gets lighter as it empties. The constant `k` is calibrated so a FULL tank burns exactly the catalog's old `burnPerKm`, keeping full-tank departure behavior identical to before; divergence only grows in flight as fuel drops off. Closed forms of `dF/dx = −k(We + ρF)` live in `lib/sim/movement.ts` (single source of truth):
  - `fuelAtWeighted(startFuel, burnPerKm, emptyWeightKg, maxFuel, distanceKm, progress)` — fuel remaining after flying `progress` of the leg (replaces the old constant-rate `fuelAt`, which is removed)
  - `requiredFuelFor(burnPerKm, emptyWeightKg, maxFuel, distanceKm)` — liters needed to cover the distance arriving empty, independent of starting load; a leg is flyable iff current fuel ≥ this and fits at all iff it ≤ tank capacity
  - `burnRateConstant(...)` + exported `FUEL_DENSITY_KG_PER_L` (0.8)
 - **Catalog gains `emptyWeightKg`** (`lib/game/catalog.ts`, ATR 72-600 OEW ≈ 9300 kg), exposed in the snapshot's `catalog[]` so clients can mirror the model; OpenAPI `CatalogEntry` follows
 - **All three burn call sites moved to the weighted model**: landing fuel on arrival (`lib/sim/engine.ts`), live in-flight fuel in the state snapshot (`lib/game/state.ts`), and fly validation (`lib/game/actions.ts` — a leg now needs `requiredFuelFor`, not `burnPerKm × km`)
 - **Refuel "just enough for the loaded package" (ISS-005, part B).** `POST /api/planes/{planeId}/refuel` takes an OPTIONAL JSON body `{ mode?: 'full' | 'forFlight', packageId?: string }`: no body or `mode:'full'` is exactly today's fill-to-max behavior; `mode:'forFlight'` adds just enough fuel to fly that loaded package's destination leg — liters = `requiredFuelFor(haversine(plane → pkg.destIcao)) − current fuel`, 409 if the package isn't loaded on this plane / is expired, or the leg doesn't fit even a full tank; bad bodies (unknown field/mode, forFlight without packageId) are 400. OpenAPI gains `RefuelRequest` + the 400
 - **UI** (`components/RightPane.tsx`): each on-board cargo row gets a "Refuel" button (`refuel-for-{pkg.id}` → `{mode:'forFlight', packageId}`, disabled while flying or busy, mirroring fly-to/abandon); the market fill-up button is renamed **"Refuel to full"** (testid `market-refuel` and behavior unchanged)
 - Tests: unit — new weighted-burn suite in `lib/sim/movement.test.ts` (full-tank calibration ≈ old constant, closed form vs numeric integration of r(F), F_req monotonic + empty-arrival identity, lighter-start burns less, clamping); `refuelPlane` forFlight cases in `lib/game/actions.test.ts` (exact liters/cost, no-op when enough, 409 not-loaded/expired/doesn't-fit via the ~7670 km UNNT↔LPPD pair, 404 unknown package, 400 missing packageId); refuel route body-validation tests; `lib/openapi.test.ts` updated (optional RefuelRequest, errorCodes `['400','404','409']`, CatalogEntry.emptyWeightKg). Adjusted where the model legitimately shifts numbers: landing-fuel assertions in `lib/sim/engine.test.ts` and `e2e/actions.spec.ts` now use the weighted closed form; the e2e "return leg unfuelable" scenario is reworked — under weight-proportional burn a full tank covers the EDDF↔LEZL round trip (the plane lightens as it flies), so the 409 insufficient-fuel assertion moves to the SECOND outbound after landing back with a partial tank
 - e2e (`right-pane.spec.ts`): new test — fly the longest hub leg on a full tank, load a package back to the hub at the far end, click the row "Refuel" and assert via the endpoint's own response snapshot that cash drops by exactly L×price and fuel rises by exactly L (L from the mirrored closed form); also asserts the market button label is "Refuel to full". `e2e/api.spec.ts` path list unchanged
 - Verified: `tsc --noEmit` clean; unit suite green locally; e2e not run locally by design — CI verifies against an isolated stack
 - **Fix (CI run #40): forFlight refuel leaves an exactly-feasible tank, and the new e2e's premise corrected.** The right-pane e2e picked the dataset's absolute farthest airport from EDDF — UNNT at ~4803 km, whose leg needs ~6955 L > the 6300 L tank (max range from empty is ~4436 km) — so the full-tank fly rightly 409'd; `farthestToHub` becomes `farthestFlyableToHub`, picking the farthest airport whose leg still fits a full tank (UWUU, ~3195 km). Server hardening in the same area: forFlight now sets fuel to EXACTLY `requiredFuelFor(...)` instead of `fuel + liters` — that sum is not guaranteed ≥ R in IEEE754 (`f + fl(R − f)` can round a hair below), and flyPlane's strict comparison would then 409 on an otherwise-feasible leg; cost math unchanged (still the added liters × price). New unit regression test: forFlight on an empty-ish tank → immediate `flyPlane` to the package destination succeeds
 - **E2e flake hardening (runs #36/#41): full-core-loop Load/Fly precondition races** — test mechanics only, no app code changes. Two independent races in `e2e/actions.spec.ts`: (1) the Fly click fires its POST asynchronously (`runAction` is fire-and-forget from the test's view), so the immediate `getState` could race ahead of it and still see status 'available' — now an `expect.poll` waits until the server shows 'flying' with the expected destIcao before proceeding; (2) `flyHomeViaApi` made its repositioning decision from a snapshot taken BEFORE waiting for a leftover in-flight leg to land — while flying, locationIcao stays at the departure airport, so a plane that landed away from home was still believed to be home and never repositioned (run #41 retry: starter stranded at EDFH) — state is now re-read after landing; plus an explicit server-side precondition poll (starter grounded at the package origin) before clicking Load
 ## v0.15.1 — 2026-09-19 11:04
 - **Right pane widened, "On board" wrapping fixed (ISS-004).** The 3-pane shell grid (`app/globals.css` `.app-shell`) moves from `300px / 1fr / 320px` to `280px / 1fr / 360px` — the map column absorbs the delta (MapLibre sizes itself from its container, no JS change). Three wrap offenders in the right pane's "On board" blocks are fixed:
  - In-flight leg header (`components/RightPane.tsx`, `.contract-route` span): the class already had `white-space: nowrap; overflow: hidden; text-overflow: ellipsis`, but as a flex item with default `min-width: auto` it could not shrink below its full text width, so long routes (e.g. "Frankfurt → Madrid–Barajas") overflowed instead of ellipsizing — `.contract-route` now has `min-width: 0`
  - Cargo-row buttons ("Fly to {dest}" / "Abandon −€X" in `.contract-main`): labels wrapped mid-text at the old width — `.pane-btn` now has `white-space: nowrap`
  - Cargo sub-line route span had no white-space rule and wrapped mid-route — it now carries the existing `contract-route` class (nowrap + ellipsis)
 - **Left pane sanity-checked at its new 280px**: fleet-row location span (`.plane-loc`) already had nowrap+ellipsis but lacked `min-width: 0`, so a long in-flight leg would have overflowed instead of truncating — same one-line guard added. Fuel/loadout spans are short fixed strings and need no guard
 - Verified: `tsc --noEmit` clean; unit suite **238/238** green locally (no lib changes); e2e not run locally by design — CI verifies against an isolated stack
 - **Unrelated test-stability fix included on this branch to unblock the pipeline** (`e2e/map-interactions.spec.ts`, no app changes): the mid-flight marker click now targets the plane's RENDERED position — it polls up to ~5 s for the rendered feature via `window.__flightMap.queryRenderedFeatures` on layers `planes-flying`/`planes-grounded` and projects that feature's coordinates, instead of fetching a fresh `/api/state`. With the sim paused the server position is static, but the map renders from its own ~1 s poll — right after the freeze confirmation the last rendered frame can still be up to one poll interval stale (tens of px at scale 1000 on EDDF→LEMD), so a click projected from a fresh fetch misses the small circle layer: the render-lag race that flaked CI run #37. Pause + freeze confirmation, popup assertions and resume are unchanged
 ## v0.15.0 — 2026-09-19 09:35
 - **Hover visualization from the side panels (ISS-002).** Hovering a fleet row in the left pane, an "On board" block (including its cargo rows) or an open-package row in the right pane now highlights the matching object on the map. The shared `HoverTarget` type (`components/hoverTypes.ts`: `{kind:'plane', id}` | `{kind:'package', originIcao, destIcao}`) is owned by the shell as a single `useState` and prop-drilled down — panes report via an `onHover` callback, `<Map>` consumes it. No React contexts introduced; the established prop-drilling pattern is kept
 - **Three top-most highlight layers** (`components/Map.tsx`, added inside idempotent `ensureLayers()` so they survive every `setStyle`): `planes-highlight` (circle over both plane layers, filter `['==',['get','id'],<planeId>]`, r=10, #38bdf8 fill + white stroke), `routes-highlight` (line over `routes-legs`, filter on the leg's `planeId`, width 6, #ef4444) and `airports-highlight` (circle ring over `airports-circles`, filter matching the hovered package's two ICAOs via `['any', …]`, r=8 stroke-only). All start filtered to match nothing — an empty-string sentinel no feature can have. Consumption follows the existing ref + effect pattern: a `[hovered]` effect calls `map.setFilter(...)` on the three layers (guarded by `getLayer`), and `ensureLayers` re-applies the current filter at its end so a hover outliving a style switch stays highlighted
@@ -5,7 +5,11 @@ import { eq } from 'drizzle-orm';
 import { afterAll, beforeAll, describe, expect, it } from 'vitest';
 import * as schema from '@/lib/db/schema';
 import { getGameDb } from '@/lib/db/client';
 import { loadAirportsGeoJson } from '@/lib/airports';
 import { haversineKm } from '@/lib/geo';
 import { requiredFuelFor } from '@/lib/sim/movement';
 import { FUEL_PRICE_PER_L, PLANE_TYPES } from '@/lib/game/catalog';
 import { HUB_ICAO } from '@/lib/game/seed';
 import { POST } from './route';
 let dir: string;
@@ -22,7 +26,15 @@ afterAll(async () => {
  await fs.rm(dir, { recursive: true, force: true });
 });
-const post = (planeId: string) => POST(new Request(`http://localhost/api/planes/${planeId}/refuel`), { params: Promise.resolve({ planeId }) });
+const post = (planeId: string, body?: unknown) =>
  POST(
    new Request(`http://localhost/api/planes/${planeId}/refuel`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: body === undefined ? undefined : JSON.stringify(body),
    }),
    { params: Promise.resolve({ planeId }) },
  );
 describe('POST /api/planes/:planeId/refuel', () => {
  it('rejects an unknown id with 404', async () => {
@@ -74,4 +86,76 @@ describe('POST /api/planes/:planeId/refuel', () => {
    expect(res.status).toBe(409);
    expect(((await res.json()) as { error: string }).error).toMatch(/insufficient funds/i);
  });
  it('accepts an explicit {mode:"full"} body exactly like no body', async () => {
    const { db } = await getGameDb();
    await db.update(schema.account).set({ cash: 50_000 }); // previous test left the account poor
    await db.update(schema.planes).set({ fuel: 1_000 }).where(eq(schema.planes.id, 'plane-starter'));
    const res = await post('plane-starter', { mode: 'full' });
    expect(res.status).toBe(200);
    const body = (await res.json()) as { planes: Array<{ id: string; fuel: number }> };
    expect(body.planes.find((p) => p.id === 'plane-starter')!.fuel).toBe(PLANE_TYPES.atr72.maxFuel);
  });
  it('rejects an unknown mode with 400', async () => {
    const res = await post('plane-starter', { mode: 'half' });
    expect(res.status).toBe(400);
    expect(((await res.json()) as { error: string }).error).toMatch(/mode/);
  });
  it('rejects forFlight without a packageId with 400', async () => {
    const res = await post('plane-starter', { mode: 'forFlight' });
    expect(res.status).toBe(400);
    expect(((await res.json()) as { error: string }).error).toMatch(/packageId/);
  });
  it('rejects an unknown body field with 400', async () => {
    const res = await post('plane-starter', { liters: 100 });
    expect(res.status).toBe(400);
    expect(((await res.json()) as { error: string }).error).toMatch(/unknown field/);
  });
  it('rejects invalid JSON with 400', async () => {
    const res = await POST(
      new Request(`http://localhost/api/planes/plane-starter/refuel`, { method: 'POST', body: '{nope' }),
      { params: Promise.resolve({ planeId: 'plane-starter' }) },
    );
    expect(res.status).toBe(400);
  });
  it('forFlight tops up exactly the liters needed for the loaded package leg', async () => {
    const { db } = await getGameDb();
    await db.update(schema.account).set({ cash: 50_000 });
    // A loaded EDDF → LEMD package on the starter (direct row — loadPackage is covered in actions tests).
    await db.insert(schema.packages).values({
      id: 'p-ff-api', originIcao: HUB_ICAO, destIcao: 'LEMD', reward: 1_000, cargoType: 'Mail', cargoCount: 4,
      deadlineSimTime: Date.now() + 24 * 3_600_000, status: 'loaded', planeId: 'plane-starter', createdSimTime: Date.now(),
    });
    const fc = await loadAirportsGeoJson();
    const from = fc.features.find((f) => f.properties.icao === HUB_ICAO)!.properties;
    const to = fc.features.find((f) => f.properties.icao === 'LEMD')!.properties;
    const km = haversineKm(from.lat, from.lon, to.lat, to.lon);
    const type = PLANE_TYPES.atr72;
    const required = requiredFuelFor(type.burnPerKm, type.emptyWeightKg, type.maxFuel, km);
    const startFuel = Math.round(required / 2); // partial tank so L > 0
    await db.update(schema.planes).set({ fuel: startFuel }).where(eq(schema.planes.id, 'plane-starter'));
    const cashBefore = (await db.select().from(schema.account))[0].cash;
    const res = await post('plane-starter', { mode: 'forFlight', packageId: 'p-ff-api' });
    expect(res.status).toBe(200);
    const body = (await res.json()) as {
      account: { cash: number };
      planes: Array<{ id: string; fuel: number }>;
    };
    const cost = Math.round((required - startFuel) * FUEL_PRICE_PER_L * 100) / 100;
    expect(body.account.cash).toBeCloseTo(cashBefore - cost, 6);
    expect(body.planes.find((p) => p.id === 'plane-starter')!.fuel).toBeCloseTo(required, 6);
    // Clean up the test package.
    await db.delete(schema.packages).where(eq(schema.packages.id, 'p-ff-api'));
  });
 });
@@ -1,11 +1,47 @@
 import { performAction, refuelPlane } from '@/lib/game/actions';
-// POST /api/planes/:planeId/refuel (v0.8.0) — no body. Fills a grounded plane to
+// POST /api/planes/:planeId/refuel (v0.8.0; optional body v0.16.0) — fills a grounded
-// maxFuel at the fuel price per missing liter; deducts the cost from cash. 404
+// plane at the fuel price per added liter and deducts the cost from cash. The body is
-// unknown id; 409 if the plane is flying or cash is insufficient. On success
+// OPTIONAL: no body, {} or {mode:'full'} fill to maxFuel (the original behavior);
-// returns the full state snapshot (fuel back to max, cash reduced by the cost).
+// {mode:'forFlight', packageId} adds just enough for that loaded package's destination
 // leg. 400 bad body (unknown field, unknown mode, forFlight without packageId); 404
 // unknown plane/package id; 409 if the plane is flying, the package isn't loaded on it
 // (or is expired), the leg doesn't fit a full tank, or cash is insufficient. On success
 // returns the full state snapshot (fuel raised by exactly the added liters).
-export async function POST(_req: Request, ctx: { params: Promise<{ planeId: string }> }) {
+export async function POST(req: Request, ctx: { params: Promise<{ planeId: string }> }) {
  const { planeId } = await ctx.params;
-  return performAction((inst) => refuelPlane(inst, planeId));
+
  let body: unknown;
  try {
    const text = await req.text();
    body = text ? JSON.parse(text) : {};
  } catch {
    return Response.json({ error: 'invalid JSON body' }, { status: 400 });
  }
  if (typeof body !== 'object' || body === null || Array.isArray(body)) {
    return Response.json({ error: 'body must be a JSON object' }, { status: 400 });
  }
  const input = body as Record<string, unknown>;
  for (const key of Object.keys(input)) {
    if (key !== 'mode' && key !== 'packageId') {
      return Response.json({ error: `unknown field "${key}"` }, { status: 400 });
    }
  }
  const mode = input.mode ?? 'full';
  if (mode !== 'full' && mode !== 'forFlight') {
    return Response.json({ error: 'mode must be "full" or "forFlight"' }, { status: 400 });
  }
  let packageId: string | undefined;
  if (input.packageId !== undefined) {
    if (typeof input.packageId !== 'string' || input.packageId.length === 0) {
      return Response.json({ error: 'packageId must be a non-empty string' }, { status: 400 });
    }
    packageId = input.packageId;
  }
  if (mode === 'forFlight' && !packageId) {
    return Response.json({ error: 'packageId is required when mode is "forFlight"' }, { status: 400 });
  }
  return performAction((inst) => refuelPlane(inst, planeId, { mode, packageId }));
 }
@@ -71,7 +71,7 @@ body {
 /* v0.9.0 — single-screen 3-pane shell: left Assets / center map / right Jobs & Market */
 .app-shell {
  display: grid;
-  grid-template-columns: 300px minmax(0, 1fr) 320px;
+  grid-template-columns: 280px minmax(0, 1fr) 360px;
  height: 100%;
 }
@@ -201,6 +201,7 @@ body {
 }
 .plane-loc {
  min-width: 0;
  overflow: hidden;
  text-overflow: ellipsis;
  white-space: nowrap;
@@ -265,6 +266,7 @@ body {
 }
 .contract-route {
  min-width: 0;
  font-weight: 600;
  color: #f1f5f9;
  overflow: hidden;
@@ -284,6 +286,7 @@ body {
 .pane-btn {
  flex-shrink: 0;
  white-space: nowrap;
  font-size: 12px;
  padding: 3px 10px;
  border-radius: 4px;
@@ -5,6 +5,7 @@ import type { PlaneState, StateSnapshot } from '@/lib/game/state';
 import { PLANE_TYPES } from '@/lib/game/catalog';
 import { formatCash, formatFuel, formatSimClock } from '@/lib/format';
 import { TIME_SCALES, scaleToSlider, sliderToScale } from '@/lib/timeScale';
 import { useSimClock } from '@/lib/useSimClock';
 import type { HoverTarget } from './hoverTypes';
 interface LeftPaneProps {
@@ -167,6 +168,12 @@ export default function LeftPane({ state, loading, error, onRefresh, onHover }:
  const displayedScale = pendingScale ?? timeScale;
  // ISS-007: the clock ticks client-side between polls, re-syncing to server truth on every
  // snapshot. Fed with EFFECTIVE controls so a scale drag / pause click takes effect immediately,
  // not when the confirming snapshot lands. Only the sim-clock paragraph uses this — deadline and
  // penalty previews stay snapshot-based (deterministic against the server clock).
  const simClockMs = useSimClock(state, { timeScale: displayedScale, paused });
  return (
    <aside data-testid="left-pane" className="pane left-pane">
      <h2 className="pane-title">Assets</h2>
@@ -221,7 +228,7 @@ export default function LeftPane({ state, loading, error, onRefresh, onHover }:
          <section className="pane-section">
            <h3 className="pane-heading">Time</h3>
            <p data-testid="sim-clock" className="sim-clock">
-              {formatSimClock(state.simState.clockMs)}
+              {simClockMs !== null && formatSimClock(simClockMs)}
              {paused ? ' (paused)' : ''}
            </p>
            <div className="time-controls">
@@ -273,6 +273,15 @@ export default function RightPane({ state, loading, applySnapshot, onHover }: Ri
                  return (
                    <div key={pkg.id} data-testid={`onboard-package-${pkg.id}`} className="contract-row">
                      <div className="contract-main">
                        <button
                          type="button"
                          data-testid={`refuel-for-${pkg.id}`}
                          className="pane-btn"
                          disabled={busy || plane.status !== 'available'}
                          onClick={() => void runAction(`/api/planes/${plane.id}/refuel`, { mode: 'forFlight', packageId: pkg.id })}
                        >
                          Refuel
                        </button>
                        <button
                          type="button"
                          data-testid={`fly-to-${pkg.id}`}
@@ -294,7 +303,7 @@ export default function RightPane({ state, loading, applySnapshot, onHover }: Ri
                        </button>
                      </div>
                      <div className="contract-sub">
-                        <span>{pkg.originName} → {pkg.destName}</span>
+                        <span className="contract-route">{pkg.originName} → {pkg.destName}</span>
                        <span>{formatCash(pkg.reward)}</span>
                        {pkg.status === 'expired' ? (
                          <span data-testid={`onboard-expired-${pkg.id}`}>expired</span>
@@ -405,7 +414,7 @@ export default function RightPane({ state, loading, applySnapshot, onHover }: Ri
              if (refuelPlane) void runAction(`/api/planes/${refuelPlane.id}/refuel`);
            }}
          >
-            Refuel
+            Refuel to full
          </button>
        </div>
      </section>
@@ -8,7 +8,7 @@ import type { PackageState, PlaneState, StateSnapshot } from '@/lib/game/state';
 // directly on the single eligible plane, or shows a picker when several qualify.
 const CATALOG = [
-  { model: 'atr72', label: 'ATR 72-600', price: 200_000, maxFuel: 6300, burnPerKm: 1.75, speedKmh: 510, capacity: 6 },
+  { model: 'atr72', label: 'ATR 72-600', price: 200_000, maxFuel: 6300, burnPerKm: 1.75, emptyWeightKg: 9_300, speedKmh: 510, capacity: 6 },
 ];
 function plane(over: Partial<PlaneState> & Pick<PlaneState, 'id'>): PlaneState {
@@ -10,14 +10,23 @@ import { expect, test } from '@playwright/test';
 const SCALE = 1000; // fastest sim speed (v0.14.0 ladder top) — keeps flights to seconds of real time
 const HUB = 'EDDF'; // Frankfurt Main — the seeded starter plane's home base (lib/game/seed.ts)
-const FAR = 'LEZL'; // Seville — one-way burn 3174 L > half tank, so the return leg is unfuelable
+const FAR = 'LEZL'; // Seville — a long leg: under the v0.16.0 weighted model a full tank covers the
                    // round trip, but the return leaves too little for another outbound
-// Mirrors lib/sim/movement.ts + lib/game/catalog.ts (atr72).
+// Mirrors lib/sim/movement.ts (v0.16.0 weight-proportional burn) + lib/game/catalog.ts (atr72).
-const BURN_PER_KM = 1.75;
+const FUEL_DENSITY_KG_PER_L = 0.8; // Jet-A1 density — must match FUEL_DENSITY_KG_PER_L in movement.ts
-const FUEL_PRICE_PER_L = 0.8;
+const FUEL_PRICE_PER_L = 0.8; // must match catalog.ts
 const REP_BASE = 1; // lib/sim/engine.ts
 const REP_PER_KM = 0.0005;
 // Fuel remaining after distanceKm from startFuel — closed form of dF/dx = −k(We + ρF),
 // k calibrated so a full tank burns exactly burnPerKm (mirrors fuelAtWeighted).
 function fuelAfter(startFuel: number, burnPerKm: number, emptyWeightKg: number, maxFuel: number, distanceKm: number): number {
  const k = burnPerKm / (emptyWeightKg + FUEL_DENSITY_KG_PER_L * maxFuel);
  const rho = FUEL_DENSITY_KG_PER_L;
  return Math.max(0, (startFuel + emptyWeightKg / rho) * Math.exp(-k * rho * distanceKm) - emptyWeightKg / rho);
 }
 // Mirrors lib/game/penalty.ts — the exact abandon penalty at a given game clock.
 function penaltyFor(reward: number, createdSimTime: number, deadlineSimTime: number, clockMs: number): number {
  const span = deadlineSimTime - createdSimTime;
@@ -33,6 +42,7 @@ interface StateBody {
    id: string; originIcao: string; destIcao: string; reward: number; cargoType: string; cargoCount: number;
    deadlineSimTime: number; status: 'open' | 'loaded' | 'delivered' | 'expired' | 'abandoned'; planeId: string | null; createdSimTime: number;
  }>;
  catalog: Array<{ model: string; burnPerKm: number; emptyWeightKg: number; maxFuel: number }>; // v0.16.0 weighted burn inputs
 }
 async function getState(page: Page): Promise<StateBody> {
@@ -90,15 +100,21 @@ test.describe.configure({ mode: 'serial' }); // shared live DB — order matters
 // (repositioning needs no package — v0.12.0 manual flight), and abandon any leftover cargo so
 // exact cash/rep assertions start from a clean baseline even after an interrupted previous run.
 async function flyHomeViaApi(page: Page): Promise<void> {
-  const s0 = await getState(page);
+  let s = await getState(page);
-  const plane = s0.planes.find((p) => p.id === 'plane-starter')!;
+  let plane = s.planes.find((p) => p.id === 'plane-starter')!;
  if (plane.status === 'flying' || plane.locationIcao !== HUB) {
    // Fast-forward any leftover leg / repositioning flight (~20 s real time worst case at 1000×).
    await setScale(page, SCALE);
  }
  if (plane.status === 'flying') {
-    // Let the in-flight leg finish before repositioning.
+    // Let the in-flight leg finish before repositioning. While flying, locationIcao stays at the
    // DEPARTURE airport, so the pre-landing snapshot can't tell us where the plane ends up — re-read
    // state after landing before deciding whether a repositioning flight is needed (run #41 retry: a
    // leftover EDDF→EDFH leg landed away from home but the helper still believed it was home and
    // skipped the fly-home).
    await expect.poll(async () => ((await getState(page)).planes.find((p) => p.id === 'plane-starter')!.status), { timeout: 240_000 }).toBe('available');
    s = await getState(page);
    plane = s.planes.find((p) => p.id === 'plane-starter')!;
  }
  if (plane.locationIcao !== HUB) {
    const res = await page.request.post(`/api/planes/${plane.id}/fly`, { data: { destIcao: HUB } });
@@ -133,6 +149,14 @@ test('full core loop via UI: load → fly to destination → exact reward + rep
  expect(pkg.originIcao).toBe(HUB);
  expect(pkg.destIcao).toBe(nearest.icao);
  // Precondition (server truth) before clicking Load: the starter must be grounded at the package's
  // origin — that is exactly what makes it load-eligible, and a stale pane snapshot can't prove it.
  await expect.poll(async () => {
    const b = await getState(page);
    const p = b.planes.find((x) => x.id === 'plane-starter')!;
    return p.status === 'available' && p.locationIcao === pkg.originIcao;
  }, { timeout: 30_000, message: 'waiting for plane-starter to be grounded at the package origin (self-heal incomplete?)' }).toBe(true);
  // LOAD via the UI: exactly one eligible plane (the starter at EDDF) → direct button.
  await page.goto('/');
  const loadBtn = page.getByTestId(`load-${pkg.id}`);
@@ -149,10 +173,17 @@ test('full core loop via UI: load → fly to destination → exact reward + rep
  await expect(flyBtn).toBeEnabled();
  await flyBtn.click();
  let s = await getState(page);
  const planeId = 'plane-starter';
-  expect(s.planes.find((p) => p.id === planeId)!.status).toBe('flying');
+  // The click fires the fly POST asynchronously (runAction is fire-and-forget from the test's view),
-  expect(s.planes.find((p) => p.id === planeId)!.destIcao).toBe(nearest.icao);
+  // so a getState issued immediately can race ahead of it and still see 'available' — poll until the
  // fly actually took effect on the server (the run #36/#41 flake).
  await expect.poll(async () => {
    const b = await getState(page);
    const p = b.planes.find((x) => x.id === planeId)!;
    return p.status === 'flying' && p.destIcao === nearest.icao;
  }, { timeout: 15_000, message: 'waiting for the fly click to take effect (status "flying" + dest set)' }).toBe(true);
  let s = await getState(page);
  // Fast-forward to arrival (a few seconds of real time at 1000×).
  await setScale(page, SCALE);
@@ -174,8 +205,12 @@ test('full core loop via UI: load → fly to destination → exact reward + rep
  const repGain = Math.round((REP_BASE + REP_PER_KM * exactKm) * 100) / 100;
  expect(s.account.reputation).toBeCloseTo(Math.round((before.account.reputation + repGain) * 100) / 100, 9);
-  // Fuel burned exactly burnPerKm × km (analytic movement — no rounding drift).
+  // Fuel burned per the v0.16.0 weight-proportional model (closed form — no rounding drift).
-  expect(landed.fuel).toBeCloseTo(Math.max(0, before.planes.find((p) => p.id === planeId)!.fuel - BURN_PER_KM * exactKm), 6);
+  const entry = before.catalog.find((e) => e.model === 'atr72')!;
  expect(landed.fuel).toBeCloseTo(
    fuelAfter(before.planes.find((p) => p.id === planeId)!.fuel, entry.burnPerKm, entry.emptyWeightKg, entry.maxFuel, exactKm),
    6,
  );
  // Refuel via the API: cost = (maxFuel − fuel) × FUEL_PRICE_PER_L, deducted exactly.
  const refuelRes = await page.request.post(`/api/planes/${planeId}/refuel`);
@@ -317,12 +352,14 @@ test('load and fly validation paths (404 / 409 / 400)', async ({ page }) => {
  expect(res.ok()).toBeTruthy();
  await expect.poll(async () => ((await getState(page)).planes.find((p) => p.id === 'plane-starter')!.locationIcao), { timeout: 120_000 }).toBe(HUB);
-  // Insufficient fuel: a full-tank one-way burn of > half the tank makes the return leg unfuelable.
+  // Insufficient fuel (v0.16.0 weighted burn): a full tank covers the FAR round trip —
  // the plane gets lighter as fuel burns off, so both legs fit — but landing back at the
  // hub leaves too little for ANOTHER long leg: the second outbound must 409.
  const s0 = await getState(page);
  const starter = s0.planes.find((p) => p.id === 'plane-starter')!;
  expect(starter.locationIcao).toBe(HUB); // landed back at the hub from the hop above
  if (starter.fuel < starter.maxFuel) {
-    await page.request.post('/api/planes/plane-starter/refuel'); // ensure a full tank for the long leg
+    await page.request.post('/api/planes/plane-starter/refuel'); // ensure a full tank for the long legs
  }
  const farRes = await page.request.post('/api/planes/plane-starter/fly', { data: { destIcao: FAR } });
  expect(farRes.ok()).toBeTruthy();
@@ -332,16 +369,18 @@ test('load and fly validation paths (404 / 409 / 400)', async ({ page }) => {
  const sFar = await getState(page);
  const atFar = sFar.planes.find((p) => p.id === 'plane-starter')!;
  expect(atFar.locationIcao).toBe(FAR);
-  // The return leg needs the same burn as the outbound — more than what's left.
+  // The return leg fits: the weighted burn over it is less than what's left in the tank.
  const backRes = await page.request.post('/api/planes/plane-starter/fly', { data: { destIcao: HUB } });
-  expect(backRes.status()).toBe(409);
+  expect(backRes.ok()).toBeTruthy();
  expect(((await backRes.json()) as { error: string }).error).toMatch(/insufficient fuel/i);
  // Restore: refuel + fly home.
  await page.request.post('/api/planes/plane-starter/refuel');
  const homeRes = await page.request.post('/api/planes/plane-starter/fly', { data: { destIcao: HUB } });
  expect(homeRes.ok()).toBeTruthy();
  await expect.poll(async () => ((await getState(page)).planes.find((p) => p.id === 'plane-starter')!.locationIcao), { timeout: 240_000 }).toBe(HUB);
  // …but the tank is now too light for another FAR leg.
  const againFar = await page.request.post('/api/planes/plane-starter/fly', { data: { destIcao: FAR } });
  expect(againFar.status()).toBe(409);
  expect(((await againFar.json()) as { error: string }).error).toMatch(/insufficient fuel/i);
  // Restore: refuel (the plane is already home).
  await page.request.post('/api/planes/plane-starter/refuel');
 });
 // Great-circle distance in km — mirrors lib/geo.ts (same formula, same R).
@@ -266,20 +266,35 @@ test('plane markers move while flying and the plane popup shows status + route',
    }, { timeout: 15_000, message: 'waiting for the paused clock to freeze the plane position' })
    .toBe(true);
-  // Fetch + project in one evaluate — with the sim paused above, the server's analytic
+  // Click the RENDERED marker position, not a fresh /api/state fetch. With the sim paused
-  // position is static, so the projected point matches what the map renders.
+  // above the server's analytic position is static — but the map renders from its own ~1 s
  // poll, so right after the freeze confirmation the last rendered frame can still be up to
  // one poll interval stale (tens of px at scale 1000 on this leg) and a click projected
  // from a fresh fetch misses the small circle layer (CI run #37). Poll for the plane's
  // rendered feature instead and project ITS coordinates — exactly what the map draws.
  // Find + project in one evaluate so nothing can change between the two steps.
  const pt = await page.evaluate(async () => {
    const m = (window as any).__flightMap;
    if (!m) return null;
-    const res = await fetch('/api/state', { cache: 'no-store' });
+    const deadline = Date.now() + 5_000;
-    const body = (await res.json()) as StateBody;
+    for (;;) {
-    const p = body.planes.find((x) => x.id === 'plane-starter');
+      let feats: Array<{ properties?: Record<string, unknown>; geometry?: { coordinates: number[] } }> = [];
-    if (!p || p.status !== 'flying') return null;
+      try {
-    const projected = m.project([p.lon, p.lat]);
+        feats = m.queryRenderedFeatures(undefined, { layers: ['planes-flying', 'planes-grounded'] });
-    const rect = m.getContainer().getBoundingClientRect();
+      } catch {
-    return { x: rect.left + projected.x, y: rect.top + projected.y };
+        // map not ready yet — keep polling
      }
      const f = feats.find((x) => x.properties?.id === 'plane-starter');
      if (f && f.geometry) {
        const projected = m.project(f.geometry.coordinates);
        const rect = m.getContainer().getBoundingClientRect();
        return { x: rect.left + projected.x, y: rect.top + projected.y };
      }
      if (Date.now() >= deadline) return null;
      await new Promise((r) => setTimeout(r, 100));
    }
  });
-  expect(pt).not.toBeNull(); // the ~10 s window at scale 1000 is still open this early after departure
+  expect(pt, 'plane marker not rendered after pause').not.toBeNull();
  await page.mouse.click(pt!.x, pt!.y);
  const popup = page.getByTestId('plane-popup');
@@ -4,6 +4,8 @@ import { test, expect, type Page } from '@playwright/test';
 // The panes render from the shell's single /api/state poll (lib/useGameState.ts); time
 // controls POST to /api/sim and refetch immediately, so UI assertions settle within a tick.
 const SCALE = 1000; // fastest sim speed — top of the v0.14.0 ladder (same convention as e2e/sim.spec.ts)
 interface SimState {
  clockMs: number;
  timeScale: number;
@@ -104,6 +106,40 @@ test('time controls: pause freezes the sim and the ladder slider sets timeScale'
  expect(after.simState.paused).toBe(false);
 });
 test('sim clock ticks smoothly between polls — seconds advance without waiting for a snapshot (ISS-007)', async ({ page }) => {
  await page.goto('/');
  const clock = page.getByTestId('sim-clock');
  await expect(clock).toBeVisible({ timeout: 15_000 });
  // Fastest scale so game seconds move visibly inside the sampling window.
  const post = await page.request.post('/api/sim', { data: { timeScale: SCALE, paused: false } });
  expect(post.status()).toBe(200);
  // "YYYY-MM-DD HH:MM:SS UTC" → epoch ms (UTC). While running there is no "(paused)" suffix.
  const sample = async () => {
    const text = ((await clock.textContent()) ?? '').trim();
    expect(text, `clock format: ${text}`).toMatch(/^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2} UTC$/);
    return Date.parse(text.replace(' ', 'T').replace(' UTC', 'Z'));
  };
  // Three samples ~1.3 s apart real time: at scale 1000 each gap is ≈1300 game seconds, so the
  // displayed clock must strictly advance between CONSECUTIVE samples — with the old poll-only
  // rendering a sample pair could straddle zero snapshot updates and show no change at all.
  const t0 = await sample();
  await new Promise((r) => setTimeout(r, 1_300));
  const t1 = await sample();
  await new Promise((r) => setTimeout(r, 1_300));
  const t2 = await sample();
  expect(t1).toBeGreaterThan(t0);
  expect(t2).toBeGreaterThan(t1);
  // Sanity: ~2.6 s real × 1000 ≈ 2.6 M game ms — generous bounds keep slow CI boxes safe while
  // still catching a frozen or wildly mis-scaled clock.
  const total = t2 - t0;
  expect(total).toBeGreaterThanOrEqual(1_000_000);
  expect(total).toBeLessThanOrEqual(6_000_000);
 });
 test('slider commit keeps the chosen scale on screen until confirmed — no snap-back (ISS-001)', async ({ page }) => {
  test.setTimeout(60_000);
  await page.goto('/');
@@ -38,6 +38,7 @@ interface CatalogEntry {
  price: number;
  maxFuel: number;
  burnPerKm: number;
  emptyWeightKg: number; // v0.16.0 weighted burn input
  speedKmh: number;
  capacity: number;
 }
@@ -114,6 +115,39 @@ async function nearestToHub(page: Page): Promise<{ icao: string; lat: number; lo
  return nearest;
 }
 // Farthest airport from EDDF whose leg still FITS A FULL TANK — the longest flyable leg (v0.16.0
 // refuel-for-flight test). The dataset's absolute farthest can exceed the aircraft's range (UNNT is
 // ~4803 km out and needs ~6955 L > the 6300 L tank), so a full-tank fly there would rightly 409;
 // this test wants a long-but-flyable leg instead.
 async function farthestFlyableToHub(
  page: Page,
  entry: CatalogEntry,
 ): Promise<{ icao: string; lat: number; lon: number; hubLat: number; hubLon: number }> {
  const fc = (await (await page.request.get('/api/airports')).json()) as {
    features: Array<{ properties: { icao: string; lat: number; lon: number } }>;
  };
  const hub = fc.features.find((f) => f.properties.icao === HUB)!.properties;
  let farthest: { icao: string; lat: number; lon: number; d: number } | null = null;
  for (const f of fc.features) {
    if (f.properties.icao === HUB) continue;
    const d = haversineKm(hub.lat, hub.lon, f.properties.lat, f.properties.lon);
    if (requiredFuelFor(entry.burnPerKm, entry.emptyWeightKg, entry.maxFuel, d) > entry.maxFuel) continue; // beyond range
    if (!farthest || d > farthest.d) {
      farthest = { icao: f.properties.icao, lat: f.properties.lat, lon: f.properties.lon, d };
    }
  }
  if (!farthest) throw new Error('no full-tank-flyable airport found in the dataset');
  return { ...farthest, hubLat: hub.lat, hubLon: hub.lon };
 }
 // Mirrors lib/sim/movement.ts (v0.16.0): fuel required to cover distanceKm arriving empty —
 // closed form of the weight-proportional burn model, k calibrated so a full tank burns burnPerKm.
 const FUEL_DENSITY_KG_PER_L = 0.8; // must match FUEL_DENSITY_KG_PER_L in lib/sim/movement.ts
 function requiredFuelFor(burnPerKm: number, emptyWeightKg: number, maxFuel: number, distanceKm: number): number {
  const k = burnPerKm / (emptyWeightKg + FUEL_DENSITY_KG_PER_L * maxFuel);
  return (emptyWeightKg / FUEL_DENSITY_KG_PER_L) * (Math.exp(k * FUEL_DENSITY_KG_PER_L * distanceKm) - 1);
 }
 // Test hook (FLIGHT_TEST_HOOKS=1): create an open package on a known route.
 async function createPackage(page: Page, fromIcao: string, toIcao: string, deadlineOffsetMs?: number): Promise<PackageState> {
  const created = await page.request.post('/api/test/create-package', {
@@ -307,3 +341,74 @@ test('market buy/sell/refuel render with previews from the catalog in /api/state
    expect(after.planes.find((p) => p.id === 'plane-starter')!.fuel).toBe(starter.maxFuel);
  }
 });
 test('on-board row Refuel tops up just enough for the package leg; market button says "Refuel to full"', async ({ page }) => {
  test.setTimeout(300_000); // self-heal + one long flight each way at scale 1000
  await flyHomeViaApi(page);
  const body = await getState(page);
  const entry = body.catalog.find((e) => e.model === 'atr72')!;
  // Deterministic baseline: a full tank.
  expect((await page.request.post('/api/planes/plane-starter/refuel')).status()).toBe(200);
  // Longest FLYABLE leg from the hub (fits a full tank) — long enough that "just enough" for it
  // exceeds what's left on arrival.
  const farthest = await farthestFlyableToHub(page, entry);
  const pkg1 = await createPackage(page, HUB, farthest.icao, 24 * 3_600_000);
  expect((await page.request.post(`/api/packages/${pkg1.id}/load`, { data: { planeId: 'plane-starter' } })).status()).toBe(200);
  // Fly there (delivers pkg1 on arrival) — the tank is now partial.
  expect((await page.request.post('/api/planes/plane-starter/fly', { data: { destIcao: farthest.icao } })).status()).toBe(200);
  await setScale(page, SCALE);
  await expect
    .poll(async () => {
      const b = await getState(page);
      const p = b.planes.find((x) => x.id === 'plane-starter');
      return !!p && p.status === 'available' && p.locationIcao === farthest.icao;
    }, { timeout: 240_000, message: `waiting for arrival at ${farthest.icao} (scale 1000)` })
    .toBe(true);
  // New work at the far end: a package back to the hub — its leg is exactly what we refuel for.
  const pkg2 = await createPackage(page, farthest.icao, HUB, 24 * 3_600_000);
  expect((await page.request.post(`/api/packages/${pkg2.id}/load`, { data: { planeId: 'plane-starter' } })).status()).toBe(200);
  // Expected "just enough" from the snapshot constants (mirrors requiredFuelFor in lib/sim/movement.ts).
  const pre = await getState(page);
  const fuelBefore = pre.planes.find((p) => p.id === 'plane-starter')!.fuel;
  const cashBefore = pre.account.cash;
  const km = haversineKm(farthest.hubLat, farthest.hubLon, farthest.lat, farthest.lon); // symmetric: hub ↔ far end
  const liters = Math.max(0, requiredFuelFor(entry.burnPerKm, entry.emptyWeightKg, entry.maxFuel, km) - fuelBefore);
  expect(liters).toBeGreaterThan(0); // the long leg genuinely needs more than what's left
  const expectedCost = Math.round(liters * pre.fuelPricePerL * 100) / 100;
  await page.goto('/');
  const refuelBtn = page.getByTestId(`refuel-for-${pkg2.id}`);
  await expect(refuelBtn, 'row Refuel button appears for the loaded package').toBeVisible({ timeout: 15_000 });
  // Capture the endpoint's OWN response — the full post-action snapshot at the action's clock.
  const [res] = await Promise.all([
    page.waitForResponse((r) => r.url().includes(`/api/planes/plane-starter/refuel`), { timeout: 15_000 }),
    refuelBtn.click(),
  ]);
  expect(res.status()).toBe(200);
  const post = (await res.json()) as StateBody;
  // Cash dropped by exactly L × price and fuel rose by exactly L.
  expect(post.account.cash).toBeCloseTo(cashBefore - expectedCost, 6);
  expect(post.planes.find((p) => p.id === 'plane-starter')!.fuel).toBeCloseTo(fuelBefore + liters, 6);
  // Market row: the fill-up button is labeled "Refuel to full" (testid unchanged).
  await expect(page.getByTestId('market-refuel')).toHaveText('Refuel to full');
  // Restore: fly home — pkg2's destination IS the hub, so it delivers on arrival. The tank holds
  // exactly the leg requirement, so this also proves "just enough" is enough.
  expect((await page.request.post('/api/planes/plane-starter/fly', { data: { destIcao: HUB } })).status()).toBe(200);
  await expect
    .poll(async () => (await getState(page)).planes.find((p) => p.id === 'plane-starter')?.locationIcao === HUB, {
      timeout: 240_000,
      message: 'waiting for plane-starter to land back at the hub',
    })
    .toBe(true);
  // Top the tank back up so later specs start with a full tank.
  expect((await page.request.post('/api/planes/plane-starter/refuel')).status()).toBe(200);
 });
@@ -6,6 +6,8 @@ import { afterAll, beforeAll, describe, expect, it, vi } from 'vitest';
 import { openGameDb, type GameDb } from '@/lib/db/client';
 import * as schema from '@/lib/db/schema';
 import { loadAirportsGeoJson } from '@/lib/airports';
 import { haversineKm } from '@/lib/geo';
 import { requiredFuelFor } from '@/lib/sim/movement';
 import { FUEL_PRICE_PER_L, PLANE_TYPES, SELL_FRACTION } from './catalog';
 import { HUB_ICAO } from './seed';
 import {
@@ -412,4 +414,110 @@ describe('refuelPlane', () => {
    const inst = await freshDb('refuel-unknown.db');
    await expectActionError(refuelPlane(inst, 'ghost'), 404);
  });
  // --- forFlight mode (v0.16.0) ---
  it('forFlight adds exactly the liters needed for the package leg and deducts L × price', async () => {
    const inst = await freshDb('refuel-forflight-ok.db');
    await insertOpenPackage(inst, 'p-ff', { destIcao: 'LEMD' }); // EDDF → LEMD
    await loadPackage(inst, 'p-ff', 'plane-starter');
    const fc = await loadAirportsGeoJson();
    const from = fc.features.find((f) => f.properties.icao === HUB_ICAO)!.properties;
    const to = fc.features.find((f) => f.properties.icao === 'LEMD')!.properties;
    const km = haversineKm(from.lat, from.lon, to.lat, to.lon);
    const type = PLANE_TYPES.atr72;
    const required = requiredFuelFor(type.burnPerKm, type.emptyWeightKg, type.maxFuel, km);
    // Partial tank below the requirement so L > 0.
    const startFuel = Math.round(required / 2);
    await inst.db.update(schema.planes).set({ fuel: startFuel }).where(eq(schema.planes.id, 'plane-starter'));
    const cashBefore = (await inst.db.select().from(schema.account))[0].cash;
    const { cost } = await refuelPlane(inst, 'plane-starter', { mode: 'forFlight', packageId: 'p-ff' });
    expect(cost).toBe(Math.round((required - startFuel) * FUEL_PRICE_PER_L * 100) / 100);
    const plane = (await inst.db.select().from(schema.planes))[0];
    expect(plane.fuel).toBeCloseTo(required, 6); // topped up to exactly the leg requirement
    const account = (await inst.db.select().from(schema.account))[0];
    expect(account.cash).toBeCloseTo(cashBefore - cost, 6);
  });
  it('forFlight leaves an exactly-feasible tank — flyPlane to the package dest succeeds right after', async () => {
    const inst = await freshDb('refuel-ff-flyafter.db');
    await insertOpenPackage(inst, 'p-fa', { destIcao: 'LEMD' }); // EDDF → LEMD
    await loadPackage(inst, 'p-fa', 'plane-starter');
    const fc = await loadAirportsGeoJson();
    const from = fc.features.find((f) => f.properties.icao === HUB_ICAO)!.properties;
    const to = fc.features.find((f) => f.properties.icao === 'LEMD')!.properties;
    const km = haversineKm(from.lat, from.lon, to.lat, to.lon);
    const type = PLANE_TYPES.atr72;
    const required = requiredFuelFor(type.burnPerKm, type.emptyWeightKg, type.maxFuel, km);
    // Empty-ish tank: well below the leg requirement.
    await inst.db.update(schema.planes).set({ fuel: Math.round(required / 4) }).where(eq(schema.planes.id, 'plane-starter'));
    await refuelPlane(inst, 'plane-starter', { mode: 'forFlight', packageId: 'p-fa' });
    // The leg must now be flyable — no epsilon-short 409 (regression guard for the float-exact target).
    await flyPlane(inst, 'plane-starter', 'LEMD');
    const plane = (await inst.db.select().from(schema.planes))[0];
    expect(plane.status).toBe('flying');
    expect(plane.destIcao).toBe('LEMD');
  });
  it('forFlight is a free no-op when the tank already covers the leg', async () => {
    const inst = await freshDb('refuel-forflight-enough.db'); // seeded starter is full at EDDF
    await insertOpenPackage(inst, 'p-ff2', { destIcao: 'LEMD' });
    await loadPackage(inst, 'p-ff2', 'plane-starter');
    const cashBefore = (await inst.db.select().from(schema.account))[0].cash;
    const { cost } = await refuelPlane(inst, 'plane-starter', { mode: 'forFlight', packageId: 'p-ff2' });
    expect(cost).toBe(0);
    const plane = (await inst.db.select().from(schema.planes))[0];
    expect(plane.fuel).toBe(PLANE_TYPES.atr72.maxFuel); // untouched
    expect((await inst.db.select().from(schema.account))[0].cash).toBe(cashBefore);
  });
  it('forFlight rejects a package that is not loaded on this plane with 409', async () => {
    const inst = await freshDb('refuel-ff-open.db'); // open — never loaded
    await insertOpenPackage(inst, 'p-x');
    await expectActionError(refuelPlane(inst, 'plane-starter', { mode: 'forFlight', packageId: 'p-x' }), 409);
    const inst2 = await freshDb('refuel-ff-other.db'); // loaded on ANOTHER plane
    await insertOpenPackage(inst2, 'p-y', { status: 'loaded', planeId: 'plane-someone-else' });
    await expectActionError(refuelPlane(inst2, 'plane-starter', { mode: 'forFlight', packageId: 'p-y' }), 409);
  });
  it('forFlight rejects an expired package with 409', async () => {
    const inst = await freshDb('refuel-ff-expired.db');
    await insertOpenPackage(inst, 'p-z', { status: 'expired', planeId: 'plane-starter' });
    await expectActionError(refuelPlane(inst, 'plane-starter', { mode: 'forFlight', packageId: 'p-z' }), 409);
  });
  it('forFlight rejects an unknown package id with 404', async () => {
    const inst = await freshDb('refuel-ff-unknown.db');
    await expectActionError(refuelPlane(inst, 'plane-starter', { mode: 'forFlight', packageId: 'nope' }), 404);
  });
  it('forFlight rejects a missing packageId with 400', async () => {
    const inst = await freshDb('refuel-ff-nopkg.db');
    await expectActionError(refuelPlane(inst, 'plane-starter', { mode: 'forFlight' }), 400);
  });
  it('forFlight rejects a leg that does not fit even a full tank with 409', async () => {
    const inst = await freshDb('refuel-ff-nofit.db');
    // UNNT (Narsarsuaq, Greenland) ↔ LPPD are ~7670 km apart — far beyond the ATR's range.
    await insertOpenPackage(inst, 'p-far', { destIcao: 'LPPD' });
    await loadPackage(inst, 'p-far', 'plane-starter');
    await inst.db.update(schema.planes).set({ locationIcao: 'UNNT' }).where(eq(schema.planes.id, 'plane-starter'));
    await expectActionError(
      refuelPlane(inst, 'plane-starter', { mode: 'forFlight', packageId: 'p-far' }),
      409,
      /does not fit/i,
    );
  });
 });
@@ -4,6 +4,7 @@ import * as schema from '@/lib/db/schema';
 import { persist, type GameDb } from '@/lib/db/client';
 import { loadAirportsGeoJson } from '@/lib/airports';
 import { haversineKm } from '@/lib/geo';
 import { requiredFuelFor } from '@/lib/sim/movement';
 import { runAction } from '@/lib/sim/engine';
 import { getStateSnapshot } from './state';
 import { FUEL_PRICE_PER_L, PLANE_TYPES, SELL_FRACTION } from './catalog';
@@ -105,9 +106,10 @@ export async function flyPlane(inst: GameDb, planeId: string, destIcao: string):
  const type = PLANE_TYPES[plane.model];
  if (!type) throw new Error(`unknown plane model ${plane.model}`); // → 500, cannot happen for seeded data
  const distanceKm = haversineKm(origin.lat, origin.lon, destFeature.properties.lat, destFeature.properties.lon);
-  const burnL = type.burnPerKm * distanceKm;
+  // Weighted burn model (v0.16.0): the leg needs enough fuel to cover it arriving empty.
-  if (burnL > plane.fuel) {
+  const requiredL = requiredFuelFor(type.burnPerKm, type.emptyWeightKg, type.maxFuel, distanceKm);
-    throw new GameActionError(409, `insufficient fuel: the leg needs ${Math.round(burnL)} L but the plane has ${Math.round(plane.fuel)} L`);
+  if (requiredL > plane.fuel) {
    throw new GameActionError(409, `insufficient fuel: the leg needs ${Math.round(requiredL)} L but the plane has ${Math.round(plane.fuel)} L`);
  }
  // runAction() ticked first, so this is current game time.
@@ -225,8 +227,19 @@ export async function sellPlane(inst: GameDb, planeId: string): Promise<{ payout
 // --- Refuel (POST /api/planes/:planeId/refuel) ---
-// Fill a grounded plane to maxFuel at FUEL_PRICE_PER_L per missing liter.
+// Refuel modes (v0.16.0): 'full' fills the tank to maxFuel; 'forFlight' adds just
-export async function refuelPlane(inst: GameDb, planeId: string): Promise<{ cost: number }> {
+// enough fuel for one loaded package's destination leg — required liters per the
 // weighted burn model, independent of how much is already in the tank.
 export interface RefuelOptions {
  mode?: 'full' | 'forFlight';
  packageId?: string;
 }
 // Fill a grounded plane to maxFuel at FUEL_PRICE_PER_L per missing liter — or, with
 // {mode:'forFlight', packageId}, top it up just enough to fly the loaded package's
 // destination leg (409 if the package isn't loaded on this plane, is expired, or the
 // leg doesn't fit a full tank).
 export async function refuelPlane(inst: GameDb, planeId: string, opts: RefuelOptions = {}): Promise<{ cost: number }> {
  const rows = await inst.db.select().from(schema.planes).where(eq(schema.planes.id, planeId));
  const plane = rows[0];
  if (!plane) throw new GameActionError(404, `plane ${planeId} not found`);
@@ -234,14 +247,47 @@ export async function refuelPlane(inst: GameDb, planeId: string): Promise<{ cost
    throw new GameActionError(409, `plane is ${plane.status}, only grounded planes can be refueled`);
  }
-  const cost = Math.round((plane.maxFuel - plane.fuel) * FUEL_PRICE_PER_L * 100) / 100;
+  const mode = opts.mode ?? 'full';
  let targetFuel: number; // tank level after the refuel
  if (mode === 'forFlight') {
    if (!opts.packageId) throw new GameActionError(400, 'packageId is required when mode is "forFlight"');
    const pkgRows = await inst.db.select().from(schema.packages).where(eq(schema.packages.id, opts.packageId));
    const pkg = pkgRows[0];
    if (!pkg) throw new GameActionError(404, `package ${opts.packageId} not found`);
    if (pkg.status !== 'loaded' || pkg.planeId !== plane.id) {
      const where = pkg.planeId === plane.id ? '' : ', and it is bound to another plane';
      throw new GameActionError(409, `only a package loaded on this plane can be refueled for (it is ${pkg.status}${where})`);
    }
    const type = PLANE_TYPES[plane.model];
    if (!type) throw new Error(`unknown plane model ${plane.model}`); // → 500, cannot happen for seeded data
    const origin = await airportByIcao(plane.locationIcao);
    const dest = await airportByIcao(pkg.destIcao);
    const distanceKm = haversineKm(origin.lat, origin.lon, dest.lat, dest.lon);
    const requiredL = requiredFuelFor(type.burnPerKm, type.emptyWeightKg, type.maxFuel, distanceKm);
    if (requiredL > plane.maxFuel) {
      throw new GameActionError(409, `the leg to ${pkg.destIcao} needs ${Math.round(requiredL)} L even starting empty — it does not fit a full ${plane.maxFuel} L tank`);
    }
    // Land EXACTLY on the leg requirement when topping up: flyPlane re-computes this same value and
    // compares with strict `>`, so fuel := requiredL guarantees the leg is feasible. The alternative
    // (fuel + liters) can round a hair BELOW R in IEEE754 — f + fl(R − f) is not guaranteed ≥ R — and
    // would 409 on an otherwise-feasible leg. Already enough → free no-op, tank untouched.
    targetFuel = Math.max(plane.fuel, requiredL);
  } else {
    // Exactly maxFuel (as before v0.16.0) — clients/tests compare against it with strict equality.
    targetFuel = plane.maxFuel;
  }
  const liters = Math.max(0, targetFuel - plane.fuel);
  const cost = Math.round(liters * FUEL_PRICE_PER_L * 100) / 100;
  const account = (await inst.db.select().from(schema.account))[0];
  if (!account) throw new Error('account row missing');
  if (cost > 0 && account.cash < cost) {
    throw new GameActionError(409, `insufficient funds: refueling costs ${cost}, you have ${Math.round(account.cash)}`);
  }
-  await inst.db.update(schema.planes).set({ fuel: plane.maxFuel }).where(eq(schema.planes.id, planeId));
+  await inst.db.update(schema.planes).set({ fuel: targetFuel }).where(eq(schema.planes.id, planeId));
  if (cost > 0) {
    await inst.db.update(schema.account).set({ cash: Math.round((account.cash - cost) * 100) / 100 });
  }
@@ -6,8 +6,11 @@ export interface PlaneType {
  name: string;
  // Fuel capacity, liters.
  maxFuel: number;
-  // Fuel burn per km of flight, liters/km (cruise).
+  // Fuel burn per km of flight at a FULL tank, liters/km (cruise) — the weighted burn
  // model (v0.16.0) calibrates its rate constant to this value at F = maxFuel.
  burnPerKm: number;
  // Operating empty weight in kg (v0.16.0) — feeds the weight-proportional burn model.
  emptyWeightKg: number;
  // Cruise speed, km/h — used by the sim tick to advance planes along routes.
  speedKmh: number;
  // Market price in € (v0.8.0): buying costs `price`, selling pays out
@@ -22,7 +25,8 @@ export const PLANE_TYPES: Record<string, PlaneType> = {
    id: 'atr72',
    name: 'ATR 72-600',
    maxFuel: 6300,
-    burnPerKm: 1.75, // ~900 kg/h at 510 km/h cruise (Jet-A1 ≈ 0.8 kg/L)
+    burnPerKm: 1.75, // full-tank rate: ~893 L/h ≈ 714 kg/h at 510 km/h cruise (Jet-A1 ≈ 0.8 kg/L); the weighted model burns less as fuel drops off
    emptyWeightKg: 9_300, // ATR 72-600 operating empty weight
    speedKmh: 510,
    // €200k — with the starting cash of €20k and typical hop rewards (~€1–3k),
    // a second ATR takes sustained play to afford, as intended for the MVP sink.
@@ -49,6 +53,9 @@ export interface CatalogEntry {
  price: number;
  maxFuel: number;
  burnPerKm: number;
  // Weighted burn model inputs (v0.16.0) — clients can mirror the closed forms in
  // lib/sim/movement.ts with these + FUEL_DENSITY_KG_PER_L.
  emptyWeightKg: number;
  speedKmh: number;
  capacity: number;
 }
@@ -62,6 +69,7 @@ export function catalogEntries(): CatalogEntry[] {
    price: t.price,
    maxFuel: t.maxFuel,
    burnPerKm: t.burnPerKm,
    emptyWeightKg: t.emptyWeightKg,
    speedKmh: t.speedKmh,
    capacity: t.capacity,
  }));
@@ -3,7 +3,7 @@ import { haversineKm } from '@/lib/geo';
 import { getGameDb } from '@/lib/db/client';
 import * as schema from '@/lib/db/schema';
 import { catalogEntries, FUEL_PRICE_PER_L, PLANE_TYPES, SELL_FRACTION, type CatalogEntry } from './catalog';
-import { fuelAt, progressAt, positionAt } from '@/lib/sim/movement';
+import { fuelAtWeighted, progressAt, positionAt } from '@/lib/sim/movement';
 // Read-only game-state snapshot for client polling (GET /api/state).
@@ -84,7 +84,7 @@ export async function getStateSnapshot(): Promise<StateSnapshot> {
    const distanceKm = haversineKm(from.lat, from.lon, to.lat, to.lon);
    const progress = progressAt(p.departureSimTime, distanceKm, type.speedKmh, simRow.clockMs);
    const pos = positionAt(from.lat, from.lon, to.lat, to.lon, progress);
-    return { ...pos, fuel: fuelAt(p.fuel, type.burnPerKm, distanceKm, progress) };
+    return { ...pos, fuel: fuelAtWeighted(p.fuel, type.burnPerKm, type.emptyWeightKg, type.maxFuel, distanceKm, progress) };
  };
  return {
@@ -17,7 +17,7 @@ function snapshot(overrides: Partial<StateSnapshot> = {}): StateSnapshot {
    planes: [],
    packages: [],
    catalog: [
-      { model: 'atr72', label: 'ATR 72-600', price: 200_000, maxFuel: 6300, burnPerKm: 1.75, speedKmh: 510, capacity: 6 },
+      { model: 'atr72', label: 'ATR 72-600', price: 200_000, maxFuel: 6300, burnPerKm: 1.75, emptyWeightKg: 9_300, speedKmh: 510, capacity: 6 },
    ],
    fuelPricePerL: 0.8,
    sellFraction: 0.5,
@@ -90,8 +90,17 @@ describe('OpenAPI spec', () => {
    expect(snap.sellFraction.type).toBe('number');
    const catalog = openApiSpec.components.schemas.CatalogEntry.properties;
-    expect(Object.keys(catalog).sort()).toEqual(['burnPerKm', 'capacity', 'label', 'maxFuel', 'model', 'price', 'speedKmh']);
+    expect(Object.keys(catalog).sort()).toEqual([
-    for (const key of ['burnPerKm', 'maxFuel', 'price', 'speedKmh'] as const) {
+      'burnPerKm',
      'capacity',
      'emptyWeightKg', // v0.16.0 weighted burn model input
      'label',
      'maxFuel',
      'model',
      'price',
      'speedKmh',
    ]);
    for (const key of ['burnPerKm', 'emptyWeightKg', 'maxFuel', 'price', 'speedKmh'] as const) {
      expect(catalog[key].type, `CatalogEntry.${key}`).toBe('number');
    }
    expect(catalog.capacity.type).toBe('integer'); // v0.12.0 slot capacity
@@ -165,7 +174,7 @@ describe('OpenAPI spec', () => {
    const post = (p: string) =>
      ((openApiSpec.paths as Record<string, { post?: unknown }>)[p]?.post ?? {}) as {
        responses: Record<string, unknown>;
-        requestBody?: { content: Record<string, { schema: { $ref: string } }> };
+        requestBody?: { required?: boolean; content: Record<string, { schema: { $ref: string } }> };
        parameters?: Array<{ name: string }>;
      };
@@ -189,9 +198,10 @@ describe('OpenAPI spec', () => {
    expect(errorCodes('/api/planes/{planeId}/fly')).toEqual(['400', '404', '409']);
    expect(errorCodes('/api/market/buy-plane')).toEqual(['400', '409']);
    expect(errorCodes('/api/market/sell-plane')).toEqual(['400', '404', '409']);
-    expect(errorCodes('/api/planes/{planeId}/refuel')).toEqual(['404', '409']);
+    expect(errorCodes('/api/planes/{planeId}/refuel')).toEqual(['400', '404', '409']); // v0.16.0 optional body
-    // Request bodies: load/fly/buy/sell take their dedicated schemas; abandon/refuel take none.
+    // Request bodies: load/fly/buy/sell take their dedicated schemas; abandon takes none;
    // refuel's is OPTIONAL (v0.16.0) — no body still means "fill to full".
    expect(post('/api/packages/{id}/load').requestBody?.content['application/json'].schema.$ref).toBe(
      '#/components/schemas/LoadPackageRequest',
    );
@@ -205,7 +215,9 @@ describe('OpenAPI spec', () => {
      '#/components/schemas/SellPlaneRequest',
    );
    expect(post('/api/packages/{id}/abandon').requestBody).toBeUndefined();
-    expect(post('/api/planes/{planeId}/refuel').requestBody).toBeUndefined();
+    const refuelBody = post('/api/planes/{planeId}/refuel').requestBody;
    expect(refuelBody?.content['application/json'].schema.$ref).toBe('#/components/schemas/RefuelRequest');
    expect(refuelBody?.required).toBe(false); // optional — no body still means "fill to full"
    // Path parameters are declared on the parameterized routes.
    const paramNames = (p: string) => post(p).parameters?.map((x) => x.name);
@@ -227,5 +239,11 @@ describe('OpenAPI spec', () => {
    const sell = openApiSpec.components.schemas.SellPlaneRequest;
    expect(sell.required).toEqual(['planeId']);
    expect(sell.properties.planeId.type).toBe('string');
    // RefuelRequest (v0.16.0): both fields optional — no body / {} means "full".
    const refuel = openApiSpec.components.schemas.RefuelRequest;
    expect((refuel as { required?: string[] }).required ?? []).toEqual([]);
    expect(((refuel.properties.mode) as { enum: string[] }).enum.sort()).toEqual(['forFlight', 'full']);
    expect(refuel.properties.packageId.type).toBe('string');
  });
 });
@@ -197,7 +197,8 @@ export const openApiSpec = {
            content: { 'application/json': { schema: { $ref: '#/components/schemas/Error' } } },
          },
          409: {
-            description: 'Plane not grounded, or insufficient fuel for the leg (burnPerKm × great-circle km)',
+            description:
              'Plane not grounded, or insufficient fuel for the leg (v0.16.0 weight-proportional burn — the fuel required to cover the great-circle distance arriving empty)',
            content: { 'application/json': { schema: { $ref: '#/components/schemas/Error' } } },
          },
        },
@@ -271,22 +272,35 @@ export const openApiSpec = {
      post: {
        summary: 'Refuel a grounded plane',
        description:
-          'Fill a grounded plane to maxFuel (v0.8.0). Cost = (maxFuel − fuel) × fuel price per liter, deducted from cash; no body.',
+          'Refuel a grounded plane at the fuel price per added liter, deducted from cash (v0.8.0). The body is optional (v0.16.0): no body or mode "full" fills to maxFuel; mode "forFlight" with packageId adds just enough for that loaded package\'s destination leg — liters = required fuel for the great-circle distance (weight-proportional burn model) minus what is already in the tank.',
        operationId: 'refuelPlane',
        parameters: [
          { name: 'planeId', in: 'path', required: true, schema: { type: 'string' } },
        ],
        requestBody: {
          required: false,
          content: {
            'application/json': {
              schema: { $ref: '#/components/schemas/RefuelRequest' },
            },
          },
        },
        responses: {
          200: {
-            description: 'Refueled — full state snapshot (fuel at max, cash reduced by the cost)',
+            description: 'Refueled — full state snapshot (fuel raised by exactly the added liters, cash reduced by the cost)',
            content: { 'application/json': { schema: { $ref: '#/components/schemas/StateSnapshot' } } },
          },
          400: {
            description: 'Invalid body (not an object, unknown field, unknown mode, or forFlight without packageId)',
            content: { 'application/json': { schema: { $ref: '#/components/schemas/Error' } } },
          },
          404: {
-            description: 'Unknown plane id',
+            description: 'Unknown plane id (or unknown package id in forFlight mode)',
            content: { 'application/json': { schema: { $ref: '#/components/schemas/Error' } } },
          },
          409: {
-            description: 'Plane is flying, or cash is insufficient for the fill-up',
+            description:
              'Plane is flying, the package is not loaded on this plane (or is expired), the leg does not fit a full tank, or cash is insufficient for the refuel',
            content: { 'application/json': { schema: { $ref: '#/components/schemas/Error' } } },
          },
        },
@@ -376,11 +390,12 @@ export const openApiSpec = {
          label: { type: 'string', description: 'Display name (e.g. "ATR 72-600").' },
          price: { type: 'number', description: 'Market price in € (buy cost; sell pays out sellFraction × this).' },
          maxFuel: { type: 'number', description: 'Fuel capacity, liters.' },
-          burnPerKm: { type: 'number', description: 'Cruise fuel burn, liters/km.' },
+          burnPerKm: { type: 'number', description: 'Cruise fuel burn at a full tank, liters/km (v0.16.0 weighted model calibrates to this).' },
          emptyWeightKg: { type: 'number', description: 'Operating empty weight, kg — with burnPerKm and maxFuel it drives the v0.16.0 weight-proportional burn model.' },
          speedKmh: { type: 'number', description: 'Cruise speed, km/h.' },
          capacity: { type: 'integer', description: 'Cargo slot capacity — packages that can be loaded on one plane (v0.12.0).' },
        },
-        required: ['model', 'label', 'price', 'maxFuel', 'burnPerKm', 'speedKmh', 'capacity'],
+        required: ['model', 'label', 'price', 'maxFuel', 'burnPerKm', 'emptyWeightKg', 'speedKmh', 'capacity'],
      },
      AccountState: {
        type: 'object',
@@ -440,6 +455,22 @@ export const openApiSpec = {
        },
        required: ['planeId'],
      },
      RefuelRequest: {
        type: 'object',
        description:
          'Optional refuel body (v0.16.0) — omit it entirely or send {} to fill the tank; both fields are optional.',
        properties: {
          mode: {
            enum: ['full', 'forFlight'],
            description:
              '"full" (default) fills the tank to maxFuel; "forFlight" adds just enough fuel for one loaded package\'s destination leg.',
          },
          packageId: {
            type: 'string',
            description: 'Required with mode "forFlight": a package LOADED on this plane — its destIcao is the refuel target.',
          },
        },
      },
      Error: {
        type: 'object',
        properties: {
@@ -9,7 +9,7 @@ import { loadAirportsGeoJson } from '@/lib/airports';
 import { haversineKm } from '@/lib/geo';
 import { PLANE_TYPES } from '@/lib/game/catalog';
 import { MARKET_TARGET_OPEN_PACKAGES, mulberry32 } from '@/lib/game/seed';
-import { arrivalTimeFor } from './movement';
+import { arrivalTimeFor, fuelAtWeighted } from './movement';
 import {
  clampTimeScale,
  deliverPackages,
@@ -182,7 +182,8 @@ describe('deliverPackages (v0.12.0 arrival delivery)', () => {
    expect(plane.locationIcao).toBe(TO);
    expect(plane.lat).toBe(to.lat);
    expect(plane.lon).toBe(to.lon);
-    expect(plane.fuel).toBeCloseTo(Math.max(0, type.maxFuel - type.burnPerKm * km), 6); // remaining fuel
+    // Remaining fuel per the v0.16.0 weight-proportional burn model (closed form).
    expect(plane.fuel).toBeCloseTo(fuelAtWeighted(type.maxFuel, type.burnPerKm, type.emptyWeightKg, type.maxFuel, km, 1), 6);
    expect(plane.departureSimTime).toBeNull();
    expect(plane.destIcao).toBeNull(); // flight context cleared on landing
@@ -12,7 +12,7 @@ import {
  type Rng,
  type SeedAirport,
 } from '@/lib/game/seed';
-import { arrivalTimeFor, fuelAt } from './movement';
+import { arrivalTimeFor, fuelAtWeighted } from './movement';
 // Server-authoritative sim engine (v0.7.0) — tick-on-read: there is NO background
 // timer. Every read/action endpoint calls tickNow() first; the clock advances by
@@ -131,14 +131,14 @@ export async function deliverPackages(inst: GameDb, clockMs: number): Promise<nu
    const distanceKm = haversineKm(from.lat, from.lon, to.lat, to.lon);
    if (clockMs < arrivalTimeFor(p.departureSimTime, distanceKm, type.speedKmh)) continue;
-    // Arrived: progress is exactly 1 here, so remaining fuel is the full-leg burn.
+    // Arrived: progress is exactly 1 here, so remaining fuel is the full-leg weighted burn.
    await inst.db.update(schema.planes)
      .set({
        status: 'available',
        locationIcao: to.icao,
        lat: to.lat,
        lon: to.lon,
-        fuel: fuelAt(p.fuel, type.burnPerKm, distanceKm, 1),
+        fuel: fuelAtWeighted(p.fuel, type.burnPerKm, type.emptyWeightKg, type.maxFuel, distanceKm, 1),
        departureSimTime: null,
        destIcao: null,
      })
@@ -1,12 +1,23 @@
 import { describe, expect, it } from 'vitest';
 import { haversineKm } from '@/lib/geo';
-import { arrivalTimeFor, fuelAt, positionAt, progressAt, travelDurationMs } from './movement';
+import {
  arrivalTimeFor,
  burnRateConstant,
  FUEL_DENSITY_KG_PER_L,
  fuelAtWeighted,
  positionAt,
  progressAt,
  requiredFuelFor,
  travelDurationMs,
 } from './movement';
 // Synthetic in-flight fixtures — no DB needed: everything is a pure function of
 // the sim clock. ATR 72-600 numbers from lib/game/catalog.ts.
 const DEP = 1_750_000_000_000; // departure sim time (ms)
 const SPEED = 510; // km/h
-const BURN = 1.75; // L/km
+const BURN = 1.75; // L/km at a full tank
 const WE = 9_300; // kg, operating empty weight
 const TANK = 6_300; // liters, full tank
 // Frankfurt → Madrid, real coordinates from the CSV dataset.
 const FROM = { lat: 50.0333, lon: 8.5706 };
@@ -96,17 +107,53 @@ describe('positionAt (great-circle slerp)', () => {
  });
 });
-describe('fuelAt', () => {
+describe('weighted burn model (v0.16.0)', () => {
-  it('burns fuel proportionally to distance flown', () => {
+  it('calibrates so a full tank burns exactly the old constant rate', () => {
-    const start = 6_300; // full ATR tank
+    const k = burnRateConstant(BURN, WE, TANK);
-    expect(fuelAt(start, BURN, KM, 0)).toBe(start);
+    expect(k * (WE + FUEL_DENSITY_KG_PER_L * TANK)).toBeCloseTo(BURN, 12);
-    expect(fuelAt(start, BURN, KM, 0.5)).toBeCloseTo(start - BURN * KM / 2, 9);
+
-    expect(fuelAt(start, BURN, KM, 1)).toBeCloseTo(start - BURN * KM, 9);
+    // Over a short hop from full, weighted ≈ constant — divergence only grows as fuel drops off.
    const d = 100;
    const consumed = TANK - fuelAtWeighted(TANK, BURN, WE, TANK, d, 1);
    expect(Math.abs(consumed - BURN * d)).toBeLessThan(1); // < 1 L over 100 km from full
  });
  it('consumption matches numeric integration of r(F) = k·(We + ρF)', () => {
    const k = burnRateConstant(BURN, WE, TANK);
    const rho = FUEL_DENSITY_KG_PER_L;
    // Euler-integrate dF/dx = −k(We + ρF) from a full tank over the whole leg.
    const steps = 200_000;
    const h = KM / steps;
    let f = TANK;
    for (let i = 0; i < steps; i++) f -= k * (WE + rho * f) * h;
    expect(Math.abs(fuelAtWeighted(TANK, BURN, WE, TANK, KM, 1) - f)).toBeLessThan(0.001); // Euler drift is sub-milliliter here
  });
  it('requiredFuelFor is zero for a zero leg and strictly increasing in distance', () => {
    expect(requiredFuelFor(BURN, WE, TANK, 0)).toBe(0);
    let prev = requiredFuelFor(BURN, WE, TANK, 100);
    for (const d of [500, 1_000, 2_000, 3_000, 4_000]) {
      const cur = requiredFuelFor(BURN, WE, TANK, d);
      expect(cur).toBeGreaterThan(prev);
      prev = cur;
    }
  });
  it('a lighter start burns less over the same distance', () => {
    const burnFromFull = TANK - fuelAtWeighted(TANK, BURN, WE, TANK, KM, 1);
    const burnFromHalf = TANK / 2 - fuelAtWeighted(TANK / 2, BURN, WE, TANK, KM, 1);
    expect(burnFromFull).toBeGreaterThan(burnFromHalf);
  });
  it('starting with exactly the required fuel arrives on empty', () => {
    const req = requiredFuelFor(BURN, WE, TANK, KM);
    expect(fuelAtWeighted(req, BURN, WE, TANK, KM, 1)).toBeCloseTo(0, 6);
  });
  it('clamps at zero instead of going negative', () => {
-    expect(fuelAt(100, BURN, 1_000, 1)).toBe(0); // needs 1750 L, has 100
+    expect(fuelAtWeighted(100, BURN, WE, TANK, KM, 1)).toBe(0); // needs ~2800 L from full, has 100
-    expect(fuelAt(100, BURN, 1_000, 0.01)).toBeCloseTo(100 - 17.5, 9);
+    expect(fuelAtWeighted(TANK, BURN, WE, TANK, KM, 0)).toBe(TANK);
    expect(fuelAtWeighted(TANK, BURN, WE, TANK, 0, 1)).toBe(TANK);
  });
  it('composes with progressAt for a just-before-arrival snapshot', () => {
@@ -114,9 +161,6 @@ describe('fuelAt', () => {
    const clock = DEP + duration - 1; // one ms before arrival
    const p = positionAt(FROM.lat, FROM.lon, TO.lat, TO.lon, progressAt(DEP, KM, SPEED, clock));
    expect(haversineKm(p.lat, p.lon, TO.lat, TO.lon)).toBeGreaterThan(0); // not yet at the gate
-    expect(fuelAt(6_300, BURN, KM, progressAt(DEP, KM, SPEED, clock))).toBeCloseTo(
+    expect(fuelAtWeighted(TANK, BURN, WE, TANK, KM, progressAt(DEP, KM, SPEED, clock))).toBeGreaterThan(0);
      6_300 - BURN * KM * (1 - 1 / duration),
      6,
    );
  });
 });
@@ -65,8 +65,56 @@ export function positionAt(
  };
 }
-// Fuel remaining after flying `progress` of a leg of distanceKm. Clamped at 0 —
+// --- Weight-proportional fuel burn (v0.16.0) ---
-// range exhaustion is not modeled yet (fuel management/refueling comes later).
+//
-export function fuelAt(startFuel: number, burnPerKm: number, distanceKm: number, progress: number): number {
+// The instantaneous burn rate is proportional to total weight: r(F) = k·(We + ρF) L/km,
-  return Math.max(0, startFuel - burnPerKm * distanceKm * progress);
+// where We is the empty weight in kg, ρ the fuel density and F the current load in
 // liters — a heavier plane burns more per km. k is calibrated so that a FULL tank
 // burns exactly the catalog's constant burnPerKm: k = burnPerKm / (We + ρ·maxFuel),
 // so full-tank legs match the old model at departure and only diverge as fuel (and
 // weight) drops off in flight. Closed forms of dF/dx = −k(We + ρF):
 //   fuel after distance D from F₀:        (F₀ + We/ρ)·e^{−kρD} − We/ρ
 //   consumption over D:                   (F₀ + We/ρ)·(1 − e^{−kρD})
 //   fuel required to cover D arriving with 0, independent of F₀: (We/ρ)(e^{kρD} − 1)
 // Jet-A1 density in kg/L — converts a liter load into its weight contribution.
 export const FUEL_DENSITY_KG_PER_L = 0.8;
 // Calibration constant k for one plane type (see the model note above).
 export function burnRateConstant(burnPerKm: number, emptyWeightKg: number, maxFuel: number): number {
  return burnPerKm / (emptyWeightKg + FUEL_DENSITY_KG_PER_L * maxFuel);
 }
 // Fuel remaining after flying `progress` of a leg of distanceKm from startFuel under the
 // weighted model. Clamped at 0 — range exhaustion is not modeled (a plane that runs dry
 // limps to the gate on fumes, same as before).
 export function fuelAtWeighted(
  startFuel: number,
  burnPerKm: number,
  emptyWeightKg: number,
  maxFuel: number,
  distanceKm: number,
  progress: number,
 ): number {
  const d = distanceKm * progress;
  if (d <= 0) return startFuel;
  const k = burnRateConstant(burnPerKm, emptyWeightKg, maxFuel);
  const rho = FUEL_DENSITY_KG_PER_L;
  const f = (startFuel + emptyWeightKg / rho) * Math.exp(-k * rho * d) - emptyWeightKg / rho;
  return Math.max(0, f);
 }
 // Total fuel required to cover distanceKm arriving with an empty tank — independent of the
 // starting load. A leg is flyable from a plane iff its current fuel covers this amount; it
 // fits in the aircraft at all iff this does not exceed the tank capacity.
 export function requiredFuelFor(
  burnPerKm: number,
  emptyWeightKg: number,
  maxFuel: number,
  distanceKm: number,
 ): number {
  if (distanceKm <= 0) return 0;
  const k = burnRateConstant(burnPerKm, emptyWeightKg, maxFuel);
  const rho = FUEL_DENSITY_KG_PER_L;
  return (emptyWeightKg / rho) * (Math.exp(k * rho * distanceKm) - 1);
 }
@@ -0,0 +1,49 @@
 import { describe, expect, it } from 'vitest';
 import { advanceSimClock, type SimClockAnchor } from './useSimClock';
 // ISS-007 (v0.16.1) — the pure extrapolation core of lib/useSimClock.ts. The hook itself is a
 // thin setInterval + re-sync wrapper covered by e2e (panes.spec.ts "ticks smoothly between polls");
 // this suite pins the math: game time advances real-time × timeScale, frozen while paused.
 const anchor = (over: Partial<SimClockAnchor> = {}): SimClockAnchor => ({
  clockMs: 1_750_000_000_000,
  at: 1_000_000,
  timeScale: 1,
  paused: false,
  ...over,
 });
 describe('advanceSimClock', () => {
  it('advances by exactly elapsed real-time × timeScale while running', () => {
    expect(advanceSimClock(anchor(), 1_001_000)).toBe(1_750_000_000_000 + 1_000); // scale 1: 1 s real = 1 s game
    expect(advanceSimClock(anchor({ timeScale: 25 }), 1_002_500)).toBe(1_750_000_000_000 + 62_500);
    // The e2e scenario: scale 1000, 2.5 s real → 2 500 game seconds.
    expect(advanceSimClock(anchor({ timeScale: 1000 }), 1_002_500)).toBe(1_750_000_000_000 + 2_500_000);
  });
  it('returns the anchor value exactly at zero elapsed', () => {
    expect(advanceSimClock(anchor({ timeScale: 1000 }), 1_000_000)).toBe(1_750_000_000_000);
  });
  it('is frozen while paused regardless of elapsed or scale', () => {
    const a = anchor({ timeScale: 1000, paused: true });
    expect(advanceSimClock(a, 1_000_000)).toBe(1_750_000_000_000);
    expect(advanceSimClock(a, 2_000_000)).toBe(1_750_000_000_000); // a full second later — still frozen
  });
  it('clamps to the anchor value when nowMs is before the anchor (clock skew), never backwards', () => {
    expect(advanceSimClock(anchor({ timeScale: 1000 }), 999_999)).toBe(1_750_000_000_000);
    expect(advanceSimClock(anchor({ paused: true }), 999_999)).toBe(1_750_000_000_000);
  });
  it('mirrors the server tick model (tickOnce): advance = elapsed × timeScale while actively polled', () => {
    // lib/sim/engine.ts: clockMs += min(now − lastRealTickMs, MAX_TICK_ELAPSED_MS) × timeScale.
    // For gaps under the 2 s clamp the client extrapolation is exactly the server's own formula.
    const scale = 50;
    for (const gap of [1, 250, 999, 1_999]) {
      expect(advanceSimClock(anchor({ timeScale: scale }), 1_000_000 + gap)).toBe(
        1_750_000_000_000 + gap * scale,
      );
    }
  });
 });
@@ -0,0 +1,68 @@
 'use client';
 import { useEffect, useRef, useState } from 'react';
 import type { StateSnapshot } from './game/state';
 // ISS-007 (v0.16.1): the sim clock ticks smoothly on the CLIENT between polls instead of
 // jumping once per snapshot. The server's authoritative rate is exactly real-time × timeScale
 // (tickOnce in lib/sim/engine.ts: advance = min(elapsed, MAX_TICK_ELAPSED_MS) × timeScale), so
 // client-side extrapolation mirrors the server's own model. Every new snapshot re-anchors to
 // server truth, bounding any drift by network latency only.
 export interface SimClockAnchor {
  // Server truth at anchor time — the snapshot's simState.clockMs.
  clockMs: number;
  // Date.now() when that snapshot was received.
  at: number;
  timeScale: number;
  paused: boolean;
 }
 // Pure core of the extrapolation — mirrors tickOnce: while running, game time advances by
 // real-time × timeScale; while paused it is frozen (advance 0). nowMs before `at` clamps to
 // the anchor value instead of going backwards. Unit-testable in node.
 export function advanceSimClock(anchor: SimClockAnchor, nowMs: number): number {
  if (anchor.paused) return anchor.clockMs;
  return anchor.clockMs + Math.max(0, nowMs - anchor.at) * anchor.timeScale;
 }
 // ~10 fps display refresh — smooth for a seconds-precision wall clock without busy re-renders.
 const DISPLAY_TICK_MS = 100;
 export interface SimClockControls {
  // EFFECTIVE controls (optimistic pending scale / current pause), not the snapshot's:
  // UI changes take effect on click/drag without waiting for a confirming snapshot.
  timeScale: number;
  paused: boolean;
 }
 // Returns the display clockMs to render, or null until the first snapshot arrives.
 export function useSimClock(snapshot: StateSnapshot | null, controls: SimClockControls): number | null {
  const anchorRef = useRef<SimClockAnchor | null>(null);
  const [displayMs, setDisplayMs] = useState<number | null>(null);
  // Re-sync on every snapshot AND effective-control change: snap to server truth. The snapshot
  // object is fresh per poll (useGameState), so this runs once per poll cycle as well.
  useEffect(() => {
    if (!snapshot) return;
    anchorRef.current = {
      clockMs: snapshot.simState.clockMs,
      at: Date.now(),
      timeScale: controls.timeScale,
      paused: controls.paused,
    };
    setDisplayMs(advanceSimClock(anchorRef.current, Date.now()));
  }, [snapshot, controls.timeScale, controls.paused]);
  useEffect(() => {
    const id = setInterval(() => {
      const anchor = anchorRef.current;
      if (anchor) setDisplayMs(advanceSimClock(anchor, Date.now()));
    }, DISPLAY_TICK_MS);
    return () => clearInterval(id);
  }, []);
  // First paint after a snapshot arrives happens before the re-sync effect runs — show the
  // snapshot value directly so the clock never blanks for a frame.
  return displayMs ?? (snapshot ? snapshot.simState.clockMs : null);
 }
@@ -1,6 +1,6 @@
 {
  "name": "flight-ops",
-  "version": "0.15.0",
+  "version": "0.16.1",
  "private": true,
  "scripts": {
    "dev": "next dev -p 3000",
Author	SHA1	Message	Date
kamilkrzywda	eb69359a38	Merge pull request 'v0.16.1 — ISS-007 smooth client-side sim clock with per-snapshot re-sync' (#18 ) from feat/smooth-sim-clock into master CI / build + unit + e2e (push) Successful in 6m34s Details	2026-09-19 16:27:21 +02:00
kamilkrzywda	3acf471295	test: fix ISS-007 clock parse — replace only fixed the first space CI / build + unit + e2e (pull_request) Successful in 6m4s Details	2026-09-19 14:20:34 +00:00
kamilkrzywda	7d2f8f07c8	feat: v0.16.1 — ISS-007 smooth client-side sim clock with per-snapshot re-sync CI / build + unit + e2e (pull_request) Failing after 6m42s Details	2026-09-19 14:00:47 +00:00
kamilkrzywda	05d956f71b	Merge pull request 'v0.16.0 — ISS-005 weighted fuel burn + "refuel just enough" per package' (#17 ) from feat/fuel-weight-refuel-for-flight into master CI / build + unit + e2e (push) Successful in 6m23s Details	2026-09-19 15:44:09 +02:00
kamilkrzywda	ae1cb93a4f	test: harden full-core-loop against Load/Fly precondition races CI / build + unit + e2e (pull_request) Successful in 6m32s Details	2026-09-19 13:36:27 +00:00
kamilkrzywda	687e4f2169	fix: forFlight refuel leaves an exactly-feasible tank (round up) — e2e 409 CI / build + unit + e2e (pull_request) Failing after 5m26s Details	2026-09-19 13:00:06 +00:00
kamilkrzywda	a801311fc5	feat: v0.16.0 — ISS-005 weight-proportional fuel burn + refuel just enough for the loaded package CI / build + unit + e2e (pull_request) Failing after 5m28s Details Part A: r(F) = k(We + rhoF) L/km, k calibrated so a full tank burns exactly the old constant; closed forms in lib/sim/movement.ts (fuelAtWeighted, requiredFuelFor, burnRateConstant, FUEL_DENSITY_KG_PER_L). Catalog gains emptyWeightKg (ATR72 OEW 9300 kg), exposed in the snapshot. All three burn call sites (engine landing, state live fuel, fly validation) moved to the weighted model; old constant-rate fuelAt removed. Part B: POST /api/planes/{planeId}/refuel takes an optional body {mode:'full'\|'forFlight', packageId} — no body keeps today's fill-to-full behavior exactly (fuel lands bit-exact on maxFuel); forFlight adds just enough for the loaded package's destination leg (409 not-loaded/expired/ doesn't-fit, 400 bad body). UI: per-cargo-row 'Refuel' button (refuel-for-{pkg.id}), market button renamed 'Refuel to full'. OpenAPI: RefuelRequest schema + optional requestBody + 400 on refuel, fly's 409 description updated, CatalogEntry.emptyWeightKg. Tests: new weighted-burn suite, forFlight action/route cases (incl. ~7670 km UNNT<->LPPD doesn't-fit), openapi guards; landing-fuel assertions in engine.test.ts + e2e/actions.spec.ts use the closed form; the e2e 'return leg unfuelable' scenario reworked — a full tank now covers the EDDF<->LEZL round trip, so the 409 moves to the second outbound. New e2e: row Refuel deducts exactly Lprice / raises fuel by exactly L via the endpoint's own response snapshot.	2026-09-19 12:24:34 +00:00
kamilkrzywda	1dc5beb0dd	Merge pull request 'v0.15.1 — ISS-004 right pane widened, On-board wrapping fixed' (#16 ) from fix/right-pane-width into master CI / build + unit + e2e (push) Successful in 5m4s Details	2026-09-19 13:38:52 +02:00
kamilkrzywda	b6bfcedaf6	test: click the rendered marker position while paused — closes render-lag race (CI run #37 ) CI / build + unit + e2e (pull_request) Successful in 5m0s Details	2026-09-19 11:32:19 +00:00
kamilkrzywda	4c99dbe550	fix: v0.15.1 — ISS-004 right pane widened to 360px, on-board wrap fixes CI / build + unit + e2e (pull_request) Failing after 6m15s Details	2026-09-19 11:05:02 +00:00