Merge pull request 'ISS-043 (part 1): flight queue backend — data model, auto-chain on landing, add/cancel endpoints' (#50 ) from feat/flight-queue-backend into master

ISS-043: add queue endpoints to e2e OpenAPI path list
Flight queue backend: planes hold a queue of upcoming legs, auto-chain on landing (ISS-043 part 1)
2026-09-20 13:04:17 +02:00 · 2026-09-20 10:57:57 +00:00 · 2026-09-20 10:39:00 +00:00 · 2026-09-20 12:00:02 +02:00 · 2026-09-20 09:48:56 +00:00 · 2026-09-20 11:24:33 +02:00
27 changed files with 746 additions and 101 deletions
@@ -1,5 +1,23 @@
 # Changelog

+## v0.25.0 — 2026-09-20 10:36
+- **Planes now hold a queue of upcoming flight legs (ISS-043, part 1 — backend).** One new column on `planes`: `queue TEXT NOT NULL DEFAULT '[]'` (`lib/db/schema.ts`, DDL + guarded `ALTER TABLE` migration in `lib/db/client.ts`) storing an ordered JSON array of ICAO strings = the legs NOT yet started. The active leg stays exactly as before (`destIcao` + `departureSimTime`); full path = `[locationIcao, destIcao, ...queue]`. No new table — queues are short, per-plane, always read/written whole
+- **Auto-chain on landing (ISS-043).** In `deliverPackages()` (`lib/sim/engine.ts`) a plane that arrives now reads its queue: if it holds legs AND fuel covers the first one (same `requiredFuelFor` feasibility rule as `/fly`), it immediately starts that leg from the arrival airport — stays `'flying'`, `departureSimTime` = the arrival instant, queue shortened. If fuel is short it grounds safely with the remaining queue kept intact for refuel + re-dispatch; an empty queue grounds exactly as before. Cargo delivery for the reached airport runs first and is unaffected by chaining. Ordering preserved on purpose: delivery runs BEFORE tickOnce's pause check (ISS-041), so a chained plane counts as still flying there — chaining never triggers the last-plane pause
+- **New endpoints (ISS-043).** `POST /api/planes/{planeId}/queue` body `{destIcao}` appends a not-yet-started leg (works grounded or flying — pre-build a route; nothing auto-starts, 400 unknown ICAO/bad body, 404 unknown plane); `POST /api/planes/{planeId}/queue/cancel` body `{index}` removes a queued leg by index (only queued legs are cancellable — the active in-flight leg is never touched; 400 non-integer/out-of-range index, 404 unknown plane). Both run through `performAction()` like every other action and return the full state snapshot. New actions `queueLeg`/`cancelQueuedLeg` in `lib/game/actions.ts`; routes under `app/api/planes/[planeId]/queue/`
+- **Snapshot + spec (ISS-043).** `PlaneState.queue: string[]` added to the `/api/state` snapshot (`lib/game/state.ts`, parsed with a null/malformed-safe helper shared by the engine); OpenAPI updated — `PlaneState.queue`, `QueueLegRequest`, `CancelQueuedLegRequest`, both new paths (200→snapshot, 400, 404)
+- Tests: unit — `lib/sim/engine.test.ts`: auto-chain block in `deliverPackages` (lands with queue + enough fuel → `'flying'` to the next dest at the arrival instant with the queue shortened; lands short on fuel → grounds with the queue intact; empty queue → unchanged grounding) plus a pause-on-landing regression guard — a chained plane does NOT trigger the last-plane pause. `lib/game/actions.test.ts`: `queueLeg` (appends in order, works while flying without touching the active leg, 404 unknown plane, 400 unknown ICAO) and `cancelQueuedLeg` (removes the right index keeping order, 400 out-of-range/negative/empty-queue, 404 unknown plane). `lib/openapi.test.ts`: endpoint count ten → twelve, PlaneState keys + both request schemas. Type-compat only: `queue: []` added to the `PlaneState`/seed fixtures in `deriveEvents`, `right-pane`, `mapData`, `seed` tests
+- Part 1 of ISS-043 (backend) — UI/map rendering of queued legs lands in a follow-up part. Verified: `tsc --noEmit` clean; unit suite green locally; `npx playwright test --list` unchanged at 42 tests in 12 files; e2e not run locally by design — CI verifies against an isolated stack
+
+## v0.24.0 — 2026-09-20 09:48
+- **Landing now pauses the sim instead of auto-slowing to 1× (ISS-041).** When the LAST plane in flight lands, `tickOnce` (`lib/sim/engine.ts`) sets `sim_state.paused = true` WITHOUT touching `timeScale` — speed is preserved. The trigger condition carries over from ISS-011's auto-slow unchanged: ≥1 landing this tick AND no `'flying'` planes remain (a landing while another plane is still airborne does not pause — there would be nothing to auto-resume it). No idle-enforcement or auto-restore of the pause exists
+- **Starting a flight auto-resumes a paused sim (ISS-041).** `flyPlane()` (`lib/game/actions.ts`) writes `sim_state.paused = false` before persisting — inside `runAction()`, so tick + unpause + dispatch are atomic under the sim lock. The cycle: dispatch unpauses → last landing pauses (speed preserved) → next dispatch unpauses again
+- Tests: unit — `lib/sim/engine.test.ts`: the auto-slow describe block rewritten for pause semantics (last plane lands → `paused === true` AND stored `timeScale` UNCHANGED, persisted on the DB row; a landing while another plane is still flying → no pause; last landing at scale 1 → pauses anyway; paused tick with a fully grounded fleet → trigger never fires). `lib/game/actions.test.ts`: new test — dispatching on a paused sim clears `paused` and leaves `timeScale` untouched. E2E — `e2e/auto-slow.spec.ts` renamed to `e2e/pause-on-landing.spec.ts` and reworked: after the starter lands, asserts `simState.paused === true` AND `timeScale` still 1000 (NOT reset), then a subsequent `/fly` dispatch clears `paused` on its own post-action snapshot. Cross-cutting fix for the new pause: every per-spec `setScale` helper (`actions`, `hover`, `map-interactions`, `relocation`, `right-pane`) now POSTs `{ timeScale, paused: false }` — a landing pauses the sim, so a scale-only fast-forward after one would leave the clock frozen and hang the next wait; no caller relied on it NOT clearing pause (verified per call site). Deliberate mid-test pauses (`sim.spec.ts` / `panes.spec.ts` freeze tests, marker-click freezes) are untouched
+- Verified: `tsc --noEmit` clean; unit suite green locally (291); `npx playwright test --list` = 42 tests in 12 files; e2e not run locally by design — CI verifies against an isolated stack
+
+## v0.23.2 — 2026-09-20 09:15
+- **On-board package hover previews the route from the carrier's current position (ISS-040).** Hovering a loaded package in the left pane used to draw the great-circle trace from the package's ORIGIN airport; it now starts at the carrying plane's live lat/lon — identical while grounded at the pickup, correct once the plane has departed with cargo still loaded. New pure builder `hoverTraceGeoJson(from: AirportCoord, toIcao, airportsByIcao)` in `lib/mapData.ts` (sibling of `hoverRouteGeoJson`, same shape/conventions; empty collection when the destination is missing); `components/Map.tsx`'s `applyHoverRef` looks up the carrier via the hover's `planeId` and uses it, falling back to the ICAO trace when no carrier is in state. The `[state]` effect now also re-applies the hover so the trace follows a moving carrier between polls while hovered (idempotent: one small setData + ring filters). Endpoint rings untouched — still ICAO-filtered origin/dest circles
+- Tests: unit — `lib/mapData.test.ts` gains a `hoverTraceGeoJson` block (exact endpoints from an arbitrary start coord; empty on missing dest). E2E — `e2e/hover.spec.ts`: new test loads a package at EDDF, dispatches the starter to LEMD via API, waits until its live position is >0.2° away from the hub, pauses the sim, hovers the on-board row and asserts some rendered trace segment starts within EPS of the carrier's live lat/lon AND some ends within EPS of LEMD AND no segment starts near EDDF (per-tile clipping handled via the existing cross-segment endpoint pattern); cleanup resumes + fast-forwards to arrival (auto-delivery) and flies home
+
 ## v0.23.1 — 2026-09-20 08:42
 - **Toasts repositioned to the map's right edge (ISS-039).** The `.toasts` stack was `position: fixed` at the viewport bottom-right, overlapping the 280px right pane; its `right` changed 12px → 292px (= 280px right pane + 12px inset) so it now sits flush against the map's right edge with the same 12px margin. No JSX/endpoint changes — all positioning lives in that one CSS value
 - Tests: e2e wording only — `toasts.spec.ts` header comment, test title, and toast visibility assertion message updated from "bottom-right" to "map right edge / clear of the right pane"; no position assertions added (none existed), suite unchanged at 41 tests in 12 files
@@ -0,0 +1,34 @@
+import { cancelQueuedLeg, performAction } from '@/lib/game/actions';
+
+// POST /api/planes/:planeId/queue/cancel (v0.25.0, ISS-043) — body { index: number }.
+// Removes a NOT-yet-started leg from the plane's queue by index; only queued legs
+// are cancellable, the active in-flight leg is never affected. 400 missing/
+// non-integer index, unknown fields, or an index outside [0, queue.length); 404
+// unknown plane id. On success returns the full state snapshot (plane.queue updated).
+
+export async function POST(req: Request, ctx: { params: Promise<{ planeId: string }> }) {
+  const { planeId } = await ctx.params;
+
+  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 !== 'index') {
+      return Response.json({ error: `unknown field "${key}"` }, { status: 400 });
+    }
+  }
+  if (!Number.isInteger(input.index)) {
+    return Response.json({ error: 'index must be an integer' }, { status: 400 });
+  }
+
+  const index = input.index as number;
+  return performAction((inst) => cancelQueuedLeg(inst, planeId, index));
+}
@@ -0,0 +1,35 @@
+import { performAction, queueLeg } from '@/lib/game/actions';
+
+// POST /api/planes/:planeId/queue (v0.25.0, ISS-043) — body { destIcao: string }.
+// Appends a NOT-yet-started leg to the plane's flight queue; works whether the
+// plane is grounded or flying (pre-building a route). Nothing auto-starts here —
+// queued legs chain on landing when fuel covers them. 400 missing/non-string
+// destIcao, unknown fields, or an ICAO not in the airport dataset; 404 unknown
+// plane id. On success returns the full state snapshot (plane.queue updated).
+
+export async function POST(req: Request, ctx: { params: Promise<{ planeId: string }> }) {
+  const { planeId } = await ctx.params;
+
+  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 !== 'destIcao') {
+      return Response.json({ error: `unknown field "${key}"` }, { status: 400 });
+    }
+  }
+  if (typeof input.destIcao !== 'string' || input.destIcao.length === 0) {
+    return Response.json({ error: 'destIcao must be a non-empty string' }, { status: 400 });
+  }
+
+  const destIcao = input.destIcao;
+  return performAction((inst) => queueLeg(inst, planeId, destIcao));
+}
@@ -8,7 +8,7 @@ import { DEFAULT_STYLE_ID, STYLES, STYLE_STORAGE_KEY, isStyleId, localAssetsAvai
 import type { GeoJsonFeatureCollection } from '../lib/airports';
 import type { StateSnapshot } from '../lib/game/state';
 import type { HoverTarget } from './hoverTypes';
-import { hoverRouteGeoJson, planesGeoJson, routesGeoJson, type AirportCoord, type PlaneFeatureProps } from '../lib/mapData';
+import { hoverRouteGeoJson, hoverTraceGeoJson, planesGeoJson, routesGeoJson, type AirportCoord, type PlaneFeatureProps } from '../lib/mapData';
 import { weatherFor } from '../lib/weather';
 import { approxLocalTime } from '../lib/localTime';

@@ -100,6 +100,9 @@ export default function FlightMap({ state, hovered, applySnapshot }: MapProps) {
  useEffect(() => {
    stateRef.current = state ?? null;
    applyDynamicRef.current();
+    // ISS-040 (v0.23.2): re-apply the hover too, so an on-board package's trace follows a moving
+    // carrier between polls while hovered — idempotent and cheap (one small setData + ring filters).
+    applyHoverRef.current();
  }, [state]);

  // ISS-002 (v0.15.0): hover highlight — same ref + effect pattern as the snapshot above.
@@ -138,7 +141,14 @@ export default function FlightMap({ state, hovered, applySnapshot }: MapProps) {
    // ICAOs (package origin→dest / relocate fromIcao→toIcao); empty when either endpoint is unknown.
    const hoverSource = map.getSource(HOVER_ROUTES_SOURCE_ID) as maplibregl.GeoJSONSource | undefined;
    if (hoverSource) {
-      void hoverSource.setData(hoverRouteGeoJson(fromIcao, toIcao, airportsIndexRef.current ?? new Map()));
+      // ISS-040 (v0.23.2): an on-board package's trace starts from the carrier plane's LIVE position,
+      // not its origin airport — identical to before while grounded at the pickup, different once it
+      // has departed with cargo still loaded. No carrier in state yet → fall back to the ICAO trace.
+      const idx = airportsIndexRef.current ?? new Map();
+      const carrier = h?.kind === 'package' && h.planeId ? stateRef.current?.planes.find((p) => p.id === h.planeId) : undefined;
+      void hoverSource.setData(
+        carrier ? hoverTraceGeoJson({ lat: carrier.lat, lon: carrier.lon }, toIcao, idx) : hoverRouteGeoJson(fromIcao, toIcao, idx),
+      );
    }
    // Package hovers ring BOTH endpoints (v0.15.0 behavior); 'route' hovers ring the TARGET only —
    // the relocation's destination is what ISS-027 asks to see. Plane hovers ring nothing.
@@ -24,6 +24,7 @@ function plane(over: Partial<PlaneState> & Pick<PlaneState, 'id'>): PlaneState {
    departureSimTime: null,
    lat: 50,
    lon: 8.5,
+    queue: [],
    ...over,
  };
 }
@@ -66,8 +66,10 @@ async function postSim(page: Page, body: Record<string, unknown>): Promise<void>

 // Set the time scale and VERIFY from the response that it stuck — if something external ever
 // resets the live instance's controls mid-test, fail loudly here instead of timing out later.
+// ISS-041 also clears pause: a landing pauses the sim, so any fast-forward after one must
+// resume it or the clock stays frozen and the next wait hangs.
 async function setScale(page: Page, scale: number): Promise<void> {
-  const res = await page.request.post('/api/sim', { data: { timeScale: scale } });
+  const res = await page.request.post('/api/sim', { data: { timeScale: scale, paused: false } });
  expect(res.status()).toBe(200);
  const body = (await res.json()) as { timeScale: number };
  expect(body.timeScale, `timeScale should be ${scale} after POST /api/sim`).toBe(scale);
@@ -118,7 +120,7 @@ async function flyHomeViaApi(page: Page): Promise<void> {
    plane = s.planes.find((p) => p.id === 'plane-starter')!;
  }
  if (plane.locationIcao !== HUB) {
-    // ISS-011: the landing above auto-slown the sim to 1× — re-set SCALE so the return leg
+    // ISS-041: the landing above paused the sim — setScale clears pause so the return leg
    // fast-forwards instead of taking real-time hours.
    await setScale(page, SCALE);
    const res = await page.request.post(`/api/planes/${plane.id}/fly`, { data: { destIcao: HUB } });
@@ -225,8 +227,8 @@ test('full core loop via UI: load → fly to destination → exact reward + rep
  const refuelCost = Math.round((afterRefuel.maxFuel - landed.fuel) * FUEL_PRICE_PER_L * 100) / 100;
  expect(s.account.cash).toBeCloseTo(before.account.cash + pkg.reward - refuelCost, 6);

-  // Restore: fly home (repositioning — no package needed in the v0.12.0 model). ISS-011: the
-  // arrival above auto-slown the sim to 1×, so re-set SCALE for the return leg.
+  // Restore: fly home (repositioning — no package needed in the v0.12.0 model). ISS-041: the
+  // arrival above paused the sim, so re-set SCALE for the return leg (setScale clears pause).
  await setScale(page, SCALE);
  const homeRes = await page.request.post(`/api/planes/${planeId}/fly`, { data: { destIcao: HUB } });
  expect(homeRes.ok()).toBeTruthy();
@@ -314,8 +316,8 @@ test('expired packages deliver and abandon with no reward and no penalty', async
  expect(s.packages.find((p) => p.id === pkgB.id)!.status).toBe('abandoned');
  expect(s.account.cash).toBe(cashBeforeAbandon); // free — expired abandons cost nothing

-  // Restore: refuel + fly home. ISS-011: the LEMD arrival above auto-slown the sim to 1×, so
-  // re-set SCALE for the return leg (the expiry wait's scale no longer persists past a landing).
+  // Restore: refuel + fly home. ISS-041: the LEMD arrival above paused the sim, so
+  // re-set SCALE for the return leg (setScale clears pause; the expiry wait's scale is kept).
  await page.request.post('/api/planes/plane-starter/refuel');
  await setScale(page, SCALE);
  const homeRes = await page.request.post('/api/planes/plane-starter/fly', { data: { destIcao: HUB } });
@@ -355,8 +357,8 @@ test('load and fly validation paths (404 / 409 / 400)', async ({ page }) => {
  res = await page.request.post(`/api/packages/${pkg.id}/abandon`);
  expect(res.status()).toBe(409);

-  // Fly home from the hop so the fuel section starts at the hub. ISS-011: the hop arrival above
-  // auto-slown the sim to 1×, so re-set SCALE for this leg.
+  // Fly home from the hop so the fuel section starts at the hub. ISS-041: the hop arrival above
+  // paused the sim, so re-set SCALE for this leg (setScale clears pause).
  await setScale(page, SCALE);
  res = await page.request.post('/api/planes/plane-starter/fly', { data: { destIcao: HUB } });
  expect(res.ok()).toBeTruthy();
@@ -380,7 +382,7 @@ test('load and fly validation paths (404 / 409 / 400)', async ({ page }) => {
  const atFar = sFar.planes.find((p) => p.id === 'plane-starter')!;
  expect(atFar.locationIcao).toBe(FAR);
  // The return leg fits: the weighted burn over it is less than what's left in the tank.
-  // ISS-011: the FAR arrival above auto-slown the sim to 1×, so re-set SCALE for this leg.
+  // ISS-041: the FAR arrival above paused the sim, so re-set SCALE for this leg (setScale clears pause).
  await setScale(page, SCALE);
  const backRes = await page.request.post('/api/planes/plane-starter/fly', { data: { destIcao: HUB } });
  expect(backRes.ok()).toBeTruthy();
@@ -13,7 +13,7 @@ test('GET /api/version returns the app version from package.json', async ({ page
  expect(body.version).toBe(pkg.version);
 });

-test('GET /api/openapi serves the spec with all ten endpoints and the package.json version', async ({ page }) => {
+test('GET /api/openapi serves the spec with all twelve endpoints and the package.json version', async ({ page }) => {
  const res = await page.request.get('/api/openapi');
  expect(res.status()).toBe(200);
  expect(res.headers()['content-type']).toContain('application/json');
@@ -28,6 +28,8 @@ test('GET /api/openapi serves the spec with all ten endpoints and the package.js
    '/api/packages/{id}/abandon',
    '/api/packages/{id}/load',
    '/api/planes/{planeId}/fly',
+    '/api/planes/{planeId}/queue',
+    '/api/planes/{planeId}/queue/cancel',
    '/api/planes/{planeId}/refuel',
    '/api/sim',
    '/api/state',
@@ -24,6 +24,8 @@ interface PlaneState {
  maxFuel: number;
  locationIcao: string;
  destIcao: string | null;
+  lat: number; // live position — interpolated per snapshot while flying, airport coords when grounded
+  lon: number;
 }

 interface PackageState {
@@ -53,9 +55,10 @@ async function postSim(page: Page, body: unknown) {
 }

 // Set the time scale and VERIFY from the response that it stuck — a silent reset would
-// otherwise surface as an unexplained landing-wait timeout.
+// otherwise surface as an unexplained landing-wait timeout. ISS-041 also clears pause: a
+// landing pauses the sim, so any fast-forward after one must resume it or the clock stays frozen.
 async function setScale(page: Page, scale: number): Promise<void> {
-  const res = await page.request.post('/api/sim', { data: { timeScale: scale } });
+  const res = await page.request.post('/api/sim', { data: { timeScale: scale, paused: false } });
  expect(res.status()).toBe(200);
  const body = (await res.json()) as { timeScale: number };
  expect(body.timeScale, `timeScale should be ${scale} after POST /api/sim`).toBe(scale);
@@ -93,7 +96,7 @@ async function flyHomeViaApi(page: Page): Promise<void> {
      .toBe(true);
  }
  if (starter.locationIcao !== HUB) {
-    // ISS-011: the landing above auto-slown the sim to 1× — re-set SCALE so the return leg
+    // ISS-041: the landing above paused the sim — setScale clears pause so the return leg
    // fast-forwards instead of taking real-time hours.
    await setScale(page, SCALE);
    const res = await page.request.post('/api/planes/plane-starter/fly', { data: { destIcao: HUB } });
@@ -485,7 +488,99 @@ test('hovering an on-board block of a flying plane highlights its route', async
    }, { timeout: 120_000, message: `waiting for plane-starter to land at ${DEST}` })
    .toBe(true);

-  // ISS-011: the arrival above auto-slown the sim to 1×, so re-set SCALE for this leg.
+  // ISS-041: the arrival above paused the sim, so re-set SCALE for this leg (setScale clears pause).
+  await setScale(page, SCALE);
+  const home = await page.request.post('/api/planes/plane-starter/fly', { data: { destIcao: HUB } });
+  expect(home.status()).toBe(200);
+  await expect
+    .poll(async () => (await getState(page)).planes.find((p) => p.id === 'plane-starter')?.locationIcao === HUB, {
+      timeout: 120_000,
+      message: 'waiting for plane-starter to land back at the hub',
+    })
+    .toBe(true);
+});
+
+test('hovering an on-board package while its carrier is mid-flight traces from current position', async ({ page }) => {
+  test.setTimeout(600_000); // self-heal + one flight at scale 1000 + fly-home cleanup
+  await flyHomeViaApi(page);
+
+  // Full tank before departure — the EDDF↔LEMD round trip burns ~4970 L of the 6300 L tank.
+  const refuel = await page.request.post('/api/planes/plane-starter/refuel');
+  expect(refuel.status()).toBe(200);
+
+  await page.goto('/');
+  await waitForAirportCount(page);
+
+  // Load + fly via the API (same pattern as e2e/map-interactions.spec.ts), then speed up.
+  const pkg = await createPackage(page, HUB, DEST);
+  const load = await page.request.post(`/api/packages/${pkg.id}/load`, { data: { planeId: 'plane-starter' } });
+  expect(load.status()).toBe(200);
+  const fly = await page.request.post('/api/planes/plane-starter/fly', { data: { destIcao: DEST } });
+  expect(fly.status()).toBe(200);
+  await setScale(page, SCALE);
+
+  // Wait until the starter is GENUINELY mid-flight — its live position clearly away from EDDF in
+  // both axes (well past HOVER_ROUTE_EPS_DEG) so "the trace starts at the plane" and "it starts at
+  // the pickup airport" are distinguishable. The ~10 s leg at scale 1000 gives a wide window.
+  const hubLonLat = await airportLonLat(page, HUB);
+  await expect
+    .poll(async () => {
+      const p = (await getState(page)).planes.find((x) => x.id === 'plane-starter');
+      if (!p || p.status !== 'flying') return false;
+      return Math.abs(p.lon - hubLonLat[0]) > 0.2 && Math.abs(p.lat - hubLonLat[1]) > 0.2;
+    }, { timeout: 60_000, message: 'waiting for plane-starter to be clearly away from the hub' })
+    .toBe(true);
+
+  // Freeze mid-flight so the position is stable while we assert (same pause pattern as the
+  // flying-plane hover test above): paused, every /api/state snapshot reports the same lat/lon.
+  await postSim(page, { paused: true });
+
+  const row = page.locator(`[data-testid="onboard-package-${pkg.id}"]`);
+  await expect(row, 'the loaded package appears in the On board section').toBeVisible({ timeout: 15_000 });
+
+  // Both endpoints must be in-viewport for queryRenderedFeatures to see the trace.
+  await fitToAirports(page, [HUB, DEST]);
+
+  const live = (await getState(page)).planes.find((x) => x.id === 'plane-starter')!;
+  const liveLonLat: [number, number] = [live.lon, live.lat]; // stable — the sim is paused
+  const destLonLat = await airportLonLat(page, DEST);
+
+  await row.hover();
+  // ISS-040 (v0.23.2): the trace starts at the carrier's LIVE position and ends at the destination,
+  // and NO segment may start near the pickup airport (the old origin-based behavior). Same per-tile
+  // clipping/quantization caveats as expectHoverRoute — check endpoints across all segments with EPS.
+  await expect.poll(async () => {
+    const feats = (await renderedFeatures(page, ['hover-route'])) as Array<{ geometry?: { type: string; coordinates: [number, number][] } }>;
+    const segs = feats.filter(
+      (f): f is { geometry: { type: 'LineString'; coordinates: [number, number][] } } =>
+        !!f.geometry && f.geometry.type === 'LineString' && Array.isArray(f.geometry.coordinates) && f.geometry.coordinates.length >= 2,
+    );
+    if (!segs.length) return false;
+    const near = (a: [number, number], b: [number, number]) =>
+      Math.abs(a[0] - b[0]) <= HOVER_ROUTE_EPS_DEG && Math.abs(a[1] - b[1]) <= HOVER_ROUTE_EPS_DEG;
+    const startsAtLive = segs.some((f) => near(f.geometry.coordinates[0], liveLonLat));
+    const endsAtDest = segs.some((f) => near(f.geometry.coordinates[f.geometry.coordinates.length - 1], destLonLat));
+    const noneStartsAtHub = !segs.some((f) => near(f.geometry.coordinates[0], hubLonLat));
+    return startsAtLive && endsAtDest && noneStartsAtHub;
+  }, { timeout: 15_000, message: 'waiting for the hover-route trace to run from the live position to the destination' }).toBe(true);
+
+  await unhover(page);
+  await expect.poll(async () => (await renderedFeatures(page, ['hover-route'])).length, {
+    timeout: 15_000,
+    message: 'waiting for the hover route trace to clear after mouseleave',
+  }).toBe(0);
+
+  // Resume and fast-forward to arrival — landing at DEST auto-delivers the package (v0.12.0), so
+  // flying home afterwards leaves the starter clean for the other specs.
+  await postSim(page, { timeScale: SCALE, paused: false });
+  await expect
+    .poll(async () => {
+      const p = (await getState(page)).planes.find((x) => x.id === 'plane-starter');
+      return !!p && p.status === 'available' && p.locationIcao === DEST;
+    }, { timeout: 120_000, message: `waiting for plane-starter to land at ${DEST}` })
+    .toBe(true);
+
+  // ISS-041: the arrival above paused the sim, so re-set SCALE for this leg (setScale clears pause).
  await setScale(page, SCALE);
  const home = await page.request.post('/api/planes/plane-starter/fly', { data: { destIcao: HUB } });
  expect(home.status()).toBe(200);
@@ -69,9 +69,10 @@ async function postSim(page: Page, body: unknown) {
 }

 // Set the time scale and VERIFY from the response that it stuck — a silent reset would
-// otherwise surface as an unexplained landing-wait timeout.
+// otherwise surface as an unexplained landing-wait timeout. ISS-041 also clears pause: a
+// landing pauses the sim, so any fast-forward after one must resume it or the clock stays frozen.
 async function setScale(page: Page, scale: number): Promise<void> {
-  const res = await page.request.post('/api/sim', { data: { timeScale: scale } });
+  const res = await page.request.post('/api/sim', { data: { timeScale: scale, paused: false } });
  expect(res.status()).toBe(200);
  const body = (await res.json()) as { timeScale: number };
  expect(body.timeScale, `timeScale should be ${scale} after POST /api/sim`).toBe(scale);
@@ -1,10 +1,11 @@
 import type { Page } from '@playwright/test';
 import { expect, test } from '@playwright/test';

-// v0.19.0 — ISS-011: when the LAST plane lands (no plane remains in flight) the sim auto-slows
-// to 1×, server-side and persisted on the sim_state row so the UI slider reflects it on the next
-// snapshot. Arrival-triggered by design: a grounded fleet at high scale is left alone, there is no
-// auto-restore — the player speeds up manually again (asserted below).
+// v0.24.0 — ISS-041: when the LAST plane lands (no plane remains in flight) the sim pauses
+// server-side WITHOUT touching timeScale (speed is preserved), and starting a flight
+// (POST /api/planes/{id}/fly) auto-resumes a paused sim. The cycle: dispatch unpauses →
+// last landing pauses → next dispatch unpauses again. Arrival-triggered by design: a grounded
+// fleet at high scale is left alone, there is no idle-enforcement or auto-restore of pause.

 const SCALE = 1000; // fastest sim speed — top of the v0.14.0 ladder (same convention as e2e/sim.spec.ts)
 const HUB = 'EDDF'; // Frankfurt Main — the seeded starter plane's home base (lib/game/seed.ts)
@@ -33,8 +34,10 @@ async function postSim(page: Page, body: Record<string, unknown>): Promise<void>

 // Set the time scale and VERIFY from the response that it stuck — if something external ever
 // resets the live instance's controls mid-test, fail loudly here instead of timing out later.
+// ISS-041 also clears pause: a landing pauses the sim, so any fast-forward after one must
+// resume it or the clock stays frozen and the next wait hangs.
 async function setScale(page: Page, scale: number): Promise<void> {
-  const res = await page.request.post('/api/sim', { data: { timeScale: scale } });
+  const res = await page.request.post('/api/sim', { data: { timeScale: scale, paused: false } });
  expect(res.status()).toBe(200);
  const body = (await res.json()) as SimState;
  expect(body.timeScale, `timeScale should be ${scale} after POST /api/sim`).toBe(scale);
@@ -75,7 +78,7 @@ async function flyHomeViaApi(page: Page): Promise<void> {
    plane = s.planes.find((p) => p.id === 'plane-starter')!;
  }
  if (plane.locationIcao !== HUB) {
-    // ISS-011: the landing above auto-slown the sim to 1× — re-set SCALE so the return leg
+    // ISS-041: the landing above paused the sim — setScale clears pause so the return leg
    // fast-forwards instead of taking real-time hours.
    await setScale(page, SCALE);
    const res = await page.request.post(`/api/planes/${plane.id}/fly`, { data: { destIcao: HUB } });
@@ -93,8 +96,8 @@ test.afterEach(async ({ page }) => {

 test.describe.configure({ mode: 'serial' }); // shared live DB — order matters within this file

-test('auto-slow to 1× when the last plane lands; manual speed-up still works (ISS-011)', async ({ page }) => {
-  test.setTimeout(300_000); // self-heal (worst case ~20 s at 1000×) + one short leg
+test('last landing pauses the sim without changing speed; dispatch auto-resumes (ISS-041)', async ({ page }) => {
+  test.setTimeout(300_000); // self-heal (worst case ~20 s at 1000×) + two short legs
  await flyHomeViaApi(page); // deterministic: the starter sits grounded at EDDF

  const nearest = await nearestToHub(page);
@@ -117,14 +120,19 @@ test('auto-slow to 1× when the last plane lands; manual speed-up still works (I
    }, { timeout: 120_000, message: `waiting for plane-starter to land at ${nearest.icao}` })
    .toBe(true);

-  // …and the server has auto-slown to 1× — persisted on sim_state, so this very snapshot shows it.
-  expect(landedBody!.simState.timeScale).toBe(1);
+  // …and the server paused the sim — persisted on sim_state, so this very snapshot shows it…
+  expect(landedBody!.simState.paused).toBe(true);
+  // …with timeScale UNCHANGED (no auto-slow anymore): speed is preserved for the next dispatch.
+  expect(landedBody!.simState.timeScale).toBe(SCALE);

-  // Manual override still works: POST /api/sim {timeScale: 1000} → confirmed by the response…
-  const post = await page.request.post('/api/sim', { data: { timeScale: SCALE } });
-  expect(post.status()).toBe(200);
-  expect(((await post.json()) as SimState).timeScale).toBe(SCALE);
-  // …and by a fresh snapshot (no auto-restore of the previous scale — and no re-slow either,
-  // since nothing is in flight: the trigger is arrival-based, not idle-enforcement).
-  expect((await getState(page)).simState.timeScale).toBe(SCALE);
+  // A subsequent /fly dispatch auto-resumes a paused sim — asserted on the endpoint's OWN full
+  // post-action snapshot, so no poll race with the client's next tick.
+  const fly2 = await page.request.post('/api/planes/plane-starter/fly', { data: { destIcao: HUB } });
+  expect(fly2.status()).toBe(200);
+  const resumedBody = (await fly2.json()) as StateBody;
+  expect(resumedBody.simState.paused).toBe(false); // ISS-041 auto-unpause…
+  expect(resumedBody.simState.timeScale).toBe(SCALE); // …with the preserved speed still in effect
+
+  // Let the return leg finish so cleanup starts from a grounded plane.
+  await expect.poll(async () => ((await getState(page)).planes.find((p) => p.id === 'plane-starter')!.status), { timeout: 120_000 }).toBe('available');
 });
@@ -31,8 +31,10 @@ async function postSim(page: Page, body: Record<string, unknown>): Promise<void>

 // Set the time scale and VERIFY from the response that it stuck — if something external ever
 // resets the live instance's controls mid-test, fail loudly here instead of timing out later.
+// ISS-041 also clears pause: a landing pauses the sim, so any fast-forward after one must
+// resume it or the clock stays frozen and the next wait hangs.
 async function setScale(page: Page, scale: number): Promise<void> {
-  const res = await page.request.post('/api/sim', { data: { timeScale: scale } });
+  const res = await page.request.post('/api/sim', { data: { timeScale: scale, paused: false } });
  expect(res.status()).toBe(200);
  const body = (await res.json()) as { timeScale: number };
  expect(body.timeScale, `timeScale should be ${scale} after POST /api/sim`).toBe(scale);
@@ -72,7 +74,7 @@ async function flyHomeViaApi(page: Page): Promise<void> {
    plane = s.planes.find((p) => p.id === 'plane-starter')!;
  }
  if (plane.locationIcao !== HUB) {
-    // ISS-011: the landing above auto-slown the sim to 1× — re-set SCALE so the return leg
+    // ISS-041: the landing above paused the sim — setScale clears pause so the return leg
    // fast-forwards instead of taking real-time hours.
    await setScale(page, SCALE);
    const res = await page.request.post(`/api/planes/${plane.id}/fly`, { data: { destIcao: HUB } });
@@ -69,9 +69,10 @@ async function postSim(page: Page, body: unknown) {
 }

 // Set the time scale and VERIFY from the response that it stuck — a silent reset would
-// otherwise surface as an unexplained landing-wait timeout.
+// otherwise surface as an unexplained landing-wait timeout. ISS-041 also clears pause: a
+// landing pauses the sim, so any fast-forward after one must resume it or the clock stays frozen.
 async function setScale(page: Page, scale: number): Promise<void> {
-  const res = await page.request.post('/api/sim', { data: { timeScale: scale } });
+  const res = await page.request.post('/api/sim', { data: { timeScale: scale, paused: false } });
  expect(res.status()).toBe(200);
  const body = (await res.json()) as { timeScale: number };
  expect(body.timeScale, `timeScale should be ${scale} after POST /api/sim`).toBe(scale);
@@ -176,7 +177,7 @@ async function flyHomeViaApi(page: Page): Promise<void> {
      .toBe(true);
  }
  if (starter.locationIcao !== HUB) {
-    // ISS-011: the landing above auto-slown the sim to 1× — re-set SCALE so the return leg
+    // ISS-041: the landing above paused the sim — setScale clears pause so the return leg
    // fast-forwards instead of taking real-time hours.
    await setScale(page, SCALE);
    const res = await page.request.post('/api/planes/plane-starter/fly', { data: { destIcao: HUB } });
@@ -289,7 +290,7 @@ test('on-board list: fly-to-destination + abandon with penalty preview; flying p
  await expect(onboardRow).not.toBeVisible({ timeout: 15_000 });

  // Restore: fly home so the live instance stays in its onboarding state for the next run.
-  // ISS-011: the arrival above auto-slown the sim to 1×, so re-set SCALE for this leg.
+  // ISS-041: the arrival above paused the sim, so re-set SCALE for this leg (setScale clears pause).
  await setScale(page, SCALE);
  const homeRes = await page.request.post('/api/planes/plane-starter/fly', { data: { destIcao: HUB } });
  expect(homeRes.status()).toBe(200);
@@ -411,8 +412,8 @@ test('on-board row Refuel tops up just enough for the package leg; left-pane but
  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. ISS-011: the far-end
-  // arrival above auto-slown the sim to 1×, so re-set SCALE for this leg.
+  // exactly the leg requirement, so this also proves "just enough" is enough. ISS-041: the far-end
+  // arrival above paused the sim, so re-set SCALE for this leg (setScale clears pause).
  await setScale(page, SCALE);
  expect((await page.request.post('/api/planes/plane-starter/fly', { data: { destIcao: HUB } })).status()).toBe(200);
  await expect
@@ -30,7 +30,8 @@ CREATE TABLE IF NOT EXISTS planes (
  dest_icao TEXT,
  lat REAL NOT NULL,
  lon REAL NOT NULL,
-  departure_sim_time INTEGER
+  departure_sim_time INTEGER,
+  queue TEXT NOT NULL DEFAULT '[]'
 );
 CREATE TABLE IF NOT EXISTS packages (
  id TEXT PRIMARY KEY NOT NULL,
@@ -72,6 +73,10 @@ function migrateColumns(raw: RawSqlJsDatabase): void {
  if (!cols('planes').has('dest_icao')) {
    raw.exec('ALTER TABLE planes ADD COLUMN dest_icao TEXT');
  }
+  // v0.25.0 (ISS-043): the flight queue — ordered JSON array of not-yet-started leg ICACs.
+  if (!cols('planes').has('queue')) {
+    raw.exec(`ALTER TABLE planes ADD COLUMN queue TEXT NOT NULL DEFAULT '[]'`);
+  }
 }

 // v0.12.0 one-time migration: contracts world → packages world. Detected by the
@@ -159,7 +164,9 @@ async function seedEmpty(instance: GameDb): Promise<void> {
  const rng = mulberry32(randomInt(0, 2 ** 31));
  const data = buildSeed({ airports, rng, nowMs: Date.now() });

-  await instance.db.insert(schema.planes).values(data.plane);
+  // SeedPlane.queue is a string[]; the column stores it as JSON text.
+  const { queue, ...planeCols } = data.plane;
+  await instance.db.insert(schema.planes).values({ ...planeCols, queue: JSON.stringify(queue ?? []) });
  await instance.db.insert(schema.packages).values(data.packages);
  await instance.db.insert(schema.account).values(data.account);
  await instance.db.insert(schema.simState).values(data.simState);
@@ -20,6 +20,10 @@ export const planes = sqliteTable('planes', {
  // flying, `fuel` is frozen at its departure value — live position/fuel are pure
  // functions of the clock (lib/sim/movement.ts), recomputed on read.
  departureSimTime: integer('departure_sim_time'),
+  // Queue of upcoming legs NOT yet started (v0.25.0, ISS-043) — ordered JSON array
+  // of ICAO strings ('[]' when empty). The ACTIVE leg stays destIcao +
+  // departureSimTime; on landing the engine auto-chains queue[0] if fuel covers it.
+  queue: text('queue').notNull().default('[]'),
 });

 // Cargo packages (v0.12.0) replace the old contracts table end-to-end: a package
@@ -22,6 +22,7 @@ const basePlane = (id: string): PlaneState => ({
  departureSimTime: null,
  lat: 50.03,
  lon: 8.56,
+  queue: [],
 });

 const basePackage = (id: string): PackageState => ({
@@ -13,9 +13,11 @@ import { HUB_ICAO } from './seed';
 import {
  abandonPackage,
  buyPlane,
+  cancelQueuedLeg,
  flyPlane,
  GameActionError,
  loadPackage,
+  queueLeg,
  refuelPlane,
  sellPlane,
 } from './actions';
@@ -167,6 +169,18 @@ describe('flyPlane', () => {
    expect(plane.fuel).toBe(PLANE_TYPES.atr72.maxFuel);
  });

+  it('clears paused on dispatch (ISS-041) — speed is left untouched', async () => {
+    const inst = await freshDb('fly-unpause.db');
+    // The last landing pauses the sim at whatever scale was in use.
+    await inst.db.update(schema.simState).set({ paused: true, timeScale: 250 });
+
+    await flyPlane(inst, 'plane-starter', 'LEMD');
+
+    const sim = (await inst.db.select().from(schema.simState))[0];
+    expect(sim.paused).toBe(false); // dispatch auto-resumes…
+    expect(sim.timeScale).toBe(250); // …with the stored speed preserved
+  });
+
  it('rejects a flying plane with 409', async () => {
    const inst = await freshDb('fly-flying.db');
    await inst.db.update(schema.planes)
@@ -194,6 +208,75 @@ describe('flyPlane', () => {
  });
 });

+describe('queueLeg (v0.25.0, ISS-043)', () => {
+  it('appends legs to the queue in order and persists them as JSON', async () => {
+    const inst = await freshDb('qleg-ok.db');
+
+    await queueLeg(inst, 'plane-starter', 'LEMD');
+    let plane = (await inst.db.select().from(schema.planes))[0];
+    expect(JSON.parse(plane.queue)).toEqual(['LEMD']);
+
+    await queueLeg(inst, 'plane-starter', 'EHAM'); // pre-building a route
+    plane = (await inst.db.select().from(schema.planes))[0];
+    expect(JSON.parse(plane.queue)).toEqual(['LEMD', 'EHAM']); // order preserved
+  });
+
+  it('works on a flying plane too — the active leg is untouched, nothing auto-starts', async () => {
+    const inst = await freshDb('qleg-flying.db');
+    await inst.db.update(schema.planes)
+      .set({ status: 'flying', departureSimTime: T0, destIcao: 'LEMD' })
+      .where(eq(schema.planes.id, 'plane-starter'));
+
+    await queueLeg(inst, 'plane-starter', 'EHAM');
+
+    const plane = (await inst.db.select().from(schema.planes))[0];
+    expect(plane.status).toBe('flying'); // still on its active leg…
+    expect(plane.destIcao).toBe('LEMD'); // …unchanged — queueing never starts a flight
+    expect(JSON.parse(plane.queue)).toEqual(['EHAM']);
+  });
+
+  it('rejects an unknown plane id with 404', async () => {
+    const inst = await freshDb('qleg-ghost.db');
+    await expectActionError(queueLeg(inst, 'ghost', 'LEMD'), 404);
+  });
+
+  it('rejects an ICAO not in the airport dataset with 400', async () => {
+    const inst = await freshDb('qleg-unknownicao.db');
+    await expectActionError(queueLeg(inst, 'plane-starter', 'ZZZZ'), 400, /unknown airport/);
+  });
+});
+
+describe('cancelQueuedLeg (v0.25.0, ISS-043)', () => {
+  it('removes the leg at the given index and keeps the rest in order', async () => {
+    const inst = await freshDb('qcancel-ok.db');
+    await queueLeg(inst, 'plane-starter', 'LEMD');
+    await queueLeg(inst, 'plane-starter', 'EHAM');
+    await queueLeg(inst, 'plane-starter', 'EDDV');
+
+    await cancelQueuedLeg(inst, 'plane-starter', 1); // drop EHAM (the middle leg)
+
+    const plane = (await inst.db.select().from(schema.planes))[0];
+    expect(JSON.parse(plane.queue)).toEqual(['LEMD', 'EDDV']);
+  });
+
+  it('rejects an out-of-range index with 400', async () => {
+    const inst = await freshDb('qcancel-oob.db');
+    await queueLeg(inst, 'plane-starter', 'LEMD'); // one leg → only index 0 is valid
+    await expectActionError(cancelQueuedLeg(inst, 'plane-starter', 1), 400);
+    await expectActionError(cancelQueuedLeg(inst, 'plane-starter', -1), 400);
+  });
+
+  it('rejects cancelling from an empty queue with 400', async () => {
+    const inst = await freshDb('qcancel-empty.db'); // seeded starter has no queued legs
+    await expectActionError(cancelQueuedLeg(inst, 'plane-starter', 0), 400);
+  });
+
+  it('rejects an unknown plane id with 404', async () => {
+    const inst = await freshDb('qcancel-ghost.db');
+    await expectActionError(cancelQueuedLeg(inst, 'ghost', 0), 404);
+  });
+});
+
 describe('abandonPackage', () => {
  // A loaded package created at T0 with a 10h window; the seeded sim clock is T0.
  const REWARD = 1_000;
@@ -6,7 +6,7 @@ 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 { getStateSnapshot, parseIcaoQueue } from './state';
 import { FUEL_PRICE_PER_L, PLANE_TYPES, SELL_FRACTION } from './catalog';
 import { abandonPenalty } from './penalty';
 import { HUB_ICAO } from './seed';
@@ -125,6 +125,51 @@ export async function flyPlane(inst: GameDb, planeId: string, destIcao: string):
      lon: origin.lon,
    })
    .where(eq(schema.planes.id, planeId));
+  // ISS-041: starting a flight resumes a paused sim (the last landing pauses it). Runs inside
+  // runAction(), so tick + unpause + dispatch are atomic under the sim lock.
+  await inst.db.update(schema.simState).set({ paused: false });
+  await persist(inst);
+}
+
+// --- Queue (POST /api/planes/:id/queue {destIcao}) — ISS-043 part 1 ---
+
+// Append a NOT-yet-started leg to the plane's queue. Works whether the plane is
+// grounded or flying (you can pre-build a route); nothing auto-starts here — the
+// active leg still starts via flyPlane, and queued legs chain on landing when fuel
+// covers them (lib/sim/engine.ts deliverPackages). Validation: known plane, ICAO
+// in the airport dataset.
+export async function queueLeg(inst: GameDb, planeId: string, destIcao: string): Promise<void> {
+  const planeRows = await inst.db.select().from(schema.planes).where(eq(schema.planes.id, planeId));
+  const plane = planeRows[0];
+  if (!plane) throw new GameActionError(404, `plane ${planeId} not found`);
+
+  const fc = await loadAirportsGeoJson();
+  if (!fc.features.some((f) => f.properties.icao === destIcao)) {
+    throw new GameActionError(400, `unknown airport ${destIcao}`);
+  }
+
+  const queue = parseIcaoQueue(plane.queue);
+  queue.push(destIcao);
+  await inst.db.update(schema.planes).set({ queue: JSON.stringify(queue) }).where(eq(schema.planes.id, planeId));
+  await persist(inst);
+}
+
+// --- Queue cancel (POST /api/planes/:id/queue/cancel {index}) — ISS-043 part 1 ---
+
+// Remove a NOT-yet-started leg from the queue by index. Only queued legs are
+// cancellable — the active in-flight leg (destIcao) is never affected. Validation:
+// known plane, integer index within [0, queue.length).
+export async function cancelQueuedLeg(inst: GameDb, planeId: string, index: number): Promise<void> {
+  const planeRows = await inst.db.select().from(schema.planes).where(eq(schema.planes.id, planeId));
+  const plane = planeRows[0];
+  if (!plane) throw new GameActionError(404, `plane ${planeId} not found`);
+
+  const queue = parseIcaoQueue(plane.queue);
+  if (index < 0 || index >= queue.length) {
+    throw new GameActionError(400, `queue index ${index} out of range — the queue holds ${queue.length} legs`);
+  }
+  queue.splice(index, 1);
+  await inst.db.update(schema.planes).set({ queue: JSON.stringify(queue) }).where(eq(schema.planes.id, planeId));
  await persist(inst);
 }

@@ -44,6 +44,7 @@ describe('buildSeed', () => {
      destIcao: null,
      lat: 50.0333,
      lon: 8.5706,
+      queue: [], // v0.25.0 (ISS-043) — no queued legs on first run
    });
  });

@@ -38,6 +38,9 @@ export interface SeedPlane {
  destIcao: null;
  lat: number;
  lon: number;
+  // Upcoming legs not yet started (v0.25.0, ISS-043) — serialized to the queue
+  // column as JSON text on insert; defaults to an empty queue.
+  queue?: string[];
 }

 export interface SeedPackage {
@@ -182,6 +185,7 @@ export function buildSeed(input: {
    destIcao: null,
    lat: hub.lat,
    lon: hub.lon,
+    queue: [], // no queued legs on first run (v0.25.0)
  };

  const count = PACKAGE_COUNT_MIN + Math.floor(rng() * (PACKAGE_COUNT_MAX - PACKAGE_COUNT_MIN + 1));
@@ -24,6 +24,21 @@ export interface PlaneState {
  departureSimTime: number | null;
  lat: number;
  lon: number;
+  // Upcoming legs NOT yet started (v0.25.0, ISS-043) — ordered ICAOs; the active
+  // leg is destIcao. The engine auto-chains queue[0] on landing when fuel covers it.
+  queue: string[];
+}
+
+// Parse the planes.queue JSON column into an ICAO list (v0.25.0). Guards against
+// null/empty/malformed values so a corrupt cell can never break a snapshot or tick.
+export function parseIcaoQueue(raw: string | null): string[] {
+  if (!raw) return [];
+  try {
+    const v: unknown = JSON.parse(raw);
+    return Array.isArray(v) ? v.filter((x): x is string => typeof x === 'string') : [];
+  } catch {
+    return [];
+  }
 }

 export interface PackageState {
@@ -108,6 +123,7 @@ export async function getStateSnapshot(): Promise<StateSnapshot> {
        departureSimTime: p.departureSimTime,
        lat: live?.lat ?? p.lat,
        lon: live?.lon ?? p.lon,
+        queue: parseIcaoQueue(p.queue),
      };
    }),
    packages: packageRows.map((p) => ({
@@ -1,6 +1,6 @@
 import { describe, expect, it } from 'vitest';
 import type { StateSnapshot } from './game/state';
-import { planesGeoJson, routesGeoJson, hoverRouteGeoJson, greatCircleArc, ROUTE_ARC_SEGMENTS, type AirportCoord } from './mapData';
+import { planesGeoJson, routesGeoJson, hoverRouteGeoJson, hoverTraceGeoJson, greatCircleArc, ROUTE_ARC_SEGMENTS, type AirportCoord } from './mapData';
 import { haversineKm } from './geo';

 const AIRPORTS = new Map<string, AirportCoord>([
@@ -34,8 +34,8 @@ describe('planesGeoJson', () => {
    const fc = planesGeoJson(
      snapshot({
        planes: [
-          { id: 'plane-starter', model: 'atr72', status: 'available', fuel: 6300, maxFuel: 6300, locationIcao: 'EDDF', locationName: 'Frankfurt Main Airport', destIcao: null, destName: null, departureSimTime: null, lat: 50.03, lon: 8.56 },
-          { id: 'plane-2', model: 'atr72', status: 'flying', fuel: 4000, maxFuel: 6300, locationIcao: 'EDDF', locationName: 'Frankfurt Main Airport', destIcao: 'EDDV', destName: 'Hannover Airport', departureSimTime: 1000, lat: 51.2, lon: 9.1 },
+          { id: 'plane-starter', model: 'atr72', status: 'available', fuel: 6300, maxFuel: 6300, locationIcao: 'EDDF', locationName: 'Frankfurt Main Airport', destIcao: null, destName: null, departureSimTime: null, lat: 50.03, lon: 8.56, queue: [] },
+          { id: 'plane-2', model: 'atr72', status: 'flying', fuel: 4000, maxFuel: 6300, locationIcao: 'EDDF', locationName: 'Frankfurt Main Airport', destIcao: 'EDDV', destName: 'Hannover Airport', departureSimTime: 1000, lat: 51.2, lon: 9.1, queue: [] },
        ],
      }),
    );
@@ -61,7 +61,7 @@ describe('planesGeoJson', () => {
      snapshot({
        catalog: [],
        planes: [
-          { id: 'p1', model: 'mystery', status: 'available', fuel: 1, maxFuel: 2, locationIcao: 'EDDF', locationName: 'x', destIcao: null, destName: null, departureSimTime: null, lat: 0, lon: 0 },
+          { id: 'p1', model: 'mystery', status: 'available', fuel: 1, maxFuel: 2, locationIcao: 'EDDF', locationName: 'x', destIcao: null, destName: null, departureSimTime: null, lat: 0, lon: 0, queue: [] },
        ],
      }),
    );
@@ -72,7 +72,7 @@ describe('planesGeoJson', () => {
    const fc = planesGeoJson(
      snapshot({
        planes: [
-          { id: 'p1', model: 'atr72', status: 'flying', fuel: 1, maxFuel: 2, locationIcao: 'EDDF', locationName: 'x', destIcao: null, destName: null, departureSimTime: 0, lat: 0, lon: 0 },
+          { id: 'p1', model: 'atr72', status: 'flying', fuel: 1, maxFuel: 2, locationIcao: 'EDDF', locationName: 'x', destIcao: null, destName: null, departureSimTime: 0, lat: 0, lon: 0, queue: [] },
        ],
      }),
    );
@@ -89,7 +89,7 @@ describe('routesGeoJson (v0.12.0 — one line per flying plane\'s current leg)',
    const fc = routesGeoJson(
      snapshot({
        planes: [
-          { id: 'p1', model: 'atr72', status: 'available', fuel: 1, maxFuel: 2, locationIcao: 'EDDF', locationName: 'F', destIcao: null, destName: null, departureSimTime: null, lat: 50.03, lon: 8.56 },
+          { id: 'p1', model: 'atr72', status: 'available', fuel: 1, maxFuel: 2, locationIcao: 'EDDF', locationName: 'F', destIcao: null, destName: null, departureSimTime: null, lat: 50.03, lon: 8.56, queue: [] },
        ],
      }),
      AIRPORTS,
@@ -101,7 +101,7 @@ describe('routesGeoJson (v0.12.0 — one line per flying plane\'s current leg)',
    const fc = routesGeoJson(
      snapshot({
        planes: [
-          { id: 'p1', model: 'atr72', status: 'flying', fuel: 1, maxFuel: 2, locationIcao: 'EDDF', locationName: 'F', destIcao: 'EHAM', destName: 'A', departureSimTime: 0, lat: 51, lon: 9 },
+          { id: 'p1', model: 'atr72', status: 'flying', fuel: 1, maxFuel: 2, locationIcao: 'EDDF', locationName: 'F', destIcao: 'EHAM', destName: 'A', departureSimTime: 0, lat: 51, lon: 9, queue: [] },
        ],
      }),
      AIRPORTS,
@@ -118,7 +118,7 @@ describe('routesGeoJson (v0.12.0 — one line per flying plane\'s current leg)',
    const fc = routesGeoJson(
      snapshot({
        planes: [
-          { id: 'p1', model: 'atr72', status: 'flying', fuel: 1, maxFuel: 2, locationIcao: 'ZZZZ', locationName: '?', destIcao: 'EDDV', destName: 'H', departureSimTime: 0, lat: 0, lon: 0 },
+          { id: 'p1', model: 'atr72', status: 'flying', fuel: 1, maxFuel: 2, locationIcao: 'ZZZZ', locationName: '?', destIcao: 'EDDV', destName: 'H', departureSimTime: 0, lat: 0, lon: 0, queue: [] },
        ],
      }),
      AIRPORTS,
@@ -130,8 +130,8 @@ describe('routesGeoJson (v0.12.0 — one line per flying plane\'s current leg)',
    const fc = routesGeoJson(
      snapshot({
        planes: [
-          { id: 'p1', model: 'atr72', status: 'flying', fuel: 1, maxFuel: 2, locationIcao: 'EDDF', locationName: 'F', destIcao: 'EDDV', destName: 'H', departureSimTime: 0, lat: 51, lon: 9 },
-          { id: 'p2', model: 'atr72', status: 'flying', fuel: 1, maxFuel: 2, locationIcao: 'EDDV', locationName: 'H', destIcao: 'EHAM', destName: 'A', departureSimTime: 0, lat: 52.4, lon: 9.6 },
+          { id: 'p1', model: 'atr72', status: 'flying', fuel: 1, maxFuel: 2, locationIcao: 'EDDF', locationName: 'F', destIcao: 'EDDV', destName: 'H', departureSimTime: 0, lat: 51, lon: 9, queue: [] },
+          { id: 'p2', model: 'atr72', status: 'flying', fuel: 1, maxFuel: 2, locationIcao: 'EDDV', locationName: 'H', destIcao: 'EHAM', destName: 'A', departureSimTime: 0, lat: 52.4, lon: 9.6, queue: [] },
        ],
      }),
      AIRPORTS,
@@ -176,6 +176,23 @@ describe('hoverRouteGeoJson (ISS-022/025/027 v0.22.0 — hover route trace)', ()
  });
 });

+describe('hoverTraceGeoJson (ISS-040 v0.23.2 — on-board package trace from the carrier\'s live position)', () => {
+  it('draws one great-circle line from the given start coord to the dest airport with exact endpoints', () => {
+    const from = { lat: 51.2, lon: 9.1 }; // a mid-flight position — not an airport
+    const fc = hoverTraceGeoJson(from, 'EHAM', AIRPORTS);
+    expect(fc.features).toHaveLength(1);
+    expect(fc.features[0].properties).toEqual({ planeId: '' }); // pure overlay — no owning plane
+    const coords = fc.features[0].geometry.coordinates;
+    expect(coords.length).toBe(ROUTE_ARC_SEGMENTS + 1); // sampled arc, not a 2-point chord
+    expect(coords[0]).toEqual([9.1, 51.2]); // live start — exact endpoint
+    expect(coords[coords.length - 1]).toEqual([4.76, 52.31]); // EHAM — exact endpoint
+  });
+
+  it('returns an empty collection when the dest airport is missing from the dataset', () => {
+    expect(hoverTraceGeoJson({ lat: 0, lon: 0 }, 'ZZZZ', AIRPORTS)).toEqual({ type: 'FeatureCollection', features: [] });
+  });
+});
+
 describe('greatCircleArc (v0.12.2 — curved route traces)', () => {
  it('samples >2 points with the endpoints exactly at the airport coords', () => {
    const arc = greatCircleArc(AIRPORTS.get('EDDF')!, AIRPORTS.get('EHAM')!);
@@ -112,6 +112,32 @@ export function hoverRouteGeoJson(
  };
 }

+// ISS-040 (v0.23.2): the on-board package hover trace — same shape as hoverRouteGeoJson but the
+// start is a live COORDINATE (the carrier plane's current position), not an airport ICAO: once the
+// plane has departed with cargo still loaded, the preview must begin where it actually is. Empty
+// collection when the destination is missing from the dataset — never guessed.
+export function hoverTraceGeoJson(
+  from: AirportCoord,
+  toIcao: string,
+  airportsByIcao: ReadonlyMap<string, AirportCoord>,
+): FeatureCollection<MapLineFeature> {
+  const to = airportsByIcao.get(toIcao);
+  if (!to) return EMPTY_LINES;
+  return {
+    type: 'FeatureCollection',
+    features: [
+      {
+        type: 'Feature',
+        geometry: {
+          type: 'LineString',
+          coordinates: greatCircleArc(from, to),
+        },
+        properties: { planeId: '' }, // no owning plane — a pure hover overlay
+      },
+    ],
+  };
+}
+
 // One LineString per FLYING plane — its current leg from locationIcao to dest_icao.
 // Grounded planes draw nothing; a flying plane missing either endpoint from the
 // dataset is skipped, never guessed. The line is sampled along the great circle
@@ -3,7 +3,7 @@ import { describe, expect, it } from 'vitest';
 import { openApiSpec } from './openapi';

 describe('OpenAPI spec', () => {
-  it('documents exactly the ten public endpoints (4 read + 6 player actions)', () => {
+  it('documents exactly the twelve public endpoints (4 read + 8 player actions)', () => {
    expect(Object.keys(openApiSpec.paths).sort()).toEqual([
      '/api/airports',
      '/api/market/buy-plane',
@@ -11,6 +11,8 @@ describe('OpenAPI spec', () => {
      '/api/packages/{id}/abandon',
      '/api/packages/{id}/load',
      '/api/planes/{planeId}/fly',
+      '/api/planes/{planeId}/queue', // v0.25.0 (ISS-043)
+      '/api/planes/{planeId}/queue/cancel', // v0.25.0 (ISS-043)
      '/api/planes/{planeId}/refuel',
      '/api/sim',
      '/api/state',
@@ -120,6 +122,7 @@ describe('OpenAPI spec', () => {
      'lon',
      'maxFuel',
      'model',
+      'queue', // v0.25.0 (ISS-043) — upcoming legs not yet started
      'status',
    ]);

@@ -169,7 +172,7 @@ describe('OpenAPI spec', () => {
    expect(Object.keys(error)).toEqual(['error']);
  });

-  it('documents the six action endpoints: snapshot on 200, Error on their 4xx paths', () => {
+  it('documents the eight action endpoints: snapshot on 200, Error on their 4xx paths', () => {
    // The spec object is a literal type; these helpers view it as plain JSON.
    const post = (p: string) =>
      ((openApiSpec.paths as Record<string, { post?: unknown }>)[p]?.post ?? {}) as {
@@ -183,6 +186,8 @@ describe('OpenAPI spec', () => {
      '/api/packages/{id}/load',
      '/api/packages/{id}/abandon',
      '/api/planes/{planeId}/fly',
+      '/api/planes/{planeId}/queue', // v0.25.0 (ISS-043)
+      '/api/planes/{planeId}/queue/cancel', // v0.25.0 (ISS-043)
      '/api/market/buy-plane',
      '/api/market/sell-plane',
      '/api/planes/{planeId}/refuel',
@@ -196,6 +201,8 @@ describe('OpenAPI spec', () => {
    expect(errorCodes('/api/packages/{id}/load')).toEqual(['400', '404', '409']);
    expect(errorCodes('/api/packages/{id}/abandon')).toEqual(['404', '409']);
    expect(errorCodes('/api/planes/{planeId}/fly')).toEqual(['400', '404', '409']);
+    expect(errorCodes('/api/planes/{planeId}/queue')).toEqual(['400', '404']); // v0.25.0 — no 409: queueing works grounded or flying
+    expect(errorCodes('/api/planes/{planeId}/queue/cancel')).toEqual(['400', '404']); // v0.25.0
    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(['400', '404', '409']); // v0.16.0 optional body
@@ -208,6 +215,12 @@ describe('OpenAPI spec', () => {
    expect(post('/api/planes/{planeId}/fly').requestBody?.content['application/json'].schema.$ref).toBe(
      '#/components/schemas/FlyPlaneRequest',
    );
+    expect(post('/api/planes/{planeId}/queue').requestBody?.content['application/json'].schema.$ref).toBe(
+      '#/components/schemas/QueueLegRequest', // v0.25.0 (ISS-043)
+    );
+    expect(post('/api/planes/{planeId}/queue/cancel').requestBody?.content['application/json'].schema.$ref).toBe(
+      '#/components/schemas/CancelQueuedLegRequest', // v0.25.0 (ISS-043)
+    );
    expect(post('/api/market/buy-plane').requestBody?.content['application/json'].schema.$ref).toBe(
      '#/components/schemas/BuyPlaneRequest',
    );
@@ -224,6 +237,8 @@ describe('OpenAPI spec', () => {
    expect(paramNames('/api/packages/{id}/load')).toEqual(['id']);
    expect(paramNames('/api/packages/{id}/abandon')).toEqual(['id']);
    expect(paramNames('/api/planes/{planeId}/fly')).toEqual(['planeId']);
+    expect(paramNames('/api/planes/{planeId}/queue')).toEqual(['planeId']); // v0.25.0 (ISS-043)
+    expect(paramNames('/api/planes/{planeId}/queue/cancel')).toEqual(['planeId']); // v0.25.0 (ISS-043)
    expect(paramNames('/api/planes/{planeId}/refuel')).toEqual(['planeId']);

    // Request schema shapes.
@@ -233,6 +248,13 @@ describe('OpenAPI spec', () => {
    const fly = openApiSpec.components.schemas.FlyPlaneRequest;
    expect(fly.required).toEqual(['destIcao']);
    expect(fly.properties.destIcao.type).toBe('string');
+    // v0.25.0 (ISS-043): the queue request schemas mirror fly's destIcao shape.
+    const queueLeg = openApiSpec.components.schemas.QueueLegRequest;
+    expect(queueLeg.required).toEqual(['destIcao']);
+    expect(queueLeg.properties.destIcao.type).toBe('string');
+    const cancelQueuedLeg = openApiSpec.components.schemas.CancelQueuedLegRequest;
+    expect(cancelQueuedLeg.required).toEqual(['index']);
+    expect(cancelQueuedLeg.properties.index.type).toBe('integer');
    const buy = openApiSpec.components.schemas.BuyPlaneRequest;
    expect(buy.required).toEqual(['model']);
    expect(buy.properties.model.type).toBe('string');
@@ -204,6 +204,74 @@ export const openApiSpec = {
        },
      },
    },
+    '/api/planes/{planeId}/queue': {
+      post: {
+        summary: 'Queue a flight leg for a plane',
+        description:
+          'Append a NOT-yet-started leg to the plane\'s flight queue (v0.25.0, ISS-043). Works whether the plane is grounded or flying — you can pre-build a route; the active leg still starts via /fly and nothing auto-starts here. On landing, the engine auto-chains the first queued leg when fuel covers it (otherwise the plane grounds with the queue kept intact for refuel + re-dispatch).',
+        operationId: 'queueLeg',
+        parameters: [
+          { name: 'planeId', in: 'path', required: true, schema: { type: 'string' } },
+        ],
+        requestBody: {
+          required: true,
+          content: {
+            'application/json': {
+              schema: { $ref: '#/components/schemas/QueueLegRequest' },
+            },
+          },
+        },
+        responses: {
+          200: {
+            description: 'Queued — full state snapshot (plane.queue now includes the new leg)',
+            content: { 'application/json': { schema: { $ref: '#/components/schemas/StateSnapshot' } } },
+          },
+          400: {
+            description:
+              'Invalid body (not an object, unknown field, or missing/non-string destIcao) or the ICAO is not in the airport dataset',
+            content: { 'application/json': { schema: { $ref: '#/components/schemas/Error' } } },
+          },
+          404: {
+            description: 'Unknown plane id',
+            content: { 'application/json': { schema: { $ref: '#/components/schemas/Error' } } },
+          },
+        },
+      },
+    },
+    '/api/planes/{planeId}/queue/cancel': {
+      post: {
+        summary: 'Cancel a queued flight leg',
+        description:
+          'Remove a NOT-yet-started leg from the plane\'s queue by index (v0.25.0, ISS-043). Only queued legs are cancellable — the active in-flight leg (destIcao) is never affected.',
+        operationId: 'cancelQueuedLeg',
+        parameters: [
+          { name: 'planeId', in: 'path', required: true, schema: { type: 'string' } },
+        ],
+        requestBody: {
+          required: true,
+          content: {
+            'application/json': {
+              schema: { $ref: '#/components/schemas/CancelQueuedLegRequest' },
+            },
+          },
+        },
+        responses: {
+          200: {
+            description: 'Cancelled — full state snapshot (plane.queue without the removed leg)',
+            content: { 'application/json': { schema: { $ref: '#/components/schemas/StateSnapshot' } } },
+          },
+          400: {
+            description:
+              'Invalid body (not an object, unknown field, or non-integer index) or the index is outside [0, queue.length)',
+            content: { 'application/json': { schema: { $ref: '#/components/schemas/Error' } } },
+          },
+          404: {
+            description: 'Unknown plane id',
+            content: { 'application/json': { schema: { $ref: '#/components/schemas/Error' } } },
+          },
+        },
+      },
+    },
    '/api/market/buy-plane': {
      post: {
        summary: 'Buy a plane from the market',
@@ -441,6 +509,20 @@ export const openApiSpec = {
        },
        required: ['destIcao'],
      },
+      QueueLegRequest: {
+        type: 'object',
+        properties: {
+          destIcao: { type: 'string', description: 'Any airport ICAO from the dataset — appended to the queue as a not-yet-started leg (v0.25.0).' },
+        },
+        required: ['destIcao'],
+      },
+      CancelQueuedLegRequest: {
+        type: 'object',
+        properties: {
+          index: { type: 'integer', description: 'Zero-based position of the queued (not-yet-started) leg to remove; must be within [0, queue.length) (v0.25.0).' },
+        },
+        required: ['index'],
+      },
      BuyPlaneRequest: {
        type: 'object',
        properties: {
@@ -502,6 +584,12 @@ export const openApiSpec = {
          },
          lat: { type: 'number' },
          lon: { type: 'number' },
+          queue: {
+            type: 'array',
+            items: { type: 'string' },
+            description:
+              'Upcoming flight legs NOT yet started (v0.25.0) — ordered ICAOs; the active leg is destIcao. The engine auto-chains queue[0] on landing when fuel covers it.',
+          },
        },
        required: [
          'id',
@@ -516,6 +604,7 @@ export const openApiSpec = {
          'departureSimTime',
          'lat',
          'lon',
+          'queue',
        ],
      },
      PackageState: {
@@ -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, fuelAtWeighted } from './movement';
+import { arrivalTimeFor, fuelAtWeighted, requiredFuelFor } from './movement';
 import {
  clampTimeScale,
  deliverPackages,
@@ -235,9 +235,71 @@ describe('deliverPackages (v0.12.0 arrival delivery)', () => {
      .set({ status: 'flying', departureSimTime: T0 });
    expect(await deliverPackages(inst, T0 + 3_600_000)).toBe(0);
  });
+
+  // --- Auto-chain on landing (v0.25.0, ISS-043) ---
+
+  it('auto-chains to the next queued leg when fuel covers it', async () => {
+    const { inst, to, km, type } = await setupFlight('chain-ok.db'); // full tank EDDF→LEMD
+    const fc = await loadAirportsGeoJson();
+    const nextP = fc.features.find((f) => f.properties.icao === 'EHAM')!.properties;
+    const nextKm = haversineKm(to.lat, to.lon, nextP.lat, nextP.lon);
+
+    // Precondition sanity: a full-tank departure leaves enough for the LEMD→EHAM hop.
+    const landedFuel = fuelAtWeighted(type.maxFuel, type.burnPerKm, type.emptyWeightKg, type.maxFuel, km, 1);
+    expect(requiredFuelFor(type.burnPerKm, type.emptyWeightKg, type.maxFuel, nextKm)).toBeLessThanOrEqual(landedFuel);
+
+    await inst.db.update(schema.planes)
+      .set({ queue: JSON.stringify(['EHAM', 'EDDV']) })
+      .where(eq(schema.planes.id, 'plane-starter'));
+
+    const clock = T0 + travelMs(km, type.speedKmh); // exactly at arrival
+    expect(await deliverPackages(inst, clock)).toBe(1);
+
+    const plane = (await inst.db.select().from(schema.planes))[0];
+    expect(plane.status).toBe('flying'); // chained — still airborne, no ground stop
+    expect(plane.destIcao).toBe('EHAM'); // first queued leg is now the active one
+    expect(plane.departureSimTime).toBe(clock); // departed at the arrival instant…
+    expect(plane.locationIcao).toBe(TO); // …from the airport just landed at
+    expect(plane.lat).toBe(to.lat);
+    expect(plane.lon).toBe(to.lon);
+    expect(JSON.parse(plane.queue)).toEqual(['EDDV']); // first leg consumed, rest kept in order
+  });
+
+  it('grounds when fuel cannot cover the next queued leg, keeping the queue intact', async () => {
+    const { inst, km, type } = await setupFlight('chain-nofuel.db');
+    const fc = await loadAirportsGeoJson();
+    const nextP = fc.features.find((f) => f.properties.icao === 'EHAM')!.properties;
+
+    // Depart with exactly the fuel for EDDF→LEMD → lands empty, cannot start LEMD→EHAM.
+    await inst.db.update(schema.planes)
+      .set({
+        fuel: requiredFuelFor(type.burnPerKm, type.emptyWeightKg, type.maxFuel, km),
+        queue: JSON.stringify(['EHAM']),
+      })
+      .where(eq(schema.planes.id, 'plane-starter'));
+
+    const clock = T0 + travelMs(km, type.speedKmh); // exactly at arrival
+    expect(await deliverPackages(inst, clock)).toBe(1);
+
+    const plane = (await inst.db.select().from(schema.planes))[0];
+    expect(plane.status).toBe('available'); // grounded safely…
+    expect(plane.destIcao).toBeNull();
+    expect(plane.departureSimTime).toBeNull();
+    expect(JSON.parse(plane.queue)).toEqual(['EHAM']); // …queue kept for refuel + re-dispatch
+  });
+
+  it('grounds as before when the queue is empty', async () => {
+    const { inst, km } = await setupFlight('chain-empty.db'); // seeded default queue '[]'
+
+    expect(await deliverPackages(inst, T0 + travelMs(km, PLANE_TYPES.atr72.speedKmh))).toBe(1);
+
+    const plane = (await inst.db.select().from(schema.planes))[0];
+    expect(plane.status).toBe('available'); // unchanged landing behavior…
+    expect(JSON.parse(plane.queue)).toEqual([]); // …and the queue stays empty
+  });
 });

-describe('auto-slow to 1× when the last plane lands (ISS-011)', () => {
+describe('pause on landing when the last plane lands (ISS-041)', () => {
  const FROM = 'EDDF';
  const TO = 'LEMD';

@@ -259,19 +321,20 @@ describe('auto-slow to 1× when the last plane lands (ISS-011)', () => {
    return { inst, from, km, type };
  }

-  it('last plane lands → stored timeScale becomes 1', async () => {
-    const { inst } = await setupLanding('autoslow-last.db', 1000);
+  it('last plane lands → sim pauses and stored timeScale is UNCHANGED', async () => {
+    const { inst } = await setupLanding('pause-last.db', 1000);
    vi.setSystemTime(T0 + 2_000); // one full clamped tick at scale 1000 → clock T0+2e6 ≥ arrival (T0)

    const sim = await tickOnce(inst);

-    expect(sim.timeScale).toBe(1); // persisted on the sim_state row…
-    expect((await inst.db.select().from(schema.simState))[0].timeScale).toBe(1); // …and visible to the next snapshot
+    expect(sim.paused).toBe(true); // persisted on the sim_state row…
+    expect((await inst.db.select().from(schema.simState))[0].paused).toBe(true); // …and visible to the next snapshot
+    expect(sim.timeScale).toBe(1000); // speed preserved — no auto-slow anymore (ISS-041)
    expect((await inst.db.select().from(schema.planes))[0].status).toBe('available'); // landing itself unchanged
  });

-  it('a landing while another plane is still flying → no change', async () => {
-    const { inst, from, type } = await setupLanding('autoslow-other.db', 1000);
+  it('a landing while another plane is still flying → no pause', async () => {
+    const { inst, from, type } = await setupLanding('pause-other.db', 1000);
    // A second plane on the same route departing at T0 — arrives far after this tick's clock.
    await inst.db.insert(schema.planes).values({
      id: 'p-b', model: 'atr72', status: 'flying', fuel: type.maxFuel, maxFuel: type.maxFuel,
@@ -281,32 +344,51 @@ describe('auto-slow to 1× when the last plane lands (ISS-011)', () => {
    vi.setSystemTime(T0 + 2_000);
    const sim = await tickOnce(inst);

-    expect(sim.timeScale).toBe(1000); // p-b still in flight — no auto-slow
+    expect(sim.paused).toBe(false); // p-b still in flight — no pause (nothing would auto-unpause it)
+    expect(sim.timeScale).toBe(1000);
    const byId = new Map((await inst.db.select().from(schema.planes)).map((p) => [p.id, p.status]));
    expect(byId.get('plane-starter')).toBe('available'); // the starter did land…
    expect(byId.get('p-b')).toBe('flying'); // …but the fleet is not idle
  });

-  it('already at 1× → stays 1', async () => {
-    const { inst } = await setupLanding('autoslow-one.db', 1);
+  it('last plane lands at scale 1 → pauses anyway, scale untouched', async () => {
+    const { inst } = await setupLanding('pause-one.db', 1);
    vi.setSystemTime(T0 + 2_000); // one tick at scale 1 advances 2e3 game ms — past the T0 arrival

    const sim = await tickOnce(inst);

+    expect(sim.paused).toBe(true);
    expect(sim.timeScale).toBe(1);
    expect((await inst.db.select().from(schema.planes))[0].status).toBe('available');
  });

+  it('a chained plane does NOT trigger the last-plane pause (ISS-043)', async () => {
+    const { inst } = await setupLanding('pause-chain.db', 1000); // full tank, arrival exactly T0
+    // A queued next hop with plenty of fuel → chains on landing instead of grounding.
+    await inst.db.update(schema.planes)
+      .set({ queue: JSON.stringify(['EDDV']) })
+      .where(eq(schema.planes.id, 'plane-starter'));
+
+    vi.setSystemTime(T0 + 2_000); // one full clamped tick at scale 1000 → clock T0+2e6 ≥ arrival (T0)
+    const sim = await tickOnce(inst);
+
+    expect(sim.paused).toBe(false); // still flying after the chain — no premature pause…
+    const plane = (await inst.db.select().from(schema.planes))[0];
+    expect(plane.status).toBe('flying'); // …the fresh select in tickOnce counts it as airborne
+    expect(plane.destIcao).toBe('EDDV');
+  });
+
  it('paused sim with all planes landed → no change', async () => {
-    const inst = await freshDb('autoslow-paused.db');
+    const inst = await freshDb('pause-paused.db');
    // The fleet is fully grounded (the seeded starter) — a paused tick must not touch the
-    // scale even though "no plane in flight" holds: the trigger requires a landing this tick.
+    // controls even though "no plane in flight" holds: the trigger requires a landing this tick.
    await inst.db.update(schema.simState).set({ timeScale: 1000, paused: true });

    vi.setSystemTime(T0 + 5_000);
    const sim = await tickOnce(inst);

-    expect(sim.timeScale).toBe(1000); // no landing processed while paused → trigger never fires
+    expect(sim.paused).toBe(true); // no landing processed while paused → trigger never fires
+    expect(sim.timeScale).toBe(1000);
    expect((await inst.db.select().from(schema.planes))[0].status).toBe('available');
  });
 });
@@ -5,6 +5,7 @@ import * as schema from '@/lib/db/schema';
 import { loadAirportsGeoJson } from '@/lib/airports';
 import { haversineKm } from '@/lib/geo';
 import { PLANE_TYPES } from '@/lib/game/catalog';
+import { parseIcaoQueue } from '@/lib/game/state';
 import {
  generatePackage,
  MARKET_TARGET_OPEN_PACKAGES,
@@ -12,7 +13,7 @@ import {
  type Rng,
  type SeedAirport,
 } from '@/lib/game/seed';
-import { arrivalTimeFor, fuelAtWeighted } from './movement';
+import { arrivalTimeFor, fuelAtWeighted, requiredFuelFor } 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
@@ -74,8 +75,8 @@ export async function tickOnce(inst: GameDb): Promise<schema.SimStateRow> {
  let landedThisTick = 0;
  if (advanceMs > 0) {
    await expirePackages(inst, clockMs);
-    // ISS-011: remember the landings so the tick can auto-slow to 1× when this was
-    // the last plane in flight.
+    // ISS-041: remember the landings so the tick can pause when this was the last
+    // plane in flight.
    landedThisTick = await deliverPackages(inst, clockMs);
    await spawnOpenPackages(inst, clockMs);
    // AFTER delivery on purpose: a plane that just landed gets work spawned
@@ -83,17 +84,18 @@ export async function tickOnce(inst: GameDb): Promise<schema.SimStateRow> {
    await spawnCoveragePackages(inst, clockMs);
  }

-  const sets: Partial<Pick<schema.SimStateRow, 'clockMs' | 'lastRealTickMs' | 'timeScale'>> = {
+  const sets: Partial<Pick<schema.SimStateRow, 'clockMs' | 'lastRealTickMs' | 'timeScale' | 'paused'>> = {
    clockMs,
    lastRealTickMs: nowMs,
  };
-  // Auto-slow (ISS-011): when ≥1 plane landed this tick and NO plane remains in flight,
-  // drop the stored timeScale to 1× — persisted here so the UI slider reflects it on the
-  // next snapshot. Arrival-triggered by design: a grounded fleet at high scale is left
-  // alone (the player speeds up manually again; there is no auto-restore).
-  if (landedThisTick > 0 && !sim.paused) {
+  // Pause on landing (ISS-041): when ≥1 plane landed this tick and NO plane remains in flight,
+  // pause the sim WITHOUT touching timeScale — speed is preserved for the next dispatch.
+  // Arrival-triggered by design: a grounded fleet at high scale is left alone (there is no
+  // auto-resume except starting a flight; see flyPlane). A paused tick never processes landings
+  // (advanceMs === 0), so the trigger can only fire on an advancing tick.
+  if (landedThisTick > 0) {
    const flying = await inst.db.select().from(schema.planes).where(eq(schema.planes.status, 'flying'));
-    if (flying.length === 0) sets.timeScale = MIN_TIME_SCALE;
+    if (flying.length === 0) sets.paused = true;
  }

  // Persist lastRealTickMs even when nothing advanced — it is the tick anchor.
@@ -121,12 +123,17 @@ export async function expirePackages(inst: GameDb, clockMs: number): Promise<num
 }

 // Finalize in-flight planes whose arrival time has passed (v0.12.0 delivery):
-// ground the plane at its dest_icao with its remaining fuel, then for every
-// package bound to it and destined for that airport — 'loaded' ones still inside
-// their deadline are delivered (cash += reward + reputation gain per package),
-// 'expired' ones just unbind (no reward). Packages destined elsewhere stay loaded
-// on the plane for a later leg. Idempotent — a finalized plane leaves the
-// 'flying' state, so it can never be awarded twice. Returns planes landed.
+// for every package bound to the plane and destined for its dest_icao — 'loaded'
+// ones still inside their deadline are delivered (cash += reward + reputation
+// gain per package), 'expired' ones just unbind (no reward). Packages destined
+// elsewhere stay loaded on the plane for a later leg. Then (v0.25.0, ISS-043)
+// auto-chain: if the queue holds legs and fuel covers the first one, start it
+// immediately from the arrival airport; otherwise ground the plane there with
+// its remaining fuel (a short tank keeps the queue intact for refuel + re-dispatch).
+// Idempotent — a finalized plane either leaves the 'flying' state or starts a NEW
+// leg whose own arrival is in the future, so it can never be awarded twice.
+// Returns planes landed. NOTE: runs BEFORE tickOnce's pause check on purpose —
+// a chained plane counts as still flying there, so chaining never pauses early.
 export async function deliverPackages(inst: GameDb, clockMs: number): Promise<number> {
  const [planeRows, packageRows] = await Promise.all([
    inst.db.select().from(schema.planes),
@@ -148,19 +155,10 @@ export async function deliverPackages(inst: GameDb, clockMs: number): Promise<nu
    if (clockMs < arrivalTimeFor(p.departureSimTime, distanceKm, type.speedKmh)) continue;

    // 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: fuelAtWeighted(p.fuel, type.burnPerKm, type.emptyWeightKg, type.maxFuel, distanceKm, 1),
-        departureSimTime: null,
-        destIcao: null,
-      })
-      .where(eq(schema.planes.id, p.id));
+    const landedFuel = fuelAtWeighted(p.fuel, type.burnPerKm, type.emptyWeightKg, type.maxFuel, distanceKm, 1);

-    // Deliver every bound package whose destination is the airport just reached.
+    // Deliver every bound package whose destination is the airport just reached —
+    // runs whether or not a queued leg chains next (ISS-043).
    const onBoard = packageRows.filter((pk) => pk.planeId === p.id && pk.destIcao === to.icao);
    for (const pk of onBoard) {
      if (pk.status === 'loaded' && clockMs <= pk.deadlineSimTime) {
@@ -177,6 +175,47 @@ export async function deliverPackages(inst: GameDb, clockMs: number): Promise<nu
        await inst.db.update(schema.packages).set({ planeId: null }).where(eq(schema.packages.id, pk.id));
      }
    }
+
+    // Auto-chain (ISS-043): with a non-empty queue and enough fuel for the first
+    // queued leg, start it immediately from `to` — same feasibility rule as flyPlane
+    // (requiredFuelFor is independent of current load). Otherwise ground here; an
+    // unknown ICAO in the queue simply cannot chain. The remaining queue is kept
+    // intact either way so a grounded plane can refuel and re-dispatch.
+    const queue = parseIcaoQueue(p.queue);
+    let chainedTo: string | null = null;
+    if (queue.length > 0) {
+      const nextDest = queue[0];
+      const next = byIcao.get(nextDest); // unknown ICAO in the queue → cannot chain
+      if (next && requiredFuelFor(type.burnPerKm, type.emptyWeightKg, type.maxFuel, haversineKm(to.lat, to.lon, next.lat, next.lon)) <= landedFuel) {
+        queue.shift();
+        chainedTo = nextDest;
+      }
+    }
+    await inst.db.update(schema.planes)
+      .set(
+        chainedTo
+          ? {
+              status: 'flying',
+              locationIcao: to.icao,
+              lat: to.lat,
+              lon: to.lon,
+              fuel: landedFuel,
+              destIcao: chainedTo,
+              departureSimTime: clockMs, // the arrival instant — position is exactly `to`
+              queue: JSON.stringify(queue),
+            }
+          : {
+              status: 'available',
+              locationIcao: to.icao,
+              lat: to.lat,
+              lon: to.lon,
+              fuel: landedFuel,
+              departureSimTime: null,
+              destIcao: null,
+              queue: JSON.stringify(queue),
+            },
+      )
+      .where(eq(schema.planes.id, p.id));
    n++;
  }
  return n;
@@ -1,6 +1,6 @@
 {
  "name": "flight-ops",
-  "version": "0.23.1",
+  "version": "0.25.0",
  "private": true,
  "scripts": {
    "dev": "next dev -p 3000",
Author	SHA1	Message	Date
kamilkrzywda	3395fb4f90	Merge pull request 'ISS-043 (part 1): flight queue backend — data model, auto-chain on landing, add/cancel endpoints' (#50 ) from feat/flight-queue-backend into master CI / build + unit + e2e (push) Successful in 6m21s Details	2026-09-20 13:04:17 +02:00
kamilkrzywda	537c494daa	ISS-043: add queue endpoints to e2e OpenAPI path list CI / build + unit + e2e (pull_request) Successful in 6m17s Details	2026-09-20 10:57:57 +00:00
kamilkrzywda	69b708dad3	Flight queue backend: planes hold a queue of upcoming legs, auto-chain on landing (ISS-043 part 1) CI / build + unit + e2e (pull_request) Failing after 6m37s Details - planes.queue TEXT NOT NULL DEFAULT '[]' — ordered JSON array of not-yet-started leg ICACs; active leg stays destIcao + departureSimTime. DDL + guarded ALTER migration for existing DBs; seed sets queue: [] explicitly. - deliverPackages() auto-chains on arrival: with a non-empty queue and fuel covering the first queued leg (same requiredFuelFor rule as /fly), the plane immediately starts that leg from the arrival airport (stays 'flying', departureSimTime = arrival instant, queue shortened). Short tank → grounds safely with the queue kept intact; empty queue → unchanged grounding. Cargo delivery for the reached airport runs first and is unaffected. Ordering kept: delivery still runs before tickOnce's pause check, so a chained plane counts as still flying — no premature last-plane pause (ISS-041 preserved). - New endpoints via performAction(): POST /api/planes/{planeId}/queue {destIcao} (append; works grounded or flying; 400 bad body/unknown ICAO, 404 unknown plane) and POST /api/planes/{planeId}/queue/cancel {index} (remove queued leg by index; active in-flight leg never affected; 400 non-integer/out-of-range, 404 unknown plane). Both return the full state snapshot. - PlaneState.queue: string[] in /api/state (null/malformed-safe parse helper shared with the engine); OpenAPI updated (PlaneState.queue, QueueLegRequest, CancelQueuedLegRequest, both paths) and openapi.test.ts expectations extended. - Tests: auto-chain block in engine.test.ts (chain / short-fuel ground / empty queue) + chained-plane-no-pause regression guard; queueLeg/cancelQueuedLeg blocks in actions.test.ts; type-compat queue: [] fixtures in deriveEvents, right-pane, mapData and seed tests. v0.25.0 — part 1 (backend) of ISS-043; UI/map rendering lands in a follow-up.	2026-09-20 10:39:00 +00:00
kamilkrzywda	e109e003c0	Merge pull request 'ISS-041: pause on landing (keep speed) + auto-resume when a flight starts' (#49 ) from fix/pause-on-landing-auto-unpause into master CI / build + unit + e2e (push) Successful in 7m51s Details	2026-09-20 12:00:02 +02:00
kamilkrzywda	cbe0cda15d	Pause on landing + auto-unpause on dispatch (ISS-041) CI / build + unit + e2e (pull_request) Successful in 7m43s Details Replace the ISS-011 auto-slow with pause-on-landing: when the last plane in flight lands, tickOnce sets sim_state.paused=true WITHOUT touching timeScale (speed preserved). flyPlane() now clears paused before persisting so starting a flight resumes a paused sim — inside runAction(), tick + unpause + dispatch are atomic under the sim lock. Tests: engine.test.ts auto-slow block rewritten for pause semantics; new flyPlane test asserts dispatch clears paused with speed untouched. E2E: auto-slow.spec.ts renamed to pause-on-landing.spec.ts asserting the new behavior (paused=true AND timeScale still 1000 after landing; /fly clears paused). Cross-cutting fix: every per-spec setScale helper now POSTs {timeScale, paused:false} — a scale-only fast-forward after a landing would otherwise leave the clock frozen. Deliberate mid-test pauses untouched.	2026-09-20 09:48:56 +00:00
kamilkrzywda	4620707abc	Merge pull request 'ISS-040: on-board package hover traces from carrier's current position' (#48 ) from fix/onboard-hover-current-location into master CI / build + unit + e2e (push) Successful in 7m6s Details	2026-09-20 11:24:33 +02:00
kamilkrzywda	3024606ac8	On-board package hover traces from the carrier's current position (ISS-040) CI / build + unit + e2e (pull_request) Successful in 7m11s Details	2026-09-20 09:16:06 +00:00