Merge branch 'main' into fix/firms-drop-snpp

# Conflicts:
#	docs/CURRENT-STATE.md

src/annotations/drawMarks.js

@@ -43,24 +43,167 @@ export function drawMarkFallbackName(mark) {
     : shape;
 }
 
+/** The kind of shape a row action is offered for: `area` or `line`. */
+const ACTION_SHAPES = Object.freeze({ area: 'area', route: 'line' });
+
+const lonLat = (point) =>
+  Array.isArray(point)
+    ? [Number(point[0]), Number(point[1])]
+    : [Number(point?.lon), Number(point?.lat)];
+const finitePairs = (points) =>
+  (Array.isArray(points) ? points : [])
+    .map(lonLat)
+    .filter(([lon, lat]) => Number.isFinite(lon) && Number.isFinite(lat));
+/** A longitude in [-180, 180]; an unwrapped outline can carry ±540. */
+const wrapLon = (lon) =>
+  lon >= -180 && lon <= 180 ? lon : ((((lon + 180) % 360) + 360) % 360) - 180;
+/** Whether consecutive positions step across the antimeridian once wrapped. */
+const crossesAntimeridian = (points) =>
+  points.some(
+    (point, index) =>
+      index > 0 && Math.abs(point[0] - points[index - 1][0]) > 180,
+  );
+/** Positions wrapped into range, or null when the sequence crosses ±180°. */
+const inRange = (points) => {
+  if (points.some(([, lat]) => Math.abs(lat) > 90)) return null;
+  const wrapped = points.map(([lon, lat]) => [wrapLon(lon), lat]);
+  return crossesAntimeridian(wrapped) ? null : wrapped;
+};
+const closed = (ring) => {
+  if (ring.length < 3) return ring;
+  const [first, last] = [ring[0], ring[ring.length - 1]];
+  return first[0] === last[0] && first[1] === last[1] ? ring : [...ring, first];
+};
+
+/**
+ * A drawn shape's geometry as GeoJSON in `[lon, lat]` degrees, longitudes in
+ * [-180, 180]: an area is a closed `Polygon` (a `MultiPolygon` when an area
+ * handle has several parts), a line a `LineString`. A pin, a shape too small
+ * to be one, or one that crosses the antimeridian has none, so it is offered
+ * no action rather than a shape that wraps the wrong way round the world.
+ */
+export function drawMarkGeometry(mark) {
+  if (mark?.type === 'route') {
+    const path = inRange(finitePairs(mark.path));
+    return path?.length >= 2 ? { type: 'LineString', coordinates: path } : null;
+  }
+  if (mark?.type !== 'area') return null;
+  const ringOf = (points) => {
+    const ring = inRange(closed(finitePairs(points)));
+    return ring?.length >= 4 ? ring : null;
+  };
+  if (Array.isArray(mark.polygons) && mark.polygons.length) {
+    const polygons = [];
+    for (const rings of mark.polygons) {
+      const parts = (Array.isArray(rings) ? rings : []).map(ringOf);
+      // A part that cannot be given whole is no part: never a hole dropped.
+      if (!parts.length || parts.some((ring) => !ring)) return null;
+      polygons.push(parts);
+    }
+    return polygons.length > 1
+      ? { type: 'MultiPolygon', coordinates: polygons }
+      : { type: 'Polygon', coordinates: polygons[0] };
+  }
+  const ring = ringOf(mark.ring);
+  return ring ? { type: 'Polygon', coordinates: [ring] } : null;
+}
+
+/**
+ * The actions an application adds to Draw's rows, checked once: each has an
+ * `id`, a Material Symbols `icon`, a `label(name)` worded by the application,
+ * the `shapes` it is for (`area`, `line`), an optional `accepts(geometry)` and
+ * `run({ id, shape, name, title, geometry })` (`name` the person's own, `title`
+ * as the row shows it). Malformed or repeated ids are dropped.
+ */
+export function drawMarkActions(actions = []) {
+  const kept = new Map();
+  for (const action of Array.isArray(actions) ? actions : []) {
+    const wellFormed =
+      typeof action?.id === 'string' &&
+      /^[a-z][a-z0-9-]{0,39}$/.test(action.id) &&
+      typeof action.icon === 'string' &&
+      typeof action.label === 'function' &&
+      typeof action.run === 'function' &&
+      Array.isArray(action.shapes);
+    if (!wellFormed || kept.has(action.id)) continue;
+    kept.set(
+      action.id,
+      Object.freeze({
+        id: action.id,
+        icon: action.icon,
+        label: action.label,
+        shapes: Object.freeze(
+          action.shapes.filter((shape) =>
+            Object.values(ACTION_SHAPES).includes(shape),
+          ),
+        ),
+        accepts:
+          typeof action.accepts === 'function' ? action.accepts : () => true,
+        run: action.run,
+      }),
+    );
+  }
+  return Object.freeze([...kept.values()]);
+}
+
+/** The actions from `drawMarkActions` that `mark` is offered, with its geometry. */
+export function drawMarkActionsFor(mark, actions = []) {
+  const shape = ACTION_SHAPES[mark?.type];
+  if (!shape || !actions.length) return { shape, geometry: null, actions: [] };
+  const geometry = drawMarkGeometry(mark);
+  if (!geometry) return { shape, geometry, actions: [] };
+  return {
+    shape,
+    geometry,
+    actions: actions.filter((action) => {
+      if (!action.shapes.includes(shape)) return false;
+      try {
+        return action.accepts(geometry, shape) === true;
+      } catch {
+        return false;
+      }
+    }),
+  };
+}
+
+/** An action's words for a row; an application's label that throws shows its id. */
+function actionLabel(action, title) {
+  try {
+    const text = action.label(title);
+    return typeof text === 'string' && text.trim() ? text.trim() : action.id;
+  } catch {
+    return action.id;
+  }
+}
+
 /**
  * The rows for the hand-drawn marks on the board, in board order. Text is
  * worded here, in the current language; the view only lays it out.
  * @param {object[]} marks The engine's `list()`.
+ * @param {ReturnType<typeof drawMarkActions>} [actions] The application's row actions.
+ * @param {Map<string, {busy: boolean, text: string}>} [notes] What an action said on a shape.
  */
-export function presentDrawMarks(marks = []) {
+export function presentDrawMarks(marks = [], actions = [], notes = new Map()) {
   return marks
     .filter((mark) => mark?.manual === true)
     .map((mark) => {
       const fallback = drawMarkFallbackName(mark);
       const title = mark.name || fallback;
       const visible = !mark.hidden;
+      const offered = drawMarkActionsFor(mark, actions).actions;
       return {
         id: mark.id,
         name: mark.name || '',
         placeholder: fallback,
         color: DRAW_COLORS.includes(mark.color) ? mark.color : 'primary',
         hidden: !visible,
+        busy: notes.get(mark.id)?.busy === true,
+        note: offered.length ? notes.get(mark.id)?.text || '' : '',
+        actions: offered.map((action) => ({
+          id: action.id,
+          icon: action.icon,
+          label: actionLabel(action, title),
+        })),
         labels: {
           name: t('Name of {name}', { name: title }),
           swatch: t('Change the colour of {name}', { name: title }),

src/annotations/drawMarks.test.mjs

@@ -3,7 +3,10 @@ import assert from 'node:assert/strict';
 import {
   DRAW_COLORS,
   DRAW_COLOR_CSS,
+  drawMarkActions,
+  drawMarkActionsFor,
   drawMarkFallbackName,
+  drawMarkGeometry,
   presentDrawMarks,
 } from './drawMarks.js';
 
@@ -78,3 +81,219 @@ test('rows list only hand-drawn marks, in board order, with their words', () =>
 test('every colour has its swatch', () => {
   assert.deepEqual(Object.keys(DRAW_COLOR_CSS), [...DRAW_COLORS]);
 });
+
+test("a drawn shape's geometry is GeoJSON in [lon, lat]: a closed area, a line, no pin", () => {
+  assert.deepEqual(
+    drawMarkGeometry({
+      type: 'area',
+      ring: [
+        [0, 0],
+        [1, 0],
+        [1, 1],
+        [0, 0],
+      ],
+    }),
+    {
+      type: 'Polygon',
+      coordinates: [
+        [
+          [0, 0],
+          [1, 0],
+          [1, 1],
+          [0, 0],
+        ],
+      ],
+    },
+  );
+  assert.deepEqual(
+    drawMarkGeometry({
+      type: 'area',
+      ring: [
+        [0, 0],
+        [1, 0],
+        [1, 1],
+      ],
+    }).coordinates[0].at(-1),
+    [0, 0],
+    'an open ring is closed',
+  );
+  assert.equal(
+    drawMarkGeometry({
+      type: 'area',
+      ring: [
+        [0, 0],
+        [1, 0],
+      ],
+    }),
+    null,
+  );
+  assert.deepEqual(
+    drawMarkGeometry({
+      type: 'route',
+      path: [
+        { lon: 1, lat: 2, height: 9 },
+        { lon: 3, lat: 4, height: 0 },
+      ],
+    }),
+    {
+      type: 'LineString',
+      coordinates: [
+        [1, 2],
+        [3, 4],
+      ],
+    },
+  );
+  assert.equal(
+    drawMarkGeometry({ type: 'pin', longitude: 1, latitude: 2 }),
+    null,
+  );
+  const square = (x) => [
+    [x, 0],
+    [x + 1, 0],
+    [x + 1, 1],
+    [x, 0],
+  ];
+  assert.deepEqual(
+    drawMarkGeometry({
+      type: 'area',
+      ring: square(0),
+      polygons: [[square(0)], [square(5)]],
+    }),
+    { type: 'MultiPolygon', coordinates: [[square(0)], [square(5)]] },
+    'an area handle with several parts keeps them all',
+  );
+  assert.equal(
+    drawMarkGeometry({
+      type: 'area',
+      polygons: [
+        [
+          square(0),
+          [
+            [0.2, 0.2],
+            [0.3, 0.2],
+          ],
+        ],
+      ],
+    }),
+    null,
+    'a hole that cannot be given whole is never dropped silently',
+  );
+});
+
+test('longitudes are wrapped into range, and a shape across the antimeridian has no geometry', () => {
+  assert.deepEqual(
+    drawMarkGeometry({
+      type: 'route',
+      path: [
+        [370, 1],
+        [371, 1],
+      ],
+    }).coordinates,
+    [
+      [10, 1],
+      [11, 1],
+    ],
+  );
+  assert.deepEqual(
+    drawMarkGeometry({
+      type: 'area',
+      ring: [
+        [180, 0],
+        [179, 0],
+        [179, 1],
+      ],
+    }).coordinates[0][0],
+    [180, 0],
+    'the antimeridian itself stays put',
+  );
+  assert.equal(
+    drawMarkGeometry({
+      type: 'area',
+      ring: [
+        [179.9, 0],
+        [-179.9, 0],
+        [-179.9, 1],
+      ],
+    }),
+    null,
+  );
+  assert.equal(
+    drawMarkGeometry({
+      type: 'route',
+      path: [
+        [179.5, 0],
+        [180.5, 0],
+      ],
+    }),
+    null,
+  );
+  assert.equal(
+    drawMarkGeometry({
+      type: 'route',
+      path: [
+        [0, 91],
+        [1, 0],
+      ],
+    }),
+    null,
+  );
+});
+
+test('row actions are checked once: malformed ones and repeated ids are dropped', () => {
+  const run = () => {};
+  const label = () => 'x';
+  const actions = drawMarkActions([
+    { id: 'Bad Id', icon: 'a', label, run, shapes: ['area'] },
+    { id: 'tag', icon: 'a', label: 'not a function', run, shapes: ['area'] },
+    {
+      id: 'tag',
+      icon: 'sell',
+      label,
+      run,
+      shapes: ['area', 'line', 'pin'],
+    },
+    { id: 'tag', icon: 'other', label, run, shapes: ['area'] },
+    null,
+  ]);
+  assert.deepEqual(
+    actions.map(({ id, icon, shapes }) => ({ id, icon, shapes: [...shapes] })),
+    [{ id: 'tag', icon: 'sell', shapes: ['area', 'line'] }],
+  );
+  assert.deepEqual(drawMarkActions('nope'), []);
+  const area = {
+    type: 'area',
+    ring: [
+      [0, 0],
+      [1, 0],
+      [1, 1],
+    ],
+  };
+  const offer = drawMarkActionsFor(area, actions);
+  assert.equal(offer.shape, 'area');
+  assert.deepEqual(
+    offer.actions.map((a) => a.id),
+    ['tag'],
+  );
+  const refusing = drawMarkActions([
+    {
+      id: 'measure',
+      icon: 'a',
+      label,
+      run,
+      shapes: ['area'],
+      accepts: () => {
+        throw new Error('no');
+      },
+    },
+  ]);
+  assert.deepEqual(
+    drawMarkActionsFor(area, refusing).actions,
+    [],
+    'an accepts that throws offers nothing',
+  );
+  assert.deepEqual(
+    presentDrawMarks([{ id: 'p', type: 'pin', manual: true }], actions)[0]
+      .actions,
+    [],
+  );
+});

src/annotations/drawTool.js

@@ -50,9 +50,28 @@ import {
   removeLastVertex,
 } from './drawMode.js';
 
-import { DRAW_COLORS, DRAW_COLOR_CSS, presentDrawMarks } from './drawMarks.js';
+import {
+  DRAW_COLORS,
+  DRAW_COLOR_CSS,
+  drawMarkActions,
+  drawMarkActionsFor,
+  drawMarkFallbackName,
+  presentDrawMarks,
+} from './drawMarks.js';
 
 import { onLocaleChange, t, translateKnown } from '../i18n/index.js';
+/** The longest note a row action leaves under its row, in characters. */
+const NOTE_MAX = 200;
+/** An action's answer as a row note: trimmed, and cut at a word with an ellipsis. */
+function noteText(text) {
+  if (typeof text !== 'string') return '';
+  const trimmed = text.trim();
+  if (trimmed.length <= NOTE_MAX) return trimmed;
+  const cut = trimmed.slice(0, NOTE_MAX - 1);
+  const space = cut.lastIndexOf(' ');
+  return `${(space > NOTE_MAX / 2 ? cut.slice(0, space) : cut).trimEnd()}…`;
+}
+
 /** The id this tool claims the pointer under. */
 const DRAW_POINTER_OWNER = 'draw';
 const PREVIEW_DATA_SOURCE_NAME = 'gev-draw-preview';
@@ -67,7 +86,10 @@ const PREVIEW = DRAW_COLOR_CSS;
  * through the actions it gives `connect`, which returns their disconnect.
  * A row's fly-to is an immediate navigation through `navigation`, like
  * Import's, so Cockpit can refuse it and a running orbit or follow lets go.
- * @param {{viewer: Cesium.Viewer, annotations: {annotate: Function, clear: Function}, navigation?: object, publish?: Function, connect?: Function}} deps
+ * `markActions` are the application's own buttons on an area's or a line's
+ * row (drawMarks.js `drawMarkActions`); a press runs the action with the
+ * shape's id, kind, name and geometry (drawMarks.js `drawMarkGeometry`).
+ * @param {{viewer: Cesium.Viewer, annotations: {annotate: Function, clear: Function}, navigation?: object, publish?: Function, connect?: Function, markActions?: object[]}} deps
  * @returns {{destroy: Function}|null}
  */
 export function initDrawTool({
@@ -76,7 +98,12 @@ export function initDrawTool({
   navigation = null,
   publish = () => {},
   connect = () => () => {},
+  markActions = [],
 }) {
+  const rowActions = drawMarkActions(markActions);
+  // What a row action said last on each drawn shape: `{ run, busy, text }`.
+  const notes = new Map();
+  let noteRun = 0;
   // A page without the Draw controls (the Display controls view omitted) has
   // no draw tool.
   if (!viewer || !annotations || !document.getElementById('draw-toggle'))
@@ -115,14 +142,19 @@ export function initDrawTool({
     () => null,
   );
 
-  const present = () =>
+  const present = () => {
+    const marks = annotations.list?.() || [];
+    // A note goes with its shape.
+    for (const id of notes.keys())
+      if (!marks.some((mark) => mark.id === id)) notes.delete(id);
     publish({
       active,
       shape,
       color,
       hint,
-      marks: presentDrawMarks(annotations.list?.() || []),
+      marks: presentDrawMarks(marks, rowActions, notes),
     });
+  };
   // The hint is kept as the call that words it, so a language switch can
   // word it again.
   let hintText = () => '';
@@ -450,6 +482,56 @@ export function initDrawTool({
     return annotations.frame?.(id) ?? false;
   }
 
+  /**
+   * Run the application's row action `actionId` on drawn shape `id`, if the
+   * shape is still on the board and still offered it. Returns whether it ran.
+   * What the action returns, or resolves to, is the row's note (a measurement,
+   * "saved"): the row is busy until it settles, a newer press or the shape's
+   * removal makes a late answer moot, and a failure clears the note, so an
+   * action words its own refusals and resolves with them.
+   */
+  function runMarkAction(id, actionId) {
+    const mark = (annotations.list?.() || []).find(
+      (entry) => entry.id === id && entry.manual === true,
+    );
+    const offer = drawMarkActionsFor(mark, rowActions);
+    const action = offer.actions.find((entry) => entry.id === actionId);
+    if (!action || notes.get(mark.id)?.busy) return false;
+    const run = ++noteRun;
+    const settle = (text) => {
+      if (destroyed || notes.get(mark.id)?.run !== run) return;
+      notes.set(mark.id, {
+        run,
+        busy: false,
+        text: noteText(text),
+      });
+      present();
+    };
+    const fail = (error) => {
+      console.warn(`[draw] ${actionId} failed`, error);
+      settle('');
+    };
+    notes.set(mark.id, { run, busy: true, text: '' });
+    let answer;
+    try {
+      answer = action.run({
+        id: mark.id,
+        shape: offer.shape,
+        name: mark.name || '',
+        title: mark.name || drawMarkFallbackName(mark),
+        geometry: offer.geometry,
+      });
+    } catch (error) {
+      fail(error);
+      return false;
+    }
+    if (typeof answer?.then === 'function') {
+      present();
+      Promise.resolve(answer).then(settle, fail);
+    } else settle(answer);
+    return true;
+  }
+
   /** Draw `next` from now on; an open shape starts over in it. */
   function chooseShape(next) {
     shape = normalizeShape(next);
@@ -478,6 +560,7 @@ export function initDrawTool({
     },
     flyToDrawMark: flyToMark,
     removeDrawMark: (id) => annotations.remove?.(id),
+    runDrawMarkAction: runMarkAction,
   });
   // The rows follow the board: a shape drawn, renamed, hidden or removed
   // here, by voice or by a clear.
@@ -500,13 +583,15 @@ export function initDrawTool({
     setActive,
     setShape: chooseShape,
     /** The hand-drawn marks the list shows, as its rows. */
-    marks: () => presentDrawMarks(annotations.list?.() || []),
+    marks: () =>
+      presentDrawMarks(annotations.list?.() || [], rowActions, notes),
     setColor(next) {
       color = DRAW_COLORS.includes(next) ? next : 'primary';
       present();
       syncPreview();
     },
     flyToMark,
+    runMarkAction,
     /** Test seam: add a vertex from lon/lat as if it had been clicked. */
     addVertex(lon, lat, height = 0) {
       if (!session) return false;

src/annotations/drawToolBehaviour.test.mjs

@@ -223,7 +223,7 @@ function fakeAnnotations() {
 }
 
 /** Stand up a tool against fresh doubles, with globals restored afterwards. */
-function harness({ navigation = null } = {}) {
+function harness({ navigation = null, markActions = [] } = {}) {
   resetPointerOwnership();
   const { byId, documentDouble } = fakeDom();
   const viewer = fakeViewer();
@@ -239,6 +239,7 @@ function harness({ navigation = null } = {}) {
     viewer,
     annotations,
     navigation,
+    markActions,
     publish: (view) => (shown.view = view),
     connect: (actions) => {
       controls.actions = actions;
@@ -576,6 +577,133 @@ test('each drawn shape is a row whose actions reach the board, and fly-to is a n
   }
 });
 
+test('an application\'s row actions show on the shapes they are for and run with the shape', async () => {
+  const ran = [];
+  const h = harness({
+    markActions: [
+      {
+        id: 'tag',
+        icon: 'sell',
+        label: (name) => `Tag ${name}`,
+        shapes: ['area', 'line'],
+        run: (shape) => ran.push(['tag', shape]),
+      },
+      {
+        id: 'measure',
+        icon: 'straighten',
+        label: (name) => `Measure ${name}`,
+        shapes: ['area'],
+        accepts: (geometry) => geometry.type === 'Polygon',
+        run: (shape) => ran.push(['measure', shape]),
+      },
+    ],
+  });
+  try {
+    const board = h.annotations;
+    board.marks.push(
+      { id: 'r1', type: 'area', manual: true, name: 'Strait', color: 'primary', hidden: false, ring: [[29, 41], [29.1, 41], [29.1, 41.1]] },
+      { id: 'l1', type: 'route', manual: true, name: null, label: '9 km', color: 'amber', hidden: false, path: [{ lon: 29, lat: 41.05, height: 0 }, { lon: 29.1, lat: 41.05, height: 0 }] },
+      { id: 'p1', type: 'pin', manual: true, name: 'Camp', color: 'red', hidden: false },
+    );
+    board.changed();
+    assert.deepEqual(
+      h.shown.view.marks.map(({ id, actions }) => [id, actions]),
+      [
+        ['r1', [
+          { id: 'tag', icon: 'sell', label: 'Tag Strait' },
+          { id: 'measure', icon: 'straighten', label: 'Measure Strait' },
+        ]],
+        ['l1', [{ id: 'tag', icon: 'sell', label: 'Tag Line · 9 km' }]],
+        ['p1', []],
+      ],
+    );
+    assert.equal(h.act('runDrawMarkAction', 'l1', 'tag'), true);
+    assert.equal(h.act('runDrawMarkAction', 'l1', 'measure'), false, 'a line is not offered an area action');
+    assert.equal(h.act('runDrawMarkAction', 'p1', 'tag'), false);
+    assert.equal(h.act('runDrawMarkAction', 'gone', 'tag'), false);
+    assert.equal(h.act('runDrawMarkAction', 'r1', 'measure'), true);
+    assert.deepEqual(ran, [
+      ['tag', { id: 'l1', shape: 'line', name: '', title: 'Line · 9 km', geometry: { type: 'LineString', coordinates: [[29, 41.05], [29.1, 41.05]] } }],
+      ['measure', { id: 'r1', shape: 'area', name: 'Strait', title: 'Strait', geometry: { type: 'Polygon', coordinates: [[[29, 41], [29.1, 41], [29.1, 41.1], [29, 41]]] } }],
+    ]);
+  } finally {
+    h.restore();
+  }
+});
+
+test('an action that throws is reported and leaves the row alone', async () => {
+  const h = harness({
+    markActions: [
+      { id: 'boom', icon: 'bolt', label: () => { throw new Error('label'); }, shapes: ['area'], run: () => { throw new Error('run'); } },
+    ],
+  });
+  const warn = console.warn;
+  const warned = [];
+  console.warn = (...args) => warned.push(args[0]);
+  try {
+    h.annotations.marks.push({ id: 'r1', type: 'area', manual: true, name: null, color: 'primary', hidden: false, ring: [[0, 0], [1, 0], [1, 1]] });
+    h.annotations.changed();
+    assert.deepEqual(h.shown.view.marks[0].actions, [{ id: 'boom', icon: 'bolt', label: 'boom' }]);
+    assert.equal(h.act('runDrawMarkAction', 'r1', 'boom'), false);
+    assert.deepEqual(warned, ['[draw] boom failed']);
+  } finally {
+    console.warn = warn;
+    h.restore();
+  }
+});
+
+test('what a row action answers is its row\'s note; the row is busy until then, and a removed shape drops it', async () => {
+  const pending = [];
+  const h = harness({
+    markActions: [
+      {
+        id: 'measure',
+        icon: 'straighten',
+        label: (name) => `Measure ${name}`,
+        shapes: ['area'],
+        run: () => new Promise((resolve, reject) => pending.push({ resolve, reject })),
+      },
+      { id: 'now', icon: 'bolt', label: () => 'Now', shapes: ['area'], run: () => '  12 km²  ' },
+      { id: 'long', icon: 'notes', label: () => 'Long', shapes: ['area'], run: () => `${'word '.repeat(60)}end` },
+    ],
+  });
+  const warn = console.warn;
+  console.warn = () => {};
+  try {
+    const board = h.annotations;
+    const area = (id) => ({ id, type: 'area', manual: true, name: null, color: 'primary', hidden: false, ring: [[0, 0], [1, 0], [1, 1]] });
+    board.marks.push(area('r1'), area('r2'));
+    board.changed();
+    const row = (id) => h.shown.view.marks.find((entry) => entry.id === id);
+    assert.equal(h.act('runDrawMarkAction', 'r1', 'now'), true);
+    assert.deepEqual([row('r1').busy, row('r1').note], [false, '12 km²']);
+    h.act('runDrawMarkAction', 'r1', 'long');
+    assert.ok(row('r1').note.length <= 200 && row('r1').note.endsWith('word…'), 'a long note is cut at a word');
+    assert.equal(h.act('runDrawMarkAction', 'r1', 'measure'), true);
+    assert.deepEqual([row('r1').busy, row('r1').note], [true, '']);
+    assert.equal(h.act('runDrawMarkAction', 'r1', 'now'), false, 'a busy row takes no second press');
+    pending[0].resolve('412 km², 38 km of edge');
+    await new Promise((resolve) => setTimeout(resolve, 0));
+    assert.deepEqual([row('r1').busy, row('r1').note], [false, '412 km², 38 km of edge']);
+    h.act('runDrawMarkAction', 'r1', 'measure');
+    pending[1].reject(new Error('refused'));
+    await new Promise((resolve) => setTimeout(resolve, 0));
+    assert.deepEqual([row('r1').busy, row('r1').note], [false, ''], 'a failure clears the note');
+    h.act('runDrawMarkAction', 'r2', 'measure');
+    board.marks.splice(1, 1);
+    board.changed();
+    pending[2].resolve('late');
+    await new Promise((resolve) => setTimeout(resolve, 0));
+    assert.equal(row('r2'), undefined);
+    board.marks.push(area('r2'));
+    board.changed();
+    assert.deepEqual([row('r2').busy, row('r2').note], [false, ''], 'a late answer never reaches a shape that went');
+  } finally {
+    console.warn = warn;
+    h.restore();
+  }
+});
+
 test('Backspace on the page removes the last vertex', () => {
   const h = harness();
   try {

src/app/application.test.mjs

@@ -2,7 +2,20 @@ import test from 'node:test';
 import assert from 'node:assert/strict';
 import { spawnSync } from 'node:child_process';
 import { createApplication } from './application.js';
-import { installTrackpadPinchZoom } from './viewer.js';
+import { KEYHOLE_OUTER_RADIUS } from '../celestialRing.js';
+import * as Cesium from 'cesium';
+import {
+  installFreeLookHeightLimit,
+  installGlobeInViewRecovery,
+  installTrackpadPinchZoom,
+} from './viewer.js';
+import {
+  FREE_LOOK_MAX_HEIGHT_METERS,
+  globeFrameShare,
+  globeOutOfFrame,
+  lookAngleWithinFrame,
+  lookStepLosesGlobe,
+} from '../globeInView.js';
 
 const phases = ['Scene', 'Controls', 'Data', 'Tools'];
 function fixture(overrides = {}) {
@@ -343,3 +356,652 @@ test('trackpad pinch falls back to the original event when relay construction fa
   assert.equal(event.propagationStopped, false);
   assert.equal(f.relayed.length, 0);
 });
+
+function freeLookFixture({ enableLook = true, height = 0 } = {}) {
+  const listeners = new Set();
+  const controller = { enableLook, minimumTrackBallHeight: 7_500_000 };
+  const camera = { positionCartographic: { height } };
+  const viewer = {
+    camera,
+    scene: {
+      screenSpaceCameraController: controller,
+      preUpdate: {
+        addEventListener(listener) {
+          listeners.add(listener);
+          return () => listeners.delete(listener);
+        },
+      },
+    },
+  };
+  const frame = (nextHeight) => {
+    camera.positionCartographic = { height: nextHeight };
+    for (const listener of listeners) listener();
+  };
+  return { viewer, controller, listeners, frame };
+}
+
+test('free look follows camera height and is restored on dispose', () => {
+  const f = freeLookFixture({ height: 500 });
+  const dispose = installFreeLookHeightLimit(f.viewer);
+  assert.equal(f.controller.enableLook, true);
+
+  f.frame(FREE_LOOK_MAX_HEIGHT_METERS + 1);
+  assert.equal(f.controller.enableLook, false);
+  f.frame(FREE_LOOK_MAX_HEIGHT_METERS);
+  assert.equal(f.controller.enableLook, true);
+  f.frame(Number.NaN);
+  assert.equal(f.controller.enableLook, true);
+
+  f.frame(FREE_LOOK_MAX_HEIGHT_METERS * 20);
+  dispose();
+  dispose();
+  assert.equal(f.controller.enableLook, true);
+  assert.equal(f.listeners.size, 0);
+});
+
+test('drags that start on the stars orbit above the free-look height', () => {
+  // Below Cesium's trackball height such a drag turns the camera in place.
+  const f = freeLookFixture({ height: 500 });
+  const dispose = installFreeLookHeightLimit(f.viewer);
+  assert.equal(
+    f.controller.minimumTrackBallHeight,
+    FREE_LOOK_MAX_HEIGHT_METERS,
+  );
+  dispose();
+  assert.equal(f.controller.minimumTrackBallHeight, 7_500_000);
+
+  const lower = freeLookFixture({ height: 500 });
+  lower.controller.minimumTrackBallHeight = 500_000;
+  const disposeLower = installFreeLookHeightLimit(lower.viewer);
+  assert.equal(
+    lower.controller.minimumTrackBallHeight,
+    500_000,
+    'never raised',
+  );
+  disposeLower();
+  assert.equal(lower.controller.minimumTrackBallHeight, 500_000);
+
+  const later = freeLookFixture({ height: 500 });
+  const disposeLater = installFreeLookHeightLimit(later.viewer);
+  later.controller.minimumTrackBallHeight = 2_000_000;
+  disposeLater();
+  assert.equal(
+    later.controller.minimumTrackBallHeight,
+    2_000_000,
+    'dispose keeps a value set after install',
+  );
+});
+
+test('free look keeps a setting other code makes after it is installed', () => {
+  const f = freeLookFixture({ height: 500 });
+  const dispose = installFreeLookHeightLimit(f.viewer);
+  f.controller.enableLook = false;
+  f.frame(10);
+  assert.equal(f.controller.enableLook, false, 'turned off stays off');
+  f.frame(FREE_LOOK_MAX_HEIGHT_METERS * 20);
+  f.frame(10);
+  assert.equal(f.controller.enableLook, false, 'and stays off after orbit');
+  f.controller.enableLook = true;
+  f.frame(10);
+  assert.equal(f.controller.enableLook, true, 'turned back on');
+  f.frame(FREE_LOOK_MAX_HEIGHT_METERS * 20);
+  assert.equal(f.controller.enableLook, false, 'still limited from orbit');
+  f.frame(10);
+  f.controller.enableLook = false;
+  dispose();
+  assert.equal(f.controller.enableLook, false, 'dispose keeps a later setting');
+});
+
+test('free look stays off when the viewer had it disabled', () => {
+  const f = freeLookFixture({ enableLook: false, height: 500 });
+  installFreeLookHeightLimit(f.viewer);
+  f.frame(10);
+  assert.equal(f.controller.enableLook, false);
+});
+
+// A real Cesium camera on the smallest scene its constructor reads, so the
+// frustum test runs on Cesium's own view math rather than a stub.
+function realCamera({ width = 1600, height = 900, mode } = {}) {
+  const scene = {
+    canvas: { clientWidth: width, clientHeight: height },
+    drawingBufferWidth: width,
+    drawingBufferHeight: height,
+    mapProjection: new Cesium.GeographicProjection(),
+    mode: mode ?? Cesium.SceneMode.SCENE3D,
+    pixelRatio: 1,
+    ellipsoid: Cesium.Ellipsoid.WGS84,
+    mapMode2D: Cesium.MapMode2D.INFINITE_SCROLL,
+    tweens: new Cesium.TweenCollection(),
+    renders: 0,
+    requestRender() {
+      this.renders += 1;
+    },
+  };
+  const camera = new Cesium.Camera(scene);
+  camera.frustum.aspectRatio = width / height;
+  return { camera, scene, viewer: { camera, scene } };
+}
+
+function aim(
+  camera,
+  { lon = -94.69, lat = 18.87, alt, heading = 0, pitch, roll = 0 },
+) {
+  camera.setView({
+    destination: Cesium.Cartesian3.fromDegrees(lon, lat, alt),
+    orientation: {
+      heading: Cesium.Math.toRadians(heading),
+      pitch: Cesium.Math.toRadians(pitch),
+      roll: Cesium.Math.toRadians(roll),
+    },
+  });
+}
+
+const reportedStuckView = {
+  alt: 17_996_811,
+  heading: 180,
+  pitch: -42,
+  roll: 180,
+};
+// Oblique poses that still show part of the planet: Director recipe shots
+// (Global Flights Radar, Omniscience Pullback) and a voice tilt from orbit.
+const partialGlobeViews = [
+  { lon: -30, lat: 20, alt: 19_000_000, pitch: -65 },
+  { lon: 2, lat: 46, alt: 8_000_000, pitch: -52 },
+  { lon: 110, lat: 20, alt: 9_500_000, pitch: -66 },
+  { lon: 0, lat: 0, alt: 2_000_000, pitch: -30 },
+];
+
+// Stars and a few pixels of limb, no surface: where a frame limit measured
+// against a sphere of the planet's largest radius used to stop a voice tilt.
+const limbOnlyView = { alt: 18_000_000, pitch: -56.75 };
+
+/**
+ * An oracle independent of the code under test: the share of an 80×45 grid of
+ * Cesium pick rays across the canvas that hit the ellipsoid surface.
+ */
+function surfacePixelShare(camera, width, height, { keyhole = false } = {}) {
+  const radius = (KEYHOLE_OUTER_RADIUS * height) / 2;
+  let hits = 0;
+  let counted = 0;
+  for (let row = 0; row < 45; row += 1) {
+    for (let column = 0; column < 80; column += 1) {
+      const x = ((column + 0.5) * width) / 80;
+      const y = ((row + 0.5) * height) / 45;
+      if (keyhole && Math.hypot(x - width / 2, y - height / 2) > radius)
+        continue;
+      counted += 1;
+      const ray = camera.getPickRay(new Cesium.Cartesian2(x, y));
+      if (Cesium.IntersectionTests.rayEllipsoid(ray, Cesium.Ellipsoid.WGS84))
+        hits += 1;
+    }
+  }
+  return hits / counted;
+}
+
+test('the globe is out of frame only when no surface is on screen', () => {
+  const cases = [
+    [reportedStuckView, 1225, 923, true],
+    [limbOnlyView, 1600, 900, true],
+    [{ alt: 17_996_811, pitch: -90 }, 1225, 923, false],
+    ...partialGlobeViews.map((view) => [view, 1600, 900, false]),
+  ];
+  for (const [view, width, height, out] of cases) {
+    const { camera } = realCamera({ width, height });
+    aim(camera, view);
+    const label = JSON.stringify(view);
+    assert.equal(globeOutOfFrame(camera), out, label);
+    assert.equal(surfacePixelShare(camera, width, height) === 0, out, label);
+    assert.ok(
+      Math.abs(
+        globeFrameShare(camera) - surfacePixelShare(camera, width, height),
+      ) < 0.03,
+      `${label}: the frame share matches the pick-ray oracle`,
+    );
+  }
+});
+
+test('a move that ends with the globe out of frame turns back to nadir', () => {
+  const { camera, scene, viewer } = realCamera({ width: 1225, height: 923 });
+  const dispose = installGlobeInViewRecovery(viewer);
+  aim(camera, reportedStuckView);
+  const position = Cesium.Cartesian3.clone(camera.positionWC);
+  const heading = camera.heading;
+  camera.moveEnd.raiseEvent();
+  assert.ok(Cesium.Math.equalsEpsilon(camera.pitch, -Math.PI / 2, 1e-6));
+  assert.ok(Cesium.Math.equalsEpsilon(camera.heading, heading, 1e-6));
+  assert.ok(
+    Cesium.Cartesian3.equalsEpsilon(camera.positionWC, position, 0, 1e-3),
+  );
+  assert.equal(globeOutOfFrame(camera), false);
+  assert.equal(scene.renders, 1);
+
+  // Looking up near the ground, then zoomed out past the limit.
+  aim(camera, { alt: 3_834_000, pitch: 10 });
+  camera.moveEnd.raiseEvent();
+  assert.ok(Cesium.Math.equalsEpsilon(camera.pitch, -Math.PI / 2, 1e-6));
+
+  // Only the limb on a 16:9 screen still counts as lost.
+  const wide = realCamera({ width: 1600, height: 900 });
+  const disposeWide = installGlobeInViewRecovery(wide.viewer);
+  aim(wide.camera, limbOnlyView);
+  wide.camera.moveEnd.raiseEvent();
+  assert.ok(Cesium.Math.equalsEpsilon(wide.camera.pitch, -Math.PI / 2, 1e-6));
+  disposeWide();
+
+  dispose();
+  dispose();
+  aim(camera, reportedStuckView);
+  camera.moveEnd.raiseEvent();
+  assert.equal(globeOutOfFrame(camera), true, 'disposed recovery is inert');
+});
+
+// True when a moveEnd leaves the camera's view direction as it was.
+function moveEndKeepsView(camera) {
+  const direction = Cesium.Cartesian3.clone(camera.directionWC);
+  camera.moveEnd.raiseEvent();
+  return Cesium.Cartesian3.equalsEpsilon(camera.directionWC, direction, 1e-9);
+}
+
+test('globe recovery leaves partial, low, locked and 2D views alone', () => {
+  for (const view of partialGlobeViews) {
+    const { camera, viewer } = realCamera();
+    installGlobeInViewRecovery(viewer);
+    aim(camera, view);
+    assert.ok(moveEndKeepsView(camera), JSON.stringify(view));
+  }
+
+  const low = realCamera();
+  installGlobeInViewRecovery(low.viewer);
+  aim(low.camera, { alt: 900_000, pitch: 85 });
+  assert.equal(globeOutOfFrame(low.camera), true);
+  assert.ok(moveEndKeepsView(low.camera), 'below the limit');
+
+  // Locked on a point in space, between it and the planet, facing away.
+  const locked = realCamera();
+  installGlobeInViewRecovery(locked.viewer);
+  locked.camera.lookAtTransform(
+    Cesium.Matrix4.fromTranslation(new Cesium.Cartesian3(30_000_000, 0, 0)),
+    new Cesium.Cartesian3(-1_000_000, 0, 0),
+  );
+  assert.equal(globeOutOfFrame(locked.camera), true);
+  assert.ok(moveEndKeepsView(locked.camera), 'locked camera');
+
+  // Tracking an entity that has no position yet keeps an identity transform.
+  const tracked = realCamera();
+  tracked.viewer.trackedEntity = { id: 'pending-fix' };
+  installGlobeInViewRecovery(tracked.viewer);
+  aim(tracked.camera, reportedStuckView);
+  assert.ok(moveEndKeepsView(tracked.camera), 'tracked camera');
+
+  const flat = realCamera({ mode: Cesium.SceneMode.COLUMBUS_VIEW });
+  installGlobeInViewRecovery(flat.viewer);
+  flat.scene.mode = Cesium.SceneMode.SCENE3D;
+  aim(flat.camera, reportedStuckView);
+  flat.scene.mode = Cesium.SceneMode.COLUMBUS_VIEW;
+  assert.ok(moveEndKeepsView(flat.camera), 'Columbus view');
+});
+
+test('the look limit from orbit tolerates grid noise and never reaches zero', () => {
+  const radians = Cesium.Math.toRadians;
+  // About 2% of a 16:9 frame on the planet, below the 10% limit.
+  const sliver = { alt: 18_000_000, pitch: -60 };
+  const { camera } = realCamera();
+  aim(camera, sliver);
+  const start = surfacePixelShare(camera, 1600, 900);
+  assert.ok(start > 0 && start < 0.1, `starts below the limit: ${start}`);
+
+  // Sideways across the sliver: the share wobbles by a cell, the planet stays.
+  assert.equal(lookStepLosesGlobe(camera, 'lookLeft', radians(0.5)), false);
+  const startShare = globeFrameShare(camera);
+  for (let i = 0; i < 20; i += 1) {
+    const step = lookAngleWithinFrame(camera, 'lookLeft', radians(0.25), {
+      startShare,
+    });
+    assert.equal(step, radians(0.25), `sideways step ${i + 1}`);
+    camera.lookLeft(step);
+  }
+  assert.ok(surfacePixelShare(camera, 1600, 900) > 0);
+
+  // Toward the planet is always allowed.
+  aim(camera, sliver);
+  assert.equal(
+    lookAngleWithinFrame(camera, 'lookDown', radians(10)),
+    radians(10),
+  );
+
+  // Away from it stops short of losing it.
+  aim(camera, sliver);
+  const away = lookAngleWithinFrame(camera, 'lookUp', radians(30));
+  assert.ok(away < radians(30));
+  camera.lookUp(away);
+  assert.ok(globeFrameShare(camera) > 0);
+  assert.ok(surfacePixelShare(camera, 1600, 900) > 0);
+});
+
+test('the look limit leaves a view with no surface to the move-end recovery', () => {
+  const { camera } = realCamera({ width: 1225, height: 923 });
+  aim(camera, reportedStuckView);
+  assert.equal(
+    lookAngleWithinFrame(camera, 'lookUp', Cesium.Math.toRadians(5)),
+    Cesium.Math.toRadians(5),
+  );
+});
+
+// Surface only in the corners of a 16:9 frame, all of it outside the scope's
+// keyhole: the full frame shows some planet, the scope shows none.
+const cornerOnlyView = { alt: 18_000_000, pitch: -52, roll: 60 };
+
+test('with a scope keyhole, surface hidden in the masked corners counts as none', () => {
+  const { camera } = realCamera();
+  aim(camera, cornerOnlyView);
+  const keyhole = { keyholeRadius: KEYHOLE_OUTER_RADIUS };
+  assert.ok(surfacePixelShare(camera, 1600, 900) > 0);
+  assert.equal(surfacePixelShare(camera, 1600, 900, { keyhole: true }), 0);
+  assert.equal(globeOutOfFrame(camera), false);
+  assert.equal(globeOutOfFrame(camera, keyhole), true);
+  aim(camera, { alt: 18_000_000, pitch: -90 });
+  assert.ok(
+    Math.abs(
+      globeFrameShare(camera, keyhole) -
+        surfacePixelShare(camera, 1600, 900, { keyhole: true }),
+    ) < 0.03,
+    'the keyhole share matches the pick-ray oracle',
+  );
+});
+
+test('the recovery follows the scope: corner-only views are turned back only behind it', () => {
+  for (const [scopeOn, expectRecovery] of [
+    [true, true],
+    [false, false],
+  ]) {
+    const { camera, viewer } = realCamera();
+    installGlobeInViewRecovery(viewer, {
+      keyholeRadius: () => (scopeOn ? KEYHOLE_OUTER_RADIUS : 0),
+    });
+    aim(camera, cornerOnlyView);
+    camera.moveEnd.raiseEvent();
+    assert.equal(
+      Cesium.Math.equalsEpsilon(camera.pitch, -Math.PI / 2, 1e-6),
+      expectRecovery,
+      `scope ${scopeOn ? 'on' : 'off'}`,
+    );
+  }
+});
+
+test('the recovery leaves a camera flight and an authored scene alone', () => {
+  let playing = true;
+  const { camera, scene, viewer } = realCamera({ width: 1225, height: 923 });
+  scene.camera = camera;
+  scene.screenSpaceCameraController = { enableInputs: true };
+  installGlobeInViewRecovery(viewer, { paused: () => playing });
+  aim(camera, reportedStuckView);
+  camera.moveEnd.raiseEvent();
+  assert.equal(globeOutOfFrame(camera), true, 'a playing scene is left alone');
+  playing = false;
+
+  // A flight that pauses looking away is left alone until it ends.
+  camera.flyTo({
+    destination: Cesium.Cartesian3.fromDegrees(10, 20, 18_000_000),
+    duration: 5,
+  });
+  camera.moveEnd.raiseEvent();
+  assert.equal(globeOutOfFrame(camera), true, 'a flight is left alone');
+  camera.cancelFlight();
+  camera.moveEnd.raiseEvent();
+  assert.ok(Cesium.Math.equalsEpsilon(camera.pitch, -Math.PI / 2, 1e-6));
+});
+
+test('a check a scene or flight defers runs once it ends', () => {
+  for (const viaMoveEnd of [false, true]) {
+    let playing = true;
+    const timers = fakeTimers();
+    const { camera, viewer } = realCamera({ width: 1225, height: 923 });
+    installGlobeInViewRecovery(viewer, {
+      paused: () => playing,
+      ...timers,
+    });
+    aim(camera, reportedStuckView);
+    camera.moveStart.raiseEvent();
+    // A hold on a stars-only shot: quiet, with or without Cesium's moveEnd.
+    for (let i = 0; i < 4; i += 1) timers.tick();
+    if (viaMoveEnd) camera.moveEnd.raiseEvent();
+    // Longer than the settle check's five-minute bound.
+    for (let i = 0; i < 1500; i += 1) timers.tick();
+    assert.equal(globeOutOfFrame(camera), true, 'left alone while it plays');
+    assert.equal(timers.pending(), 1, 'still watching');
+    playing = false;
+    timers.tick();
+    assert.ok(
+      Cesium.Math.equalsEpsilon(camera.pitch, -Math.PI / 2, 1e-6),
+      `recovered once the scene ends (${viaMoveEnd ? 'after moveEnd' : 'no moveEnd'})`,
+    );
+  }
+});
+
+// Holding a drag still for half a second on a view that already showed no
+// surface looked like a settled camera, and the view was turned down under
+// the user's hand.
+test('the recovery waits while a pointer is held on the globe', () => {
+  const timers = fakeTimers();
+  const { camera, scene, viewer } = realCamera({ width: 1225, height: 923 });
+  const document = new EventTarget();
+  scene.canvas = Object.assign(new EventTarget(), {
+    clientWidth: 1225,
+    clientHeight: 923,
+    ownerDocument: document,
+  });
+  const dispose = installGlobeInViewRecovery(viewer, timers);
+  aim(camera, reportedStuckView);
+  scene.canvas.dispatchEvent(new Event('pointerdown'));
+  camera.moveStart.raiseEvent();
+  for (let i = 0; i < 8; i += 1) timers.tick();
+  camera.moveEnd.raiseEvent();
+  for (let i = 0; i < 8; i += 1) timers.tick();
+  assert.equal(globeOutOfFrame(camera), true, 'left alone while held');
+  document.dispatchEvent(new Event('pointerup'));
+  for (let i = 0; i < 3; i += 1) timers.tick();
+  assert.ok(
+    Cesium.Math.equalsEpsilon(camera.pitch, -Math.PI / 2, 1e-6),
+    'recovered once the pointer is released',
+  );
+  dispose();
+  aim(camera, reportedStuckView);
+  scene.canvas.dispatchEvent(new Event('pointerdown'));
+  document.dispatchEvent(new Event('pointerup'));
+  assert.equal(timers.pending(), 0, 'disposed recovery holds no listeners');
+});
+
+/** A held-pointer recovery over a canvas in a document in a window. */
+function heldPointerRecovery() {
+  const timers = fakeTimers();
+  const { camera, scene, viewer } = realCamera({ width: 1225, height: 923 });
+  const window = new EventTarget();
+  const document = Object.assign(new EventTarget(), {
+    defaultView: window,
+    visibilityState: 'visible',
+  });
+  scene.canvas = Object.assign(new EventTarget(), {
+    clientWidth: 1225,
+    clientHeight: 923,
+    ownerDocument: document,
+  });
+  const dispose = installGlobeInViewRecovery(viewer, timers);
+  const pointer = (target, type, pointerId, init = {}) =>
+    target.dispatchEvent(
+      Object.assign(new Event(type), { pointerId, ...init }),
+    );
+  /** Press, move and hold still: the check defers while a pointer is held. */
+  const holdStill = () => {
+    aim(camera, reportedStuckView);
+    camera.moveStart.raiseEvent();
+    for (let i = 0; i < 8; i += 1) timers.tick();
+    camera.moveEnd.raiseEvent();
+    for (let i = 0; i < 8; i += 1) timers.tick();
+  };
+  const settle = () => {
+    for (let i = 0; i < 3; i += 1) timers.tick();
+  };
+  const recovered = () =>
+    Cesium.Math.equalsEpsilon(camera.pitch, -Math.PI / 2, 1e-6);
+  return {
+    camera,
+    document,
+    window,
+    dispose,
+    pointer,
+    holdStill,
+    settle,
+    recovered,
+    canvas: scene.canvas,
+  };
+}
+
+// Releasing one of two fingers cleared the held flag, and the recovery
+// turned the view down under the finger still on the glass.
+test('the recovery waits until every held pointer is released', () => {
+  const h = heldPointerRecovery();
+  h.pointer(h.canvas, 'pointerdown', 1);
+  h.pointer(h.canvas, 'pointerdown', 2);
+  h.holdStill();
+  h.pointer(h.document, 'pointerup', 1);
+  h.settle();
+  assert.equal(h.recovered(), false, 'left alone under the second finger');
+  assert.equal(globeOutOfFrame(h.camera), true);
+  h.pointer(h.document, 'pointercancel', 2);
+  h.settle();
+  assert.equal(h.recovered(), true, 'recovered once both are released');
+  h.dispose();
+});
+
+// A release the page never sees (the pointer let go outside the window)
+// must not hold the recovery off for good.
+for (const [label, lose] of [
+  ['the window loses focus', (h) => h.window.dispatchEvent(new Event('blur'))],
+  [
+    'the page is hidden',
+    (h) => {
+      h.document.visibilityState = 'hidden';
+      h.document.dispatchEvent(new Event('visibilitychange'));
+    },
+  ],
+  [
+    'the canvas loses the pointer capture',
+    (h) => h.pointer(h.canvas, 'lostpointercapture', 1),
+  ],
+  [
+    'the pointer moves with no button down',
+    (h) => h.pointer(h.document, 'pointermove', 1, { buttons: 0 }),
+  ],
+]) {
+  test(`a held pointer whose release is lost stops deferring when ${label}`, () => {
+    const h = heldPointerRecovery();
+    h.pointer(h.canvas, 'pointerdown', 1);
+    h.holdStill();
+    h.pointer(h.document, 'pointermove', 1, { buttons: 1 });
+    h.settle();
+    assert.equal(h.recovered(), false, 'left alone while held');
+    lose(h);
+    h.settle();
+    assert.equal(h.recovered(), true, 'recovered once the hold is let go');
+    h.dispose();
+  });
+}
+
+function fakeTimers() {
+  let next = 1;
+  const pending = new Map();
+  return {
+    setTimeout: (callback) => {
+      const id = next++;
+      pending.set(id, callback);
+      return id;
+    },
+    clearTimeout: (id) => pending.delete(id),
+    pending: () => pending.size,
+    /** Run the earliest pending callback, as 250 ms passing would. */
+    tick() {
+      const [id, callback] = pending.entries().next().value ?? [];
+      if (id === undefined) return false;
+      pending.delete(id);
+      callback();
+      return true;
+    },
+  };
+}
+
+test('a stuck view is recovered once it has held still, without waiting for moveEnd', () => {
+  // At this pose the camera can drift by a rounding error every frame, so
+  // Cesium never sees it stop and never raises moveEnd for it.
+  const timers = fakeTimers();
+  const { camera, viewer } = realCamera({ width: 1225, height: 923 });
+  installGlobeInViewRecovery(viewer, timers);
+  aim(camera, reportedStuckView);
+  camera.moveStart.raiseEvent();
+  timers.tick();
+  assert.equal(globeOutOfFrame(camera), true, 'one quiet sample is not enough');
+  // A rounding-error drift between samples still counts as at rest.
+  camera.lookUp(1e-15);
+  timers.tick();
+  assert.ok(Cesium.Math.equalsEpsilon(camera.pitch, -Math.PI / 2, 1e-6));
+  // Under that drift Cesium raises no new moveStart, so a later move that
+  // ends looking away is caught by the same check.
+  aim(camera, reportedStuckView);
+  timers.tick();
+  timers.tick();
+  assert.equal(globeOutOfFrame(camera), true, 'not yet at rest');
+  timers.tick();
+  assert.ok(Cesium.Math.equalsEpsilon(camera.pitch, -Math.PI / 2, 1e-6));
+  camera.moveEnd.raiseEvent();
+  assert.equal(timers.pending(), 0, 'moveEnd ends the check');
+});
+
+test('the settle check follows a long move and gives up five minutes after the last one', () => {
+  // A drag of half a minute that stops at a stuck pose is still recovered.
+  const long = fakeTimers();
+  const dragged = realCamera({ width: 1225, height: 923 });
+  installGlobeInViewRecovery(dragged.viewer, long);
+  aim(dragged.camera, reportedStuckView);
+  dragged.camera.moveStart.raiseEvent();
+  for (let i = 0; i < 120; i += 1) {
+    dragged.camera.moveLeft(0.01);
+    long.tick();
+  }
+  assert.equal(globeOutOfFrame(dragged.camera), true, 'still moving');
+  while (long.tick());
+  assert.ok(
+    Cesium.Math.equalsEpsilon(dragged.camera.pitch, -Math.PI / 2, 1e-6),
+    'recovered once it stopped',
+  );
+
+  // A camera that keeps moving is followed, and left alone, for as long as it
+  // moves; once it rests the check gives up five minutes later.
+  const timers = fakeTimers();
+  const { camera, viewer } = realCamera({ width: 1225, height: 923 });
+  installGlobeInViewRecovery(viewer, timers);
+  aim(camera, reportedStuckView);
+  camera.moveStart.raiseEvent();
+  for (let i = 0; i < 2000; i += 1) {
+    camera.moveLeft(0.01);
+    timers.tick();
+  }
+  assert.equal(timers.pending(), 1, 'still following after eight minutes');
+  assert.equal(globeOutOfFrame(camera), true, 'a moving camera is left alone');
+  let idleSamples = 0;
+  while (timers.tick()) idleSamples += 1;
+  assert.ok(
+    Cesium.Math.equalsEpsilon(camera.pitch, -Math.PI / 2, 1e-6),
+    'recovered once it stopped',
+  );
+  assert.ok(
+    idleSamples >= 1200 && idleSamples <= 1205,
+    `gave up ${idleSamples} samples after it stopped`,
+  );
+
+  const disposed = fakeTimers();
+  const other = realCamera({ width: 1225, height: 923 });
+  const dispose = installGlobeInViewRecovery(other.viewer, disposed);
+  aim(other.camera, reportedStuckView);
+  other.camera.moveStart.raiseEvent();
+  dispose();
+  assert.equal(disposed.pending(), 0, 'dispose cancels the pending check');
+});

src/app/catalog.js

@@ -5,6 +5,7 @@ const CONTROL_LAYER_IDS = Object.freeze({
   satellitesLayer: 'satellites',
   cctvLayer: 'cctv',
   streetLevelLayer: 'street-level',
+  wildlifeSightingsLayer: 'wildlife-sightings',
   radioLayer: 'radio',
   bikeshareLayer: 'bikeshare',
   transitLayer: 'transit',

src/app/catalog.test.mjs

@@ -139,6 +139,7 @@ test('controls bind catalog instances rather than similarly named defaults', ()
     'rocket-launches',
     'street-level',
     'local-adsb',
+    'wildlife-sightings',
   ];
   const layers = ids.map((id) => ({ id }));
   const catalog = createLayerCatalog(layers, metadata(layers));
@@ -147,6 +148,7 @@ test('controls bind catalog instances rather than similarly named defaults', ()
   assert.equal(services.transitLayer, layers[7]);
   assert.equal(services.aisLiveVesselsLayer, layers[8]);
   assert.equal(services.localAdsbLayer, layers[13]);
+  assert.equal(services.wildlifeSightingsLayer, layers[14]);
   assert.equal(new Set(Object.values(services)).size, layers.length);
   assert.throws(
     () => catalogControlServices(createLayerCatalog([], [])),

src/app/constructCatalog.js

@@ -1,7 +1,8 @@
 import { resolveCatalogSources } from './sourceComposition.js';
 import { createWeatherClock } from '../layers/weather/clock.js';
+import { worldClock } from '../time/worldClock.js';
 import { createWeatherLayer } from '../layers/weather/index.js';
-import { createCyclonesLayer } from '../layers/cyclones/index.js';
+import { createApplicationCyclones } from './layers/cyclones.js';
 import { createWindLayer } from '../layers/wind/index.js';
 import { createLayerCatalog } from './catalog.js';
 import { LAYER_STATE_REGISTRY } from '../data/layerState.js';
@@ -30,6 +31,7 @@ import { createApplicationFirePerimeters } from './layers/perimeters.js';
 import { createApplicationGnssIntegrity } from './layers/gnss.js';
 import { createApplicationGhostMaps } from './layers/ghostMaps.js';
 import { createApplicationDroneAirspace } from './layers/droneAirspace.js';
+import { createApplicationWildlifeSightings } from './layers/wildlifeSightings.js';
 import { createApplicationCables } from './layers/submarineCables.js';
 import { createOsmOverlayLayers } from '../data/osmOverlays.js';
 import { createApplicationStreetLevel } from './layers/streetLevel.js';
@@ -77,7 +79,7 @@ export function createApplicationCatalog({
   const sourceComposition = resolveCatalogSources(sources);
   sources = sourceComposition.sources;
   const militaryRegistry = createMilitaryRegistry();
-  const weatherClock = createWeatherClock();
+  const weatherClock = createWeatherClock({ world: worldClock });
   const dispose = () => {
     signal.removeEventListener('abort', dispose);
     militaryRegistry.dispose();
@@ -137,6 +139,10 @@ export function createApplicationCatalog({
         createApplicationDroneAirspace({
           source: sources['drone-airspace'],
         }),
+        createApplicationWildlifeSightings({
+          source: sources['wildlife-sightings'],
+          groundFloor: surface.groundFloor,
+        }),
         createApplicationAlpr({ surface, source: sources.alpr }),
         createApplicationStreetLevel({
           surface,
@@ -177,7 +183,7 @@ export function createApplicationCatalog({
           id: 'weather-lightning',
           clock: weatherClock,
         }),
-        createCyclonesLayer({ feed: sources.cyclones }),
+        createApplicationCyclones({ feed: sources.cyclones }),
         ...createOsmOverlayLayers(),
         ...createInfrastructureLayers(localGeoJsonServices),
         createApplicationCables({ source: sources.cables }),

src/app/constructCatalog.test.mjs

@@ -40,7 +40,7 @@ test('catalogs construct distinct layers and classification from their supplied
     signal: b.signal,
     surface: fixtureSurface(b.signal),
   });
-  assert.equal(first.layers.length, 37);
+  assert.equal(first.layers.length, 38);
   assert.ok(first.get('local-adsb'), 'Local ADS-B is registered');
   assert.deepEqual(
     first.metadata.find(({ id }) => id === 'osm-places'),
@@ -161,7 +161,7 @@ test('Mapillary can be omitted or replaced without changing catalog membership',
     surface: fixtureSurface(lifetime.signal),
   };
   const catalog = createApplicationCatalog(options);
-  assert.equal(catalog.layers.length, 37);
+  assert.equal(catalog.layers.length, 38);
   assert.deepEqual(catalog.get('street-level').providerIds, []);
   assert.equal(
     catalogControlServices(catalog).streetLevelLayer,

src/app/layers/cyclones.js

@@ -0,0 +1,10 @@
+import { createCyclonesLayer } from '../../layers/cyclones/index.js';
+import * as context from '../../data/contextStore.js';
+
+/** Wire cyclone selection to the application shared context. */
+export function createApplicationCyclones(options) {
+  return createCyclonesLayer({
+    context: typeof window !== 'undefined' ? context : null,
+    ...options,
+  });
+}

src/app/layers/gnss.js

@@ -1,6 +1,10 @@
 import { createGnssIntegrityLayer } from '../../layers/gnss/index.js';
+import { worldTimeFor } from '../../time/worldClock.js';
 
 /** Wire the adsb.lol GNSS navigation-integrity layer into the application catalog. */
 export function createApplicationGnssIntegrity(options) {
-  return createGnssIntegrityLayer(options);
+  return createGnssIntegrityLayer({
+    worldNow: worldTimeFor('gnss-integrity'),
+    ...options,
+  });
 }

src/app/layers/recentImagery.js

@@ -2,6 +2,9 @@ import { createRecentImageryLayer } from '../../layers/recentImagery/index.js';
 import { createRecentImageryRenderer } from '../../layers/recentImagery/rendering.js';
 import { createThumbnailLoader } from '../../layers/recentImagery/thumbnails.js';
 import { governorRequestRender } from '../../renderGovernor.js';
+import { worldTimeFor } from '../../time/worldClock.js';
+
+const imageryTime = worldTimeFor('recent-imagery');
 
 /** Construct imagery presentation over one explicitly supplied acquisition source. */
 export function createApplicationRecentImagery({ source }) {
@@ -15,5 +18,6 @@ export function createApplicationRecentImagery({ source }) {
     thumbnails: createThumbnailLoader({
       requestThumbnail: (...args) => source.getThumbnail(...args),
     }),
+    now: () => new Date(imageryTime()),
   });
 }

src/app/layers/wildlifeSightings.js

@@ -0,0 +1,30 @@
+import * as Cesium from 'cesium';
+import { createWildlifeSightingsLayer } from '../../layers/wildlifeSightings/index.js';
+import * as picking from '../../data/pickRegistry.js';
+import * as overlays from '../../overlays/worldOverlay.js';
+import * as sprites from '../../data/spriteOrder.js';
+import * as render from '../../renderGovernor.js';
+import * as context from '../../data/contextStore.js';
+import * as focus from '../../worldFocus.js';
+import { isPointerFree } from '../../data/inputOwnership.js';
+
+/** Bind the wildlife layer to the application's scene and selection owners. */
+export function createApplicationWildlifeSightings(options) {
+  return createWildlifeSightingsLayer({
+    overlayHost: {
+      setEntries: overlays.setOverlayEntries,
+      setVisible: overlays.setOverlaySourceVisible,
+      clearSource: overlays.clearOverlaySource,
+      hitTest: overlays.hitTestWorldOverlay,
+    },
+    screenSpaceEventHandlerFactory: (viewer) =>
+      new Cesium.ScreenSpaceEventHandler(viewer.scene.canvas),
+    picking,
+    pointer: { isPointerFree },
+    sprites,
+    render,
+    context,
+    focus,
+    ...options,
+  });
+}

src/app/scene.js

@@ -2,6 +2,7 @@ import { createApplicationOperations } from './operations.js';
 import * as Cesium from 'cesium';
 import {
   createApplicationViewer,
+  installFreeLookHeightLimit,
   installTrackpadPinchZoom,
 } from '../app/viewer.js';
 import { registerDataCredits } from '../data/dataCredits.js';
@@ -14,6 +15,8 @@ import {
   governorRequestRender,
 } from '../renderGovernor.js';
 import { describeError } from './errors.js';
+import { worldClock, worldTimeFor } from '../time/worldClock.js';
+import { followWorldTime } from '../time/viewerClock.js';
 import { onLocaleChange, t } from '../i18n/index.js';
 
 /** Construct the application globe using the caller's local configuration. */
@@ -58,6 +61,13 @@ export async function createApplicationScene({
     if (!viewer.isDestroyed()) viewer.destroy();
   });
   defer(installTrackpadPinchZoom(viewer));
+  defer(
+    followWorldTime(viewer, worldTimeFor('sky'), {
+      subscribe: worldClock.subscribe,
+      requestRender: () => governorRequestRender('world-time'),
+    }),
+  );
+  defer(installFreeLookHeightLimit(viewer));
   registerDataCredits(viewer, credits);
   configureCreditKeyboardAccess(document);
   defer(onLocaleChange(() => configureCreditKeyboardAccess(document)));

src/app/sourceComposition.js

@@ -50,6 +50,7 @@ export const CATALOG_SOURCE_CONTRACTS = Object.freeze({
   'gnss-integrity': contract(['gnss-integrity'], ['getSnapshot']),
   's2-ghostmaps': contract(['s2-ghostmaps'], ['getCatalog', 'getFile']),
   'drone-airspace': contract(['drone-airspace'], ['getSnapshot']),
+  'wildlife-sightings': contract(['wildlife-sightings'], ['getSnapshot']),
   cables: contract(['telegeography-submarine-cables'], ['fetch']),
   transit: contract(['transit'], ['requestSnapshot', 'getHistory']),
 });

src/app/sourceComposition.test.mjs

@@ -37,7 +37,7 @@ test('every acquisition source can be omitted without losing catalog membership'
 
 test('all acquisition sources may be absent, and enable fails before initializing or fetching', async (t) => {
   const actual = catalog({}, t);
-  assert.equal(actual.layers.length, 37);
+  assert.equal(actual.layers.length, 38);
   const manager = new LayerLifecycle(
     {},
     { getSourceAvailability: actual.getSourceAvailability },

src/app/tools.js

@@ -8,7 +8,13 @@ import { initImageryBoxTool } from '../ui/imageryBoxTool.js';
 import { createRecentImageryPanel } from '../ui/recentImagery.js';
 import { initGevVoiceCommands } from '../voice/gevRealtime.js';
 import { installViews, isEmbeddedInline } from './embed.js';
-import { installScopeMask, destroyScopeMask } from '../scopeMask.js';
+import {
+  installScopeMask,
+  destroyScopeMask,
+  isScopeMaskEnabled,
+} from '../scopeMask.js';
+import { KEYHOLE_OUTER_RADIUS } from '../celestialRing.js';
+import { installGlobeInViewRecovery } from './viewer.js';
 import { installLayerReleaseTrim } from '../sceneCommandRelease.js';
 import {
   installRenderGovernor,
@@ -29,6 +35,7 @@ export function createApplicationTools({
   startChrome,
   onSceneDirector,
   sceneDataPacks,
+  drawMarkActions = [],
   signal,
   defer,
 }) {
@@ -44,6 +51,14 @@ export function createApplicationTools({
     .get('bhote-koshi-2026')
     ?.module.attachSceneController(sceneDirector);
   defer(() => sceneDirector.destroy());
+  defer(
+    installGlobeInViewRecovery(viewer, {
+      // The scope mask hides everything outside its keyhole.
+      keyholeRadius: () => (isScopeMaskEnabled() ? KEYHOLE_OUTER_RADIUS : 0),
+      // An authored scene frames its own shots, holds included.
+      paused: () => sceneDirector.running,
+    }),
+  );
   onSceneDirector?.(sceneDirector);
   const annotations = initAnnotations({
     viewer,
@@ -66,12 +81,15 @@ export function createApplicationTools({
   // while a session is open, so its teardown belongs to the application
   // lifetime rather than to whoever last pressed the button. A row's fly-to
   // goes through the shell's navigation policy, as Import's does.
+  // `drawMarkActions` are an application's own buttons on a drawn area's or
+  // line's row (annotations/drawMarks.js); the standalone shell adds none.
   const drawTool = initDrawTool({
     viewer,
     annotations,
     navigation: styleManager,
     publish: (view) => displayStore.publishDraw(view),
     connect: connectDisplay,
+    markActions: drawMarkActions,
   });
   defer(() => drawTool?.destroy());
   // UTILITIES ▸ Import: the person's own GeoJSON/KML/KMZ/GPX files, each its

src/app/viewer.js

@@ -1,6 +1,53 @@
 import * as Cesium from 'cesium';
 import { applyModelAtmosphereWorkaround } from './atmosphereCompat.js';
 import { StarrySky } from '../sky/starrySky.js';
+import {
+  FREE_LOOK_MAX_HEIGHT_METERS,
+  globeOutOfFrame,
+  isFreeGlobeCamera,
+} from '../globeInView.js';
+
+/**
+ * At the farthest a hand can zoom out, the globe is this share of the
+ * screen's height across. Cesium sets no limit, so zooming on left the globe
+ * a speck among the stars.
+ */
+const MIN_GLOBE_SHARE = 0.3;
+
+/**
+ * The farthest a hand can zoom out, in metres above the ellipsoid, for a
+ * vertical field of view. It follows the screen's shape, as the app's own
+ * whole-globe view does, so that view always lies within it.
+ * @param {number} fovy Vertical field of view, radians.
+ */
+export function zoomOutLimit(fovy) {
+  const radius = Cesium.Ellipsoid.WGS84.maximumRadius;
+  const angular = Math.atan(MIN_GLOBE_SHARE * Math.tan(fovy / 2));
+  return radius / Math.sin(angular) - radius;
+}
+
+/**
+ * Hold a hand's zoom out to `zoomOutLimit` on the globe, each frame, since the
+ * field of view follows the screen's shape. The limit never sits below the
+ * camera: one already past it (a flight, a screen turned) stops there rather
+ * than jumping in at the next zoom. Flat maps keep Cesium's own, unlimited.
+ * @returns {() => void} Stop limiting.
+ */
+export function limitZoomOut(viewer) {
+  const { scene, camera } = viewer;
+  return scene.preRender.addEventListener(() => {
+    const controller = scene.screenSpaceCameraController;
+    const fovy = camera.frustum.fovy;
+    if (scene.mode !== Cesium.SceneMode.SCENE3D || !Number.isFinite(fovy)) {
+      controller.maximumZoomDistance = Number.POSITIVE_INFINITY;
+      return;
+    }
+    controller.maximumZoomDistance = Math.max(
+      zoomOutLimit(fovy),
+      camera.positionCartographic?.height ?? 0,
+    );
+  });
+}
 
 const PINCH_ZOOM_MULTIPLIER = 8;
 const MAX_PINCH_PIXEL_DELTA = 120;
@@ -103,6 +150,231 @@ export function installTrackpadPinchZoom(
   };
 }
 
+/**
+ * Allow Cesium's free look only below `maxHeight` and return its disposer.
+ * Orbit, tilt and zoom stay available at every height. A value other code
+ * sets later is kept as the one to allow below that height, and restored on
+ * dispose; a `false` written while the camera is above `maxHeight` cannot be
+ * told apart from this limit's own write, so dispose restores the earlier
+ * value then. `enableLook` gates the Shift+drag binding only: below its trackball
+ * height Cesium also turns the camera in place for a drag that starts on the
+ * stars. That height is lowered to `maxHeight` too, so above it such a drag
+ * orbits the globe, as it does above Cesium's own 7,500 km.
+ */
+export function installFreeLookHeightLimit(
+  viewer,
+  maxHeight = FREE_LOOK_MAX_HEIGHT_METERS,
+) {
+  const scene = viewer?.scene;
+  const controller = scene?.screenSpaceCameraController;
+  const camera = viewer?.camera;
+  if (!controller || !camera || !scene?.preUpdate)
+    throw new TypeError('A complete Cesium viewer is required');
+
+  const originalTrackBallHeight = controller.minimumTrackBallHeight;
+  const trackBallHeight = Math.min(originalTrackBallHeight, maxHeight);
+  controller.minimumTrackBallHeight = trackBallHeight;
+  let wanted = controller.enableLook;
+  let written;
+  const sync = () => {
+    if (written !== undefined && controller.enableLook !== written)
+      wanted = controller.enableLook;
+    const height = camera.positionCartographic?.height;
+    written = wanted && !(Number.isFinite(height) && height > maxHeight);
+    controller.enableLook = written;
+  };
+  sync();
+  const removeListener = scene.preUpdate.addEventListener(sync);
+
+  let active = true;
+  return () => {
+    if (!active) return;
+    active = false;
+    removeListener();
+    if (controller.enableLook === written) controller.enableLook = wanted;
+    if (controller.minimumTrackBallHeight === trackBallHeight)
+      controller.minimumTrackBallHeight = originalTrackBallHeight;
+  };
+}
+
+// How often a moving camera is sampled to see whether it has come to rest, how
+// far a pose may drift between samples and still count as at rest, and how
+// long after the camera last moved the check gives up if Cesium never raises
+// moveEnd.
+const SETTLE_SAMPLE_MS = 250;
+const SETTLE_POSITION_TOLERANCE_M = 1e-3;
+const SETTLE_DIRECTION_TOLERANCE = 1e-9;
+const SETTLE_GIVE_UP_MS = 5 * 60_000;
+
+/**
+ * Turn the camera back to the planet when a move ends above `minHeight` with
+ * no surface on screen (`globeOutOfFrame`: limb glow and slivers up to about
+ * one sample cell thick can count as none), and return the disposer. Views with
+ * more surface, such as an oblique orbital shot, are left as they are. This
+ * catches a saved or shared view that looked away, or any other move that ends
+ * looking away from the planet.
+ * Heading and position are kept. Tracked cameras, locked ones (non-identity
+ * transform), a camera flight in progress, a pointer held down on the canvas
+ * (a drag held still), the 2D and Columbus modes, and any time `paused`
+ * returns true (an authored scene playing) are left alone; a check they defer
+ * runs once they end, however long they last.
+ * `keyholeRadius`
+ * returns the radius of the visible circle when a scope mask hides the rest of
+ * the frame (see `globeFrameShare`), or 0; it is read at every check.
+ *
+ * Cesium's `moveEnd` alone is not enough: Cesium compares the camera with the
+ * last frame's to the last rounding error, and at some of these poses the
+ * camera drifts by a rounding error every frame, so Cesium never sees it stop.
+ * So each `moveStart` also starts a check of its own that samples the pose
+ * every 250 ms, with a tolerance for that drift, and once the pose has held
+ * for half a second after moving runs the same recovery. It keeps watching
+ * until Cesium raises `moveEnd`, since under that drift Cesium raises no new
+ * `moveStart` for a later move, and gives up five minutes after the camera
+ * last moved.
+ * `setTimeout` and `clearTimeout` can be injected for tests.
+ */
+export function installGlobeInViewRecovery(
+  viewer,
+  {
+    minHeight = FREE_LOOK_MAX_HEIGHT_METERS,
+    keyholeRadius = () => 0,
+    paused = () => false,
+    setTimeout: schedule = globalThis.setTimeout,
+    clearTimeout: unschedule = globalThis.clearTimeout,
+  } = {},
+) {
+  const scene = viewer?.scene;
+  const camera = viewer?.camera;
+  if (!scene || !camera?.moveEnd || !camera?.moveStart)
+    throw new TypeError('A complete Cesium viewer is required');
+
+  // A pointer held on the globe is a gesture in progress, even when it holds
+  // still for half a second: the check waits until every pointer pressed on
+  // it (each finger of a pinch) is released. A release the page never sees,
+  // outside the window, is taken as given when the window loses focus, the
+  // page is hidden, the canvas loses the pointer's capture, or the pointer
+  // moves with no button down.
+  const canvas = scene.canvas;
+  const releaseTarget = canvas?.ownerDocument ?? canvas;
+  const releaseWindow = canvas?.ownerDocument?.defaultView;
+  const heldPointers = new Set();
+  const onPointerDown = (event) => heldPointers.add(event?.pointerId);
+  const onPointerUp = (event) => heldPointers.delete(event?.pointerId);
+  const onPointerMove = (event) => {
+    if (event?.buttons === 0) heldPointers.delete(event.pointerId);
+  };
+  const releaseAll = () => heldPointers.clear();
+  const onVisibilityChange = () => {
+    if (canvas.ownerDocument.visibilityState === 'hidden') releaseAll();
+  };
+  const listeners = [
+    [canvas, 'pointerdown', onPointerDown],
+    [canvas, 'lostpointercapture', onPointerUp],
+    [releaseTarget, 'pointerup', onPointerUp],
+    [releaseTarget, 'pointercancel', onPointerUp],
+    [releaseTarget, 'pointermove', onPointerMove],
+    [canvas?.ownerDocument, 'visibilitychange', onVisibilityChange],
+    [releaseWindow, 'blur', releaseAll],
+  ];
+  for (const [target, type, listener] of listeners)
+    target?.addEventListener?.(type, listener);
+
+  // Returns false while a flight, a paused scene or a held pointer defers the
+  // check, so the caller can try again once it ends.
+  const recover = () => {
+    if (!isFreeGlobeCamera(viewer)) return true;
+    // Cesium has no public running-flight flag.
+    if (camera._currentFlight || paused() || heldPointers.size > 0)
+      return false;
+    const height = camera.positionCartographic?.height;
+    if (
+      !(height > minHeight) ||
+      !globeOutOfFrame(camera, { keyholeRadius: keyholeRadius() })
+    )
+      return true;
+    camera.setView({
+      orientation: {
+        heading: camera.heading,
+        pitch: -Cesium.Math.PI_OVER_TWO,
+        roll: 0,
+      },
+    });
+    scene.requestRender?.();
+    return true;
+  };
+
+  const lastPosition = new Cesium.Cartesian3();
+  const lastDirection = new Cesium.Cartesian3();
+  let settleTimer = null;
+  let settleElapsed = 0;
+  let restingSamples = 0;
+  let movedSinceCheck = false;
+  const stopSettling = () => {
+    if (settleTimer !== null) unschedule(settleTimer);
+    settleTimer = null;
+  };
+  const sample = () => {
+    settleTimer = null;
+    settleElapsed += SETTLE_SAMPLE_MS;
+    const atRest =
+      Cesium.Cartesian3.equalsEpsilon(
+        camera.positionWC,
+        lastPosition,
+        0,
+        SETTLE_POSITION_TOLERANCE_M,
+      ) &&
+      Cesium.Cartesian3.equalsEpsilon(
+        camera.directionWC,
+        lastDirection,
+        0,
+        SETTLE_DIRECTION_TOLERANCE,
+      );
+    restingSamples = atRest ? restingSamples + 1 : 0;
+    if (!atRest) {
+      movedSinceCheck = true;
+      settleElapsed = 0;
+    }
+    // Two quiet samples in a row after a move: at rest for half a second, as
+    // for moveEnd.
+    if (restingSamples >= 2 && movedSinceCheck) {
+      if (recover()) movedSinceCheck = false;
+      // A flight or a playing scene bounds its own deferral.
+      else settleElapsed = 0;
+    }
+    if (settleElapsed >= SETTLE_GIVE_UP_MS) return;
+    Cesium.Cartesian3.clone(camera.positionWC, lastPosition);
+    Cesium.Cartesian3.clone(camera.directionWC, lastDirection);
+    settleTimer = schedule(sample, SETTLE_SAMPLE_MS);
+  };
+  const startSettling = () => {
+    stopSettling();
+    settleElapsed = 0;
+    restingSamples = 0;
+    movedSinceCheck = true;
+    Cesium.Cartesian3.clone(camera.positionWC, lastPosition);
+    Cesium.Cartesian3.clone(camera.directionWC, lastDirection);
+    settleTimer = schedule(sample, SETTLE_SAMPLE_MS);
+  };
+  const removeMoveEnd = camera.moveEnd.addEventListener(() => {
+    if (recover()) stopSettling();
+    // Deferred: keep sampling so the check runs once the flight or scene ends.
+    else if (settleTimer === null) startSettling();
+  });
+  const removeMoveStart = camera.moveStart.addEventListener(startSettling);
+
+  let active = true;
+  return () => {
+    if (!active) return;
+    active = false;
+    stopSettling();
+    removeMoveEnd();
+    removeMoveStart();
+    for (const [target, type, listener] of listeners)
+      target?.removeEventListener?.(type, listener);
+    heldPointers.clear();
+  };
+}
+
 /** Cesium.Viewer options of the standard globe viewer. */
 export function applicationViewerOptions(creditContainer) {
   return {
@@ -142,6 +414,7 @@ export function createApplicationViewer({ container, creditContainer }) {
     // required on touch-first screens. Mouse/trackpad sensitivity stays native.
     if (globalThis.matchMedia?.('(pointer: coarse)').matches)
       viewer.scene.screenSpaceCameraController.zoomFactor *= 3;
+    limitZoomOut(viewer);
     // Before any tile builds a draw command: Cesium's per-vertex model
     // atmosphere fails to LINK on Apple's Metal backend and kills the
     // render loop. See app/atmosphereCompat.js.

src/app/viewer.test.mjs

@@ -0,0 +1,73 @@
+// A hand zooming out stops while the globe is still a fair share of the
+// screen, on any screen's shape, rather than leaving it a speck.
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import * as Cesium from 'cesium';
+import { limitZoomOut, zoomOutLimit } from './viewer.js';
+
+// The share of the screen's height the globe spans from `altitude`.
+function globeShare(altitude, fovy) {
+  const radius = Cesium.Ellipsoid.WGS84.maximumRadius;
+  const angular = Math.asin(radius / (radius + altitude));
+  return Math.tan(angular) / Math.tan(fovy / 2);
+}
+
+test("zooming out stops with the globe 30% of the screen's height across", () => {
+  for (const fovy of [Math.PI / 3, 0.4, 0.2]) {
+    const limit = zoomOutLimit(fovy);
+    assert.ok(Math.abs(globeShare(limit, fovy) - 0.3) < 1e-9, `fovy ${fovy}`);
+  }
+});
+
+test('a wide screen, whose view is narrower, may zoom out farther', () => {
+  assert.ok(zoomOutLimit(0.4) > zoomOutLimit(Math.PI / 3));
+  assert.ok(zoomOutLimit(Math.PI / 3) > 20_000_000, 'past the views a link opens');
+});
+
+function fakeViewer({ fovy = Math.PI / 3, height = 10_000_000 } = {}) {
+  const scene = {
+    mode: Cesium.SceneMode.SCENE3D,
+    preRender: new Cesium.Event(),
+    screenSpaceCameraController: { maximumZoomDistance: Infinity },
+  };
+  const camera = {
+    frustum: { fovy },
+    positionCartographic: { height },
+  };
+  return { scene, camera };
+}
+
+test('the limit follows the screen, and holds a camera already past it', () => {
+  const viewer = fakeViewer();
+  const controller = viewer.scene.screenSpaceCameraController;
+  const stop = limitZoomOut(viewer);
+  viewer.scene.preRender.raiseEvent();
+  assert.equal(controller.maximumZoomDistance, zoomOutLimit(Math.PI / 3));
+
+  // A wider screen narrows the view, and the globe may go farther.
+  viewer.camera.frustum.fovy = 0.4;
+  viewer.scene.preRender.raiseEvent();
+  assert.equal(controller.maximumZoomDistance, zoomOutLimit(0.4));
+
+  // Flown past it, the next zoom out stops there instead of jumping in.
+  viewer.camera.positionCartographic.height = zoomOutLimit(0.4) * 2;
+  viewer.scene.preRender.raiseEvent();
+  assert.equal(controller.maximumZoomDistance, zoomOutLimit(0.4) * 2);
+
+  stop();
+  viewer.camera.positionCartographic.height = 0;
+  viewer.scene.preRender.raiseEvent();
+  assert.equal(controller.maximumZoomDistance, zoomOutLimit(0.4) * 2);
+});
+
+test('flat maps keep zooming out unlimited', () => {
+  const viewer = fakeViewer();
+  const controller = viewer.scene.screenSpaceCameraController;
+  limitZoomOut(viewer);
+  viewer.scene.preRender.raiseEvent();
+  assert.ok(Number.isFinite(controller.maximumZoomDistance));
+  viewer.scene.mode = Cesium.SceneMode.SCENE2D;
+  viewer.camera.frustum = {};
+  viewer.scene.preRender.raiseEvent();
+  assert.equal(controller.maximumZoomDistance, Infinity);
+});

src/cameraGlobeRotation.test.mjs

@@ -13,8 +13,16 @@ import {
   moveCamera,
 } from './cameraVerbs.js';
 import { getRenderGovernorDiagnostics } from './renderGovernor.js';
+import {
+  MIN_GLOBE_FRAME_SHARE,
+  globeFrameShare,
+  globeOutOfFrame,
+} from './globeInView.js';
+import { KEYHOLE_OUTER_RADIUS } from './celestialRing.js';
+import { setScopeMaskEnabled } from './scopeMask.js';
 
 const radians = Cesium.Math.toRadians;
+const degrees = Cesium.Math.toDegrees;
 const clone = (value) => Cesium.Cartesian3.clone(value);
 const longitude = (camera) =>
   Cesium.Cartographic.fromCartesian(camera.positionWC).longitude;
@@ -1347,3 +1355,664 @@ test('close-up ultrawide refusal does not offer an unfit reset or move the camer
   samePose(h.camera, before);
   assert.equal(hasRenderHold(), false);
 });
+
+/**
+ * An oracle independent of the code under test: the share of an 80×45 grid of
+ * Cesium pick rays across the canvas that hit the ellipsoid surface. With
+ * `keyhole`, only the pixels inside the scope's visible circle count.
+ */
+function surfacePixelShare(camera, width, height, { keyhole = false } = {}) {
+  const radius = (KEYHOLE_OUTER_RADIUS * height) / 2;
+  let hits = 0;
+  let counted = 0;
+  for (let row = 0; row < 45; row += 1) {
+    for (let column = 0; column < 80; column += 1) {
+      const x = ((column + 0.5) * width) / 80;
+      const y = ((row + 0.5) * height) / 45;
+      if (keyhole && Math.hypot(x - width / 2, y - height / 2) > radius)
+        continue;
+      counted += 1;
+      const ray = camera.getPickRay(new Cesium.Cartesian2(x, y));
+      if (Cesium.IntersectionTests.rayEllipsoid(ray, Cesium.Ellipsoid.WGS84))
+        hits += 1;
+    }
+  }
+  return hits / counted;
+}
+
+/** Run a test with the scope mask on or off, restoring the default after. */
+function withScope(t, enabled) {
+  setScopeMaskEnabled(enabled);
+  t.after(() => setScopeMaskEnabled(true));
+}
+
+// The frame limit is measured on a coarser grid than the oracle.
+const SHARE_SLACK = 0.02;
+// Far-out poses, height in metres and pitch in degrees, where a few tilts up
+// are accepted before the limit refuses the next one.
+const FAR_OUT_POSES = [
+  [35_884_000, -86.26],
+  [35_884_000, -89],
+  [30_000_000, -86],
+  [25_000_000, -80],
+  [40_000_000, -88],
+];
+
+test('voice tilt from orbit stops with the planet still on screen and then says so', (t) => {
+  withScope(t, false); // the whole frame is visible
+  // Slightly off nadir: from straight down a tilt is clamped before it moves.
+  const { camera, finishOnce } = harness(t, {
+    pitch: -80,
+    viewportWidth: 1600,
+    viewportHeight: 900,
+  });
+  const results = [];
+  for (let i = 0; i < 4; i += 1) {
+    const result = moveCamera({
+      motion: 'tilt',
+      direction: 'up',
+      mode: 'once',
+    });
+    results.push(result);
+    if (result.ok) finishOnce();
+    assert.ok(
+      surfacePixelShare(camera, 1600, 900) >=
+        MIN_GLOBE_FRAME_SHARE - SHARE_SLACK,
+      `after tilt ${i + 1}`,
+    );
+  }
+  // From 18,000 km a 16:9 frame keeps a tenth of its area on the planet down
+  // to about -67°: the first tilt stops there, and later ones are refused.
+  assert.deepEqual(
+    results.map((result) => result.ok),
+    [true, false, false, false],
+  );
+  assert.match(results[1].error, /globe out of view/);
+  assert.ok(camera.pitch > radians(-68.5) && camera.pitch < radians(-66));
+});
+
+// The frame limit judges a tilt by the way its pitch moves, not by the
+// direction word: a tilt down or to a steeper angle turns toward the planet.
+for (const args of [{ direction: 'down' }, { pitchDeg: -80 }]) {
+  test(`a tilt ${JSON.stringify(args)} from the frame limit is judged as the look down it is`, (t) => {
+    withScope(t, false);
+    const { camera, finishOnce } = harness(t, {
+      pitch: -80,
+      viewportWidth: 1600,
+      viewportHeight: 900,
+    });
+    assert.equal(moveCamera({ motion: 'tilt', direction: 'up' }).ok, true);
+    finishOnce();
+    const atLimit = camera.pitch;
+    const result = moveCamera({ motion: 'tilt', ...args });
+    assert.equal(result.ok, true, result.error);
+    finishOnce();
+    assert.ok(camera.pitch < atLimit - radians(5), 'the tilt turned down');
+  });
+}
+
+for (const args of [{ pitchDeg: -10 }, {}]) {
+  test(`a tilt ${JSON.stringify(args)} up from the frame limit is refused, not reported as done`, (t) => {
+    withScope(t, false);
+    const { camera, finishOnce } = harness(t, {
+      pitch: -80,
+      viewportWidth: 1600,
+      viewportHeight: 900,
+    });
+    assert.equal(moveCamera({ motion: 'tilt', direction: 'up' }).ok, true);
+    finishOnce();
+    const atLimit = camera.pitch;
+    // A bare tilt means -45°: up from the -67° limit.
+    const result = moveCamera({ motion: 'tilt', ...args });
+    assert.equal(result.ok, false);
+    assert.match(result.error, /globe out of view/);
+    assert.equal(camera.pitch, atLimit);
+  });
+}
+
+// A tilt to an angle, or a bare tilt (-45°), from orbit turns in place like
+// a nudge and must keep the planet in frame the whole way, or the globe
+// recovery would snap the view back down.
+for (const [label, args, options] of [
+  ['a bare tilt', { motion: 'tilt' }, { pitch: -90 }],
+  ['a tilt to -10°', { motion: 'tilt', pitchDeg: -10 }, { pitch: -90 }],
+  [
+    'a continuous tilt up',
+    { motion: 'tilt', direction: 'up', mode: 'continuous' },
+    { pitch: -90 },
+  ],
+  [
+    'a tilt to -5° from 2,000 km',
+    { motion: 'tilt', pitchDeg: -5 },
+    { pitch: -90, height: 2_000_000 },
+  ],
+]) {
+  test(`${label} from top-down never turns the planet out of frame`, (t) => {
+    withScope(t, false);
+    const { camera, tick } = harness(t, {
+      ...options,
+      viewportWidth: 1600,
+      viewportHeight: 900,
+    });
+    const startPitch = camera.pitch;
+    const result = moveCamera(args);
+    for (let i = 0; i < 600 && getActiveCameraMotion(); i += 1) {
+      tick();
+      assert.ok(
+        surfacePixelShare(camera, 1600, 900) >=
+          MIN_GLOBE_FRAME_SHARE - SHARE_SLACK,
+        `frame ${i}: the planet left the frame`,
+      );
+    }
+    assert.equal(getActiveCameraMotion(), null, 'the tilt must stop');
+    assert.equal(globeOutOfFrame(camera), false, 'no snap-back');
+    if (result.ok) assert.ok(camera.pitch > startPitch, 'the tilt moved');
+  });
+}
+
+// The frame limit stops a tilt to an angle short of it: the reply names the
+// angle the camera reaches, not the one asked for (a tilt to -10° from
+// top-down reported -10° and ended at -66.5°).
+for (const [label, args, options] of [
+  ['a bare tilt', { motion: 'tilt' }, { pitch: -90 }],
+  ['a tilt to -10°', { motion: 'tilt', pitchDeg: -10 }, { pitch: -90 }],
+  [
+    'a tilt to -10° from -80°',
+    { motion: 'tilt', pitchDeg: -10 },
+    { pitch: -80 },
+  ],
+  [
+    'a tilt to -5° from 2,000 km',
+    { motion: 'tilt', pitchDeg: -5 },
+    { pitch: -90, height: 2_000_000 },
+  ],
+  // A rolled camera's look turns its pitch by less than the look angle:
+  // reported -25°, ended at -27.3°.
+  [
+    'a tilt to -5° from 2,000 km rolled 30°',
+    { motion: 'tilt', pitchDeg: -5 },
+    { pitch: -70, roll: 30, height: 2_000_000 },
+  ],
+]) {
+  test(`${label} from orbit reports the angle it reaches`, (t) => {
+    withScope(t, false);
+    const { camera, tick } = harness(t, {
+      ...options,
+      viewportWidth: 1600,
+      viewportHeight: 900,
+    });
+    const result = moveCamera(args);
+    assert.equal(result.ok, true, result.error);
+    for (let i = 0; i < 600 && getActiveCameraMotion(); i += 1) tick();
+    assert.equal(getActiveCameraMotion(), null, 'the tilt must stop');
+    const reached = degrees(camera.pitch);
+    assert.ok(
+      Math.abs(reached - result.pitchDeg) < 1,
+      `reported ${result.pitchDeg}°, reached ${reached}°`,
+    );
+    const asked = args.pitchDeg ?? -45;
+    if (Math.abs(reached - asked) >= 1)
+      assert.match(result.note ?? '', /globe out of view/);
+    else assert.equal(result.note, undefined);
+  });
+}
+
+// A continuous tilt promises no angle: it runs until stopped or the frame
+// limit ends it.
+test('a continuous tilt up from orbit claims no angle it may not reach', (t) => {
+  withScope(t, false);
+  const { tick } = harness(t, {
+    pitch: -90,
+    viewportWidth: 1600,
+    viewportHeight: 900,
+  });
+  const result = moveCamera({
+    motion: 'tilt',
+    direction: 'up',
+    mode: 'continuous',
+  });
+  assert.equal(result.ok, true, result.error);
+  assert.equal('pitchDeg' in result, false);
+  assert.equal(result.mode, 'continuous');
+  for (let i = 0; i < 600 && getActiveCameraMotion(); i += 1) tick();
+  assert.equal(getActiveCameraMotion(), null, 'the frame limit ends it');
+});
+
+test('voice turn in place from orbit stops with the planet still on screen', (t) => {
+  withScope(t, false); // the whole frame is visible
+  const { camera, tick } = harness(t, { pitch: -75 });
+  assert.equal(
+    moveCamera({ motion: 'rotate', direction: 'left', mode: 'continuous' }).ok,
+    true,
+  );
+  const heading = camera.heading;
+  for (let i = 0; i < 400 && getActiveCameraMotion(); i += 1) {
+    tick();
+    assert.ok(
+      surfacePixelShare(camera, 1280, 800) >=
+        MIN_GLOBE_FRAME_SHARE - SHARE_SLACK,
+      `tick ${i + 1}`,
+    );
+  }
+  assert.equal(getActiveCameraMotion(), null, 'the turn stops at the limit');
+  assert.notEqual(camera.heading, heading, 'the turn moved before stopping');
+});
+
+test('a long voice turn below the limit keeps the share it started with', (t) => {
+  withScope(t, false); // the whole frame is visible
+  // About 2% of a 16:9 frame on the planet: the limit is that share, less two
+  // grid cells of sampling noise, for the whole motion rather than per step.
+  const { camera, tick } = harness(t, {
+    pitch: -60,
+    viewportWidth: 1600,
+    viewportHeight: 900,
+  });
+  const start = globeFrameShare(camera);
+  assert.ok(start > 0 && start < MIN_GLOBE_FRAME_SHARE);
+  assert.equal(
+    moveCamera({ motion: 'rotate', direction: 'left', mode: 'continuous' }).ok,
+    true,
+  );
+  for (let i = 0; i < 400 && getActiveCameraMotion(); i += 1) {
+    tick();
+    assert.ok(
+      globeFrameShare(camera) >= start - 2 / (32 * 18) - 1e-9,
+      `tick ${i + 1}`,
+    );
+  }
+  assert.equal(getActiveCameraMotion(), null, 'the turn stops at the limit');
+  assert.ok(surfacePixelShare(camera, 1600, 900) > 0);
+});
+
+test('repeated voice turns from one spot cannot each take a little more', (t) => {
+  withScope(t, false); // the whole frame is visible
+  // About 2% of a 16:9 frame on the planet. Every turn from this position is
+  // measured against the same baseline, so asking again stops being allowed.
+  const { camera, finishOnce, tick } = harness(t, {
+    pitch: -60,
+    viewportWidth: 1600,
+    viewportHeight: 900,
+  });
+  const start = globeFrameShare(camera);
+  const floor = start - 2 / (32 * 18) - 1e-9;
+  const results = [];
+  for (const mode of ['once', 'once', 'continuous', 'once', 'continuous']) {
+    for (let i = 0; i < 4; i += 1) {
+      const result = moveCamera({ motion: 'rotate', direction: 'left', mode });
+      results.push(result.ok);
+      if (!result.ok) continue;
+      if (mode === 'once') finishOnce();
+      else for (let j = 0; j < 400 && getActiveCameraMotion(); j += 1) tick();
+      assert.ok(globeFrameShare(camera) >= floor, `${mode} turn ${i + 1}`);
+    }
+  }
+  assert.ok(results.includes(false), 'a turn at the limit is refused');
+  assert.equal(results.at(-1), false);
+  assert.ok(surfacePixelShare(camera, 1600, 900) > 0);
+});
+
+test('a voice turn after something else turned the camera starts over', (t) => {
+  withScope(t, false); // the whole frame is visible
+  // The same spot, first framed straight down, then turned to about 2% of the
+  // frame by something other than voice: a turn left is measured from there.
+  const { camera, finishOnce } = harness(t, {
+    pitch: -90,
+    viewportWidth: 1600,
+    viewportHeight: 900,
+  });
+  assert.equal(
+    moveCamera({ motion: 'rotate', direction: 'left', mode: 'once' }).ok,
+    true,
+  );
+  finishOnce();
+  camera.setView({
+    orientation: { heading: 0, pitch: radians(-60), roll: 0 },
+  });
+  const start = globeFrameShare(camera);
+  assert.ok(start > 0 && start < MIN_GLOBE_FRAME_SHARE);
+  assert.equal(
+    moveCamera({ motion: 'rotate', direction: 'left', mode: 'once' }).ok,
+    true,
+  );
+  finishOnce();
+  assert.ok(globeFrameShare(camera) >= start - 2 / (32 * 18) - 1e-9);
+});
+
+test('nudging the camera between voice turns cannot take the planet below the 1% floor', (t) => {
+  withScope(t, false); // the whole frame is visible
+  // A wheel notch or an orbit drag between requests starts each turn afresh;
+  // the 1% floor still holds, and below it a turn may only keep what it has.
+  for (const [nudge, pitch] of [
+    [(camera) => camera.moveBackward(2), -60],
+    [(camera) => camera.rotateRight(radians(0.2)), -60],
+    [(camera) => camera.moveBackward(2), -58],
+  ]) {
+    const { camera, tick } = harness(t, {
+      pitch,
+      viewportWidth: 1600,
+      viewportHeight: 900,
+    });
+    const start = globeFrameShare(camera);
+    const floor = Math.min(0.01, start) - 1e-9;
+    for (let i = 0; i < 12; i += 1) {
+      nudge(camera);
+      if (
+        moveCamera({ motion: 'rotate', direction: 'left', mode: 'continuous' })
+          .ok
+      )
+        for (let j = 0; j < 400 && getActiveCameraMotion(); j += 1) tick();
+      assert.ok(
+        globeFrameShare(camera) >= floor,
+        `start ${start}, turn ${i + 1}`,
+      );
+    }
+    assert.ok(surfacePixelShare(camera, 1600, 900) > 0);
+  }
+});
+
+test('after the frame changes size, a voice turn toward the planet is allowed', (t) => {
+  withScope(t, false); // the whole frame is visible
+  // A tilt stops at its limit; then the window widens at the same pose, so the
+  // frame shows less than the carried limit. Toward the planet must still go.
+  const { camera, canvas, viewer, finishOnce } = harness(t, {
+    pitch: -80,
+    viewportWidth: 1600,
+    viewportHeight: 900,
+  });
+  assert.equal(
+    moveCamera({ motion: 'tilt', direction: 'up', mode: 'once' }).ok,
+    true,
+  );
+  finishOnce();
+  canvas.clientWidth = canvas.width = viewer.scene.drawingBufferWidth = 3200;
+  camera.frustum.aspectRatio = 3200 / 900;
+  const narrowed = globeFrameShare(camera);
+  assert.ok(narrowed < MIN_GLOBE_FRAME_SHARE, `frame now shows ${narrowed}`);
+
+  const down = moveCamera({ motion: 'tilt', direction: 'down', mode: 'once' });
+  assert.equal(down.ok, true, down.error);
+  finishOnce();
+  assert.ok(globeFrameShare(camera) > narrowed);
+  assert.equal(
+    moveCamera({ motion: 'tilt', direction: 'down', mode: 'once' }).ok,
+    true,
+  );
+  finishOnce();
+  const up = moveCamera({ motion: 'tilt', direction: 'up', mode: 'once' });
+  if (up.ok) finishOnce();
+  assert.ok(surfacePixelShare(camera, 3200, 900) > 0);
+});
+
+test('with the scope on, a voice tilt stops while the keyhole still shows the planet', (t) => {
+  withScope(t, true);
+  const { camera, finishOnce } = harness(t, {
+    pitch: -80,
+    viewportWidth: 1600,
+    viewportHeight: 900,
+  });
+  const results = [];
+  for (let i = 0; i < 4; i += 1) {
+    const result = moveCamera({
+      motion: 'tilt',
+      direction: 'up',
+      mode: 'once',
+    });
+    results.push(result.ok);
+    if (result.ok) finishOnce();
+    assert.ok(
+      surfacePixelShare(camera, 1600, 900, { keyhole: true }) >=
+        MIN_GLOBE_FRAME_SHARE - SHARE_SLACK,
+      `after tilt ${i + 1}`,
+    );
+  }
+  assert.equal(results[0], true);
+  assert.equal(results.at(-1), false, 'a tilt past the limit is refused');
+});
+
+test('with the scope on, a voice turn cannot leave the planet only in the masked corners', (t) => {
+  // An oblique orbit view: turning in place swings the planet toward a corner,
+  // where the full frame still shows it but the scope mask hides it.
+  for (const [height, pitch] of [
+    [5_000_000, -70],
+    [3_000_000, -75],
+    [18_000_000, -80],
+  ]) {
+    withScope(t, true);
+    const { camera, tick } = harness(t, {
+      height,
+      pitch,
+      viewportWidth: 1600,
+      viewportHeight: 900,
+    });
+    assert.equal(
+      moveCamera({ motion: 'rotate', direction: 'left', mode: 'continuous' })
+        .ok,
+      true,
+    );
+    for (let i = 0; i < 600 && getActiveCameraMotion(); i += 1) tick();
+    assert.equal(getActiveCameraMotion(), null, 'the turn stops at the limit');
+    assert.ok(
+      surfacePixelShare(camera, 1600, 900, { keyhole: true }) >=
+        MIN_GLOBE_FRAME_SHARE - SHARE_SLACK,
+      `${height / 1000} km at ${pitch}°`,
+    );
+  }
+});
+
+test('far out, a voice tilt is either refused or really moves, at display frame rates', (t) => {
+  // A small planet disc: its sampled share wobbles as it crosses the grid.
+  // Whatever the limit decides, "done" must mean the camera turned, and some
+  // of these tilts must be accepted for that to be checked at all.
+  let accepted = 0;
+  for (const [height, pitch] of FAR_OUT_POSES) {
+    withScope(t, true);
+    const { camera, tick } = harness(t, {
+      latitude: 45.37,
+      longitudeDeg: -33.33,
+      height,
+      heading: 89.9,
+      pitch,
+      viewportWidth: 1280,
+      viewportHeight: 1024,
+    });
+    for (let i = 0; i < 4; i += 1) {
+      const before = camera.pitch;
+      const result = moveCamera({
+        motion: 'tilt',
+        direction: 'up',
+        mode: 'once',
+      });
+      if (!result.ok) {
+        assert.match(result.error, /zoom in first/);
+        continue;
+      }
+      accepted += 1;
+      for (let j = 0; j < 600 && getActiveCameraMotion(); j += 1) tick(1 / 60);
+      assert.ok(
+        camera.pitch - before > radians(0.5) - 1e-9,
+        `${height / 1000} km at ${pitch}°: tilt ${i + 1} reported done but moved ${Cesium.Math.toDegrees(camera.pitch - before)}°`,
+      );
+    }
+    assert.ok(surfacePixelShare(camera, 1280, 1024, { keyhole: true }) > 0);
+  }
+  assert.ok(accepted > 0, 'no far-out tilt was accepted');
+});
+
+test('a voice turn reported as done turns at least the half degree its check proved', (t) => {
+  // A grazing sliver: the first frame's small step lands in a dip of the
+  // sampled share, which used to stop the turn before it moved at all.
+  for (const scope of [true, false]) {
+    withScope(t, scope);
+    const { camera, tick } = harness(t, {
+      latitude: 20,
+      longitudeDeg: 10,
+      height: 18_000_000,
+      pitch: -58,
+      heading: 37,
+      viewportWidth: 1600,
+      viewportHeight: 900,
+    });
+    const before = Cesium.Cartesian3.clone(camera.directionWC);
+    const result = moveCamera({
+      motion: 'rotate',
+      direction: 'left',
+      mode: 'once',
+    });
+    if (!result.ok) {
+      assert.match(result.error, /globe out of view/);
+      continue;
+    }
+    for (let i = 0; i < 600 && getActiveCameraMotion(); i += 1) tick(1 / 60);
+    const turned = Cesium.Cartesian3.angleBetween(before, camera.directionWC);
+    assert.ok(
+      turned >= radians(0.5) - 1e-9,
+      `scope ${scope ? 'on' : 'off'}: turned ${Cesium.Math.toDegrees(turned)}°`,
+    );
+    assert.ok(surfacePixelShare(camera, 1600, 900, { keyhole: scope }) > 0);
+  }
+});
+
+/** Track an entity below `camera`, locking it into that entity's frame. */
+function trackFrom(viewer, camera) {
+  viewer.trackedEntity = { id: 'high-satellite' };
+  const below = Cesium.Cartesian3.fromDegrees(10, 20, 400_000);
+  camera.lookAtTransform(Cesium.Transforms.eastNorthUpToFixedFrame(below));
+}
+
+test('a voice turn that releases a tracked camera is checked as released', (t) => {
+  // Voice releases the follow camera inside the navigation that runs the
+  // motion, so the request is judged by the pose the release will leave.
+  let accepted = 0;
+  for (const [scope, direction, motion] of [
+    [true, 'up', 'tilt'],
+    [false, 'up', 'tilt'],
+    [false, 'left', 'rotate'],
+  ]) {
+    withScope(t, scope);
+    const { camera, viewer, tick } = harness(t, {
+      latitude: 20,
+      longitudeDeg: 10,
+      height: 18_000_000,
+      pitch: -58,
+      heading: 37,
+      viewportWidth: 1600,
+      viewportHeight: 900,
+    });
+    trackFrom(viewer, camera);
+    const releaseThenRun = (start) => {
+      viewer.trackedEntity = undefined;
+      camera.lookAtTransform(Cesium.Matrix4.IDENTITY);
+      return start();
+    };
+    const before = Cesium.Cartesian3.clone(camera.directionWC);
+    const result = moveCamera(
+      { motion, direction, mode: 'once' },
+      releaseThenRun,
+    );
+    const label = `${motion} ${direction}, scope ${scope ? 'on' : 'off'}`;
+    if (!result.ok) {
+      assert.match(result.error, /globe out of view/, label);
+      continue;
+    }
+    accepted += 1;
+    for (let i = 0; i < 600 && getActiveCameraMotion(); i += 1) tick(1 / 60);
+    const turned = Cesium.Cartesian3.angleBetween(before, camera.directionWC);
+    assert.ok(turned >= radians(0.5) - 1e-9, `${label}: turned ${turned}`);
+    assert.ok(
+      surfacePixelShare(camera, 1600, 900, { keyhole: scope }) > 0,
+      `${label}: the planet stays on screen`,
+    );
+  }
+  assert.ok(accepted > 0, 'no released turn was accepted');
+});
+
+test('a refused voice turn leaves a tracked camera tracking', (t) => {
+  for (const scope of [true, false]) {
+    withScope(t, scope);
+    const { camera, viewer, tick } = harness(t, {
+      pitch: -80,
+      viewportWidth: 1600,
+      viewportHeight: 900,
+    });
+    // Tilt up to the limit untracked, then track from there.
+    for (let i = 0; i < 40; i += 1) {
+      if (!moveCamera({ motion: 'tilt', direction: 'up', mode: 'once' }).ok)
+        break;
+      for (let j = 0; j < 600 && getActiveCameraMotion(); j += 1) tick(1 / 60);
+    }
+    trackFrom(viewer, camera);
+    const tracked = viewer.trackedEntity;
+    const transform = Cesium.Matrix4.clone(camera.transform);
+    let released = false;
+    const result = moveCamera(
+      { motion: 'tilt', direction: 'up', mode: 'once' },
+      (start) => {
+        released = true;
+        viewer.trackedEntity = undefined;
+        camera.lookAtTransform(Cesium.Matrix4.IDENTITY);
+        return start();
+      },
+    );
+    const label = `scope ${scope ? 'on' : 'off'}`;
+    assert.equal(result.ok, false, label);
+    assert.match(result.error, /globe out of view/, label);
+    assert.equal(released, false, label);
+    assert.equal(viewer.trackedEntity, tracked, label);
+    assert.ok(Cesium.Matrix4.equals(camera.transform, transform), label);
+  }
+});
+
+test('a turn proven at one position is checked again after a release moves the camera', (t) => {
+  withScope(t, false);
+  const { camera, tick } = harness(t, {
+    pitch: -80,
+    viewportWidth: 1600,
+    viewportHeight: 900,
+  });
+  // Tilt up to the limit, then check from 4,000 km closer along the same view
+  // direction, where the next tilt fits; the release moves the camera back.
+  for (let i = 0; i < 40; i += 1) {
+    if (!moveCamera({ motion: 'tilt', direction: 'up', mode: 'once' }).ok)
+      break;
+    for (let j = 0; j < 600 && getActiveCameraMotion(); j += 1) tick(1 / 60);
+  }
+  camera.moveForward(4_000_000);
+  const result = moveCamera(
+    { motion: 'tilt', direction: 'up', mode: 'once' },
+    (start) => {
+      camera.moveBackward(4_000_000);
+      return start();
+    },
+  );
+  assert.equal(result.ok, false);
+  assert.match(result.error, /globe out of view/);
+});
+
+test('the voice frame limit leaves Columbus view alone', (t) => {
+  // At its limit in 3D a further tilt up is refused; the same tilt in Columbus
+  // view is not limited by the frame.
+  withScope(t, false);
+  const { viewer, finishOnce } = harness(t, {
+    pitch: -80,
+    viewportWidth: 1600,
+    viewportHeight: 900,
+  });
+  assert.equal(
+    moveCamera({ motion: 'tilt', direction: 'up', mode: 'once' }).ok,
+    true,
+  );
+  finishOnce();
+  const refused = moveCamera({ motion: 'tilt', direction: 'up', mode: 'once' });
+  assert.match(refused.error || '', /globe out of view/);
+  viewer.scene.mode = Cesium.SceneMode.COLUMBUS_VIEW;
+  const result = moveCamera({ motion: 'tilt', direction: 'up', mode: 'once' });
+  assert.doesNotMatch(result.error || '', /globe out of view/);
+});
+
+test('voice tilt below the free-look height is not limited by the frame', (t) => {
+  const { camera, finishOnce } = harness(t, { height: 500_000, pitch: -60 });
+  const result = moveCamera({ motion: 'tilt', direction: 'up', mode: 'once' });
+  assert.equal(result.ok, true);
+  finishOnce();
+  near(camera.pitch, radians(-45), 1e-6, 'full 15° tilt');
+});

src/cameraHandoff.test.mjs

@@ -42,7 +42,7 @@ function ordered(source, needles, label) {
 test('Cockpit takeover invalidates deferred work before camera cancellation', () => {
   const enter = cockpitEnter.toString();
   ordered(enter, [
-    'if (!info || !entity?.position) return false;',
+    'if (!info || (!vessel && !satellite && !entity?.position)) return false;',
     'this.onCameraTakeover?.();',
     'this.viewer.camera.cancelFlight();',
     'this.viewer.trackedEntity = undefined;',
@@ -106,7 +106,8 @@ test('voice Cockpit entry reaches the camera only through stamping seams', () =>
   );
   ordered(transaction, [
     /if \(\s*!selectedLayer\.trackById\?\.\(selectedTarget\.id, \{\s*origin: selectionOrigin,?\s*\}\)\s*\) \{/,
-    'if (!entryError) entered = Boolean(cockpitView.enter());',
+    // Aircraft-only: a selected vessel must not stand in for a voice target.
+    "if (!entryError) entered = Boolean(cockpitView.enter({ kind: 'aircraft' }));",
   ], 'Cockpit entry transaction');
   // No direct camera control: every mutation goes through a layer tracker or
   // the cockpit controller, both of which stamp.
@@ -223,11 +224,20 @@ test('validated voice camera destinations share the UI navigation authority faca
     'move camera',
   );
   ordered(move, [
-    "if (!['orbit', 'pan', 'tilt', 'rotate', 'rotate_globe'].includes(motion))",
+    'if (argsError) return argsError;',
     'const start = () => {',
     /const preserveCameraFlight =\s*motion === 'orbit'/,
     'runNavigation(start, { preserveCameraFlight })',
   ], 'move validation before handoff');
+  const moveArgs = body(
+    cameraVerbs,
+    /export function moveCameraArgsError\(args = \{\}\) \{([\s\S]*?)\n\}/,
+    'move camera argument checks',
+  );
+  assert.ok(
+    moveArgs.includes("if (!['orbit', 'pan', 'tilt', 'rotate', 'rotate_globe'].includes(motion))"),
+    'unknown motions are refused before handoff',
+  );
 
   const route = body(
     cameraVerbs,

src/cameraTilt.test.mjs

@@ -0,0 +1,773 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import * as Cesium from 'cesium';
+import {
+  adjustOrbitRange,
+  getActiveCameraMotion,
+  initCameraVerbs,
+  interruptCameraMotion,
+  moveCamera,
+} from './cameraVerbs.js';
+import { createGevActionRunner } from './voice/gevActions.js';
+
+const radians = Cesium.Math.toRadians;
+const degrees = Cesium.Math.toDegrees;
+
+/** Real Cesium camera over London with no renderer: the voice fly-to frame. */
+function harness(
+  t,
+  { height = 4000, heading = 0, pitch = -90, pivot = true } = {},
+) {
+  const realPerformance = globalThis.performance;
+  let nowMs = 0;
+  globalThis.performance = { now: () => nowMs };
+  const canvas = Object.assign(new EventTarget(), {
+    clientWidth: 1280,
+    clientHeight: 800,
+    width: 1280,
+    height: 800,
+  });
+  const ellipsoid = Cesium.Ellipsoid.WGS84;
+  const scene = {
+    canvas,
+    drawingBufferWidth: 1280,
+    drawingBufferHeight: 800,
+    frameState: { mode: Cesium.SceneMode.SCENE3D },
+    mapProjection: new Cesium.GeographicProjection(ellipsoid),
+    globe: { ellipsoid },
+    mapMode2D: Cesium.MapMode2D.INFINITE_SCROLL,
+    mode: Cesium.SceneMode.SCENE3D,
+    pixelRatio: 1,
+    tweens: [],
+    requestRender() {},
+  };
+  const camera = new Cesium.Camera(scene);
+  scene.camera = camera;
+  camera.setView({
+    destination: Cesium.Cartesian3.fromDegrees(-0.1276, 51.5072, height),
+    orientation: { heading: radians(heading), pitch: radians(pitch), roll: 0 },
+  });
+  const viewer = {
+    camera,
+    scene,
+    trackedEntity: undefined,
+    trackedEntityChanged: new Cesium.Event(),
+    clock: { onTick: new Cesium.Event() },
+  };
+  // The app's view target: the ground point under the screen centre.
+  const viewTarget = () => {
+    const ray = new Cesium.Ray(camera.positionWC, camera.directionWC);
+    const hit = Cesium.IntersectionTests.rayEllipsoid(ray, ellipsoid);
+    return hit ? Cesium.Ray.getPoint(ray, hit.start) : undefined;
+  };
+  const target = viewTarget();
+  initCameraVerbs(viewer, pivot ? viewTarget : () => undefined);
+  t.after(() => {
+    interruptCameraMotion('test-cleanup');
+    globalThis.performance = realPerformance;
+  });
+  const tick = (seconds = 1 / 30) => {
+    nowMs += seconds * 1000;
+    viewer.clock.onTick.raiseEvent(viewer.clock);
+  };
+  const finish = () => {
+    for (let i = 0; i < 600 && getActiveCameraMotion(); i += 1) tick();
+    assert.equal(getActiveCameraMotion(), null, 'tilt must finish');
+  };
+  return { viewer, camera, target, tick, finish, viewTarget };
+}
+
+const pitchDeg = (camera) => degrees(camera.pitch);
+/** Tick until done() holds; a regression fails here instead of hanging. */
+const tickUntil = (h, done, frames = 600) => {
+  for (let i = 0; i < frames && !done(); i += 1) h.tick();
+  assert.ok(done(), `not reached in ${frames} frames`);
+};
+const headingDeg = (camera) =>
+  degrees(Cesium.Math.negativePiToPi(camera.heading));
+
+/** Metres between the original centre and the ground now under the crosshair. */
+function centreDrift(h) {
+  return Cesium.Cartesian3.distance(h.viewTarget(), h.target);
+}
+
+test('tilt up leaves a top-down view and keeps the place centred', (t) => {
+  const h = harness(t);
+  const result = moveCamera({ motion: 'tilt', direction: 'up' });
+  assert.equal(result.ok, true);
+  h.finish();
+  assert.ok(
+    Math.abs(pitchDeg(h.camera) - -75) < 0.5,
+    `pitch ${pitchDeg(h.camera)}`,
+  );
+  assert.ok(centreDrift(h) < 5, `centre drifted ${centreDrift(h)} m`);
+  assert.ok(Cesium.Matrix4.equals(h.camera.transform, Cesium.Matrix4.IDENTITY));
+});
+
+test('continuous tilt up from top-down keeps moving', (t) => {
+  const h = harness(t);
+  assert.equal(
+    moveCamera({ motion: 'tilt', direction: 'up', mode: 'continuous' }).ok,
+    true,
+  );
+  for (let i = 0; i < 30; i += 1) h.tick();
+  assert.equal(getActiveCameraMotion()?.kind, 'tilt');
+  assert.ok(pitchDeg(h.camera) > -82, `pitch ${pitchDeg(h.camera)}`);
+});
+
+test('a requested angle tilts to that pitch', (t) => {
+  const h = harness(t);
+  const result = moveCamera({ motion: 'tilt', pitchDeg: -45 });
+  assert.equal(result.ok, true);
+  assert.equal(result.direction, 'up');
+  assert.equal(result.pitchDeg, -45);
+  h.finish();
+  assert.ok(
+    Math.abs(pitchDeg(h.camera) - -45) < 0.5,
+    `pitch ${pitchDeg(h.camera)}`,
+  );
+  assert.ok(centreDrift(h) < 5, `centre drifted ${centreDrift(h)} m`);
+});
+
+test('a bare tilt settles on the default oblique angle', (t) => {
+  const h = harness(t);
+  const result = moveCamera({ motion: 'tilt' });
+  assert.equal(result.ok, true);
+  assert.equal(result.pitchDeg, -45);
+  h.finish();
+  assert.ok(Math.abs(pitchDeg(h.camera) - -45) < 0.5);
+});
+
+test('a requested angle can tilt back down toward top-down', (t) => {
+  const h = harness(t, { pitch: -30 });
+  const result = moveCamera({ motion: 'tilt', pitchDeg: -80 });
+  assert.equal(result.direction, 'down');
+  h.finish();
+  assert.ok(Math.abs(pitchDeg(h.camera) - -80) < 0.5);
+});
+
+test('requested angles clamp to the tilt limits', (t) => {
+  const h = harness(t);
+  assert.equal(moveCamera({ motion: 'tilt', pitchDeg: -2 }).pitchDeg, -5);
+  h.finish();
+  assert.ok(Math.abs(pitchDeg(h.camera) - -5) < 0.5);
+});
+
+test('a positive angle is read as the same angle below the horizon', (t) => {
+  const h = harness(t);
+  assert.equal(moveCamera({ motion: 'tilt', pitchDeg: 45 }).pitchDeg, -45);
+  h.finish();
+  assert.ok(Math.abs(pitchDeg(h.camera) - -45) < 0.5);
+});
+
+for (const pitch of ['', null, false, ' ', 'steep'])
+  test(`a blank or non-numeric angle ${JSON.stringify(pitch)} is ignored`, (t) => {
+    harness(t);
+    const result = moveCamera({ motion: 'tilt', pitchDeg: pitch });
+    // No angle and no direction: the default oblique view, never the horizon.
+    assert.equal(result.pitchDeg, -45);
+  });
+
+test('a requested angle the camera already holds is a no-op', (t) => {
+  harness(t, { pitch: -45 });
+  const result = moveCamera({ motion: 'tilt', pitchDeg: -45 });
+  assert.equal(result.ok, true);
+  assert.equal(result.unchanged, true);
+  assert.equal(getActiveCameraMotion(), null);
+});
+
+for (const pitch of [-90, -89]) {
+  test(`a top-down view asked for ${pitch}° stays put`, (t) => {
+    // The tool description calls -89 top-down; the clamp must not tilt a
+    // -90° view up 1° and report it as a move up.
+    const h = harness(t);
+    const before = pitchDeg(h.camera);
+    const result = moveCamera({ motion: 'tilt', pitchDeg: pitch });
+    assert.equal(result.ok, true);
+    assert.equal(result.unchanged, true);
+    assert.equal(result.pitchDeg, Math.round(before));
+    assert.equal(getActiveCameraMotion(), null);
+    assert.equal(pitchDeg(h.camera), before);
+  });
+}
+
+test('tilt down from top-down still refuses honestly', (t) => {
+  harness(t);
+  const result = moveCamera({ motion: 'tilt', direction: 'down' });
+  assert.equal(result.ok, false);
+  assert.match(result.error, /straight down/);
+});
+
+test('a tilt up nudge stops at the horizon limit', (t) => {
+  const h = harness(t, { pitch: -12 });
+  assert.equal(moveCamera({ motion: 'tilt', direction: 'up' }).ok, true);
+  h.finish();
+  assert.ok(Math.abs(pitchDeg(h.camera) - -5) < 0.5);
+});
+
+test('without a ground pivot a tilt still leaves top-down in place', (t) => {
+  const h = harness(t, { pivot: false });
+  const before = Cesium.Cartesian3.clone(h.camera.positionWC);
+  assert.equal(moveCamera({ motion: 'tilt', direction: 'up' }).ok, true);
+  h.finish();
+  assert.ok(Math.abs(pitchDeg(h.camera) - -75) < 0.5);
+  assert.ok(Cesium.Cartesian3.distance(h.camera.positionWC, before) < 1e-6);
+});
+
+for (const heading of [0, 30, -120])
+  test(`tilt from top-down keeps the ${heading}° heading`, (t) => {
+    const h = harness(t, { heading, height: 67000 });
+    // Top-down float noise must not pick a new heading for the pivot.
+    assert.equal(moveCamera({ motion: 'tilt', pitchDeg: -45 }).ok, true);
+    h.finish();
+    assert.ok(
+      Math.abs(headingDeg(h.camera) - heading) < 1,
+      `heading ${headingDeg(h.camera)}`,
+    );
+    assert.ok(centreDrift(h) < 50, `centre drifted ${centreDrift(h)} m`);
+  });
+
+test('an oblique tilt keeps its heading toward the pivot', (t) => {
+  const h = harness(t, { heading: 75, pitch: -60 });
+  assert.equal(moveCamera({ motion: 'tilt', pitchDeg: -30 }).ok, true);
+  h.finish();
+  assert.ok(Math.abs(headingDeg(h.camera) - 75) < 0.5);
+  assert.ok(centreDrift(h) < 5, `centre drifted ${centreDrift(h)} m`);
+});
+
+test('a pivoting tilt yields when tracking takes the camera', (t) => {
+  const h = harness(t);
+  assert.equal(moveCamera({ motion: 'tilt', pitchDeg: -45 }).ok, true);
+  h.tick();
+  const entity = { id: 'tracked' };
+  h.viewer.trackedEntity = entity;
+  h.viewer.trackedEntityChanged.raiseEvent(entity);
+  assert.equal(getActiveCameraMotion(), null);
+});
+
+/** Metres between the camera and the point it pivots about. */
+const pivotRange = (h) =>
+  Cesium.Cartesian3.distance(h.camera.positionWC, h.target);
+const heightM = (camera) =>
+  Cesium.Cartographic.fromCartesian(camera.positionWC).height;
+
+test('a zoom during a pivoting tilt changes the range it holds', (t) => {
+  const h = harness(t);
+  assert.equal(
+    moveCamera({ motion: 'tilt', direction: 'up', mode: 'continuous' }).ok,
+    true,
+  );
+  h.tick();
+  const before = pivotRange(h);
+  assert.deepEqual(
+    adjustOrbitRange(0.5),
+    { kind: 'tilt', changed: true },
+    'the tilt must take the zoom',
+  );
+  for (let i = 0; i < 5; i += 1) h.tick();
+  // The next frame's lookAt must not put the old range back.
+  assert.ok(
+    Math.abs(pivotRange(h) - before / 2) < 1,
+    `range ${pivotRange(h)} m, wanted ${before / 2} m`,
+  );
+});
+
+test('a zoom with no pivot to hold is left to the camera', (t) => {
+  harness(t, { pivot: false });
+  moveCamera({ motion: 'tilt', direction: 'up', mode: 'continuous' });
+  assert.equal(adjustOrbitRange(0.5), null);
+});
+
+test('a pivot tilt toward the horizon keeps its clearance above the ground', (t) => {
+  // A close top-down view: swinging 250 m of range to -5° would end ~22 m up.
+  const h = harness(t, { height: 250 });
+  assert.equal(moveCamera({ motion: 'tilt', pitchDeg: -5 }).ok, true);
+  let lowest = Infinity;
+  for (let i = 0; i < 600 && getActiveCameraMotion(); i += 1) {
+    h.tick();
+    lowest = Math.min(lowest, heightM(h.camera));
+  }
+  assert.equal(getActiveCameraMotion(), null, 'tilt must finish');
+  assert.ok(lowest > 149, `camera dropped to ${lowest} m`);
+  assert.ok(
+    Math.abs(pitchDeg(h.camera) - -5) < 0.5,
+    `pitch ${pitchDeg(h.camera)}`,
+  );
+  assert.ok(Cesium.Matrix4.equals(h.camera.transform, Cesium.Matrix4.IDENTITY));
+});
+
+test('a continuous tilt up from close in keeps its clearance', (t) => {
+  const h = harness(t, { height: 250 });
+  moveCamera({ motion: 'tilt', direction: 'up', mode: 'continuous' });
+  for (let i = 0; i < 600 && getActiveCameraMotion(); i += 1) {
+    h.tick();
+    assert.ok(heightM(h.camera) > 149, `camera at ${heightM(h.camera)} m`);
+  }
+  assert.ok(Math.abs(pitchDeg(h.camera) - -5) < 0.5);
+});
+
+test('a city-scale pivot tilt keeps the place centred to the horizon limit', (t) => {
+  const h = harness(t);
+  moveCamera({ motion: 'tilt', pitchDeg: -5 });
+  h.finish();
+  // 4 km of range clears the floor at every pitch: all pivot, no drift.
+  assert.ok(centreDrift(h) < 5, `centre drifted ${centreDrift(h)} m`);
+});
+
+test('pitchDeg against a contradicting direction is refused', (t) => {
+  harness(t, { pitch: -45 });
+  // "tilt down 10 degrees": -10° is an absolute angle, which is up from -45°.
+  const result = moveCamera({
+    motion: 'tilt',
+    direction: 'down',
+    pitchDeg: 10,
+  });
+  assert.equal(result.ok, false);
+  assert.match(result.error, /absolute angle/);
+  assert.equal(getActiveCameraMotion(), null);
+});
+
+test('pitchDeg with a direction that agrees still tilts', (t) => {
+  const h = harness(t, { pitch: -45 });
+  const result = moveCamera({
+    motion: 'tilt',
+    direction: 'down',
+    pitchDeg: -80,
+  });
+  assert.equal(result.ok, true);
+  assert.equal(result.direction, 'down');
+  h.finish();
+  assert.ok(Math.abs(pitchDeg(h.camera) - -80) < 0.5);
+});
+
+test('the pitchDeg and direction check uses the camera pitch', (t) => {
+  // At regional range the Earth curves away and the pivot pitch is a degree
+  // or two shallower than the camera's (-30°); -29° is still up from it.
+  harness(t, { height: 150000, pitch: -30 });
+  const down = moveCamera({ motion: 'tilt', direction: 'down', pitchDeg: -29 });
+  assert.equal(down.ok, false);
+  assert.match(down.error, /tilts up, not down/);
+  const up = moveCamera({ motion: 'tilt', direction: 'up', pitchDeg: -29 });
+  assert.equal(up.ok, true);
+  assert.equal(up.direction, 'up');
+});
+
+test('after a zoom in, a pivoting tilt never lowers the camera further', (t) => {
+  const h = harness(t, { height: 1000 });
+  moveCamera({ motion: 'tilt', direction: 'up', mode: 'continuous' });
+  tickUntil(h, () => pitchDeg(h.camera) >= -30);
+  adjustOrbitRange(1 / 2.4);
+  adjustOrbitRange(1 / 2.4);
+  h.tick();
+  const afterZoom = heightM(h.camera);
+  for (let i = 0; i < 600 && getActiveCameraMotion(); i += 1) {
+    h.tick();
+    assert.ok(
+      heightM(h.camera) > afterZoom - 1,
+      `camera fell from ${afterZoom} m to ${heightM(h.camera)} m`,
+    );
+  }
+  assert.ok(Math.abs(pitchDeg(h.camera) - -5) < 0.5);
+});
+
+test('a zoom in during a close pivot tilt never pushes the camera out', (t) => {
+  // 62 m of range, under the 80 m zoom floor.
+  const h = harness(t, { height: 40, pitch: -40 });
+  moveCamera({ motion: 'tilt', direction: 'down', mode: 'continuous' });
+  h.tick();
+  const before = pivotRange(h);
+  assert.ok(before < 80, `range ${before} m`);
+  adjustOrbitRange(1 / 1.6);
+  h.tick();
+  assert.ok(pivotRange(h) <= before + 0.01, `range grew to ${pivotRange(h)} m`);
+});
+
+test('a zoom out during a far orbit never pulls the camera in', (t) => {
+  // 15,000 km up, beyond the 5,000 km zoom cap.
+  const h = harness(t, { height: 15_000_000 });
+  assert.equal(moveCamera({ motion: 'orbit', mode: 'continuous' }).ok, true);
+  h.tick();
+  const before = pivotRange(h);
+  assert.ok(before > 5_000_000, `range ${before} m`);
+  assert.deepEqual(adjustOrbitRange(2.4), { kind: 'orbit', changed: false });
+  h.tick();
+  assert.ok(pivotRange(h) >= before - 1, `range fell to ${pivotRange(h)} m`);
+});
+
+test('an out-of-range pitchDeg is clamped to the tilt limits', (t) => {
+  // The schema carries no range; 120 reads as 120° below the horizon.
+  const h = harness(t, { pitch: -45 });
+  assert.equal(moveCamera({ motion: 'tilt', pitchDeg: 120 }).ok, true);
+  h.finish();
+  assert.ok(
+    Math.abs(pitchDeg(h.camera) - -89) < 0.5,
+    `pitch ${pitchDeg(h.camera)}`,
+  );
+});
+
+test('a zoom in during a pivot tilt stops at the clearance', (t) => {
+  // 400 m of range at -40°, then "zoom in a lot" twice: unfloored, that left
+  // the camera about 107 m up, then at the 80 m zoom floor.
+  const h = harness(t, { height: 400 });
+  moveCamera({ motion: 'tilt', direction: 'up', mode: 'continuous' });
+  tickUntil(h, () => pitchDeg(h.camera) >= -40);
+  assert.deepEqual(adjustOrbitRange(1 / 2.4), { kind: 'tilt', changed: true });
+  // At -40° the floor is 150 / sin 40° ≈ 233 m, which the first zoom reached.
+  assert.deepEqual(adjustOrbitRange(1 / 2.4), { kind: 'tilt', changed: false });
+  // The camera must take that range, not just report it.
+  h.tick();
+  const floor = 150 / Math.sin(radians(40));
+  assert.ok(
+    Math.abs(pivotRange(h) - floor) < floor * 0.02,
+    `range ${pivotRange(h)} m, wanted about ${floor} m`,
+  );
+  for (let i = 0; i < 600 && getActiveCameraMotion(); i += 1) {
+    h.tick();
+    assert.ok(heightM(h.camera) > 149, `camera at ${heightM(h.camera)} m`);
+  }
+  assert.ok(Math.abs(pitchDeg(h.camera) - -5) < 0.5);
+});
+
+test('a voice zoom during a pivot tilt says what it changed', async (t) => {
+  const h = harness(t, { height: 400 });
+  const runner = createGevActionRunner({
+    viewer: h.viewer,
+    styleManager: {},
+    dataManager: { layers: new Map(), getAll: () => [] },
+  });
+  moveCamera({ motion: 'tilt', direction: 'up', mode: 'continuous' });
+  h.tick();
+  const zoom = { direction: 'in', amount: 'lot' };
+  const first = await runner('adjust_camera_zoom', zoom);
+  assert.equal(first.ok, true);
+  assert.equal(first.tiltRangeAdjusted, true);
+  assert.equal('orbitRadiusAdjusted' in first, false);
+  // 400 m → 167 m → the 150 m clearance; a third zoom in moves nothing, and
+  // says so.
+  assert.equal((await runner('adjust_camera_zoom', zoom)).ok, true);
+  const third = await runner('adjust_camera_zoom', zoom);
+  assert.equal(third.ok, false);
+  assert.match(third.error, /tilt is already at its closest range/);
+});
+
+test('from globe range a tilt happens in place', (t) => {
+  // A pivot 2,000 km out would swing the camera thousands of km.
+  const h = harness(t, { height: 2_000_000 });
+  const before = Cesium.Cartesian3.clone(h.camera.positionWC);
+  assert.equal(moveCamera({ motion: 'tilt', pitchDeg: -45 }).ok, true);
+  h.finish();
+  assert.ok(Math.abs(pitchDeg(h.camera) - -45) < 0.5);
+  assert.ok(Cesium.Cartesian3.distance(h.camera.positionWC, before) < 1e-3);
+});
+
+for (const height of [100_000, 400_000])
+  test(`from ${height / 1000} km a tilt to -5° ends with the camera at -5°`, (t) => {
+    // The pivot pitch is shallower than the camera's by up to 4° at this
+    // range; the camera reached only -5.9° and -8.6° when the swing stopped
+    // at a pivot pitch of -5°.
+    const h = harness(t, { height });
+    const result = moveCamera({ motion: 'tilt', pitchDeg: 5 });
+    assert.equal(result.pitchDeg, -5);
+    h.finish();
+    assert.ok(
+      Math.abs(pitchDeg(h.camera) - -5) < 0.5,
+      `pitch ${pitchDeg(h.camera)}`,
+    );
+    assert.ok(heightM(h.camera) > 149, `camera at ${heightM(h.camera)} m`);
+    const nudge = moveCamera({ motion: 'tilt', direction: 'up' });
+    assert.equal(nudge.ok, false);
+    assert.match(nudge.error, /upper tilt limit/);
+  });
+
+// From 550 km out the camera's -5° lies beyond the place's own horizon: the
+// swing ran into its clearance, let go of the pivot and tilted the rest in
+// place, which put the crosshair on the sky (28 to 63 km up), and a return
+// to top-down then landed 600 to 900 km from the place.
+for (const height of [600_000, 700_000, 900_000]) {
+  test(`from ${height / 1000} km a tilt to -5° keeps the place centred`, (t) => {
+    const h = harness(t, { height });
+    const result = moveCamera({ motion: 'tilt', pitchDeg: 5 });
+    assert.equal(result.ok, true);
+    h.finish();
+    assert.ok(h.viewTarget(), 'the crosshair is on the sky');
+    assert.ok(centreDrift(h) < 100, `centre drifted ${centreDrift(h)} m`);
+    assert.ok(heightM(h.camera) > 149, `camera at ${heightM(h.camera)} m`);
+    // The reply names the angle the camera reached, not the one asked for.
+    assert.ok(result.pitchDeg < -5, `reported ${result.pitchDeg}°`);
+    assert.ok(
+      Math.abs(pitchDeg(h.camera) - result.pitchDeg) < 0.5,
+      `camera at ${pitchDeg(h.camera)}°, reported ${result.pitchDeg}°`,
+    );
+    assert.match(result.note, /horizon/);
+    const nudge = moveCamera({ motion: 'tilt', direction: 'up' });
+    assert.equal(nudge.ok, false);
+    assert.match(nudge.error, /upper tilt limit/);
+    assert.equal(moveCamera({ motion: 'tilt', pitchDeg: -89 }).ok, true);
+    h.finish();
+    assert.ok(centreDrift(h) < 100, `centre drifted ${centreDrift(h)} m`);
+    // Back over the place at the range it began with (-89° is ~1° off nadir).
+    const range = Cesium.Cartesian3.distance(h.camera.positionWC, h.target);
+    assert.ok(
+      Math.abs(range - height) < height * 0.01,
+      `top-down ${range} m from the place`,
+    );
+  });
+
+  test(`a continuous tilt up from ${height / 1000} km stops with the place centred`, (t) => {
+    const h = harness(t, { height });
+    moveCamera({ motion: 'tilt', direction: 'up', mode: 'continuous' });
+    for (let i = 0; i < 1200 && getActiveCameraMotion(); i += 1) {
+      h.tick();
+      assert.ok(h.viewTarget(), `the crosshair is on the sky at frame ${i}`);
+    }
+    assert.equal(getActiveCameraMotion(), null, 'tilt must stop at its limit');
+    assert.ok(centreDrift(h) < 100, `centre drifted ${centreDrift(h)} m`);
+  });
+}
+
+test('a pitchDeg tilt toward the horizon limit says it is already there', (t) => {
+  const h = harness(t, { height: 900_000 });
+  moveCamera({ motion: 'tilt', pitchDeg: 5 });
+  h.finish();
+  const again = moveCamera({ motion: 'tilt', pitchDeg: 5 });
+  assert.equal(again.ok, false);
+  assert.match(again.error, /upper tilt limit/);
+});
+
+test('a regional tilt-up nudge goes to the camera horizon limit', (t) => {
+  // 20 km up at -7°: the pivot 186 km out sits at -5.3°, but the camera can
+  // still tilt up 2°.
+  const h = harness(t, { height: 20000, pitch: -7 });
+  assert.equal(moveCamera({ motion: 'tilt', direction: 'up' }).ok, true);
+  h.finish();
+  assert.ok(
+    Math.abs(pitchDeg(h.camera) - -5) < 0.5,
+    `pitch ${pitchDeg(h.camera)}`,
+  );
+});
+
+test('a voice tilt from a tracked view judges its limit from the camera pitch', (t) => {
+  const h = harness(t, { height: 20000, pitch: -5.2 });
+  h.viewer.trackedEntity = { id: 'tracked' };
+  // Voice releases the follow camera before the motion starts.
+  const release = (start) => {
+    h.viewer.trackedEntity = undefined;
+    return start();
+  };
+  const result = moveCamera({ motion: 'tilt', direction: 'up' }, release);
+  assert.equal(result.ok, false);
+  assert.match(result.error, /upper tilt limit/);
+});
+
+test('a zoom out during a pivoting tilt stops at the pivot range limit', (t) => {
+  // 900 km top-down, "tilt to 10°", then "zoom out a lot" twice: capped at
+  // the orbit's 5,000 km, the swing reached 2,386 km up at a real -44°.
+  const h = harness(t, { height: 900_000 });
+  assert.equal(moveCamera({ motion: 'tilt', pitchDeg: -10 }).ok, true);
+  h.tick();
+  assert.deepEqual(adjustOrbitRange(2.4), { kind: 'tilt', changed: true });
+  assert.deepEqual(adjustOrbitRange(2.4), { kind: 'tilt', changed: false });
+  let farthest = 0;
+  for (let i = 0; i < 600 && getActiveCameraMotion(); i += 1) {
+    h.tick();
+    farthest = Math.max(farthest, pivotRange(h));
+  }
+  assert.equal(getActiveCameraMotion(), null, 'tilt must finish');
+  assert.ok(farthest <= 1_000_001, `swung ${farthest} m from the pivot`);
+  assert.ok(
+    Math.abs(pitchDeg(h.camera) - -10) < 0.5,
+    `pitch ${pitchDeg(h.camera)}`,
+  );
+});
+
+test('an unchanged angle still stops a running motion through navigation', (t) => {
+  const h = harness(t);
+  moveCamera({ motion: 'tilt', direction: 'up', mode: 'continuous' });
+  tickUntil(h, () => pitchDeg(h.camera) >= -45.3);
+  let handoffs = 0;
+  const navigate = (start) => {
+    handoffs += 1;
+    return start();
+  };
+  const result = moveCamera({ motion: 'tilt', pitchDeg: -45 }, navigate);
+  assert.equal(result.ok, true);
+  assert.equal(result.unchanged, true);
+  assert.equal(handoffs, 1, 'the request must take navigation');
+  assert.equal(getActiveCameraMotion(), null, 'the tilt must stop');
+  const held = pitchDeg(h.camera);
+  for (let i = 0; i < 30; i += 1) h.tick();
+  assert.equal(pitchDeg(h.camera), held);
+});
+
+for (const direction of ['left', 'right'])
+  test(`a tilt ${direction} is refused`, (t) => {
+    harness(t, { pitch: -45 });
+    const result = moveCamera({ motion: 'tilt', direction });
+    assert.equal(result.ok, false);
+    assert.match(result.error, /tilt needs up or down/);
+    const angled = moveCamera({ motion: 'tilt', direction, pitchDeg: -30 });
+    assert.equal(angled.ok, false);
+    assert.match(angled.error, /pitchDeg alone/);
+    assert.equal(getActiveCameraMotion(), null);
+  });
+
+// The 1,000 km pivot cutoff includes its boundary: at exactly 1,000 km the
+// pivot range came back a hair over it, so the tilt ran in place and put the
+// crosshair on the sky.
+test('from exactly 1,000 km a tilt to -5° still pivots about the place', (t) => {
+  const h = harness(t, { height: 1_000_000 });
+  const result = moveCamera({ motion: 'tilt', pitchDeg: 5 });
+  assert.equal(result.ok, true);
+  h.finish();
+  assert.ok(h.viewTarget(), 'the crosshair is on the sky');
+  assert.ok(centreDrift(h) < 100, `centre drifted ${centreDrift(h)} m`);
+  assert.ok(
+    Math.abs(pitchDeg(h.camera) - result.pitchDeg) < 0.5,
+    `camera at ${pitchDeg(h.camera)}°, reported ${result.pitchDeg}°`,
+  );
+  assert.match(result.note, /horizon/);
+});
+
+// A zoom mid-tilt moves the pivot's horizon limit: the zoom's reply names the
+// angle the tilt now ends at, and the camera ends there.
+test('a zoom out during a tilt to an angle reports the angle it now ends at', (t) => {
+  const h = harness(t, { height: 400_000 });
+  const result = moveCamera({ motion: 'tilt', pitchDeg: -5 });
+  assert.equal(result.pitchDeg, -5);
+  assert.equal(result.note, undefined);
+  for (let i = 0; i < 10; i += 1) h.tick();
+  const zoom = adjustOrbitRange(2.5);
+  assert.equal(zoom.kind, 'tilt');
+  assert.equal(zoom.changed, true);
+  h.finish();
+  assert.ok(h.viewTarget(), 'the crosshair is on the sky');
+  assert.ok(zoom.pitchDeg < -5, `zoom reported ${zoom.pitchDeg}°`);
+  assert.ok(
+    Math.abs(pitchDeg(h.camera) - zoom.pitchDeg) < 0.5,
+    `camera at ${pitchDeg(h.camera)}°, zoom reported ${zoom.pitchDeg}°`,
+  );
+  assert.match(zoom.note, /horizon/);
+});
+
+test('a zoom in during a horizon-limited tilt reports the angle it now reaches', (t) => {
+  const h = harness(t, { height: 900_000 });
+  const result = moveCamera({ motion: 'tilt', pitchDeg: -5 });
+  assert.ok(result.pitchDeg < -5, `reported ${result.pitchDeg}°`);
+  for (let i = 0; i < 10; i += 1) h.tick();
+  const zoom = adjustOrbitRange(1 / 2.4);
+  assert.equal(zoom.changed, true);
+  h.finish();
+  assert.equal(zoom.pitchDeg, -5);
+  assert.ok(
+    Math.abs(pitchDeg(h.camera) - -5) < 0.5,
+    `camera at ${pitchDeg(h.camera)}°`,
+  );
+});
+
+test('a voice zoom during a tilt to an angle passes on the new end angle', async (t) => {
+  const h = harness(t, { height: 400_000 });
+  const runner = createGevActionRunner({
+    viewer: h.viewer,
+    styleManager: {},
+    dataManager: { layers: new Map(), getAll: () => [] },
+  });
+  moveCamera({ motion: 'tilt', pitchDeg: -5 });
+  for (let i = 0; i < 10; i += 1) h.tick();
+  const zoom = await runner('adjust_camera_zoom', {
+    direction: 'out',
+    amount: 'lot',
+  });
+  assert.equal(zoom.ok, true);
+  assert.equal(zoom.tiltRangeAdjusted, true);
+  h.finish();
+  assert.ok(
+    Math.abs(pitchDeg(h.camera) - zoom.pitchDeg) < 0.5,
+    `camera at ${pitchDeg(h.camera)}°, zoom reported ${zoom.pitchDeg}°`,
+  );
+  assert.match(zoom.note, /horizon/);
+});
+
+// Late in the tilt the camera is already past the angle the new range's
+// horizon allows (from 400 km at -8°, a zoom out x2.5 reported -8°): past it
+// the place is behind the Earth, so the camera steps down to that limit with
+// the zoom, then holds it with no further jump, and the zoom's reply names
+// the angle it ends at, not the one it stood at.
+test('a late zoom out during a tilt steps to the new limit and reports it', (t) => {
+  const h = harness(t, { height: 400_000 });
+  moveCamera({ motion: 'tilt', pitchDeg: -5 });
+  for (let i = 0; i < 70; i += 1) h.tick();
+  const zoom = adjustOrbitRange(2.5);
+  assert.equal(zoom.changed, true);
+  h.tick();
+  assert.equal(zoom.pitchDeg, Math.round(pitchDeg(h.camera)));
+  let last = pitchDeg(h.camera);
+  let maxStep = 0;
+  for (let i = 0; i < 600 && getActiveCameraMotion(); i += 1) {
+    h.tick();
+    maxStep = Math.max(maxStep, Math.abs(pitchDeg(h.camera) - last));
+    last = pitchDeg(h.camera);
+  }
+  assert.equal(getActiveCameraMotion(), null, 'tilt must finish');
+  assert.ok(maxStep < 0.1, `pitch jumped ${maxStep}° in one frame`);
+  assert.ok(h.viewTarget(), 'the crosshair is on the sky');
+  // Replies give whole degrees: the reported angle is the reached one rounded.
+  assert.equal(
+    zoom.pitchDeg,
+    Math.round(pitchDeg(h.camera)),
+    `camera at ${pitchDeg(h.camera)}°, zoom reported ${zoom.pitchDeg}°`,
+  );
+  assert.match(zoom.note, /horizon/);
+});
+
+// Easing from the camera's old pitch at the zoomed-out range put the camera
+// below the place's horizon: the first frame's crosshair hit the ground
+// 186 km from London, and London stayed hidden for ~11 frames.
+test('a late zoom out during a tilt keeps the place under the crosshair', (t) => {
+  const h = harness(t, { height: 400_000 });
+  moveCamera({ motion: 'tilt', pitchDeg: -5 });
+  for (let i = 0; i < 70; i += 1) h.tick();
+  const zoom = adjustOrbitRange(2.5);
+  assert.equal(zoom.changed, true);
+  for (let i = 0; i < 600 && getActiveCameraMotion(); i += 1) {
+    h.tick();
+    const hit = h.viewTarget();
+    assert.ok(hit, `frame ${i}: the crosshair is on the sky`);
+    const drift = centreDrift(h);
+    assert.ok(
+      drift < 100,
+      `frame ${i}: crosshair ${Math.round(drift)} m off the place`,
+    );
+  }
+  assert.equal(getActiveCameraMotion(), null, 'tilt must finish');
+  assert.ok(
+    Math.abs(pivotRange(h) - 1_000_000) < 1,
+    `range ${pivotRange(h)} m`,
+  );
+  assert.equal(
+    zoom.pitchDeg,
+    Math.round(pitchDeg(h.camera)),
+    `camera at ${pitchDeg(h.camera)}°, zoom reported ${zoom.pitchDeg}°`,
+  );
+  assert.match(zoom.note, /horizon/);
+});
+
+// The zoom out left the pivot pitch level with the place, so the zoom in's
+// clearance floor came out infinite and it was refused at 1,000 km.
+test('a zoom in right after a late zoom out brings the tilt back in', (t) => {
+  const h = harness(t, { height: 400_000 });
+  moveCamera({ motion: 'tilt', pitchDeg: -5 });
+  for (let i = 0; i < 70; i += 1) h.tick();
+  const range = pivotRange(h);
+  assert.equal(adjustOrbitRange(2.5).changed, true);
+  const zoomIn = adjustOrbitRange(0.4);
+  assert.equal(zoomIn.changed, true, 'the zoom in must not be refused');
+  h.finish();
+  assert.ok(
+    Math.abs(pivotRange(h) - range) < 1,
+    `range ${pivotRange(h)} m, wanted ${range} m`,
+  );
+  assert.ok(
+    centreDrift(h) < 100,
+    `crosshair ${centreDrift(h)} m off the place`,
+  );
+});

src/cameraVerbs.js

@@ -20,11 +20,19 @@
 
 import * as Cesium from 'cesium';
 import { GLOBE_VIEW } from './locations.js';
+import {
+  globeFrameShare,
+  isFreeGlobeCamera,
+  lookAngleWithinFrame,
+  lookStepLosesGlobe,
+} from './globeInView.js';
 import {
   projectEarthDiscToViewport,
   earthDiscScreenRadius,
   getKeyholeGeometry,
+  KEYHOLE_OUTER_RADIUS,
 } from './celestialRing.js';
+import { isScopeMaskEnabled } from './scopeMask.js';
 import {
   holdContinuousRender,
   releaseContinuousRender,
@@ -48,6 +56,33 @@ const ONCE = {
 };
 const PITCH_MIN = Cesium.Math.toRadians(-89);
 const PITCH_MAX = Cesium.Math.toRadians(-5);
+/** A bare "tilt the camera" / "oblique view" settles here. */
+const TILT_DEFAULT_PITCH_DEG = -45;
+/** °/s for a tilt to a requested angle; short ones keep the once duration. */
+const TILT_TO_DEG_S = 30;
+/**
+ * A pivoting tilt keeps the range, so its height above the pivot is
+ * range × sin|pitch|. It swings no lower than this; the rest tilts in place.
+ */
+const TILT_MIN_CLEARANCE_M = 150;
+/**
+ * Beyond this range a pivot would swing the camera thousands of km about the
+ * crosshair point, so the tilt happens in place instead.
+ */
+const TILT_PIVOT_MAX_RANGE_M = 1_000_000;
+/**
+ * A pivot range rebuilt from the camera's position comes back a hair off the
+ * range it was set at: a range this close past the cutoff still counts as on
+ * it.
+ */
+const TILT_PIVOT_RANGE_SLACK_M = 1;
+/**
+ * The shallowest a pivot swing goes when its clearance is not what stops it.
+ * From several hundred km the camera's own horizon limit lies past the
+ * place's horizon; tilting the rest in place there would lift the crosshair
+ * onto the sky, so the swing stops with the place this far above it.
+ */
+const TILT_MIN_PIVOT_ELEVATION = Cesium.Math.toRadians(0.5);
 
 /* ── Route dolly: cinematic tuning ──────────────────────────────────────────
  * Every knob an owner may want to retune lives in this block. The shaping is
@@ -966,6 +1001,17 @@ let _trackingRemover = null;
 let _inputRemovers = [];
 /** Monotonic id for the motion currently running; 0 means "no motion". */
 let _motionSeq = 0;
+/** Canvas grabs, touches and wheel turns since load. */
+let _manualInputCount = 0;
+
+/**
+ * Lets a caller holding a motion back (behind a fly-to) see whether the user
+ * took the camera meanwhile; Cesium does not cancel a flight on input.
+ * @returns {number} Manual camera inputs so far.
+ */
+export function manualCameraInputCount() {
+  return _manualInputCount;
+}
 
 /**
  * Install a motion and stamp it with a fresh id. The id is what lets a caller
@@ -1008,6 +1054,187 @@ export function interruptCameraMotionIfActive(
   return interruptCameraMotion(reason);
 }
 
+// The frame share that in-place voice turns measure their limit against, with
+// the pose the last voice turn left the camera in. A turn that starts where
+// the last one left off keeps that baseline (raised if the planet now fills
+// more of the frame), so repeating a request cannot take a little more each
+// time. Once anything else has moved or turned the camera, a turn starts over
+// from what is on screen.
+let _lookBaseline = null;
+
+// The pre-check's proof that a half-degree turn from this pose keeps the planet
+// in view: which way, from which position and direction. A motion that starts from that
+// pose turns at least that far, so a request reported as done really moves
+// even when a smaller first step lands in a dip of the sampled share.
+const PROVEN_TURN_RAD = Cesium.Math.toRadians(0.5);
+let _provenLook = null;
+
+/** The part of the frame a viewer can see: the scope keyhole when it is on. */
+function visibleFrame() {
+  return { keyholeRadius: isScopeMaskEnabled() ? KEYHOLE_OUTER_RADIUS : 0 };
+}
+
+/** The frame share an in-place turn from `cam`'s pose is limited against. */
+function lookBaselineShare(cam) {
+  const share = globeFrameShare(cam, visibleFrame());
+  const continues =
+    _lookBaseline &&
+    Cesium.Cartesian3.equalsEpsilon(
+      _lookBaseline.position,
+      cam.positionWC,
+      0,
+      1,
+    ) &&
+    Cesium.Cartesian3.equalsEpsilon(
+      _lookBaseline.direction,
+      cam.directionWC,
+      0,
+      1e-9,
+    );
+  _lookBaseline = {
+    position: Cesium.Cartesian3.clone(cam.positionWC),
+    direction: Cesium.Cartesian3.clone(cam.directionWC),
+    share: continues ? Math.max(_lookBaseline.share, share) : share,
+  };
+  return _lookBaseline.share;
+}
+
+/**
+ * One in-place look step of motion `m`. From orbit a free globe camera turns
+ * only as far as keeps the planet in frame, measured against the baseline the
+ * turn started from, then the motion ends there.
+ */
+function lookWithinFrame(cam, m, look, angle) {
+  let allowed = angle;
+  if (isFreeGlobeCamera(_viewer)) {
+    if (m.globeShareAtStart === undefined) {
+      m.globeShareAtStart = lookBaselineShare(cam);
+      m.provenTurnRad = lookProven(cam, look) ? PROVEN_TURN_RAD : 0;
+      m.turnedRad = 0;
+    }
+    _provenLook = null;
+    allowed = lookAngleWithinFrame(cam, look, angle, {
+      ...visibleFrame(),
+      startShare: m.globeShareAtStart,
+    });
+    const owed = Math.min(angle, m.provenTurnRad - m.turnedRad);
+    if (allowed < owed) allowed = owed;
+    m.turnedRad += allowed;
+  }
+  if (allowed > 0) cam[look](allowed);
+  // The pose this turn leaves, for a turn that continues from it.
+  if (_lookBaseline)
+    Cesium.Cartesian3.clone(cam.directionWC, _lookBaseline.direction);
+  if (allowed < angle) interruptCameraMotion('globe-out-of-frame');
+}
+
+/**
+ * The in-place look a pitch change from `fromPitch` to `goalPitch` makes:
+ * 'lookUp', 'lookDown', or null when it does not move. A tilt is judged by
+ * the way its pitch moves, whatever form or direction word it came in.
+ */
+function tiltLook(fromPitch, goalPitch) {
+  if (!Number.isFinite(fromPitch) || !Number.isFinite(goalPitch)) return null;
+  if (goalPitch > fromPitch) return 'lookUp';
+  return goalPitch < fromPitch ? 'lookDown' : null;
+}
+
+/** Tilt `m` in place to `goalPitch`, as far as the frame limit allows. */
+function tiltInPlaceWithinFrame(cam, m, goalPitch) {
+  const look = tiltLook(cam.pitch, goalPitch);
+  if (look) lookWithinFrame(cam, m, look, Math.abs(goalPitch - cam.pitch));
+}
+
+/**
+ * The pitch an in-place tilt from `cam`'s pose toward `goalPitch` reaches
+ * before the frame limit stops it, judged as its steps will be: `goalPitch`
+ * itself when the planet stays in frame the whole way, or the camera is not a
+ * free globe camera. The steps run on a copy of the camera, each looking by
+ * the pitch still to go as the tilt's frames do, because a rolled camera's
+ * look turns its pitch by less than the look angle.
+ */
+function tiltPitchWithinFrame(cam, goalPitch) {
+  const look = tiltLook(cam.pitch, goalPitch);
+  if (!look || !isFreeGlobeCamera(_viewer)) return goalPitch;
+  const frame = { ...visibleFrame(), startShare: lookBaselineShare(cam) };
+  // A proven half degree is turned whatever the sampled share says.
+  let owed = lookProven(cam, look) ? PROVEN_TURN_RAD : 0;
+  const probe = Cesium.Camera.clone(cam);
+  for (let i = 0; i < 32; i += 1) {
+    if (tiltLook(probe.pitch, goalPitch) !== look) return goalPitch;
+    const angle = Math.abs(goalPitch - probe.pitch);
+    if (angle < 1e-6) return goalPitch;
+    const allowed = Math.max(
+      lookAngleWithinFrame(probe, look, angle, frame),
+      Math.min(angle, owed),
+    );
+    owed -= allowed;
+    if (allowed > 0) probe[look](allowed);
+    if (allowed < angle) return probe.pitch;
+  }
+  return probe.pitch;
+}
+
+/** The reply's note for a tilt the frame limit stops short of its angle. */
+function tiltFrameNote(pitch) {
+  return `Stopped at ${Math.round(Cesium.Math.toDegrees(pitch))}°: from this height a shallower angle would turn the globe out of view. Zoom in to tilt further.`;
+}
+
+/** True when the pre-check proved a half-degree `look` from `cam`'s pose. */
+function lookProven(cam, look) {
+  return (
+    _provenLook?.look === look &&
+    Cesium.Cartesian3.equalsEpsilon(
+      _provenLook.position,
+      cam.positionWC,
+      0,
+      1,
+    ) &&
+    Cesium.Cartesian3.equalsEpsilon(
+      _provenLook.direction,
+      cam.directionWC,
+      0,
+      1e-9,
+    )
+  );
+}
+
+/**
+ * The check a voice in-place turn (`look`: 'lookUp', 'lookDown', 'lookLeft'
+ * or 'lookRight') must pass from orbit: refused when even half a degree would
+ * cross the frame limit, otherwise proven for that half degree from this pose.
+ * With `released`, the turn runs through a navigation that first releases a
+ * tracked or locked camera and keeps its world pose. The frame measure and the
+ * turn are the same in any reference frame, so such a camera is judged as it
+ * is, before the release, and a refusal leaves tracking as it was. Otherwise a
+ * camera that is not a free globe camera is not checked. Returns the refusal,
+ * or null.
+ */
+function checkLookFromOrbit(look, { released = false } = {}) {
+  _provenLook = null;
+  if (_viewer.scene.mode !== Cesium.SceneMode.SCENE3D) return null;
+  const cam = _viewer.camera;
+  if (!released && !isFreeGlobeCamera(_viewer)) return null;
+  if (
+    lookStepLosesGlobe(cam, look, PROVEN_TURN_RAD, {
+      ...visibleFrame(),
+      startShare: lookBaselineShare(cam),
+    })
+  )
+    return {
+      ok: false,
+      action: 'move_camera',
+      error:
+        'From this height that would turn the globe out of view — zoom in first, or turn the other way.',
+    };
+  _provenLook = {
+    look,
+    position: Cesium.Cartesian3.clone(cam.positionWC),
+    direction: Cesium.Cartesian3.clone(cam.directionWC),
+  };
+  return null;
+}
+
 function clearLookAt() {
   try {
     _viewer.camera.lookAtTransform(Cesium.Matrix4.IDENTITY);
@@ -1052,7 +1279,9 @@ export function interruptCameraMotion(reason = 'interrupt') {
   if (
     wasActive &&
     !tracking &&
-    (_active.kind === 'orbit' || _active.kind === 'route')
+    (_active.kind === 'orbit' ||
+      _active.kind === 'route' ||
+      (_active.kind === 'tilt' && _active.hpr))
   )
     clearLookAt();
   // Instant, not eased: the user grabbed the camera, or the flight is over.
@@ -1104,7 +1333,7 @@ function onTick() {
   let scale = 1;
   if (m.mode === 'once') {
     m.elapsed = (m.elapsed || 0) + dt;
-    const t = Math.min(1, m.elapsed / ONCE.durationS);
+    const t = Math.min(1, m.elapsed / (m.durationS || ONCE.durationS));
     scale = 1 - (1 - t) * (1 - t); // ease-out progress share
     if (t >= 1) {
       interruptCameraMotion('once-complete');
@@ -1173,30 +1402,20 @@ function onTick() {
       else if (m.direction === 'right') cam.moveRight(step);
       else if (m.direction === 'up') cam.moveUp(step);
       else cam.moveDown(step);
-    } else if (
-      m.kind === 'tilt' ||
-      m.kind === 'rotate' ||
-      m.kind === 'rotate_globe'
-    ) {
+    } else if (m.kind === 'tilt') {
+      tickTilt(cam, m, scale, dt);
+    } else if (m.kind === 'rotate' || m.kind === 'rotate_globe') {
       const degS = TILT_DEG_S[m.speed];
       const stepRad =
         m.mode === 'once'
-          ? Cesium.Math.toRadians(
-              m.kind === 'tilt' ? ONCE.tiltDeg : ONCE.rotateDeg,
-            ) *
-            (scale - (m.lastScale || 0))
+          ? Cesium.Math.toRadians(ONCE.rotateDeg) * (scale - (m.lastScale || 0))
           : Cesium.Math.toRadians(degS) * dt;
       m.lastScale = scale;
       if (m.kind === 'rotate_globe') {
         // Tracking can acquire the camera without going through navigation.
         // Yield without resetting its pose/frame: the world-space arc proof
         // only describes Cesium's rotation while the frame is identity.
-        if (
-          _viewer.scene.mode !== Cesium.SceneMode.SCENE3D ||
-          _viewer.trackedEntity ||
-          _isCockpitActive?.() ||
-          !Cesium.Matrix4.equals(cam.transform, Cesium.Matrix4.IDENTITY)
-        ) {
+        if (!isFreeGlobeCamera(_viewer) || _isCockpitActive?.()) {
           interruptCameraMotion('globe-camera-owner-changed');
           return;
         }
@@ -1218,18 +1437,14 @@ function onTick() {
           return;
         }
         cam.rotate(m.rotationAxis, angle);
-      } else if (m.kind === 'tilt') {
-        const up = m.direction === 'up';
-        // Clamp pitch to [-89°, -5°]: never through the ground, never at the sky.
-        const next = cam.pitch + (up ? stepRad : -stepRad);
-        if (next > PITCH_MAX || next < PITCH_MIN) {
-          interruptCameraMotion('tilt-clamp');
-          return;
-        }
-        if (up) cam.lookUp(stepRad);
-        else cam.lookDown(stepRad);
-      } else if (m.direction === 'left') cam.lookLeft(stepRad);
-      else cam.lookRight(stepRad);
+      } else {
+        lookWithinFrame(
+          cam,
+          m,
+          m.direction === 'left' ? 'lookLeft' : 'lookRight',
+          stepRad,
+        );
+      }
     } else if (m.kind === 'route') {
       // The dolly's shaping lives in advanceRouteFlight(); the tick only
       // applies the pose and honours the same completion path as before.
@@ -1252,6 +1467,186 @@ function onTick() {
   }
 }
 
+/**
+ * One frame of tilt. With a ground pivot the camera swings about it (lookAt),
+ * so the place under the crosshair stays centred; without one it looks up or
+ * down in place. Every angle and limit is the camera's own pitch, which at
+ * regional range is several degrees steeper than the pivot's (the Earth
+ * curves away), so the swing solves for the pivot pitch that gives it. Pitch
+ * is clamped to [-89°, -5°] only in the direction of travel: a top-down view
+ * sits at -90°, below the limit, and must still be able to tilt up out of it.
+ * A pivot swing toward the horizon lowers the camera, so it stops at
+ * TILT_MIN_CLEARANCE_M and the rest tilts in place. Farther out it stops with
+ * the camera TILT_MIN_PIVOT_ELEVATION above the place's horizon instead, and
+ * keeps the place centred: tilting in place there would lift the crosshair
+ * onto the sky.
+ */
+function tickTilt(cam, m, scale, dt) {
+  const from = cam.pitch;
+  const want =
+    m.mode === 'once'
+      ? m.startPitch + (m.goalPitch - m.startPitch) * scale
+      : from +
+        Cesium.Math.toRadians(TILT_DEG_S[m.speed]) *
+          dt *
+          (m.direction === 'up' ? 1 : -1);
+  const up = want > from;
+  const limited = up
+    ? Math.min(want, Math.max(from, PITCH_MAX))
+    : Math.max(want, Math.min(from, PITCH_MIN));
+  let atLimit = false;
+  if (m.hpr) {
+    // Apply a range a zoom set since the last frame, even when the pitch
+    // then has nowhere to go (a zoom in to the clearance ends the pivot).
+    cam.lookAt(m.target, m.hpr);
+    // Up toward the horizon the swing lowers the camera: hold the clearance,
+    // and keep the place below the horizon.
+    const cap = up
+      ? Math.max(m.hpr.pitch, tiltPivotPitchMax(m.hpr.range))
+      : Infinity;
+    for (let i = 0; i < 3 && Math.abs(limited - cam.pitch) > 1e-6; i += 1) {
+      const pitch = Math.min(
+        cap,
+        Math.max(-Cesium.Math.PI_OVER_TWO, m.hpr.pitch + limited - cam.pitch),
+      );
+      if (pitch === m.hpr.pitch) break;
+      m.hpr.pitch = pitch;
+      cam.lookAt(m.target, m.hpr);
+    }
+    // A once motion that just completed released the lookAt frame before
+    // this last step re-took it.
+    if (_active !== m) clearLookAt();
+    if (up && m.hpr.pitch >= cap && cam.pitch < limited - 1e-6) {
+      if (tiltClearanceBinds(m.hpr.range)) {
+        // Down to its clearance: let go of the pivot and tilt the rest in
+        // place, which keeps the height.
+        if (_active === m) clearLookAt();
+        m.hpr = null;
+        m.target = null;
+      } else {
+        // The place is at its horizon limit: stop here, still centred.
+        atLimit = true;
+      }
+    }
+  }
+  if (!m.hpr) tiltInPlaceWithinFrame(cam, m, limited);
+  if (m.mode !== 'once' && (limited !== want || atLimit))
+    interruptCameraMotion('tilt-clamp');
+}
+
+/** The refusal for a tilt up the camera has no room left for. */
+function tiltUpLimitRefusal() {
+  return {
+    ok: false,
+    action: 'move_camera',
+    error:
+      'Already at the upper tilt limit (near the horizon) — tilt down, or zoom/pan instead.',
+  };
+}
+
+/** Shallowest pivot pitch that keeps the clearance at this range. */
+function tiltPivotPitchMax(range) {
+  return Math.min(
+    -Math.asin(Math.min(1, TILT_MIN_CLEARANCE_M / range)),
+    -TILT_MIN_PIVOT_ELEVATION,
+  );
+}
+
+/**
+ * Whether the clearance, not the horizon, stops a swing at this range. Only
+ * then does the rest of the tilt happen in place: that close in (under ~17
+ * km) the camera's -5° limit stays well below its own horizon.
+ */
+function tiltClearanceBinds(range) {
+  return TILT_MIN_CLEARANCE_M / range >= Math.sin(TILT_MIN_PIVOT_ELEVATION);
+}
+
+/**
+ * The shallowest camera pitch a tilt starting from this frame can reach with
+ * the place under the crosshair still in view: PITCH_MAX, or less where a
+ * far pivot meets its horizon limit first.
+ */
+function tiltUpLimit({ target, pivot }) {
+  if (!pivot || tiltClearanceBinds(pivot.range)) return PITCH_MAX;
+  return Math.min(
+    PITCH_MAX,
+    pivotCameraPitch(
+      target,
+      pivot,
+      Math.max(pivot.pitch, tiltPivotPitchMax(pivot.range)),
+    ),
+  );
+}
+
+/** The camera pitch lookAt gives for this pivot at the given pivot pitch. */
+function pivotCameraPitch(target, { heading, range }, pitch) {
+  const offset = new Cesium.Cartesian3(
+    -range * Math.cos(pitch) * Math.sin(heading),
+    -range * Math.cos(pitch) * Math.cos(heading),
+    -range * Math.sin(pitch),
+  );
+  const eye = Cesium.Matrix4.multiplyByPoint(
+    Cesium.Transforms.eastNorthUpToFixedFrame(target),
+    offset,
+    new Cesium.Cartesian3(),
+  );
+  const look = Cesium.Cartesian3.subtract(target, eye, new Cesium.Cartesian3());
+  Cesium.Cartesian3.normalize(look, look);
+  const ellipsoid = _viewer.scene.globe?.ellipsoid ?? Cesium.Ellipsoid.WGS84;
+  const upAtEye = ellipsoid.geodeticSurfaceNormal(eye, new Cesium.Cartesian3());
+  return Math.asin(
+    Cesium.Math.clamp(Cesium.Cartesian3.dot(look, upAtEye), -1, 1),
+  );
+}
+
+/**
+ * Where a tilt starts. It swings about the ground under the crosshair so the
+ * place stays centred. It tilts in place with no ground there, from globe
+ * range, or while an entity is tracked (the follow camera owns that frame;
+ * voice releases it before moving, so a voice tilt still pivots).
+ */
+function tiltStartFrame(cam) {
+  const target = _viewer.trackedEntity ? null : _getTarget?.(_viewer);
+  let pivot = target ? tiltPivot(cam, target) : null;
+  if (pivot && !tiltPivotInReach(pivot.range)) pivot = null;
+  return { target, pivot, from: cam.pitch };
+}
+
+/** Whether a tilt may pivot at this range: up to and including the cutoff. */
+function tiltPivotInReach(range) {
+  return range <= TILT_PIVOT_MAX_RANGE_M + TILT_PIVOT_RANGE_SLACK_M;
+}
+
+/** The reply's note for a tilt the place's horizon stops short of its angle. */
+function tiltHorizonNote(pitch) {
+  return `Stopped at ${Math.round(Cesium.Math.toDegrees(pitch))}°: from this range a shallower angle puts the place past the horizon. Zoom in to tilt further.`;
+}
+
+/** Ground pivot for a tilt: heading, pitch and range in the target's own frame. */
+function tiltPivot(cam, target) {
+  const local = Cesium.Matrix4.multiplyByPoint(
+    Cesium.Matrix4.inverseTransformation(
+      Cesium.Transforms.eastNorthUpToFixedFrame(target),
+      new Cesium.Matrix4(),
+    ),
+    cam.positionWC,
+    new Cesium.Cartesian3(),
+  );
+  const range = Cesium.Cartesian3.magnitude(local);
+  if (!(range > 1) || local.z <= 0) return null;
+  // Near straight overhead the offset's heading is float noise (it flipped a
+  // north-up London view to south); keep the camera's own.
+  const heading =
+    Math.hypot(local.x, local.y) > range * 0.01
+      ? Math.atan2(-local.x, -local.y)
+      : cam.heading;
+  return new Cesium.HeadingPitchRange(
+    heading,
+    -Math.asin(Math.min(1, local.z / range)),
+    range,
+  );
+}
+
 /** Rigid origin-centred rotation stays outside the actual ellipsoid's bounding sphere. */
 function globeRotationHasClearance(position) {
   const ellipsoid = _viewer.scene.globe?.ellipsoid ?? Cesium.Ellipsoid.WGS84;
@@ -1413,6 +1808,7 @@ export function initCameraVerbs(
   _isCockpitActive =
     typeof isCockpitActive === 'function' ? isCockpitActive : null;
   _viewer = viewer;
+  _lookBaseline = null;
   if (_tickRemover) _tickRemover();
   _tickRemover = viewer.clock.onTick.addEventListener(onTick);
   if (_trackingRemover) _trackingRemover();
@@ -1421,18 +1817,108 @@ export function initCameraVerbs(
   _trackingRemover = viewer.trackedEntityChanged?.addEventListener((entity) => {
     if (entity && _active?.kind === 'rotate_globe')
       interruptCameraMotion('globe-camera-owner-changed');
+    // A pivoting tilt's lookAt would fight the follow camera every frame.
+    else if (entity && _active?.kind === 'tilt' && _active.hpr)
+      interruptCameraMotion('tilt-camera-owner-changed');
   });
   for (const rm of _inputRemovers) rm();
   _inputRemovers = [];
   const canvas = viewer.scene.canvas;
   // ANY manual camera input reclaims control — the cancelFlight reflex.
   for (const evt of ['pointerdown', 'touchstart', 'wheel']) {
-    const h = () => interruptCameraMotion('manual-input');
+    const h = () => {
+      _manualInputCount += 1;
+      interruptCameraMotion('manual-input');
+    };
     canvas.addEventListener(evt, h, { passive: true });
     _inputRemovers.push(() => canvas.removeEventListener(evt, h));
   }
 }
 
+/**
+ * A tilt's angle: the one asked for, the default oblique view when a bare
+ * "tilt the camera" names neither angle nor direction, or null for a nudge.
+ */
+function requestedTiltPitch(args, direction) {
+  // Only a real number or numeric text: Number('') and Number(null) are 0,
+  // which would swing the camera to the horizon.
+  const raw = args.pitchDeg;
+  const requested =
+    typeof raw === 'number' || (typeof raw === 'string' && raw.trim() !== '')
+      ? Number(raw)
+      : NaN;
+  // The camera never looks above the horizon, so a positive angle can only
+  // mean the same angle below it ("tilt 45 degrees" sent as 45).
+  if (Number.isFinite(requested))
+    return Cesium.Math.clamp(
+      Cesium.Math.toRadians(-Math.abs(requested)),
+      PITCH_MIN,
+      PITCH_MAX,
+    );
+  return direction === null
+    ? Cesium.Math.toRadians(TILT_DEFAULT_PITCH_DEG)
+    : null;
+}
+
+/**
+ * Argument errors move_camera refuses whatever the camera is doing, so a
+ * caller holding a motion back behind a flight can refuse it before waiting.
+ * @param {Object} args
+ * @returns {Object|null} The refusal, or null when the arguments are usable.
+ */
+export function moveCameraArgsError(args = {}) {
+  const motion = String(args.motion || '').toLowerCase();
+  const direction = args.direction
+    ? String(args.direction).toLowerCase()
+    : null;
+  if (motion === 'stop') return null;
+  if (!['orbit', 'pan', 'tilt', 'rotate', 'rotate_globe'].includes(motion)) {
+    return {
+      ok: false,
+      action: 'move_camera',
+      error: `Unknown motion "${args.motion}" — use orbit, pan, tilt, rotate, rotate_globe, or stop.`,
+    };
+  }
+  if (
+    motion !== 'orbit' &&
+    motion !== 'rotate_globe' &&
+    (motion !== 'tilt' || requestedTiltPitch(args, direction) === null) &&
+    !['left', 'right', 'up', 'down'].includes(direction)
+  ) {
+    return {
+      ok: false,
+      action: 'move_camera',
+      error: `${motion} needs a direction (${motion === 'tilt' ? 'up/down' : motion === 'rotate' ? 'left/right' : 'left/right/up/down'}).`,
+    };
+  }
+  if (motion === 'tilt' && (direction === 'left' || direction === 'right')) {
+    return {
+      ok: false,
+      action: 'move_camera',
+      error: 'tilt needs up or down, or pitchDeg alone for an angle.',
+    };
+  }
+  if (motion === 'rotate' && !['left', 'right'].includes(direction)) {
+    return {
+      ok: false,
+      action: 'move_camera',
+      error: 'rotate needs left or right.',
+    };
+  }
+  if (
+    motion === 'rotate_globe' &&
+    direction !== null &&
+    !['left', 'right'].includes(direction)
+  ) {
+    return {
+      ok: false,
+      action: 'move_camera',
+      error: 'rotate_globe needs left or right.',
+    };
+  }
+  return null;
+}
+
 /**
  * move_camera implementation. Returns the house result shape; rejections are
  * plain-English `ok:false` errors.
@@ -1465,54 +1951,66 @@ export function moveCamera(args = {}, runNavigation = null) {
     };
     return typeof runNavigation === 'function' ? runNavigation(stop) : stop();
   }
-  if (!['orbit', 'pan', 'tilt', 'rotate', 'rotate_globe'].includes(motion)) {
-    return {
-      ok: false,
-      action: 'move_camera',
-      error: `Unknown motion "${args.motion}" — use orbit, pan, tilt, rotate, rotate_globe, or stop.`,
-    };
-  }
-  if (
-    motion !== 'orbit' &&
-    motion !== 'rotate_globe' &&
-    !['left', 'right', 'up', 'down'].includes(direction)
-  ) {
-    return {
-      ok: false,
-      action: 'move_camera',
-      error: `${motion} needs a direction (left/right${motion !== 'rotate' ? '/up/down' : ''}).`,
-    };
-  }
-  if (motion === 'rotate' && !['left', 'right'].includes(direction)) {
-    return {
-      ok: false,
-      action: 'move_camera',
-      error: 'rotate needs left or right.',
-    };
-  }
-  if (
-    motion === 'rotate_globe' &&
-    direction !== null &&
-    !['left', 'right'].includes(direction)
-  ) {
-    return {
-      ok: false,
-      action: 'move_camera',
-      error: 'rotate_globe needs left or right.',
-    };
-  }
-  if (motion === 'tilt') {
-    // Honest limits: at the clamp a tilt is a no-op — say so instead of
-    // reporting success and letting the model gaslight itself (field test).
-    const pitch = _viewer.camera.pitch;
-    if (direction === 'up' && pitch >= PITCH_MAX - Cesium.Math.toRadians(0.5)) {
+  const argsError = moveCameraArgsError(args);
+  if (argsError) return argsError;
+  const tiltToPitch =
+    motion === 'tilt' ? requestedTiltPitch(args, direction) : null;
+  if (motion === 'tilt' && tiltToPitch !== null) {
+    // Angles and limits are the camera's own pitch, whatever the swing pivots
+    // about; releasing the follow camera does not change it.
+    const from = _viewer.camera.pitch;
+    // -89 or -90 means top-down, which a -90° view already is: the clamp
+    // must not tilt it up 1°.
+    const atTopDown = tiltToPitch <= PITCH_MIN && from <= PITCH_MIN;
+    if (
+      atTopDown ||
+      Math.abs(tiltToPitch - from) < Cesium.Math.toRadians(0.5)
+    ) {
+      // Still a camera request: it stops a running motion and releases the
+      // follow camera, as a tilt that moves would.
+      const hold = () => {
+        interruptCameraMotion('replaced');
+        return {
+          ok: true,
+          action: 'move_camera',
+          motion,
+          pitchDeg: Math.round(
+            Cesium.Math.toDegrees(atTopDown ? from : tiltToPitch),
+          ),
+          unchanged: true,
+        };
+      };
+      return typeof runNavigation === 'function' ? runNavigation(hold) : hold();
+    }
+    // pitchDeg is an absolute angle, not a step: "tilt down 10 degrees" sent
+    // as {direction:'down', pitchDeg:10} would tilt up from -45°.
+    const towards = tiltToPitch > from ? 'up' : 'down';
+    if ((direction === 'up' || direction === 'down') && direction !== towards) {
+      const target = Math.round(Cesium.Math.toDegrees(tiltToPitch));
+      const now = Math.round(Cesium.Math.toDegrees(from));
       return {
         ok: false,
         action: 'move_camera',
-        error:
-          'Already at the upper tilt limit (near the horizon) — tilt down, or zoom/pan instead.',
+        error: `pitchDeg is an absolute angle, not a step: ${target}° from ${now}° tilts ${towards}, not ${direction}. Send direction alone for a nudge, or pitchDeg alone for an angle.`,
       };
     }
+    if (
+      towards === 'up' &&
+      from >=
+        tiltUpLimit(tiltStartFrame(_viewer.camera)) - Cesium.Math.toRadians(0.5)
+    )
+      return tiltUpLimitRefusal();
+  } else if (motion === 'tilt') {
+    // Honest limits: at the clamp a tilt is a no-op — say so instead of
+    // reporting success and letting the model gaslight itself (field test).
+    const pitch = _viewer.camera.pitch;
+    if (
+      direction === 'up' &&
+      pitch >=
+        tiltUpLimit(tiltStartFrame(_viewer.camera)) - Cesium.Math.toRadians(0.5)
+    ) {
+      return tiltUpLimitRefusal();
+    }
     if (
       direction === 'down' &&
       pitch <= PITCH_MIN + Cesium.Math.toRadians(0.5)
@@ -1524,6 +2022,34 @@ export function moveCamera(args = {}, runNavigation = null) {
       };
     }
   }
+  // A tilt is judged by the way its pitch will move: toward its angle, or a
+  // nudge up or down; a rotate turns left only when told to, as it runs.
+  const look =
+    motion === 'tilt'
+      ? tiltLook(
+          _viewer.camera.pitch,
+          tiltToPitch ??
+            _viewer.camera.pitch +
+              Cesium.Math.toRadians(ONCE.tiltDeg) *
+                (direction === 'up' ? 1 : -1),
+        )
+      : motion === 'rotate'
+        ? direction === 'left'
+          ? 'lookLeft'
+          : 'lookRight'
+        : null;
+  // Honest limits from orbit too: a stopped turn rests within 0.05° of its
+  // limit, so one that cannot go half a degree further is refused rather than
+  // run and reported as done, and one that can is then turned at least that
+  // far. Near the limit the sampled share wobbles as the planet's edge crosses
+  // the grid, so a turn that would keep the planet can occasionally be refused
+  // too.
+  // A camera that is tracked or locked now is judged as the navigation that
+  // runs the turn will release it, so a refusal keeps the tracking.
+  const lookRefusal =
+    look &&
+    checkLookFromOrbit(look, { released: typeof runNavigation === 'function' });
+  if (lookRefusal) return lookRefusal;
   if (
     (motion === 'rotate_globe' ||
       (motion === 'orbit' && typeof runNavigation !== 'function')) &&
@@ -1607,14 +2133,70 @@ export function moveCamera(args = {}, runNavigation = null) {
         error: 'Globe rotation requires a clear ellipsoid bounding sphere.',
       };
   }
+  // The angle a tilt to an angle stops at short of it, and why.
+  let stoppedAt = null;
+  let stopNote = null;
   const start = () => {
     interruptCameraMotion('replaced');
+    // Checked again only if the release left the camera somewhere other than
+    // where the check above expected it.
+    if (look && !lookProven(_viewer.camera, look)) {
+      const refusal = checkLookFromOrbit(look);
+      if (refusal) return refusal;
+    }
     const state = {
       kind: motion,
       direction: direction || 'right',
       speed,
       mode,
     };
+    if (motion === 'tilt') {
+      const frame = tiltStartFrame(_viewer.camera);
+      const { target, pivot, from } = frame;
+      if (pivot) {
+        state.target = target;
+        state.hpr = pivot;
+      }
+      state.startPitch = from;
+      const upLimit = tiltUpLimit(frame);
+      if (tiltToPitch !== null) {
+        // From far out the place reaches its horizon before the camera
+        // reaches the asked angle: stop there, and say so.
+        let goal =
+          tiltToPitch > from
+            ? Math.min(tiltToPitch, Math.max(from, upLimit))
+            : tiltToPitch;
+        if (goal !== tiltToPitch) stopNote = tiltHorizonNote(goal);
+        // From orbit an in-place tilt stops where the planet would leave the
+        // frame: aim it there, and say so.
+        if (!pivot) {
+          const framed = tiltPitchWithinFrame(_viewer.camera, goal);
+          if (framed !== goal) {
+            goal = framed;
+            stopNote = tiltFrameNote(goal);
+          }
+        }
+        state.mode = 'once';
+        state.direction = goal > from ? 'up' : 'down';
+        state.goalPitch = goal;
+        // A zoom mid-tilt moves the horizon limit; it re-judges the goal
+        // against the angle asked for.
+        state.askedPitch = tiltToPitch;
+        state.durationS = Math.max(
+          ONCE.durationS,
+          Math.abs(Cesium.Math.toDegrees(goal - from)) / TILT_TO_DEG_S,
+        );
+        if (goal !== tiltToPitch) stoppedAt = goal;
+      } else {
+        // A nudge stops at the limit it travels toward.
+        const step =
+          Cesium.Math.toRadians(ONCE.tiltDeg) * (direction === 'up' ? 1 : -1);
+        state.goalPitch =
+          step > 0
+            ? Math.min(from + step, Math.max(from, upLimit))
+            : Math.max(from + step, Math.min(from, PITCH_MIN));
+      }
+    }
     if (motion === 'rotate_globe') {
       // Convert an inherited ground-target frame without changing the world
       // pose. Rotation must pivot about Earth, never the previous local target.
@@ -1633,9 +2215,11 @@ export function moveCamera(args = {}, runNavigation = null) {
     }
     if (motion === 'orbit') {
       if (_viewer.scene.tweens.length > 0) {
-        // A camera flight is in progress ("fly to X and orbit it") — ALWAYS arm
-        // and capture at the destination; a target existing right now is
-        // meaningless (the globe is always under the crosshair).
+        // A camera flight is in progress — ALWAYS arm and capture at the
+        // destination; a target existing right now is meaningless (the globe
+        // is always under the crosshair). The voice runner already holds an
+        // orbit until its own fly-to lands; this covers any other
+        // flight.
         setActiveMotion({
           kind: 'orbit',
           direction: direction || 'right',
@@ -1699,7 +2283,11 @@ export function moveCamera(args = {}, runNavigation = null) {
       motion,
       direction: state.direction,
       speed,
-      mode,
+      mode: state.mode,
+      ...(tiltToPitch !== null && {
+        pitchDeg: Math.round(Cesium.Math.toDegrees(stoppedAt ?? tiltToPitch)),
+      }),
+      ...(stopNote !== null && { note: stopNote }),
     };
   };
   const preserveCameraFlight =
@@ -1714,16 +2302,93 @@ export function moveCamera(args = {}, runNavigation = null) {
 /**
  * Zoom while orbiting: scale the orbit RADIUS instead of letting the zoom
  * fight the per-frame lookAt (field test: "zoom out did literally nothing").
+ * A tilt swinging about its pivot holds a range the same way.
  * @param {number} factor  >1 zooms out (radius grows), <1 zooms in.
- * @returns {boolean} true when an orbit consumed the zoom.
+ * @returns {{kind: string, changed: boolean, pitchDeg?: number,
+ *   note?: string}|null} the motion that consumed the zoom, and whether its
+ *   range moved; null when none did. A tilt to an angle whose end the new
+ *   range moves also names the angle it now ends at (pitchDeg), with a note.
  */
 export function adjustOrbitRange(factor) {
-  if (!_active || _active.kind !== 'orbit' || !_active.hpr) return false;
-  _active.hpr.range = Math.max(
-    80,
-    Math.min(5_000_000, _active.hpr.range * factor),
+  if (!_active || !['orbit', 'tilt'].includes(_active.kind) || !_active.hpr)
+    return null;
+  // A tilt's zoom in stops at the range that keeps its clearance. The limits
+  // never move a view the wrong way: a zoom in leaves a closer view in place,
+  // and a zoom out leaves a farther one.
+  const { kind, hpr } = _active;
+  const floor =
+    kind === 'tilt'
+      ? Math.max(80, TILT_MIN_CLEARANCE_M / Math.abs(Math.sin(hpr.pitch)))
+      : 80;
+  // A tilt pivots only within TILT_PIVOT_MAX_RANGE_M; farther out the swing
+  // would carry the camera thousands of km.
+  const ceiling = kind === 'tilt' ? TILT_PIVOT_MAX_RANGE_M : 5_000_000;
+  const range = hpr.range;
+  hpr.range = Math.max(
+    Math.min(floor, range),
+    Math.min(Math.max(ceiling, range), range * factor),
   );
-  return true;
+  // Under half a metre counts as not moved, as for a plain zoom.
+  const changed = Math.abs(hpr.range - range) >= 0.5;
+  return { kind, changed, ...(changed && retargetTiltAfterZoom(_active)) };
+}
+
+/**
+ * A zoom changed the range a tilt to an angle holds, and with it the place's
+ * horizon limit: aim the tilt at the angle asked for or the new limit,
+ * whichever comes first, from where the camera is now. The pivot pitch is
+ * re-solved so the new range keeps the camera's pitch, and a limit the camera
+ * is already past is eased down to rather than jumped to. Returns the end
+ * angle and a note for the reply when that end moved, otherwise nothing.
+ */
+function retargetTiltAfterZoom(m) {
+  if (m.kind !== 'tilt' || m.mode !== 'once' || m.askedPitch === undefined)
+    return {};
+  let from = _viewer.camera.pitch;
+  if (!(m.askedPitch > from)) return {};
+  if (m.hpr) {
+    // At the same pivot pitch a longer range looks down more steeply (the
+    // Earth curves away): find the pivot pitch that holds this camera pitch.
+    // It stays below the place's horizon limit (or where the pivot already
+    // was): past it the place drops behind the Earth, so a camera the zoom
+    // leaves past that limit steps down to it with the zoom.
+    const cap = Math.max(m.hpr.pitch, tiltPivotPitchMax(m.hpr.range));
+    for (let i = 0; i < 4; i += 1) {
+      const error = from - pivotCameraPitch(m.target, m.hpr, m.hpr.pitch);
+      if (Math.abs(error) < 1e-7) break;
+      const pitch = Cesium.Math.clamp(
+        m.hpr.pitch + error,
+        -Cesium.Math.PI_OVER_TWO,
+        cap,
+      );
+      if (pitch === m.hpr.pitch) break;
+      m.hpr.pitch = pitch;
+    }
+    from = Math.min(from, pivotCameraPitch(m.target, m.hpr, m.hpr.pitch));
+  }
+  const limit =
+    m.hpr && !tiltClearanceBinds(m.hpr.range)
+      ? Math.min(
+          PITCH_MAX,
+          pivotCameraPitch(m.target, m.hpr, tiltPivotPitchMax(m.hpr.range)),
+        )
+      : PITCH_MAX;
+  const goal = Math.min(m.askedPitch, limit);
+  if (Math.abs(goal - m.goalPitch) < 1e-6) return {};
+  m.goalPitch = goal;
+  m.startPitch = from;
+  m.elapsed = 0;
+  m.durationS = Math.max(
+    ONCE.durationS,
+    Math.abs(Cesium.Math.toDegrees(goal - from)) / TILT_TO_DEG_S,
+  );
+  const limited = goal !== m.askedPitch;
+  return {
+    pitchDeg: Math.round(Cesium.Math.toDegrees(goal)),
+    note: limited
+      ? tiltHorizonNote(goal)
+      : `The tilt now reaches ${Math.round(Cesium.Math.toDegrees(goal))}°.`,
+  };
 }
 
 /**

src/celestialRing.js

@@ -1,5 +1,9 @@
 import * as Cesium from 'cesium';
 import { governorRequestRender } from './renderGovernor.js';
+import { worldClock, worldTimeFor } from './time/worldClock.js';
+
+// The ring shows the sun and moon at the time the sky is drawn.
+const skyTime = worldTimeFor('sky');
 
 /** Outer edge of the existing NVG/FLIR keyhole in normalized shader space. */
 export const KEYHOLE_OUTER_RADIUS = 1.05;
@@ -28,6 +32,9 @@ export const KEYHOLE_LABEL_FEATHER_MAX_RATIO = 0.4;
  */
 export const KEYHOLE_OUTSIDE_OPACITY_DEFAULT = 0.01;
 
+// How far the world time moves before the sun and moon move with it: a
+// minute moves the sun a quarter of a degree.
+const EPHEMERIS_WORLD_STEP_MS = 60_000;
 const RING_INSET_PX = 11;
 const MARKER_INSET_PX = 36;
 const COLLIDING_MARKER_EXTRA_INSET_PX = 32;
@@ -445,6 +452,20 @@ export class CelestialRing {
       if (typeof document !== 'undefined' && document.hidden) return;
       governorRequestRender('celestial-ephemeris');
     }, 60_000);
+    // A jump in the world time moves the sun and moon at once.
+    this._skyDate = new Date();
+    this._skyTime = new Cesium.JulianDate();
+    // Played through, the sky moves on each minute of world time it passes.
+    this._ephemerisWorldMs = null;
+    this._unsubscribeWorldTime = worldClock.subscribe(({ timeMs }) => {
+      if (
+        this._ephemerisWorldMs !== null &&
+        Math.abs(timeMs - this._ephemerisWorldMs) < EPHEMERIS_WORLD_STEP_MS
+      )
+        return;
+      this._ephemerisWorldMs = timeMs;
+      this._ephemerisDirty = true;
+    });
     this.setEnabled(this.enabled);
   }
 
@@ -801,7 +822,8 @@ export class CelestialRing {
       return;
     }
 
-    const time = Cesium.JulianDate.now();
+    this._skyDate.setTime(skyTime());
+    const time = Cesium.JulianDate.fromDate(this._skyDate, this._skyTime);
     if (!this._updateEphemeris(time)) return;
     this._present({ ephemerisUpdates: String(this._ephemerisUpdateCount) });
     const camera = this.viewer.camera;
@@ -890,6 +912,8 @@ export class CelestialRing {
       clearInterval(this._ephemerisTimer);
       this._ephemerisTimer = null;
     }
+    this._unsubscribeWorldTime?.();
+    this._unsubscribeWorldTime = null;
     if (this._removePostRender) this._removePostRender();
     this._removePostRender = null;
     if (this._shown()) {

src/cockpitCloudEffects.js

@@ -170,6 +170,18 @@ export function cockpitWeatherEnabledFromStoredValue(value) {
   return value === '1';
 }
 
+/**
+ * Whether the cloud pass runs for a Cockpit subject's layer. Not in orbit:
+ * the pass fades out above 24 km (weatherAltitudeFactors), so a satellite
+ * would pay for it and see nothing. The saved preference is left as it is
+ * for the next aircraft or bridge; cloud cover from orbit is the Weather
+ * layer's.
+ * @param {string|null|undefined} layerId
+ */
+export function cockpitCloudsShowFor(layerId) {
+  return layerId !== 'satellites';
+}
+
 /**
  * Weather-backed volumetric cloud pass that exists only while cockpit mode is
  * active. It owns no Cesium fog/post-process stages and cannot affect map mode.
@@ -207,10 +219,12 @@ class CockpitCloudEffectsController {
     this.enabled = this.readEnabledPreference();
 
     this.onResize = () => this.resize();
+    this.orbit = false;
     this.onCockpitMode = (event) => {
       const active =
         event?.detail?.active ??
         document.body.classList.contains('cockpit-mode');
+      this.orbit = active && !cockpitCloudsShowFor(event?.detail?.layerId);
       if (active && this.enabled) this.start();
       else this.stop();
     };
@@ -344,7 +358,8 @@ class CockpitCloudEffectsController {
       this.destroyed ||
       !this.enabled ||
       this.frame !== null ||
-      this.suspended
+      this.suspended ||
+      this.orbit
     )
       return;
     if (!this.gl) {

src/cockpitCloudEffects.test.mjs

@@ -2,6 +2,7 @@ import test from 'node:test';
 import assert from 'node:assert/strict';
 import {
   cockpitCloudRenderSize,
+  cockpitCloudsShowFor,
   cockpitWeatherRefreshDue,
   cockpitWeatherEnabledFromStoredValue,
 } from './cockpitCloudEffects.js';
@@ -23,6 +24,13 @@ test('cockpit weather defaults off and enables only from an explicit saved opt-i
   assert.equal(cockpitWeatherEnabledFromStoredValue('1'), true);
 });
 
+test('the cloud pass stays off in orbit and runs for aircraft and bridges', () => {
+  assert.equal(cockpitCloudsShowFor('satellites'), false);
+  for (const layerId of ['flights', 'military', 'ais-live-vessels', null]) {
+    assert.equal(cockpitCloudsShowFor(layerId), true, String(layerId));
+  }
+});
+
 test('cockpit weather refreshes after time or meaningful movement', () => {
   const anchor = { latitude: 30, longitude: -97 };
   assert.equal(cockpitWeatherRefreshDue({

src/cockpitLook.js

@@ -0,0 +1,244 @@
+/**
+ * Bridge look-around policy: how the arrow keys turn the bridge camera away
+ * from the bow and back, and how a turned view is described. Yaw is relative
+ * to the ship's heading; pitch is the view's absolute pitch. Pure: no DOM, no
+ * Cesium and no translated text; the Cockpit words the readout.
+ */
+
+/** One arrow press turns the view this far. */
+export const LOOK_STEP_DEG = 5;
+
+/** One Shift+arrow press turns the view this far: two reach either beam. */
+export const LOOK_COARSE_STEP_DEG = 45;
+
+/** The view pitches no further than straight up or straight down. */
+export const LOOK_PITCH_LIMIT_DEG = 90;
+
+/**
+ * The eased view's time constant. Three of them (about 180 ms) close 95% of
+ * a step, so a press glides rather than snaps and a held key turns smoothly.
+ */
+export const LOOK_EASE_TAU_MS = 60;
+
+/** Closer than this the eased view lands on its target. */
+const LOOK_SETTLE_DEG = 0.05;
+
+/** Arrow key → the axis it turns and the direction it turns it. */
+const LOOK_ARROWS = Object.freeze({
+  ArrowLeft: Object.freeze({ axis: 'yaw', sign: -1 }),
+  ArrowRight: Object.freeze({ axis: 'yaw', sign: 1 }),
+  ArrowUp: Object.freeze({ axis: 'pitch', sign: 1 }),
+  ArrowDown: Object.freeze({ axis: 'pitch', sign: -1 }),
+});
+
+/**
+ * Wrap a yaw to (-180, 180]: negative to port, positive to starboard.
+ * @param {number} deg Yaw in degrees; a non-finite yaw reads as ahead.
+ * @returns {number}
+ */
+export function wrapLookYaw(deg) {
+  if (!Number.isFinite(deg)) return 0;
+  const wrapped = (((deg % 360) + 360) % 360) - 360;
+  const yaw = wrapped <= -180 ? wrapped + 360 : wrapped;
+  return yaw === 0 ? 0 : yaw;
+}
+
+/**
+ * Clamp a view pitch to [-90, 90].
+ * @param {number} deg Pitch in degrees; a non-finite pitch reads as level.
+ * @returns {number}
+ */
+export function clampLookPitch(deg) {
+  if (!Number.isFinite(deg)) return 0;
+  const pitch = Math.min(
+    LOOK_PITCH_LIMIT_DEG,
+    Math.max(-LOOK_PITCH_LIMIT_DEG, deg),
+  );
+  return pitch === 0 ? 0 : pitch;
+}
+
+/**
+ * The step an arrow key asks for, or null for any other key.
+ * @param {string} key `KeyboardEvent.key`.
+ * @param {boolean} [coarse] Shift is held: step 45° instead of 5°.
+ * @returns {{axis: 'yaw'|'pitch', sign: 1|-1, stepDeg: number}|null}
+ */
+export function lookKeyStep(key, coarse = false) {
+  const arrow = LOOK_ARROWS[key];
+  if (!arrow) return null;
+  return {
+    ...arrow,
+    stepDeg: coarse ? LOOK_COARSE_STEP_DEG : LOOK_STEP_DEG,
+  };
+}
+
+/**
+ * Move one value to the next multiple of `stepDeg` in the direction `sign`.
+ * A value off the grid (the bridge's -2° rest pitch) lands on it first, so
+ * the readout shows round angles.
+ */
+function nextOnGrid(value, sign, stepDeg) {
+  const cells = value / stepDeg;
+  const next =
+    sign > 0 ? Math.floor(cells + 1e-9) + 1 : Math.ceil(cells - 1e-9) - 1;
+  return next * stepDeg;
+}
+
+/**
+ * Apply one key step to a look target.
+ * @param {{yawDeg: number, pitchDeg: number}} target Current look target.
+ * @param {{axis: 'yaw'|'pitch', sign: number, stepDeg: number}} step From
+ *   {@link lookKeyStep}.
+ * @returns {{yawDeg: number, pitchDeg: number}} The new target: yaw wrapped
+ *   to (-180, 180], pitch clamped to [-90, 90].
+ */
+export function stepLook(target, step) {
+  const yawDeg = wrapLookYaw(target?.yawDeg ?? 0);
+  const pitchDeg = clampLookPitch(target?.pitchDeg ?? 0);
+  if (!step) return { yawDeg, pitchDeg };
+  if (step.axis === 'yaw')
+    return {
+      yawDeg: wrapLookYaw(nextOnGrid(yawDeg, step.sign, step.stepDeg)),
+      pitchDeg,
+    };
+  return {
+    yawDeg,
+    pitchDeg: clampLookPitch(nextOnGrid(pitchDeg, step.sign, step.stepDeg)),
+  };
+}
+
+/**
+ * Advance the eased view toward its target. Yaw takes the shorter way
+ * round; with `immediate` (reduced motion) the view jumps to the target.
+ * @param {{yawDeg: number, pitchDeg: number}} current Eased view now.
+ * @param {{yawDeg: number, pitchDeg: number}} target Look target.
+ * @param {number} dtMs Milliseconds since the previous step.
+ * @param {{immediate?: boolean}} [options]
+ * @returns {{yawDeg: number, pitchDeg: number}}
+ */
+export function easeLook(current, target, dtMs, { immediate = false } = {}) {
+  const goalYaw = wrapLookYaw(target?.yawDeg ?? 0);
+  const goalPitch = clampLookPitch(target?.pitchDeg ?? 0);
+  if (immediate || !current) return { yawDeg: goalYaw, pitchDeg: goalPitch };
+  const fraction =
+    Number.isFinite(dtMs) && dtMs > 0
+      ? 1 - Math.exp(-dtMs / LOOK_EASE_TAU_MS)
+      : 0;
+  const fromYaw = wrapLookYaw(current.yawDeg);
+  const yawError = wrapLookYaw(goalYaw - fromYaw);
+  const pitchError = goalPitch - clampLookPitch(current.pitchDeg);
+  const yawDeg =
+    Math.abs(yawError * (1 - fraction)) < LOOK_SETTLE_DEG
+      ? goalYaw
+      : wrapLookYaw(fromYaw + yawError * fraction);
+  const pitchDeg =
+    Math.abs(pitchError * (1 - fraction)) < LOOK_SETTLE_DEG
+      ? goalPitch
+      : clampLookPitch(current.pitchDeg + pitchError * fraction);
+  return { yawDeg, pitchDeg };
+}
+
+/**
+ * Whether a look differs from the rest view (ahead at `restPitchDeg`).
+ * @param {{yawDeg: number, pitchDeg: number}} look
+ * @param {number} restPitchDeg The camera profile's pitch.
+ * @returns {boolean}
+ */
+export function lookIsOffset(look, restPitchDeg) {
+  return (
+    wrapLookYaw(look?.yawDeg ?? 0) !== 0 ||
+    clampLookPitch(look?.pitchDeg ?? restPitchDeg) !==
+      clampLookPitch(restPitchDeg)
+  );
+}
+
+/**
+ * The parts of a look readout, for the Cockpit to word. A part is null when
+ * that axis rests: yaw ahead, or pitch at the rest pitch.
+ * @param {{yawDeg: number, pitchDeg: number}} look Look target.
+ * @param {number} restPitchDeg The camera profile's pitch.
+ * @returns {{side: 'port'|'starboard'|'astern'|null, bearingDeg: number,
+ *   elevation: 'up'|'down'|'level'|null, angleDeg: number}} `bearingDeg` is
+ *   the angle off the bow (0–180) and `angleDeg` the angle off level (0–90),
+ *   both rounded to whole degrees.
+ */
+export function lookReadoutParts(look, restPitchDeg) {
+  const yaw = Math.round(wrapLookYaw(look?.yawDeg ?? 0));
+  const pitch = Math.round(clampLookPitch(look?.pitchDeg ?? restPitchDeg));
+  const pitchOffset =
+    clampLookPitch(look?.pitchDeg ?? restPitchDeg) !==
+    clampLookPitch(restPitchDeg);
+  let side = null;
+  if (Math.abs(yaw) >= 180) side = 'astern';
+  else if (yaw > 0) side = 'starboard';
+  else if (yaw < 0) side = 'port';
+  let elevation = null;
+  if (pitchOffset) elevation = pitch > 0 ? 'up' : pitch < 0 ? 'down' : 'level';
+  return {
+    side,
+    bearingDeg: Math.abs(yaw),
+    elevation,
+    angleDeg: Math.abs(pitch),
+  };
+}
+
+/**
+ * The orbital view's off-nadir limit on each axis. The orbital look reuses
+ * the bridge's `{yawDeg, pitchDeg}` shape over a fixed nadir frame: yaw tilts
+ * the view east (positive) or west, pitch tilts it north (positive) or
+ * south. Single 5° steps only; the bridge keeps its own limits.
+ */
+export const ORBITAL_LOOK_LIMIT_DEG = 45;
+
+/** Clamp one orbital look axis to ±ORBITAL_LOOK_LIMIT_DEG; NaN rests. */
+function clampOrbitalAxis(deg) {
+  if (!Number.isFinite(deg)) return 0;
+  const value = Math.min(
+    ORBITAL_LOOK_LIMIT_DEG,
+    Math.max(-ORBITAL_LOOK_LIMIT_DEG, deg),
+  );
+  return value === 0 ? 0 : value;
+}
+
+/**
+ * Clamp an orbital look to the off-nadir limit on both axes.
+ * @param {{yawDeg: number, pitchDeg: number}} look East and north tilt.
+ * @returns {{yawDeg: number, pitchDeg: number}}
+ */
+export function clampOrbitalLook(look) {
+  return {
+    yawDeg: clampOrbitalAxis(look?.yawDeg),
+    pitchDeg: clampOrbitalAxis(look?.pitchDeg),
+  };
+}
+
+/**
+ * Apply one arrow step to an orbital look: the bridge's stepping on the
+ * same 5° grid, then the off-nadir clamp.
+ * @param {{yawDeg: number, pitchDeg: number}} target Current look target.
+ * @param {{axis: 'yaw'|'pitch', sign: number, stepDeg: number}} step From
+ *   {@link lookKeyStep}.
+ * @returns {{yawDeg: number, pitchDeg: number}}
+ */
+export function stepOrbitalLook(target, step) {
+  return clampOrbitalLook(stepLook(clampOrbitalLook(target), step));
+}
+
+/**
+ * The parts of an off-nadir readout, for the Cockpit to word: the north or
+ * south tilt and the east or west tilt, each null at rest, in whole degrees.
+ * @param {{yawDeg: number, pitchDeg: number}} look Orbital look target.
+ * @returns {{northSouth: 'N'|'S'|null, northSouthDeg: number,
+ *   eastWest: 'E'|'W'|null, eastWestDeg: number}}
+ */
+export function orbitalLookReadoutParts(look) {
+  const { yawDeg, pitchDeg } = clampOrbitalLook(look);
+  const north = Math.round(pitchDeg);
+  const east = Math.round(yawDeg);
+  return {
+    northSouth: north > 0 ? 'N' : north < 0 ? 'S' : null,
+    northSouthDeg: Math.abs(north),
+    eastWest: east > 0 ? 'E' : east < 0 ? 'W' : null,
+    eastWestDeg: Math.abs(east),
+  };
+}

src/cockpitLook.test.mjs

@@ -0,0 +1,195 @@
+// src/cockpitLook.test.mjs — the bridge look-around policy: arrow steps,
+// yaw wrapping, pitch limits, easing and the readout's parts.
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import {
+  LOOK_COARSE_STEP_DEG,
+  LOOK_STEP_DEG,
+  ORBITAL_LOOK_LIMIT_DEG,
+  clampLookPitch,
+  clampOrbitalLook,
+  easeLook,
+  lookIsOffset,
+  lookKeyStep,
+  lookReadoutParts,
+  orbitalLookReadoutParts,
+  stepLook,
+  stepOrbitalLook,
+  wrapLookYaw,
+} from './cockpitLook.js';
+
+const REST = { yawDeg: 0, pitchDeg: -2 };
+
+/** Press one key `count` times from `start`. */
+function press(start, key, count = 1, coarse = false) {
+  let look = start;
+  for (let index = 0; index < count; index += 1)
+    look = stepLook(look, lookKeyStep(key, coarse));
+  return look;
+}
+
+test('yaw wraps to (-180, 180] and pitch clamps to [-90, 90]', () => {
+  assert.equal(wrapLookYaw(0), 0);
+  assert.equal(wrapLookYaw(-0), 0);
+  assert.equal(wrapLookYaw(180), 180);
+  assert.equal(wrapLookYaw(-180), 180);
+  assert.equal(wrapLookYaw(185), -175);
+  assert.equal(wrapLookYaw(-185), 175);
+  assert.equal(wrapLookYaw(720 + 45), 45);
+  assert.equal(wrapLookYaw(NaN), 0);
+  assert.equal(clampLookPitch(120), 90);
+  assert.equal(clampLookPitch(-120), -90);
+  assert.equal(clampLookPitch(-0), 0);
+  assert.equal(clampLookPitch(Infinity), 0);
+});
+
+test('only the arrows step, 5° plain and 45° with Shift', () => {
+  assert.deepEqual(lookKeyStep('ArrowLeft'), {
+    axis: 'yaw',
+    sign: -1,
+    stepDeg: LOOK_STEP_DEG,
+  });
+  assert.deepEqual(lookKeyStep('ArrowUp', true), {
+    axis: 'pitch',
+    sign: 1,
+    stepDeg: LOOK_COARSE_STEP_DEG,
+  });
+  assert.equal(lookKeyStep('ArrowDown').sign, -1);
+  assert.equal(lookKeyStep('ArrowRight').sign, 1);
+  for (const key of ['Home', '0', 'a', 'Escape', undefined])
+    assert.equal(lookKeyStep(key), null);
+});
+
+test('arrows turn the yaw in 5° steps and Shift reaches either beam in two', () => {
+  assert.deepEqual(press(REST, 'ArrowRight'), { yawDeg: 5, pitchDeg: -2 });
+  assert.deepEqual(press(REST, 'ArrowLeft', 3), { yawDeg: -15, pitchDeg: -2 });
+  assert.equal(press(REST, 'ArrowRight', 2, true).yawDeg, 90);
+  assert.equal(press(REST, 'ArrowLeft', 2, true).yawDeg, -90);
+  // A coarse step from off the 45° grid lands on it.
+  assert.equal(press({ ...REST, yawDeg: 5 }, 'ArrowRight', 1, true).yawDeg, 45);
+  // Past astern the yaw wraps to the other side.
+  assert.equal(press(REST, 'ArrowRight', 4, true).yawDeg, 180);
+  assert.equal(press(REST, 'ArrowRight', 5, true).yawDeg, -135);
+  assert.equal(press(REST, 'ArrowLeft', 37).yawDeg, 175);
+});
+
+test('pitch steps onto the 5° grid from the rest pitch and stops at ±90°', () => {
+  assert.equal(press(REST, 'ArrowUp').pitchDeg, 0);
+  assert.equal(press(REST, 'ArrowUp', 3).pitchDeg, 10);
+  assert.equal(press(REST, 'ArrowDown').pitchDeg, -5);
+  assert.equal(press(REST, 'ArrowUp', 40).pitchDeg, 90);
+  assert.equal(press(REST, 'ArrowDown', 40).pitchDeg, -90);
+  assert.equal(press(REST, 'ArrowUp', 3, true).pitchDeg, 90);
+  assert.equal(press(REST, 'ArrowDown', 2, true).pitchDeg, -90);
+  assert.equal(press(REST, 'ArrowUp').yawDeg, 0, 'pitch leaves the yaw');
+});
+
+test('the eased view closes most of a step in about 180 ms', () => {
+  const target = { yawDeg: 90, pitchDeg: -2 };
+  let view = { ...REST };
+  view = easeLook(view, target, 180);
+  assert.ok(view.yawDeg > 85 && view.yawDeg < 90, `yaw ${view.yawDeg}`);
+  for (let step = 0; step < 20; step += 1) view = easeLook(view, target, 50);
+  assert.deepEqual(view, target, 'it lands exactly on the target');
+  assert.deepEqual(easeLook(REST, target, 0), REST, 'no time, no motion');
+});
+
+test('the eased yaw takes the short way across astern', () => {
+  const view = easeLook(
+    { yawDeg: 170, pitchDeg: 0 },
+    { yawDeg: -170, pitchDeg: 0 },
+    30,
+  );
+  assert.ok(view.yawDeg > 170 || view.yawDeg < -170, `yaw ${view.yawDeg}`);
+});
+
+test('reduced motion jumps straight to the target', () => {
+  const target = { yawDeg: -45, pitchDeg: 30 };
+  assert.deepEqual(easeLook(REST, target, 1, { immediate: true }), target);
+});
+
+test('the readout names the side, the bearing and the elevation', () => {
+  assert.equal(lookIsOffset(REST, -2), false);
+  assert.equal(lookIsOffset({ yawDeg: 0, pitchDeg: 0 }, -2), true);
+  assert.equal(lookIsOffset({ yawDeg: 5, pitchDeg: -2 }, -2), true);
+  assert.deepEqual(lookReadoutParts({ yawDeg: 45, pitchDeg: 10 }, -2), {
+    side: 'starboard',
+    bearingDeg: 45,
+    elevation: 'up',
+    angleDeg: 10,
+  });
+  assert.deepEqual(lookReadoutParts({ yawDeg: -90, pitchDeg: -2 }, -2), {
+    side: 'port',
+    bearingDeg: 90,
+    elevation: null,
+    angleDeg: 2,
+  });
+  assert.deepEqual(lookReadoutParts({ yawDeg: 0, pitchDeg: -30 }, -2), {
+    side: null,
+    bearingDeg: 0,
+    elevation: 'down',
+    angleDeg: 30,
+  });
+  assert.equal(
+    lookReadoutParts({ yawDeg: 0, pitchDeg: 0 }, -2).elevation,
+    'level',
+  );
+  assert.equal(
+    lookReadoutParts({ yawDeg: 180, pitchDeg: -2 }, -2).side,
+    'astern',
+  );
+});
+
+test('an orbital look steps 5° per arrow and stops at 45° on each axis', () => {
+  let look = { yawDeg: 0, pitchDeg: 0 };
+  for (let index = 0; index < 3; index += 1)
+    look = stepOrbitalLook(look, lookKeyStep('ArrowUp'));
+  assert.deepEqual(look, { yawDeg: 0, pitchDeg: 15 });
+  look = stepOrbitalLook(look, lookKeyStep('ArrowRight'));
+  assert.deepEqual(look, { yawDeg: 5, pitchDeg: 15 });
+  for (let index = 0; index < 20; index += 1) {
+    look = stepOrbitalLook(look, lookKeyStep('ArrowDown'));
+    look = stepOrbitalLook(look, lookKeyStep('ArrowLeft'));
+  }
+  assert.deepEqual(look, {
+    yawDeg: -ORBITAL_LOOK_LIMIT_DEG,
+    pitchDeg: -ORBITAL_LOOK_LIMIT_DEG,
+  });
+  assert.deepEqual(clampOrbitalLook({ yawDeg: 90, pitchDeg: NaN }), {
+    yawDeg: 45,
+    pitchDeg: 0,
+  });
+  assert.deepEqual(clampOrbitalLook({ yawDeg: 180, pitchDeg: -60 }), {
+    yawDeg: 45,
+    pitchDeg: -45,
+  });
+});
+
+test('the orbital readout names north or south and east or west', () => {
+  assert.deepEqual(orbitalLookReadoutParts({ yawDeg: 15, pitchDeg: 10 }), {
+    northSouth: 'N',
+    northSouthDeg: 10,
+    eastWest: 'E',
+    eastWestDeg: 15,
+  });
+  assert.deepEqual(orbitalLookReadoutParts({ yawDeg: -5, pitchDeg: 0 }), {
+    northSouth: null,
+    northSouthDeg: 0,
+    eastWest: 'W',
+    eastWestDeg: 5,
+  });
+  assert.equal(
+    orbitalLookReadoutParts({ yawDeg: 0, pitchDeg: -45 }).northSouth,
+    'S',
+  );
+});
+
+test('the bridge look keeps its own limits beside the orbital clamp', () => {
+  const look = stepLook({ yawDeg: 45, pitchDeg: 45 }, lookKeyStep('ArrowUp'));
+  assert.deepEqual(look, { yawDeg: 45, pitchDeg: 50 });
+  assert.equal(
+    stepLook({ yawDeg: 45, pitchDeg: 0 }, lookKeyStep('ArrowRight', true))
+      .yawDeg,
+    90,
+  );
+});

src/cockpitMarkup.test.mjs

@@ -79,7 +79,7 @@ test('Cockpit has one reset action beside its bottom exit path', () => {
   assert.doesNotMatch(html, /id="cockpit-exit"/);
   assert.match(
     html,
-    /id="map-view-switch"[^>]*aria-label="Exit cockpit view"[^>]*aria-keyshortcuts="Escape C"[\s\S]*?close_fullscreen[\s\S]*?EXIT COCKPIT/,
+    /id="map-view-switch"[^>]*aria-label="Exit cockpit view"[^>]*aria-keyshortcuts="Escape"[\s\S]*?close_fullscreen[\s\S]*?EXIT COCKPIT/,
   );
   const topCenterActions = html.match(
     /<nav id="top-center-actions"[\s\S]*?<\/nav>/,
@@ -163,7 +163,8 @@ test('Cockpit vision cycle exposes every map preset exactly once', () => {
   assert.match(html, /id="cockpit-vision-current-label"[^>]*>NORMAL<\/strong>/);
   assert.match(
     cockpitEnter.toString(),
-    /this\.setVisionMode\(this\.getInitialVisionMode\(\)\)/,
+    // Orbit alone opens optical (src/ui/cockpitOrbitalView.test.mjs).
+    /this\.setVisionMode\(\s*satellite \? 'optical' : this\.getInitialVisionMode\(\)\s*,?\s*\)/,
     'Cockpit must enter on the mode matching the active map preset',
   );
   assert.match(
@@ -232,14 +233,12 @@ test('Cockpit Escape handling precedes form-control shortcut suppression and foc
   );
 });
 
-test('Cockpit shortcut failures do not leak and open utilities own the first Escape', () => {
+test('open utilities own the first Escape and Cockpit leaves C alone', () => {
   const keydown = cockpitKeyDown.toString();
   assert.ok(keydown, 'Cockpit keyboard handler is missing');
   assert.match(keydown, /if \(this\.isUtilityDisclosureOpen\?\.\(\)\) return;/);
-  assert.match(
-    keydown,
-    /const cockpitAttempt = !!\(\s*this\.readAircraftInfo\(\) && this\.viewer\.trackedEntity\?\.position\s*\);[\s\S]*?event\.preventDefault\(\);[\s\S]*?event\.stopImmediatePropagation\(\);[\s\S]*?!this\.isEntryAllowed\(\)/,
-  );
+  // C is the app-wide CCTV shortcut; Cockpit never claims it.
+  assert.doesNotMatch(keydown, /=== 'c'/);
 });
 
 test('the Contact panel never hides itself out from under its own NEXT button', () => {
@@ -1306,12 +1305,12 @@ test('voice Cockpit entry honours a requested contact layer before it enters', (
     ui.indexOf("if (normalized === 'exit') {"),
   );
   assert.ok(branch, 'cockpit enter branch is missing');
-  const gateIndex = branch.indexOf('isEntryAllowed?.()');
+  const gateIndex = branch.indexOf('this._cockpitEntryRefusal()');
   const retargetIndex = branch.indexOf('_retargetCockpitEntryLayer(');
   const enterIndex = branch.indexOf('enterCockpitWithTracking({');
   assert.ok(
     gateIndex >= 0,
-    'entry consults the same gate the manual chip uses',
+    'entry refuses on the gate it can check before tracking',
   );
   assert.ok(
     retargetIndex > gateIndex,
@@ -1362,9 +1361,21 @@ test('voice Cockpit entry refuses when the entry gate is shut', () => {
     ui.indexOf("if (normalized === 'enter') {"),
     ui.indexOf("if (normalized === 'exit') {"),
   );
-  assert.match(branch, /if \(!this\.cockpitView\.isEntryAllowed\?\.\(\)\) \{/);
-  assert.match(branch, /Contacts must be active to enter Cockpit/);
-  assert.match(branch, /Contacts is still starting up/);
+  // Contacts is not required: only a Context change in flight or no aircraft
+  // layer to ride shuts the gate before tracking, and the entry itself then
+  // applies the manual chip's gate to the aircraft it rides.
+  assert.match(
+    branch,
+    /const refusal = this\._cockpitEntryRefusal\(\);\s*if \(refusal\) \{/,
+  );
+  assert.doesNotMatch(branch, /Contacts must be active/);
+  const refusal = ui.slice(
+    ui.indexOf('  _cockpitEntryRefusal() {'),
+    ui.indexOf('  getCockpitState() {'),
+  );
+  assert.match(refusal, /Context is still changing/);
+  assert.match(refusal, /No aircraft layer is on/);
+  assert.doesNotMatch(refusal, /[Cc]ontacts/);
 });
 
 test('cockpit state cannot report entryAllowed while already active', () => {
@@ -1382,7 +1393,8 @@ test('cockpit state cannot report entryAllowed while already active', () => {
   );
   assert.match(state, /entryBlockedReason:/, 'and a refusal can be explained');
   assert.match(state, /'contacts-starting'/);
-  assert.match(state, /'contacts-inactive'/);
+  assert.match(state, /'subject-layer-off'/);
+  assert.doesNotMatch(state, /'contacts-inactive'/, 'Contacts is not required');
   assert.match(state, /'no-tracked-aircraft'/);
 });
 

src/cockpitMath.js

@@ -176,6 +176,46 @@ export function compassDivisions(heading) {
   );
 }
 
+/**
+ * A heading tape that scrolls continuously: the 30-degree divisions within
+ * `reach` divisions of `heading`, each placed by its offset from the exact
+ * heading in division slots, so the centre caret reads the heading itself
+ * rather than the nearest division. `nearest` marks the division closest to
+ * the caret.
+ * @param {number} heading Degrees true.
+ * @param {number} [reach] Divisions each side of the caret.
+ * @returns {Array<{heading: number, slot: number, nearest: boolean}>}
+ */
+export function scrollingCompassDivisions(heading, reach = 4) {
+  if (!Number.isFinite(heading)) return [];
+  const exact = normalizeHeading(heading);
+  const centre = Math.round(exact / 30) * 30;
+  const divisions = [];
+  for (let step = -reach; step <= reach; step += 1) {
+    const division = normalizeHeading(centre + step * 30);
+    divisions.push({
+      heading: division,
+      slot: Number((relativeBearing(division, exact) / 30).toFixed(4)),
+      nearest: step === 0,
+    });
+  }
+  return divisions;
+}
+
+/**
+ * Where a heading falls on the `scrollingCompassDivisions(tapeHeading)` tape:
+ * its offset from the caret (the tape's exact heading) in division slots of
+ * 30 degrees, or null when it lies more than three divisions out.
+ * @param {number} heading Degrees true.
+ * @param {number} tapeHeading The heading under the tape's caret.
+ * @returns {?number}
+ */
+export function compassMarkerSlot(heading, tapeHeading) {
+  if (!Number.isFinite(heading) || !Number.isFinite(tapeHeading)) return null;
+  const slot = Number((relativeBearing(heading, tapeHeading) / 30).toFixed(4));
+  return Math.abs(slot) <= 3 ? slot : null;
+}
+
 /** Format a compass division as a cardinal/intercardinal label or degrees. */
 export function formatCompassDivision(heading) {
   const normalized = normalizeHeading(heading);

src/cockpitMath.test.mjs

@@ -11,6 +11,8 @@ import {
   cockpitSurfaceWaitExpired,
   cockpitUiUpdateDue,
   compassDivisions,
+  compassMarkerSlot,
+  scrollingCompassDivisions,
   formatAltitudeRulerTick,
   formatCockpitContextScope,
   formatCockpitEmergency,
@@ -151,6 +153,46 @@ test('compass divisions remain ordered across north', () => {
   assert.deepEqual(compassDivisions(359), [270, 300, 330, 0, 30, 60, 90]);
 });
 
+test('compass marks sit in division slots off the caret, or off the tape', () => {
+  // Measured from the exact heading under the caret, not the nearest division.
+  assert.equal(compassMarkerSlot(350, 350), 0);
+  assert.equal(compassMarkerSlot(35, 350), 1.5);
+  assert.equal(compassMarkerSlot(260, 350), -3);
+  assert.equal(compassMarkerSlot(80, 350), 3);
+  assert.equal(compassMarkerSlot(90, 350), null);
+  assert.equal(compassMarkerSlot(180, 350), null);
+  assert.equal(compassMarkerSlot(Number.NaN, 0), null);
+});
+
+test('a scrolling tape puts the exact heading under the caret', () => {
+  // At 100° the divisions sit a third of a slot off their snapped places,
+  // so the bow mark (also 100°) lines up with the caret, not 10° beside it.
+  const tape = scrollingCompassDivisions(100);
+  assert.deepEqual(
+    tape.map(({ heading }) => heading),
+    [330, 0, 30, 60, 90, 120, 150, 180, 210],
+  );
+  const nearest = tape.find((division) => division.nearest);
+  assert.equal(nearest.heading, 90);
+  assert.equal(nearest.slot, -0.3333);
+  assert.equal(tape.find(({ heading }) => heading === 120).slot, 0.6667);
+  assert.equal(compassMarkerSlot(100, 100), 0);
+  assert.equal(compassMarkerSlot(90, 100), nearest.slot);
+  // Across north the slots stay continuous.
+  assert.deepEqual(
+    scrollingCompassDivisions(355, 1).map(({ heading, slot }) => [
+      heading,
+      slot,
+    ]),
+    [
+      [330, -0.8333],
+      [0, 0.1667],
+      [30, 1.1667],
+    ],
+  );
+  assert.deepEqual(scrollingCompassDivisions(Number.NaN), []);
+});
+
 test('compass labels use cardinals where exact and degrees elsewhere', () => {
   assert.equal(formatCompassDivision(270), 'W');
   assert.equal(formatCompassDivision(30), '030');

src/cockpitOrbital.js

@@ -0,0 +1,808 @@
+/**
+ * Camera policy for the orbital (satellite) view: the eye rides the tracked
+ * satellite and looks straight down at the Earth's centre. Satellites publish
+ * no attitude, so the picture is turned to the ground track (track-up; see
+ * nadirOrientation's `headingDeg`), or north-up for a satellite with none
+ * (geostationary). This module holds the zoom steps,
+ * the field of view, the nadir orientation, the ground footprint and the zoom
+ * transition curves. No DOM, Cesium or i18n dependencies: vectors are plain
+ * `{x, y, z}` objects in Earth-fixed (ECEF) metres, so the policy is
+ * unit-testable and the Cockpit camera copies them into its own scratch.
+ */
+
+/** Mean Earth radius used for footprint and framing geometry, metres. */
+export const ORBITAL_EARTH_RADIUS_M = 6371008.8;
+
+/**
+ * The whole zoom ladder. Steps past ORBITAL_BASE_MAX_ZOOM belong only to
+ * imaging satellites with a known sensor, each up to the step its sensor's
+ * swath allows (`orbitalMaxZoom`).
+ */
+export const ORBITAL_ZOOM_LADDER = Object.freeze([1, 2, 4, 8, 16, 32, 64, 128]);
+
+/** The tightest step for a satellite without sensor data. */
+export const ORBITAL_BASE_MAX_ZOOM = 8;
+
+/** The zoom an orbital view opens at. */
+export const ORBITAL_DEFAULT_ZOOM = 1;
+
+/**
+ * Vertical field of view at 1x for low orbits. From the ISS (~420 km) a 60°
+ * frame spans roughly 490 km of ground top to bottom: a regional picture
+ * with the curvature just out of frame, which 8x narrows to ~60 km.
+ */
+export const ORBITAL_BASE_FOV_LEO_RAD = (60 * Math.PI) / 180;
+
+/**
+ * How much wider than the Earth's disk a high orbit's 1x frame is. A fixed
+ * 60° frame from GEO (~35,786 km) would show a 17° Earth floating in black;
+ * above about 8,000 km the base frame instead fits the whole disk with this
+ * margin, so 1x is "the whole Earth" and the steps zoom into it.
+ */
+export const ORBITAL_DISK_MARGIN = 1.15;
+
+/** Duration of one zoom step's field-of-view change, ms. */
+export const ORBITAL_ZOOM_TRANSITION_MS = 400;
+
+/** How long the reticle shows its lock tick after a step settles, ms. */
+export const ORBITAL_LOCK_TICK_MS = 220;
+
+/** Peak focus-pull blur at the middle of a zoom step, CSS pixels. */
+export const ORBITAL_MAX_BLUR_PX = 6;
+
+/**
+ * Longest a zoom step holds its focus pull for the new field of view's
+ * imagery, ms. The camera moves at orbital speed, so the tiles may never
+ * all arrive; the hold gives them a start, then the reticle locks anyway.
+ */
+export const ORBITAL_SETTLE_MAX_MS = 2500;
+
+/** The soft blur held while a step waits for its imagery, CSS pixels. */
+export const ORBITAL_SETTLE_BLUR_PX = 2.5;
+
+/** Relative slack so a zoom computed in floating point still meets its step. */
+const ZOOM_EPSILON = 1e-6;
+
+/**
+ * The next tighter ladder step, up to `maxZoom`; at the cap the zoom stays.
+ * A zoom between steps (the SENSOR step) moves to the step above it.
+ * @param {number} zoom Current zoom.
+ * @param {number} [maxZoom] The satellite's tightest step.
+ * @returns {number}
+ */
+export function nextOrbitalZoom(zoom, maxZoom = ORBITAL_BASE_MAX_ZOOM) {
+  const current = Number.isFinite(zoom) && zoom > 0 ? zoom : 1;
+  const next = ORBITAL_ZOOM_LADDER.find(
+    (step) => step > current * (1 + ZOOM_EPSILON) && step <= maxZoom,
+  );
+  return next ?? current;
+}
+
+/**
+ * The next wider ladder step; 1x stays where it is. A zoom between steps
+ * moves to the step below it.
+ * @param {number} zoom Current zoom.
+ * @returns {number}
+ */
+export function previousOrbitalZoom(zoom) {
+  const current = Number.isFinite(zoom) && zoom > 0 ? zoom : 1;
+  const wider = ORBITAL_ZOOM_LADDER.filter(
+    (step) => step < current * (1 - ZOOM_EPSILON),
+  );
+  return wider.length ? wider[wider.length - 1] : ORBITAL_DEFAULT_ZOOM;
+}
+
+/**
+ * The ground width the view spans at a zoom: what the SWATH readout shows.
+ * @param {number} altitudeM Satellite altitude, metres.
+ * @param {number} zoom Magnification.
+ * @param {number} aspect Canvas width / height.
+ * @returns {number|null} Kilometres, or null for an unusable altitude.
+ */
+export function viewWidthKm(altitudeM, zoom, aspect) {
+  return footprintWidthKm(
+    altitudeM,
+    fovForZoom(orbitalBaseFovRad(altitudeM), zoom),
+    aspect,
+  );
+}
+
+/**
+ * A satellite's tightest zoom step at its live altitude: the tightest ladder
+ * step whose view is still at least as wide as its sensor's narrowest
+ * standard swath, so the view never shows finer ground than the sensor
+ * images. Never below ORBITAL_BASE_MAX_ZOOM; no sensor swath, no extra steps.
+ * @param {number} altitudeM Live altitude, metres.
+ * @param {number|null|undefined} sensorSwathKm Narrowest standard swath.
+ * @param {number} aspect Canvas width / height.
+ * @returns {number} One of ORBITAL_ZOOM_LADDER.
+ */
+export function orbitalMaxZoom(altitudeM, sensorSwathKm, aspect) {
+  if (!Number.isFinite(sensorSwathKm) || sensorSwathKm <= 0)
+    return ORBITAL_BASE_MAX_ZOOM;
+  let max = ORBITAL_BASE_MAX_ZOOM;
+  for (const step of ORBITAL_ZOOM_LADDER) {
+    if (step <= ORBITAL_BASE_MAX_ZOOM) continue;
+    const width = viewWidthKm(altitudeM, step, aspect);
+    if (!Number.isFinite(width)) break;
+    if (width * (1 + ZOOM_EPSILON) < sensorSwathKm) break;
+    max = step;
+  }
+  return max;
+}
+
+/**
+ * The zoom at which the view is exactly as wide as the sensor's swath, for
+ * the SENSOR step; null when that lies outside 1x..`maxZoom` (a swath wider
+ * than the 1x view, or narrower than the tightest allowed step).
+ * @param {number} altitudeM Live altitude, metres.
+ * @param {number|null|undefined} sensorSwathKm
+ * @param {number} aspect Canvas width / height.
+ * @param {number} maxZoom The satellite's tightest step.
+ * @returns {number|null}
+ */
+export function sensorSwathZoom(altitudeM, sensorSwathKm, aspect, maxZoom) {
+  if (!Number.isFinite(sensorSwathKm) || sensorSwathKm <= 0) return null;
+  const widest = viewWidthKm(altitudeM, 1, aspect);
+  const tightest = viewWidthKm(altitudeM, maxZoom, aspect);
+  if (!Number.isFinite(widest) || !Number.isFinite(tightest)) return null;
+  if (sensorSwathKm > widest * (1 + ZOOM_EPSILON)) return null;
+  if (sensorSwathKm < tightest * (1 - ZOOM_EPSILON)) return null;
+  // The width falls monotonically with zoom: bisect in log space.
+  let low = 0;
+  let high = Math.log2(maxZoom);
+  for (let i = 0; i < 48; i += 1) {
+    const mid = (low + high) / 2;
+    if (viewWidthKm(altitudeM, 2 ** mid, aspect) > sensorSwathKm) low = mid;
+    else high = mid;
+  }
+  return Math.round(2 ** ((low + high) / 2) * 100) / 100;
+}
+
+/**
+ * How much of the view's width a sensor swath covers, for the strip drawn
+ * to scale in the reticle: 0..1, 1 when the swath fills the view or more.
+ * @param {number|null|undefined} sensorSwathKm
+ * @param {number|null|undefined} viewKm The view's current ground width.
+ * @returns {number|null} Null without both widths.
+ */
+export function sensorStripFraction(sensorSwathKm, viewKm) {
+  if (!Number.isFinite(sensorSwathKm) || sensorSwathKm <= 0) return null;
+  if (!Number.isFinite(viewKm) || viewKm <= 0) return null;
+  return Math.min(1, sensorSwathKm / viewKm);
+}
+
+/**
+ * Angular radius of the Earth's disk seen from an altitude, radians.
+ * @param {number} altitudeM Height above the mean sphere, metres.
+ * @returns {number} Half-angle from nadir to the limb (π/2 at the surface).
+ */
+export function earthAngularRadiusRad(altitudeM) {
+  const h = Math.max(0, Number.isFinite(altitudeM) ? altitudeM : 0);
+  return Math.asin(ORBITAL_EARTH_RADIUS_M / (ORBITAL_EARTH_RADIUS_M + h));
+}
+
+/**
+ * Vertical field of view at 1x for an altitude, radians.
+ *
+ * Low orbits get the fixed 60° regional frame. Higher orbits, where 60° would
+ * leave the Earth small in a black frame, get the Earth's disk plus
+ * ORBITAL_DISK_MARGIN. The two meet near 8,100 km, so the base never jumps
+ * as an eccentric orbit climbs: GPS (~20,200 km) opens at ~32°, GEO at ~20°.
+ * @param {number} altitudeM Satellite altitude, metres.
+ * @returns {number} Vertical field of view, radians.
+ */
+export function orbitalBaseFovRad(altitudeM) {
+  const diskFov = 2 * earthAngularRadiusRad(altitudeM) * ORBITAL_DISK_MARGIN;
+  return Math.min(ORBITAL_BASE_FOV_LEO_RAD, diskFov);
+}
+
+/**
+ * Field of view at an optical zoom: magnification divides the tangent of
+ * the half-angle, as a lens's focal length does.
+ * @param {number} baseFovRad Field of view at 1x, radians.
+ * @param {number} zoom Magnification (1 leaves the base unchanged).
+ * @returns {number} Field of view, radians.
+ */
+export function fovForZoom(baseFovRad, zoom) {
+  const magnification = Number.isFinite(zoom) && zoom > 0 ? zoom : 1;
+  return 2 * Math.atan(Math.tan(baseFovRad / 2) / magnification);
+}
+
+/**
+ * Cesium's `PerspectiveFrustum.fov` is horizontal on a landscape canvas and
+ * vertical on a portrait one; convert a vertical field of view to it.
+ * @param {number} verticalFovRad Vertical field of view, radians.
+ * @param {number} aspect Canvas width / height.
+ * @returns {number} The value to assign to `frustum.fov`, radians.
+ */
+export function cesiumFrustumFovRad(verticalFovRad, aspect) {
+  if (!(aspect > 1)) return verticalFovRad;
+  return 2 * Math.atan(Math.tan(verticalFovRad / 2) * aspect);
+}
+
+/**
+ * Ground width covered across the frame, along a great circle through the
+ * sub-satellite point, km. A ray past the limb ends at the horizon, so a
+ * frame wider than the disk reports the visible cap's width.
+ * @param {number} altitudeM Satellite altitude, metres.
+ * @param {number} fovRad Vertical field of view, radians.
+ * @param {number} [aspect=1] Frame width / height; the width is measured
+ *   across the wider horizontal extent.
+ * @returns {number|null} Width in kilometres, or null without a usable input.
+ */
+export function footprintWidthKm(altitudeM, fovRad, aspect = 1) {
+  if (!Number.isFinite(altitudeM) || altitudeM <= 0) return null;
+  if (!Number.isFinite(fovRad) || fovRad <= 0) return null;
+  const ratio = Number.isFinite(aspect) && aspect > 0 ? aspect : 1;
+  const halfAngle = Math.atan(Math.tan(fovRad / 2) * ratio);
+  const R = ORBITAL_EARTH_RADIUS_M;
+  const sinGround = ((R + altitudeM) / R) * Math.sin(halfAngle);
+  // Central angle from nadir to where the ray meets the sphere, or the limb.
+  const central =
+    sinGround >= 1
+      ? Math.acos(R / (R + altitudeM))
+      : Math.asin(sinGround) - halfAngle;
+  return (2 * R * central) / 1000;
+}
+
+function length(v) {
+  return Math.hypot(v.x, v.y, v.z);
+}
+
+function scale(v, s) {
+  return { x: v.x * s, y: v.y * s, z: v.z * s };
+}
+
+function dot(a, b) {
+  return a.x * b.x + a.y * b.y + a.z * b.z;
+}
+
+function cross(a, b) {
+  return {
+    x: a.y * b.z - a.z * b.y,
+    y: a.z * b.x - a.x * b.z,
+    z: a.x * b.y - a.y * b.x,
+  };
+}
+
+/** `v` with its component along unit `d` removed, or null when degenerate. */
+function perpendicularUnit(v, d) {
+  const along = dot(v, d);
+  const p = {
+    x: v.x - along * d.x,
+    y: v.y - along * d.y,
+    z: v.z - along * d.z,
+  };
+  const n = length(p);
+  return n > 1e-6 ? scale(p, 1 / n) : null;
+}
+
+const NORTH_AXIS = Object.freeze({ x: 0, y: 0, z: 1 });
+
+/**
+ * Camera orientation looking from an Earth-fixed position at the Earth's
+ * centre, with north at the top of the frame.
+ *
+ * `up` is the Earth's rotation axis projected perpendicular to the view, which
+ * is local north at the sub-satellite point. Directly over a pole north is
+ * undefined; the previous frame's `up` is kept when given (so a polar pass
+ * does not spin the picture), otherwise the limit along the prime meridian
+ * is used: over the north pole the top of the frame faces 180°E, over the
+ * south pole 0°E.
+ *
+ * With `headingDeg` the frame turns so that bearing (degrees clockwise from
+ * north) is at the top: the ground track, for a view that scrolls along it.
+ * @param {{x: number, y: number, z: number}} position ECEF position, metres.
+ * @param {{previousUp?: {x: number, y: number, z: number}|null,
+ *   headingDeg?: number|null}} [options] `previousUp` is a previous frame's
+ *   `north`, not its turned `up`.
+ * @returns {{direction: {x: number, y: number, z: number},
+ *   up: {x: number, y: number, z: number},
+ *   right: {x: number, y: number, z: number},
+ *   north: {x: number, y: number, z: number}}|null} Unit vectors (right =
+ *   direction × up, as Cesium's camera keeps them), or null at the centre.
+ */
+export function nadirOrientation(
+  position,
+  { previousUp = null, headingDeg = null } = {},
+) {
+  if (!position) return null;
+  const r = length(position);
+  if (!Number.isFinite(r) || r < 1) return null;
+  const direction = scale(position, -1 / r);
+  let up = perpendicularUnit(NORTH_AXIS, direction);
+  if (!up && previousUp && Number.isFinite(length(previousUp)))
+    up = perpendicularUnit(previousUp, direction);
+  if (!up) {
+    // Looking down -z (north pole): north at longitude 0 points along -x.
+    up = perpendicularUnit(
+      { x: direction.z < 0 ? -1 : 1, y: 0, z: 0 },
+      direction,
+    );
+  }
+  const north = up;
+  if (Number.isFinite(headingDeg) && headingDeg % 360 !== 0) {
+    // Looking down, right = direction × north is east: the bearing turns
+    // north toward it.
+    const east = cross(direction, north);
+    const θ = (headingDeg * Math.PI) / 180;
+    up = {
+      x: north.x * Math.cos(θ) + east.x * Math.sin(θ),
+      y: north.y * Math.cos(θ) + east.y * Math.sin(θ),
+      z: north.z * Math.cos(θ) + east.z * Math.sin(θ),
+    };
+  }
+  return { direction, up, right: cross(direction, up), north };
+}
+
+/**
+ * Ease-in-out progress of a zoom step (cubic), clamped to 0..1.
+ * @param {number} elapsedMs Time since the step began.
+ * @param {{durationMs?: number, reducedMotion?: boolean}} [options]
+ *   Reduced motion cuts straight to the end.
+ * @returns {number} Eased progress, 0..1.
+ */
+export function zoomTransitionProgress(
+  elapsedMs,
+  { durationMs = ORBITAL_ZOOM_TRANSITION_MS, reducedMotion = false } = {},
+) {
+  if (reducedMotion || !(durationMs > 0)) return 1;
+  const linear = Math.min(1, Math.max(0, (elapsedMs || 0) / durationMs));
+  return linear < 0.5 ? 4 * linear ** 3 : 1 - (-2 * linear + 2) ** 3 / 2;
+}
+
+/**
+ * Focus-pull blur for a zoom step: zero at both ends, peaking mid-step.
+ * @param {number} progress Step progress, 0..1 (linear or eased).
+ * @param {{maxBlurPx?: number, reducedMotion?: boolean}} [options]
+ *   Reduced motion never blurs.
+ * @returns {number} Blur radius, CSS pixels.
+ */
+export function zoomTransitionBlurPx(
+  progress,
+  { maxBlurPx = ORBITAL_MAX_BLUR_PX, reducedMotion = false } = {},
+) {
+  if (reducedMotion || !Number.isFinite(progress)) return 0;
+  const p = Math.min(1, Math.max(0, progress));
+  return Math.max(0, maxBlurPx) * Math.sin(Math.PI * p);
+}
+
+/**
+ * Field of view part-way through a zoom step. Interpolates the tangent of
+ * the half-angle geometrically, so each moment of the step magnifies by the
+ * same ratio and 1x→2x feels like 4x→8x.
+ * @param {number} fromFovRad Field of view the step starts at.
+ * @param {number} toFovRad Field of view the step ends at.
+ * @param {number} progress Eased progress, 0..1.
+ * @returns {number} Field of view, radians.
+ */
+export function interpolateZoomFov(fromFovRad, toFovRad, progress) {
+  const p = Math.min(1, Math.max(0, Number.isFinite(progress) ? progress : 1));
+  const a = Math.log(Math.tan(fromFovRad / 2));
+  const b = Math.log(Math.tan(toFovRad / 2));
+  return 2 * Math.atan(Math.exp(a + (b - a) * p));
+}
+
+/**
+ * The HUD's transition state at a moment of a zoom step, in the store shape
+ * `{ active, blurPx, lockTick }`: blur while the field of view moves, then a
+ * brief reticle lock tick once it settles. Reduced motion skips the blur and
+ * the tick (the cut is instant).
+ * @param {number} elapsedMs Time since the step began.
+ * @param {{durationMs?: number, lockTickMs?: number, maxBlurPx?: number,
+ *   reducedMotion?: boolean}} [options]
+ * @returns {{active: boolean, progress: number, blurPx: number,
+ *   lockTick: boolean}}
+ */
+export function zoomTransitionState(
+  elapsedMs,
+  {
+    durationMs = ORBITAL_ZOOM_TRANSITION_MS,
+    lockTickMs = ORBITAL_LOCK_TICK_MS,
+    maxBlurPx = ORBITAL_MAX_BLUR_PX,
+    reducedMotion = false,
+  } = {},
+) {
+  const progress = zoomTransitionProgress(elapsedMs, {
+    durationMs,
+    reducedMotion,
+  });
+  if (reducedMotion)
+    return { active: false, progress: 1, blurPx: 0, lockTick: false };
+  const elapsed = Math.max(0, elapsedMs || 0);
+  const linear = durationMs > 0 ? Math.min(1, elapsed / durationMs) : 1;
+  return {
+    active: elapsed < durationMs,
+    progress,
+    blurPx: zoomTransitionBlurPx(linear, { maxBlurPx }),
+    lockTick: elapsed >= durationMs && elapsed < durationMs + lockTickMs,
+  };
+}
+
+/**
+ * Whether a zoom step whose field of view has landed still holds its focus
+ * pull: until the imagery has loaded, at most `maxHoldMs`.
+ * @param {number} sinceLandedMs Time since the field of view stopped moving.
+ * @param {boolean} tilesLoaded Whether the scene's imagery has loaded.
+ * @param {{maxHoldMs?: number}} [options]
+ */
+export function zoomSettleHolding(
+  sinceLandedMs,
+  tilesLoaded,
+  { maxHoldMs = ORBITAL_SETTLE_MAX_MS } = {},
+) {
+  return !tilesLoaded && Math.max(0, sinceLandedMs || 0) < maxHoldMs;
+}
+
+/**
+ * The total angle between a tilted view and nadir, degrees:
+ * acos(cos north · cos east), as `offNadirOrientation` tilts.
+ * @param {{northDeg?: number, eastDeg?: number}} [offset] Tilt in degrees.
+ * @returns {number}
+ */
+export function offNadirAngleDeg({ northDeg = 0, eastDeg = 0 } = {}) {
+  const n = ((Number.isFinite(northDeg) ? northDeg : 0) * Math.PI) / 180;
+  const e = ((Number.isFinite(eastDeg) ? eastDeg : 0) * Math.PI) / 180;
+  const cosine = Math.min(1, Math.max(-1, Math.cos(n) * Math.cos(e)));
+  return (Math.acos(cosine) * 180) / Math.PI;
+}
+
+/**
+ * Whether the view's centre, tilted off nadir, still meets the Earth: its
+ * angle from nadir (`offNadirAngleDeg`) is within the Earth's angular radius
+ * from the satellite, asin(R / (R + altitude)).
+ * @param {number} altitudeM
+ * @param {{northDeg?: number, eastDeg?: number}} [offset]
+ * @returns {boolean}
+ */
+export function offNadirCentreMeetsEarth(altitudeM, offset = {}) {
+  if (!Number.isFinite(altitudeM) || altitudeM <= 0) return false;
+  const R = ORBITAL_EARTH_RADIUS_M;
+  const limbDeg = (Math.asin(R / (R + altitudeM)) * 180) / Math.PI;
+  return offNadirAngleDeg(offset) < limbDeg;
+}
+
+/**
+ * Roughly how much wider the ground across the frame is at the centre of a
+ * tilted view than at nadir, on a flat Earth: tilting across the frame (east,
+ * the frame's right) stretches its width by 1/cos², tilting along it (north,
+ * the frame's top) by 1/cos. 1 at nadir; an approximation, so the HUD marks
+ * the width it scales with ≈.
+ * @param {{northDeg?: number, eastDeg?: number}} [offset] Tilt in degrees.
+ * @returns {number} At least 1.
+ */
+export function offNadirSwathScale({ northDeg = 0, eastDeg = 0 } = {}) {
+  const n = ((Number.isFinite(northDeg) ? northDeg : 0) * Math.PI) / 180;
+  const e = ((Number.isFinite(eastDeg) ? eastDeg : 0) * Math.PI) / 180;
+  const along = Math.abs(Math.cos(n));
+  const across = Math.cos(e) ** 2;
+  if (!(along > 1e-6) || !(across > 1e-6)) return 1;
+  return Math.max(1, 1 / (along * across));
+}
+
+/**
+ * Tilt a nadir orientation off nadir: first toward north (a rotation about
+ * the nadir frame's right axis), then toward east (about the tilted up
+ * axis). The base frame is always the nadir one, so a tilt never drifts with
+ * the orbit; the angle from nadir is acos(cos north · cos east).
+ * @param {{direction: object, up: object, right: object}} nadir From
+ *   {@link nadirOrientation}.
+ * @param {{northDeg?: number, eastDeg?: number}} [offset] Tilt in degrees;
+ *   negative is south or west.
+ * @returns {{direction: object, up: object, right: object}} Unit vectors,
+ *   right = direction × up.
+ */
+export function offNadirOrientation(nadir, { northDeg = 0, eastDeg = 0 } = {}) {
+  const n = ((Number.isFinite(northDeg) ? northDeg : 0) * Math.PI) / 180;
+  const e = ((Number.isFinite(eastDeg) ? eastDeg : 0) * Math.PI) / 180;
+  if (n === 0 && e === 0) return nadir;
+  const { direction: d, up: u, right: r } = nadir;
+  const combine = (a, ka, b, kb) => ({
+    x: a.x * ka + b.x * kb,
+    y: a.y * ka + b.y * kb,
+    z: a.z * ka + b.z * kb,
+  });
+  // Toward north: the view swings onto the up axis, up swings off it.
+  const d1 = combine(d, Math.cos(n), u, Math.sin(n));
+  const u1 = combine(u, Math.cos(n), d, -Math.sin(n));
+  // Toward east: the view swings onto the right axis.
+  const direction = combine(d1, Math.cos(e), r, Math.sin(e));
+  return { direction, up: u1, right: cross(direction, u1) };
+}
+
+/** Scroll distance, in pixels, that makes one zoom step. A mouse notch is ~100. */
+export const ORBITAL_WHEEL_PIXELS_PER_STEP = 100;
+
+/**
+ * After a step, the rest of that gesture is absorbed for this long, so one
+ * physical notch (which some browsers deliver as several events) is one step.
+ */
+export const ORBITAL_WHEEL_COOLDOWN_MS = 200;
+
+/**
+ * A pause this long ends a scroll gesture: a partial sum left from an earlier
+ * gesture never adds to a later one.
+ */
+export const ORBITAL_WHEEL_GESTURE_GAP_MS = 300;
+
+/** `WheelEvent.deltaMode` line and page units, in pixels. */
+const WHEEL_LINE_PX = 16;
+const WHEEL_PAGE_PX = 800;
+
+/**
+ * Turn wheel events into zoom steps. Trackpads send many small pixel deltas,
+ * so they are summed until they reach a step; a change of direction, or a
+ * pause of ORBITAL_WHEEL_GESTURE_GAP_MS, starts over. Wheeling away from the
+ * viewer (negative deltaY) zooms in.
+ * @param {{sum: number, lastStepMs: number, lastEventMs?: number}|null}
+ *   accumulator Previous state.
+ * @param {{deltaY: number, deltaMode?: number}} wheel The event's deltas.
+ * @param {number} nowMs
+ * @returns {{accumulator: {sum: number, lastStepMs: number,
+ *   lastEventMs: number}, step: -1|0|1}} The new state and the step to take
+ *   (1 = zoom in).
+ */
+export function wheelZoomStep(accumulator, wheel, nowMs) {
+  const held = accumulator || { sum: 0, lastStepMs: -Infinity };
+  const previous =
+    nowMs - (held.lastEventMs ?? -Infinity) > ORBITAL_WHEEL_GESTURE_GAP_MS
+      ? { ...held, sum: 0 }
+      : held;
+  const unit =
+    wheel?.deltaMode === 1
+      ? WHEEL_LINE_PX
+      : wheel?.deltaMode === 2
+        ? WHEEL_PAGE_PX
+        : 1;
+  const delta = (Number.isFinite(wheel?.deltaY) ? wheel.deltaY : 0) * unit;
+  if (!delta) return { accumulator: held, step: 0 };
+  if (nowMs - previous.lastStepMs < ORBITAL_WHEEL_COOLDOWN_MS)
+    return {
+      accumulator: { ...previous, sum: 0, lastEventMs: nowMs },
+      step: 0,
+    };
+  const sum =
+    Math.sign(previous.sum) === -Math.sign(delta)
+      ? delta
+      : previous.sum + delta;
+  if (Math.abs(sum) < ORBITAL_WHEEL_PIXELS_PER_STEP)
+    return { accumulator: { ...previous, sum, lastEventMs: nowMs }, step: 0 };
+  return {
+    accumulator: { sum: 0, lastStepMs: nowMs, lastEventMs: nowMs },
+    step: sum < 0 ? 1 : -1,
+  };
+}
+
+/** From this zoom the view pre-loads imagery ahead along the ground track. */
+export const ORBITAL_PREFETCH_MIN_ZOOM = 16;
+
+/** How often the pre-load looks ahead, ms. */
+export const ORBITAL_PREFETCH_INTERVAL_MS = 2000;
+
+/** How far ahead it looks, seconds of ground-track travel, nearest first. */
+export const ORBITAL_PREFETCH_LEAD_S = Object.freeze([5, 10, 15, 20]);
+
+/**
+ * Where across the track it looks, as fractions of the view's width: the
+ * centre line, a third out and the frame's edges each side, so a row of
+ * tiles a fifth of the view wide or more spans the frame.
+ */
+export const ORBITAL_PREFETCH_ACROSS = Object.freeze([
+  0,
+  -1 / 3,
+  1 / 3,
+  -1 / 2,
+  1 / 2,
+]);
+
+/**
+ * The points ahead, regrouped by their place across the track: every lead's
+ * centre point first, then each lead's next pair out, so the tile cap trims
+ * the frame's edges before it trims the far leads.
+ * @param {Array<{lat: number, lon: number}>} points From `groundTrackAhead`,
+ *   lead by lead.
+ * @param {number} [across] Points per lead.
+ * @returns {Array<{lat: number, lon: number}>}
+ */
+export function centreLinesFirst(
+  points,
+  across = ORBITAL_PREFETCH_ACROSS.length,
+) {
+  const out = [];
+  for (let k = 0; k < across; k += 1)
+    for (let i = k; i < points.length; i += across) out.push(points[i]);
+  return out;
+}
+
+/** At most this many tile requests per look-ahead. */
+export const ORBITAL_PREFETCH_MAX_TILES = 12;
+
+const toRadians = (deg) => (deg * Math.PI) / 180;
+const toDegrees = (rad) => (rad * 180) / Math.PI;
+
+/**
+ * The point `distanceM` from a point along an initial bearing, on a sphere.
+ * @returns {{lat: number, lon: number}} Degrees, longitude in -180..180.
+ */
+export function destinationPoint(latDeg, lonDeg, bearingDeg, distanceM) {
+  const delta = distanceM / ORBITAL_EARTH_RADIUS_M;
+  const lat1 = toRadians(latDeg);
+  const theta = toRadians(bearingDeg);
+  const lat2 = Math.asin(
+    Math.sin(lat1) * Math.cos(delta) +
+      Math.cos(lat1) * Math.sin(delta) * Math.cos(theta),
+  );
+  const lon2 =
+    toRadians(lonDeg) +
+    Math.atan2(
+      Math.sin(theta) * Math.sin(delta) * Math.cos(lat1),
+      Math.cos(delta) - Math.sin(lat1) * Math.sin(lat2),
+    );
+  const lon = ((((toDegrees(lon2) + 180) % 360) + 360) % 360) - 180;
+  return { lat: toDegrees(lat2), lon };
+}
+
+/**
+ * Points the view will pass over: for each lead time, the sub-satellite
+ * point that far along the ground track (orbital speed scaled down to the
+ * ground), and points across the track at `across` fractions of the view's
+ * width. Nearest lead first. Empty without a track, speed or width.
+ * @param {{latitude: number, longitude: number, groundTrackDeg: number,
+ *   velocityMps: number, altitudeM: number}} info Satellite subject.
+ * @param {number} viewKm The view's ground width, km.
+ * @returns {Array<{lat: number, lon: number}>}
+ */
+export function groundTrackAhead(
+  info,
+  viewKm,
+  { leadS = ORBITAL_PREFETCH_LEAD_S, across = ORBITAL_PREFETCH_ACROSS } = {},
+) {
+  const { latitude, longitude, groundTrackDeg, velocityMps, altitudeM } =
+    info || {};
+  if (
+    ![latitude, longitude, groundTrackDeg, velocityMps, altitudeM].every(
+      Number.isFinite,
+    ) ||
+    velocityMps <= 0 ||
+    altitudeM <= 0 ||
+    !(viewKm > 0)
+  )
+    return [];
+  const R = ORBITAL_EARTH_RADIUS_M;
+  const groundMps = (velocityMps * R) / (R + altitudeM);
+  const points = [];
+  for (const seconds of leadS) {
+    const centre = destinationPoint(
+      latitude,
+      longitude,
+      groundTrackDeg,
+      groundMps * seconds,
+    );
+    for (const fraction of across) {
+      points.push(
+        fraction === 0
+          ? centre
+          : destinationPoint(
+              centre.lat,
+              centre.lon,
+              groundTrackDeg + (fraction > 0 ? 90 : -90),
+              Math.abs(fraction) * viewKm * 1000,
+            ),
+      );
+    }
+  }
+  return points;
+}
+
+/** WGS84's equatorial radius: Cesium sizes terrain and imagery tiles on it. */
+const WGS84_MAXIMUM_RADIUS_M = 6378137;
+
+/**
+ * Cesium's geometric error for a heightmap terrain tile at `level`, metres:
+ * its level-zero estimate (TerrainProvider's
+ * getEstimatedLevelZeroGeometricErrorForAHeightmap, heightmap quality 0.25)
+ * for the ellipsoid terrain's 64-sample tiles on two root tiles, halved per
+ * level.
+ * @param {number} level
+ * @returns {number}
+ */
+export function ellipsoidTerrainLevelErrorM(level) {
+  return (WGS84_MAXIMUM_RADIUS_M * 2 * Math.PI * 0.25) / (64 * 2) / 2 ** level;
+}
+
+/** The deepest terrain level considered. */
+const MAX_TERRAIN_LEVEL = 30;
+
+/**
+ * The imagery level Cesium draws under the view, and so the one to pre-load.
+ * Cesium refines the terrain tile under the view while its geometric error
+ * spans more than `maximumScreenSpaceError` pixels (QuadtreePrimitive's
+ * screenSpaceError: error over the ground a pixel covers), then drapes the
+ * imagery level whose texel spacing is nearest that error (ImageryLayer's
+ * getLevelWithMaximumTexelSpacing, rounded): about one to two screen pixels
+ * per texel, not one. Fog, which below 800 km can only coarsen the choice,
+ * is left out. Clamped to the provider's levels; null without a usable input.
+ * @param {{getNumberOfXTilesAtLevel?: (level: number) => number,
+ *   rectangle?: {width: number}}} tilingScheme The imagery tiling scheme.
+ * @param {{metresPerPixel: number, latitudeDeg: number,
+ *   geographic?: boolean, tileWidthPx?: number, minimumLevel?: number,
+ *   maximumLevel?: number, maximumScreenSpaceError?: number,
+ *   terrainLevelErrorM?: (level: number) => number}} view `metresPerPixel`
+ *   is the ground one CSS pixel covers at the view's centre; `geographic`
+ *   marks a scheme in the geographic projection, whose texels do not narrow
+ *   with latitude as Web Mercator's do; `terrainLevelErrorM` is the terrain
+ *   provider's getLevelMaximumGeometricError.
+ * @returns {number|null}
+ */
+export function imageryLevelForView(
+  tilingScheme,
+  {
+    metresPerPixel,
+    latitudeDeg,
+    geographic = false,
+    tileWidthPx = 256,
+    minimumLevel = 0,
+    maximumLevel = 30,
+    maximumScreenSpaceError = 2,
+    terrainLevelErrorM = ellipsoidTerrainLevelErrorM,
+  },
+) {
+  if (!(metresPerPixel > 0) || !Number.isFinite(latitudeDeg)) return null;
+  const sse = maximumScreenSpaceError > 0 ? maximumScreenSpaceError : 2;
+  let terrainLevel = 0;
+  while (
+    terrainLevel < MAX_TERRAIN_LEVEL &&
+    !(terrainLevelErrorM(terrainLevel) / metresPerPixel <= sse)
+  )
+    terrainLevel += 1;
+  const errorM = terrainLevelErrorM(terrainLevel);
+  if (!(errorM > 0)) return null;
+  const rootTiles = tilingScheme?.getNumberOfXTilesAtLevel?.(0) || 1;
+  const widthRad = tilingScheme?.rectangle?.width || 2 * Math.PI;
+  const latitudeFactor = geographic
+    ? 1
+    : Math.cos(toRadians(Math.min(89, Math.abs(latitudeDeg))));
+  const levelZeroTexelM =
+    (WGS84_MAXIMUM_RADIUS_M * widthRad * latitudeFactor) /
+    ((tileWidthPx || 256) * rootTiles);
+  const level = Math.max(0, Math.round(Math.log2(levelZeroTexelM / errorM)));
+  if (!Number.isFinite(level)) return null;
+  const top = Number.isFinite(maximumLevel) ? maximumLevel : 30;
+  const bottom = Number.isFinite(minimumLevel) ? minimumLevel : 0;
+  return Math.min(top, Math.max(bottom, level));
+}
+
+/**
+ * The tiles at `level` holding `points`, in order, without repeats or tiles
+ * `skip` reports as already asked for, at most `maxTiles`.
+ * @param {{positionToTileXY: Function}} tilingScheme Cesium tiling scheme.
+ * @param {Array<{lat: number, lon: number}>} points Degrees.
+ * @param {number} level
+ * @param {{maxTiles?: number, skip?: (key: string) => boolean}} [options]
+ * @returns {Array<{x: number, y: number, level: number, key: string}>}
+ */
+export function tilesForPoints(
+  tilingScheme,
+  points,
+  level,
+  { maxTiles = ORBITAL_PREFETCH_MAX_TILES, skip = () => false } = {},
+) {
+  const tiles = [];
+  if (typeof tilingScheme?.positionToTileXY !== 'function') return tiles;
+  if (!Number.isInteger(level) || level < 0) return tiles;
+  const seen = new Set();
+  for (const point of points) {
+    if (tiles.length >= maxTiles) break;
+    const xy = tilingScheme.positionToTileXY(
+      { longitude: toRadians(point.lon), latitude: toRadians(point.lat) },
+      level,
+    );
+    if (!xy) continue;
+    const key = `${level}/${xy.x}/${xy.y}`;
+    if (seen.has(key) || skip(key)) continue;
+    seen.add(key);
+    tiles.push({ x: xy.x, y: xy.y, level, key });
+  }
+  return tiles;
+}

src/cockpitOrbital.test.mjs

@@ -0,0 +1,618 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import {
+  ORBITAL_ZOOM_LADDER,
+  ORBITAL_BASE_FOV_LEO_RAD,
+  ORBITAL_EARTH_RADIUS_M,
+  ORBITAL_SETTLE_MAX_MS,
+  ORBITAL_WHEEL_COOLDOWN_MS,
+  cesiumFrustumFovRad,
+  earthAngularRadiusRad,
+  footprintWidthKm,
+  fovForZoom,
+  interpolateZoomFov,
+  nadirOrientation,
+  nextOrbitalZoom,
+  offNadirAngleDeg,
+  offNadirCentreMeetsEarth,
+  centreLinesFirst,
+  offNadirSwathScale,
+  orbitalMaxZoom,
+  sensorStripFraction,
+  sensorSwathZoom,
+  viewWidthKm,
+  wheelZoomStep,
+  ORBITAL_WHEEL_GESTURE_GAP_MS,
+  offNadirOrientation,
+  orbitalBaseFovRad,
+  previousOrbitalZoom,
+  zoomSettleHolding,
+  zoomTransitionBlurPx,
+  zoomTransitionProgress,
+  zoomTransitionState,
+  ORBITAL_PREFETCH_ACROSS,
+  ORBITAL_PREFETCH_LEAD_S,
+  ORBITAL_PREFETCH_MAX_TILES,
+  destinationPoint,
+  groundTrackAhead,
+  imageryLevelForView,
+  tilesForPoints,
+} from './cockpitOrbital.js';
+import * as Cesium from 'cesium';
+import { greatCircleKm } from './geoDistance.js';
+
+const RAD = Math.PI / 180;
+const dot = (a, b) => a.x * b.x + a.y * b.y + a.z * b.z;
+const norm = (v) => Math.hypot(v.x, v.y, v.z);
+
+/** ECEF position on the mean sphere at a latitude, longitude and altitude. */
+function ecef(latDeg, lonDeg, altitudeM) {
+  const r = ORBITAL_EARTH_RADIUS_M + altitudeM;
+  const lat = latDeg * RAD;
+  const lon = lonDeg * RAD;
+  return {
+    x: r * Math.cos(lat) * Math.cos(lon),
+    y: r * Math.cos(lat) * Math.sin(lon),
+    z: r * Math.sin(lat),
+  };
+}
+
+/** Local north unit vector at a latitude and longitude. */
+function localNorth(latDeg, lonDeg) {
+  const lat = latDeg * RAD;
+  const lon = lonDeg * RAD;
+  return {
+    x: -Math.sin(lat) * Math.cos(lon),
+    y: -Math.sin(lat) * Math.sin(lon),
+    z: Math.cos(lat),
+  };
+}
+
+function assertOrthonormal(orientation) {
+  const { direction, up, right } = orientation;
+  for (const v of [direction, up, right])
+    assert.ok(Math.abs(norm(v) - 1) < 1e-9);
+  assert.ok(Math.abs(dot(direction, up)) < 1e-9);
+  assert.ok(Math.abs(dot(direction, right)) < 1e-9);
+  assert.ok(Math.abs(dot(up, right)) < 1e-9);
+}
+
+test('the nadir view points at the Earth centre with north up', () => {
+  for (const [lat, lon, alt] of [
+    [0, 0, 420e3],
+    [51.6, -97.3, 420e3],
+    [-33.9, 151.2, 20.2e6],
+    [0.05, 75, 35.786e6],
+  ]) {
+    const position = ecef(lat, lon, alt);
+    const orientation = nadirOrientation(position);
+    const toCentre = {
+      x: -position.x / norm(position),
+      y: -position.y / norm(position),
+      z: -position.z / norm(position),
+    };
+    assert.ok(dot(orientation.direction, toCentre) > 1 - 1e-12);
+    assert.ok(dot(orientation.up, localNorth(lat, lon)) > 1 - 1e-9);
+    assertOrthonormal(orientation);
+    // North up puts east on the right of a picture looking down.
+    const east = { x: -Math.sin(lon * RAD), y: Math.cos(lon * RAD), z: 0 };
+    assert.ok(dot(orientation.right, east) > 1 - 1e-9);
+  }
+});
+
+test('over a pole the orientation stays valid and keeps the previous up', () => {
+  for (const z of [1, -1]) {
+    const position = { x: 0, y: 0, z: z * (ORBITAL_EARTH_RADIUS_M + 800e3) };
+    const fallback = nadirOrientation(position);
+    assertOrthonormal(fallback);
+    assert.equal(fallback.direction.z, -z);
+    // The prime-meridian limit of north.
+    assert.ok(Math.abs(fallback.up.x - -z) < 1e-9);
+    const kept = nadirOrientation(position, {
+      previousUp: { x: 0, y: 1, z: 0 },
+    });
+    assertOrthonormal(kept);
+    assert.ok(kept.up.y > 1 - 1e-9);
+  }
+  // Just off the pole, north still points over it.
+  const nearPole = nadirOrientation(ecef(89.9999, 30, 500e3));
+  assertOrthonormal(nearPole);
+  assert.ok(dot(nearPole.up, localNorth(89.9999, 30)) > 1 - 1e-6);
+});
+
+test('a degenerate position has no orientation', () => {
+  assert.equal(nadirOrientation(null), null);
+  assert.equal(nadirOrientation({ x: 0, y: 0, z: 0 }), null);
+  assert.equal(nadirOrientation({ x: NaN, y: 0, z: 0 }), null);
+});
+
+test('each zoom step divides the tangent of the half-angle', () => {
+  const base = ORBITAL_BASE_FOV_LEO_RAD;
+  for (const zoom of ORBITAL_ZOOM_LADDER) {
+    const fov = fovForZoom(base, zoom);
+    assert.ok(Math.abs(Math.tan(fov / 2) - Math.tan(base / 2) / zoom) < 1e-12);
+  }
+  assert.ok(
+    Math.abs(
+      Math.tan(fovForZoom(base, 4) / 2) / Math.tan(fovForZoom(base, 2) / 2) -
+        0.5,
+    ) < 1e-12,
+  );
+  assert.equal(fovForZoom(base, 1), base);
+  assert.equal(fovForZoom(base, 0), base);
+});
+
+test('zoom steps clamp at both ends without wrapping', () => {
+  assert.equal(nextOrbitalZoom(1), 2);
+  assert.equal(nextOrbitalZoom(4), 8);
+  assert.equal(nextOrbitalZoom(8), 8);
+  assert.equal(previousOrbitalZoom(8), 4);
+  assert.equal(previousOrbitalZoom(2), 1);
+  assert.equal(previousOrbitalZoom(1), 1);
+  assert.equal(nextOrbitalZoom(undefined), 2);
+});
+
+test('the base frame is regional in low orbit and fits the disk from GEO', () => {
+  assert.equal(orbitalBaseFovRad(420e3), ORBITAL_BASE_FOV_LEO_RAD);
+  const geo = orbitalBaseFovRad(35.786e6);
+  const disk = 2 * earthAngularRadiusRad(35.786e6);
+  assert.ok(geo > disk && geo < ORBITAL_BASE_FOV_LEO_RAD);
+  // Continuous across the crossover: no jump as an orbit climbs.
+  let previous = orbitalBaseFovRad(1e6);
+  for (let alt = 1e6; alt <= 40e6; alt += 50e3) {
+    const fov = orbitalBaseFovRad(alt);
+    assert.ok(fov <= previous + 1e-12);
+    assert.ok(previous - fov < 0.01);
+    previous = fov;
+  }
+});
+
+test('the footprint shrinks with zoom and stops at the limb', () => {
+  const alt = 420e3;
+  const widths = [1, 2, 4, 8].map((zoom) =>
+    footprintWidthKm(alt, fovForZoom(orbitalBaseFovRad(alt), zoom)),
+  );
+  for (let i = 1; i < widths.length; i++) assert.ok(widths[i] < widths[i - 1]);
+  assert.ok(widths[0] > 400 && widths[0] < 600, `1x ${widths[0]} km`);
+  assert.ok(widths[3] > 40 && widths[3] < 80, `8x ${widths[3]} km`);
+  // A wider frame covers more ground across.
+  assert.ok(
+    footprintWidthKm(alt, ORBITAL_BASE_FOV_LEO_RAD, 16 / 9) > widths[0],
+  );
+  // From GEO a frame wider than the disk spans the visible cap only.
+  const cap =
+    (2 *
+      ORBITAL_EARTH_RADIUS_M *
+      Math.acos(ORBITAL_EARTH_RADIUS_M / (ORBITAL_EARTH_RADIUS_M + 35.786e6))) /
+    1000;
+  assert.ok(Math.abs(footprintWidthKm(35.786e6, 40 * RAD) - cap) < 1e-6);
+  assert.equal(footprintWidthKm(0, 1), null);
+  assert.equal(footprintWidthKm(420e3, NaN), null);
+});
+
+test('Cesium frustum fov widens to the horizontal on a landscape canvas', () => {
+  const vertical = 30 * RAD;
+  assert.equal(cesiumFrustumFovRad(vertical, 0.75), vertical);
+  const horizontal = cesiumFrustumFovRad(vertical, 2);
+  assert.ok(
+    Math.abs(Math.tan(horizontal / 2) - 2 * Math.tan(vertical / 2)) < 1e-12,
+  );
+});
+
+test('zoom transition curves stay bounded and settle', () => {
+  assert.equal(zoomTransitionProgress(0), 0);
+  assert.equal(zoomTransitionProgress(400), 1);
+  assert.equal(zoomTransitionProgress(9999), 1);
+  assert.equal(zoomTransitionProgress(-50), 0);
+  assert.equal(zoomTransitionProgress(0, { reducedMotion: true }), 1);
+  let previous = 0;
+  for (let ms = 0; ms <= 500; ms += 10) {
+    const p = zoomTransitionProgress(ms);
+    assert.ok(p >= previous && p >= 0 && p <= 1);
+    previous = p;
+    const blur = zoomTransitionBlurPx(ms / 400);
+    assert.ok(blur >= 0 && blur <= 6);
+  }
+  assert.equal(zoomTransitionBlurPx(0), 0);
+  assert.ok(zoomTransitionBlurPx(1) < 1e-9);
+  assert.ok(Math.abs(zoomTransitionBlurPx(0.5) - 6) < 1e-9);
+  assert.equal(zoomTransitionBlurPx(0.5, { reducedMotion: true }), 0);
+
+  const from = fovForZoom(1, 1);
+  const to = fovForZoom(1, 2);
+  assert.equal(interpolateZoomFov(from, to, 0).toFixed(12), from.toFixed(12));
+  assert.equal(interpolateZoomFov(from, to, 1).toFixed(12), to.toFixed(12));
+  const mid = interpolateZoomFov(from, to, 0.5);
+  assert.ok(mid < from && mid > to);
+});
+
+test('the transition state blurs, then ticks the lock, then rests', () => {
+  const moving = zoomTransitionState(200);
+  assert.equal(moving.active, true);
+  assert.ok(moving.blurPx > 5);
+  assert.equal(moving.lockTick, false);
+  const settled = zoomTransitionState(450);
+  assert.equal(settled.active, false);
+  assert.equal(settled.lockTick, true);
+  assert.equal(settled.progress, 1);
+  assert.ok(settled.blurPx < 1e-9);
+  const rest = zoomTransitionState(2000);
+  assert.equal(rest.lockTick, false);
+  assert.deepEqual(zoomTransitionState(100, { reducedMotion: true }), {
+    active: false,
+    progress: 1,
+    blurPx: 0,
+    lockTick: false,
+  });
+});
+
+test('an off-nadir tilt turns the view by its angle from the nadir frame', () => {
+  const nadir = nadirOrientation(ecef(30, -97, 420_000));
+  assert.equal(offNadirOrientation(nadir), nadir, 'no tilt is nadir itself');
+  const angle = (v) => Math.acos(Math.min(1, dot(v, nadir.direction))) / RAD;
+  const north = offNadirOrientation(nadir, { northDeg: 10 });
+  assert.ok(Math.abs(angle(north.direction) - 10) < 1e-9);
+  assert.ok(dot(north.direction, nadir.up) > 0, 'toward north');
+  assert.ok(Math.abs(dot(north.direction, nadir.right)) < 1e-12);
+  const west = offNadirOrientation(nadir, { eastDeg: -20 });
+  assert.ok(Math.abs(angle(west.direction) - 20) < 1e-9);
+  assert.ok(dot(west.direction, nadir.right) < 0, 'toward west');
+  const both = offNadirOrientation(nadir, { northDeg: 45, eastDeg: 45 });
+  const expected = Math.acos(Math.cos(45 * RAD) ** 2) / RAD;
+  assert.ok(Math.abs(angle(both.direction) - expected) < 1e-9);
+  for (const view of [north, west, both]) {
+    assert.ok(Math.abs(norm(view.direction) - 1) < 1e-12);
+    assert.ok(Math.abs(norm(view.up) - 1) < 1e-12);
+    assert.ok(Math.abs(dot(view.direction, view.up)) < 1e-12);
+  }
+});
+
+test('a landed zoom step holds for its imagery, but never past the cap', () => {
+  assert.equal(zoomSettleHolding(0, false), true, 'still loading');
+  assert.equal(zoomSettleHolding(ORBITAL_SETTLE_MAX_MS - 1, false), true);
+  assert.equal(zoomSettleHolding(ORBITAL_SETTLE_MAX_MS, false), false, 'cap');
+  assert.equal(zoomSettleHolding(0, true), false, 'loaded: lock at once');
+  assert.equal(zoomSettleHolding(Number.NaN, false), true);
+});
+
+const WIDE = 16 / 9;
+
+test("the zoom ladder climbs to a satellite's own cap and steps off a SENSOR zoom", () => {
+  assert.equal(nextOrbitalZoom(8), 8, 'no sensor: 8x is the top');
+  assert.equal(nextOrbitalZoom(8, 64), 16);
+  assert.equal(nextOrbitalZoom(32, 64), 64);
+  assert.equal(nextOrbitalZoom(64, 64), 64, 'the cap holds');
+  assert.equal(nextOrbitalZoom(5.7, 64), 8, 'between steps: the step above');
+  assert.equal(previousOrbitalZoom(5.7), 4, 'between steps: the step below');
+  assert.equal(previousOrbitalZoom(128), 64);
+  assert.equal(previousOrbitalZoom(1), 1);
+});
+
+test('a sensor caps the zoom at its swath for the live altitude', () => {
+  // WorldView-3 at 617 km, 13.1 km swath: 64x spans ~20 km, 128x ~10 km.
+  assert.ok(viewWidthKm(617e3, 64, WIDE) >= 13.1);
+  assert.ok(viewWidthKm(617e3, 128, WIDE) < 13.1);
+  assert.equal(orbitalMaxZoom(617e3, 13.1, WIDE), 64);
+  // ICEYE spotlight, 5 km at 570 km.
+  assert.equal(orbitalMaxZoom(570e3, 5, WIDE), 128);
+  // PlanetScope SuperDove, 32.5 km: 32x at 525 km but 16x at 470 km.
+  assert.equal(orbitalMaxZoom(525e3, 32.5, WIDE), 32);
+  assert.equal(orbitalMaxZoom(470e3, 32.5, WIDE), 16);
+  // Landsat's 185 km swath fits inside 8x: no extra steps, never fewer.
+  assert.equal(orbitalMaxZoom(705e3, 185, WIDE), 8);
+  assert.equal(orbitalMaxZoom(705e3, 2330, WIDE), 8);
+  // No sensor, or an unusable swath.
+  assert.equal(orbitalMaxZoom(617e3, null, WIDE), 8);
+  assert.equal(orbitalMaxZoom(617e3, 0, WIDE), 8);
+  // A swath exactly as wide as the 16x view allows 16x.
+  assert.equal(orbitalMaxZoom(617e3, viewWidthKm(617e3, 16, WIDE), WIDE), 16);
+});
+
+test('the SENSOR step frames the swath when it lies in range', () => {
+  const landsat = sensorSwathZoom(705e3, 185, WIDE, 8);
+  assert.ok(landsat > 4 && landsat < 8, String(landsat));
+  assert.ok(Math.abs(viewWidthKm(705e3, landsat, WIDE) - 185) < 1);
+  const worldview = sensorSwathZoom(617e3, 13.1, WIDE, 64);
+  assert.equal(worldview, null, 'narrower than the 64x cap allows');
+  assert.equal(sensorSwathZoom(705e3, 2330, WIDE, 8), null, 'wider than 1x');
+  assert.equal(sensorSwathZoom(705e3, null, WIDE, 8), null);
+});
+
+test('the sensor strip spans its share of the view', () => {
+  assert.equal(sensorStripFraction(13, 130), 0.1);
+  assert.equal(sensorStripFraction(500, 131), 1, 'clipped to the view');
+  assert.equal(sensorStripFraction(null, 131), null);
+  assert.equal(sensorStripFraction(13.1, null), null);
+});
+
+test('the wheel steps once per notch and sums a trackpad swipe', () => {
+  // A mouse notch away from the viewer zooms in.
+  let r = wheelZoomStep(null, { deltaY: -100, deltaMode: 0 }, 1000);
+  assert.equal(r.step, 1);
+  // The rest of that notch, inside the cooldown, is absorbed.
+  r = wheelZoomStep(r.accumulator, { deltaY: -100, deltaMode: 0 }, 1050);
+  assert.equal(r.step, 0);
+  // A notch toward the viewer after the cooldown zooms out.
+  r = wheelZoomStep(
+    r.accumulator,
+    { deltaY: 120, deltaMode: 0 },
+    1050 + ORBITAL_WHEEL_COOLDOWN_MS + 1,
+  );
+  assert.equal(r.step, -1);
+  // A trackpad's small deltas add up before they step.
+  let pad = null;
+  const steps = [];
+  for (let i = 0; i < 4; i += 1) {
+    const out = wheelZoomStep(
+      pad,
+      { deltaY: -30, deltaMode: 0 },
+      5000 + i * 16,
+    );
+    pad = out.accumulator;
+    steps.push(out.step);
+  }
+  assert.deepEqual(steps, [0, 0, 0, 1]);
+  // Turning back starts the sum over.
+  const turned = wheelZoomStep(
+    { sum: -90, lastStepMs: -Infinity },
+    { deltaY: 30, deltaMode: 0 },
+    9000,
+  );
+  assert.equal(turned.step, 0);
+  assert.equal(turned.accumulator.sum, 30);
+  // Line-mode wheels (Firefox): three lines make a notch.
+  assert.equal(wheelZoomStep(null, { deltaY: -3, deltaMode: 1 }, 0).step, 0);
+  assert.equal(wheelZoomStep(null, { deltaY: -7, deltaMode: 1 }, 0).step, 1);
+  assert.equal(wheelZoomStep(null, { deltaY: 0 }, 0).step, 0);
+});
+
+test('a heading turns the nadir frame, keeping north to fall back on', () => {
+  // Over the equator at 0°E: north is +z, east is +y.
+  const position = { x: ORBITAL_EARTH_RADIUS_M + 500_000, y: 0, z: 0 };
+  const northUp = nadirOrientation(position);
+  const east = nadirOrientation(position, { headingDeg: 90 });
+  const close = (a, b) =>
+    Math.abs(a.x - b.x) < 1e-9 &&
+    Math.abs(a.y - b.y) < 1e-9 &&
+    Math.abs(a.z - b.z) < 1e-9;
+  assert.ok(close(northUp.up, { x: 0, y: 0, z: 1 }));
+  assert.ok(close(east.up, { x: 0, y: 1, z: 0 }), 'east at the top');
+  assert.ok(close(east.north, northUp.up), 'north kept for the next frame');
+  assert.ok(
+    close(nadirOrientation(position, { headingDeg: 0 }).up, northUp.up),
+  );
+});
+
+test('a partial scroll does not carry over into a later gesture', () => {
+  // 90 px: short of a step.
+  let r = wheelZoomStep(null, { deltaY: -90, deltaMode: 0 }, 1000);
+  assert.equal(r.step, 0);
+  // Still the same gesture: 10 px more completes the step.
+  const same = wheelZoomStep(
+    r.accumulator,
+    { deltaY: -10, deltaMode: 0 },
+    1100,
+  );
+  assert.equal(same.step, 1);
+  // Minutes later a 10 px nudge is a new gesture, not the rest of the old.
+  r = wheelZoomStep(
+    r.accumulator,
+    { deltaY: -10, deltaMode: 0 },
+    1000 + ORBITAL_WHEEL_GESTURE_GAP_MS + 60_000,
+  );
+  assert.equal(r.step, 0);
+});
+
+test('the total off-nadir angle combines both tilts', () => {
+  assert.equal(offNadirAngleDeg(), 0);
+  assert.ok(Math.abs(offNadirAngleDeg({ northDeg: 10 }) - 10) < 1e-9);
+  // FWD 15° and RIGHT 10° read OFF-NADIR 18.0°.
+  const total = offNadirAngleDeg({ northDeg: 15, eastDeg: 10 });
+  assert.equal(total.toFixed(1), '18.0');
+  assert.equal(offNadirAngleDeg({ northDeg: -15, eastDeg: -10 }), total);
+});
+
+test("a tilted view's width grows faster across the frame than along it", () => {
+  assert.equal(offNadirSwathScale(), 1, 'nadir');
+  const cos = (deg) => Math.cos((deg * Math.PI) / 180);
+  assert.ok(
+    Math.abs(offNadirSwathScale({ northDeg: 30 }) - 1 / cos(30)) < 1e-9,
+  );
+  assert.ok(
+    Math.abs(offNadirSwathScale({ eastDeg: 30 }) - 1 / cos(30) ** 2) < 1e-9,
+  );
+  let last = 1;
+  for (const deg of [5, 15, 25, 35, 45]) {
+    const scale = offNadirSwathScale({ northDeg: deg, eastDeg: deg });
+    assert.ok(scale > last, `${deg}°`);
+    last = scale;
+  }
+  assert.equal(offNadirSwathScale({ northDeg: Number.NaN }), 1);
+});
+
+// ── imagery pre-load ahead of the ground track ─────────────────────────
+
+const PASS = Object.freeze({
+  latitude: 30,
+  longitude: -97,
+  groundTrackDeg: 45,
+  velocityMps: 7_600,
+  altitudeM: 500_000,
+});
+
+test('destinationPoint walks a great circle along a bearing', () => {
+  const east = destinationPoint(0, 179.9, 90, 111_195 * 0.2);
+  assert.ok(Math.abs(east.lat) < 1e-9);
+  assert.ok(Math.abs(east.lon - -179.9) < 1e-3, 'wraps the antimeridian');
+  const north = destinationPoint(10, 20, 0, 50_000);
+  assert.ok(Math.abs(greatCircleKm({ lat: 10, lon: 20 }, north) - 50) < 0.1);
+  assert.ok(north.lat > 10 && Math.abs(north.lon - 20) < 1e-9);
+});
+
+test('the points ahead run along the ground track at ground speed', () => {
+  const points = groundTrackAhead(PASS, 20);
+  const across = ORBITAL_PREFETCH_ACROSS.length;
+  assert.equal(points.length, ORBITAL_PREFETCH_LEAD_S.length * across);
+  // Ground speed is the orbital speed scaled to the surface: ~7.0 km/s.
+  const groundKmPerS = (7.6 * 6371) / (6371 + 500);
+  const start = { lat: PASS.latitude, lon: PASS.longitude };
+  ORBITAL_PREFETCH_LEAD_S.forEach((seconds, i) => {
+    const centre = points[i * across];
+    const km = greatCircleKm(start, centre);
+    assert.ok(Math.abs(km - groundKmPerS * seconds) < 0.5, `${seconds} s`);
+    // North-east of the start, on a 45° track.
+    assert.ok(centre.lat > PASS.latitude && centre.lon > PASS.longitude);
+    // The side points sit their fraction of the view off the centre line.
+    points.slice(i * across + 1, (i + 1) * across).forEach((side, k) => {
+      const offKm = 20 * Math.abs(ORBITAL_PREFETCH_ACROSS[k + 1]);
+      assert.ok(Math.abs(greatCircleKm(centre, side) - offKm) < 0.05);
+    });
+  });
+  assert.deepEqual(groundTrackAhead({ ...PASS, groundTrackDeg: null }, 20), []);
+  assert.deepEqual(groundTrackAhead(PASS, null), []);
+});
+
+test('the tile level is the one Cesium draws for the view', () => {
+  const mercator = new Cesium.WebMercatorTilingScheme();
+  // Worked case: 10 m per CSS pixel at the equator. Cesium refines the
+  // ellipsoid terrain until a tile's error is at most 2 px, 20 m: level 12,
+  // 78,271.5 m / 2^12 = 19.11 m. The Web Mercator texel nearest that is
+  // level 13's (156,543 m / 2^13 = 19.11 m), about 1.9 px each, where a
+  // one-pixel texel would have asked for level 14.
+  assert.equal(
+    imageryLevelForView(mercator, { metresPerPixel: 10, latitudeDeg: 0 }),
+    13,
+  );
+  // 5 m/px: terrain level 13 (9.55 m), imagery level 14.
+  assert.equal(
+    imageryLevelForView(mercator, { metresPerPixel: 5, latitudeDeg: 0 }),
+    14,
+  );
+  // 7 m/px still takes terrain level 13 (9.55 m <= 14 m): level 14, so a
+  // texel spans 1.4 px.
+  assert.equal(
+    imageryLevelForView(mercator, { metresPerPixel: 7, latitudeDeg: 0 }),
+    14,
+  );
+  // At 60° a Mercator texel covers half the ground: one level coarser.
+  assert.equal(
+    imageryLevelForView(mercator, { metresPerPixel: 10, latitudeDeg: 60 }),
+    12,
+  );
+  // A geographic scheme starts from two root tiles and keeps its texels at
+  // every latitude.
+  const geographic = new Cesium.GeographicTilingScheme();
+  for (const latitudeDeg of [0, 60])
+    assert.equal(
+      imageryLevelForView(geographic, {
+        metresPerPixel: 10,
+        latitudeDeg,
+        geographic: true,
+      }),
+      12,
+      `${latitudeDeg}°`,
+    );
+  // A terrain provider's own errors (Cesium World Terrain: 65-sample tiles)
+  // and a looser screen-space error are honoured.
+  const worldTerrain = (level) =>
+    (6378137 * 2 * Math.PI * 0.25) / (65 * 2) / 2 ** level;
+  assert.equal(
+    imageryLevelForView(mercator, {
+      metresPerPixel: 10,
+      latitudeDeg: 0,
+      terrainLevelErrorM: worldTerrain,
+    }),
+    13,
+  );
+  assert.equal(
+    imageryLevelForView(mercator, {
+      metresPerPixel: 10,
+      latitudeDeg: 0,
+      maximumScreenSpaceError: 4,
+    }),
+    12,
+  );
+  // Clamped to the provider's levels.
+  assert.equal(
+    imageryLevelForView(mercator, {
+      metresPerPixel: 5,
+      latitudeDeg: 0,
+      maximumLevel: 12,
+    }),
+    12,
+  );
+  assert.equal(
+    imageryLevelForView(mercator, { metresPerPixel: 0, latitudeDeg: 0 }),
+    null,
+  );
+});
+
+test('the tiles ahead are the ones the points fall in, bounded and new', () => {
+  const mercator = new Cesium.WebMercatorTilingScheme();
+  const points = groundTrackAhead(PASS, 20);
+  const tiles = tilesForPoints(mercator, points, 13);
+  assert.ok(tiles.length > 0 && tiles.length <= ORBITAL_PREFETCH_MAX_TILES);
+  assert.equal(new Set(tiles.map((tile) => tile.key)).size, tiles.length);
+  // Each tile holds its point: the first is the centre line 5 s ahead.
+  const first = mercator.tileXYToRectangle(tiles[0].x, tiles[0].y, 13);
+  assert.ok(
+    Cesium.Rectangle.contains(
+      first,
+      Cesium.Cartographic.fromDegrees(points[0].lon, points[0].lat),
+    ),
+  );
+  // Ahead along a north-east track: rows north (smaller y), columns east.
+  const here = mercator.positionToTileXY(
+    Cesium.Cartographic.fromDegrees(PASS.longitude, PASS.latitude),
+    13,
+  );
+  assert.ok(tiles.every((tile) => tile.x >= here.x && tile.y <= here.y));
+  // Bounded, and a tile already asked for is skipped.
+  assert.equal(tilesForPoints(mercator, points, 15, { maxTiles: 3 }).length, 3);
+  const asked = new Set(
+    tilesForPoints(mercator, points, 13, { maxTiles: Infinity }).map(
+      (tile) => tile.key,
+    ),
+  );
+  assert.deepEqual(
+    tilesForPoints(mercator, points, 13, { skip: (key) => asked.has(key) }),
+    [],
+  );
+  assert.deepEqual(tilesForPoints({}, points, 13), []);
+});
+
+test('a view tilted past the limb no longer meets the Earth', () => {
+  // GEO: the Earth spans about 8.7 degrees either side of nadir.
+  assert.equal(offNadirCentreMeetsEarth(35_786_000, { northDeg: 5 }), true);
+  assert.equal(offNadirCentreMeetsEarth(35_786_000, { northDeg: 15 }), false);
+  // LEO: a 30 degree tilt still lands on the ground.
+  assert.equal(
+    offNadirCentreMeetsEarth(420_000, { northDeg: 20, eastDeg: 20 }),
+    true,
+  );
+  assert.equal(offNadirCentreMeetsEarth(420_000, { eastDeg: 80 }), false);
+  assert.equal(offNadirCentreMeetsEarth(NaN, {}), false);
+});
+
+test('the centre line of every lead comes before the frame edges', () => {
+  const points = groundTrackAhead(PASS, 20);
+  const across = ORBITAL_PREFETCH_ACROSS.length;
+  const ordered = centreLinesFirst(points);
+  assert.equal(ordered.length, points.length);
+  const leads = ORBITAL_PREFETCH_LEAD_S.length;
+  assert.deepEqual(
+    ordered.slice(0, leads),
+    points.filter((_, i) => i % across === 0),
+  );
+  // The 12-tile cap at a level of small tiles still reaches the far lead.
+  const mercator = new Cesium.WebMercatorTilingScheme();
+  const tiles = tilesForPoints(mercator, ordered, 17);
+  const far = mercator.positionToTileXY(
+    Cesium.Cartographic.fromDegrees(
+      ordered[leads - 1].lon,
+      ordered[leads - 1].lat,
+    ),
+    17,
+  );
+  assert.ok(tiles.some((tile) => tile.x === far.x && tile.y === far.y));
+});

src/cockpitOrbitalFocus.js

@@ -0,0 +1,163 @@
+/**
+ * Ground focus for the orbital view: the look that keeps a point on the
+ * ground at the centre of the picture as the satellite moves, whether that
+ * look is within the off-nadir reach, and which mapped points the view can
+ * show or be turned to. The look is the orbital view's own
+ * `{yawDeg, pitchDeg}` over its nadir frame (see `offNadirOrientation` in
+ * `src/cockpitOrbital.js`), so a focused view is a tilt like any other.
+ * No DOM, Cesium or i18n dependencies: vectors are plain `{x, y, z}` objects
+ * in Earth-fixed (ECEF) metres.
+ */
+import {
+  LOOK_EASE_TAU_MS,
+  ORBITAL_LOOK_LIMIT_DEG,
+  easeLook,
+} from './cockpitLook.js';
+
+/**
+ * How long a focus takes to swing the view onto its target, or back to
+ * nadir when it ends: the look's own easing curve, on a slower clock. Three
+ * of them (about 0.75 s) close 95% of the turn.
+ */
+export const ORBITAL_FOCUS_EASE_TAU_MS = 250;
+
+/** How often the orbital Live Signals rows are rebuilt, ms. */
+export const ORBITAL_REACH_REFRESH_MS = 1000;
+
+/** WGS84 semi-axes squared, m²: the surface normal for the horizon test. */
+const WGS84_A2 = 6378137 ** 2;
+const WGS84_B2 = 6356752.314245179 ** 2;
+
+/** Slack on the reach limit so a target held exactly at 45° stays. */
+const REACH_EPSILON_DEG = 1e-6;
+
+const toDegrees = (rad) => (rad * 180) / Math.PI;
+
+function dot(a, b) {
+  return a.x * b.x + a.y * b.y + a.z * b.z;
+}
+
+function finiteVector(v) {
+  return (
+    Boolean(v) &&
+    Number.isFinite(v.x) &&
+    Number.isFinite(v.y) &&
+    Number.isFinite(v.z)
+  );
+}
+
+/**
+ * The look that centres `target` in the picture, in the nadir frame's tilt
+ * (north first, then east; see `offNadirOrientation`): east is the angle off
+ * the frame's top-bottom plane, north the angle along it. Also the single
+ * angle between nadir and the line of sight, the image's off-nadir angle,
+ * and whether the target faces the satellite (above its horizon).
+ * @param {{direction: object, up: object, right: object}} nadir From
+ *   `nadirOrientation`.
+ * @param {{x: number, y: number, z: number}} satellite ECEF, metres.
+ * @param {{x: number, y: number, z: number}} target ECEF, metres.
+ * @returns {{yawDeg: number, pitchDeg: number, offNadirDeg: number,
+ *   visible: boolean}|null} Null without usable positions.
+ */
+export function focusLook(nadir, satellite, target) {
+  if (!nadir || !finiteVector(satellite) || !finiteVector(target)) return null;
+  const line = {
+    x: target.x - satellite.x,
+    y: target.y - satellite.y,
+    z: target.z - satellite.z,
+  };
+  const range = Math.hypot(line.x, line.y, line.z);
+  if (!(range > 1)) return null;
+  const v = { x: line.x / range, y: line.y / range, z: line.z / range };
+  const along = dot(v, nadir.direction);
+  const up = dot(v, nadir.up);
+  const right = Math.min(1, Math.max(-1, dot(v, nadir.right)));
+  // The target's own zenith, the WGS84 surface normal there: the satellite
+  // is above its horizon when the line from the target to it points up.
+  const normal = {
+    x: target.x / WGS84_A2,
+    y: target.y / WGS84_A2,
+    z: target.z / WGS84_B2,
+  };
+  const visible =
+    Math.hypot(normal.x, normal.y, normal.z) > 0 && -dot(line, normal) > 0;
+  const yawDeg = toDegrees(Math.asin(right));
+  const pitchDeg = toDegrees(Math.atan2(up, along));
+  return {
+    yawDeg: yawDeg === 0 ? 0 : yawDeg,
+    pitchDeg: pitchDeg === 0 ? 0 : pitchDeg,
+    offNadirDeg: toDegrees(Math.acos(Math.min(1, Math.max(-1, along)))),
+    visible,
+  };
+}
+
+/**
+ * Whether a focus look is within the off-nadir reach: the target faces the
+ * satellite and each axis is within the arrows' ±45° clamp.
+ * @param {{yawDeg: number, pitchDeg: number, visible?: boolean}|null} look
+ * @returns {boolean}
+ */
+export function focusInReach(look) {
+  if (!look || look.visible === false) return false;
+  const limit = ORBITAL_LOOK_LIMIT_DEG + REACH_EPSILON_DEG;
+  return (
+    Number.isFinite(look.yawDeg) &&
+    Number.isFinite(look.pitchDeg) &&
+    Math.abs(look.yawDeg) <= limit &&
+    Math.abs(look.pitchDeg) <= limit
+  );
+}
+
+/**
+ * Ease what is left of the turn onto a focus target toward nothing: the
+ * look's easing (`easeLook`) on the focus's slower clock. The view is the
+ * live target's look plus this remainder, so once it lands the view holds
+ * the target exactly, without the lag of chasing it. Reduced motion cuts.
+ * @param {{yawDeg: number, pitchDeg: number}} remainder View minus target.
+ * @param {number} dtMs Milliseconds since the previous frame.
+ * @param {{immediate?: boolean}} [options]
+ * @returns {{yawDeg: number, pitchDeg: number}}
+ */
+export function easeFocusRemainder(
+  remainder,
+  dtMs,
+  { immediate = false } = {},
+) {
+  return easeLook(remainder, { yawDeg: 0, pitchDeg: 0 }, focusEaseDtMs(dtMs), {
+    immediate,
+  });
+}
+
+/**
+ * A frame's time on the focus's clock, for `easeLook`: its fixed time
+ * constant scaled to ORBITAL_FOCUS_EASE_TAU_MS.
+ * @param {number} dtMs
+ * @returns {number}
+ */
+export function focusEaseDtMs(dtMs) {
+  return Number.isFinite(dtMs) && dtMs > 0
+    ? (dtMs * LOOK_EASE_TAU_MS) / ORBITAL_FOCUS_EASE_TAU_MS
+    : 0;
+}
+
+/**
+ * The mapped points the view can be turned to: those facing the satellite
+ * and within the off-nadir reach, nearest to nadir first.
+ * @param {Iterable<{key: string, position: {x: number, y: number,
+ *   z: number}}>} candidates
+ * @param {{nadir: object, satellite: object}} frame
+ * @returns {Array<{key: string, offNadirDeg: number, look: object}>}
+ */
+export function pointsInReach(candidates, { nadir, satellite }) {
+  const entries = [];
+  if (!nadir || !finiteVector(satellite)) return entries;
+  for (const candidate of candidates) {
+    const look = focusLook(nadir, satellite, candidate?.position);
+    if (!focusInReach(look)) continue;
+    entries.push({ key: candidate.key, offNadirDeg: look.offNadirDeg, look });
+  }
+  return entries.sort(
+    (a, b) =>
+      a.offNadirDeg - b.offNadirDeg || String(a.key).localeCompare(b.key),
+  );
+}

src/cockpitOrbitalFocus.test.mjs

@@ -0,0 +1,227 @@
+// src/cockpitOrbitalFocus.test.mjs — the geometry of a ground focus in the
+// orbital view: the look that centres a target, its off-nadir angle, the
+// reach, the easing onto and off a target, and the reach list.
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import * as Cesium from 'cesium';
+import {
+  ORBITAL_FOCUS_EASE_TAU_MS,
+  easeFocusRemainder,
+  focusEaseDtMs,
+  focusInReach,
+  focusLook,
+  pointsInReach,
+} from './cockpitOrbitalFocus.js';
+import {
+  ORBITAL_EARTH_RADIUS_M,
+  nadirOrientation,
+  offNadirAngleDeg,
+  offNadirOrientation,
+} from './cockpitOrbital.js';
+import { LOOK_EASE_TAU_MS } from './cockpitLook.js';
+
+const near = (actual, expected, label, tolerance = 1e-9) =>
+  assert.ok(
+    Math.abs(actual - expected) <= tolerance,
+    `${label}: ${actual} not within ${tolerance} of ${expected}`,
+  );
+
+const unit = (v) => {
+  const n = Math.hypot(v.x, v.y, v.z);
+  return { x: v.x / n, y: v.y / n, z: v.z / n };
+};
+const sub = (a, b) => ({ x: a.x - b.x, y: a.y - b.y, z: a.z - b.z });
+const angleBetweenDeg = (a, b) => {
+  const u = unit(a);
+  const v = unit(b);
+  const cosine = Math.min(1, Math.max(-1, u.x * v.x + u.y * v.y + u.z * v.z));
+  return (Math.acos(cosine) * 180) / Math.PI;
+};
+
+/** A point on a sphere of radius `radiusM`, ECEF. */
+const onSphere = (latDeg, lonDeg, radiusM) => {
+  const lat = (latDeg * Math.PI) / 180;
+  const lon = (lonDeg * Math.PI) / 180;
+  return {
+    x: radiusM * Math.cos(lat) * Math.cos(lon),
+    y: radiusM * Math.cos(lat) * Math.sin(lon),
+    z: radiusM * Math.sin(lat),
+  };
+};
+
+/** A point on the WGS84 ellipsoid, as the globe draws it. */
+const geodeticToEcef = (latDeg, lonDeg, heightM = 0) =>
+  Cesium.Cartesian3.fromDegrees(lonDeg, latDeg, heightM);
+
+const ISS_ALT_M = 420_000;
+const satelliteAt = (latDeg, lonDeg, altitudeM = ISS_ALT_M) =>
+  geodeticToEcef(latDeg, lonDeg, altitudeM);
+
+test('the focus look turns the nadir frame onto the target exactly', () => {
+  const satellite = satelliteAt(30, -97);
+  for (const heading of [null, 0, 51.6, 200]) {
+    const nadir = nadirOrientation(satellite, { headingDeg: heading });
+    for (const [lat, lon] of [
+      [31.5, -96],
+      [28.2, -99.4],
+      [30, -97],
+      [32.9, -97.1],
+    ]) {
+      const target = geodeticToEcef(lat, lon, 300);
+      const look = focusLook(nadir, satellite, target);
+      const view = offNadirOrientation(nadir, {
+        northDeg: look.pitchDeg,
+        eastDeg: look.yawDeg,
+      });
+      near(
+        angleBetweenDeg(view.direction, sub(target, satellite)),
+        0,
+        `centred at ${lat},${lon} heading ${heading}`,
+        1e-5,
+      );
+      // The single angle the readout gives is the tilt's total angle.
+      near(
+        look.offNadirDeg,
+        offNadirAngleDeg({ northDeg: look.pitchDeg, eastDeg: look.yawDeg }),
+        'one off-nadir angle',
+        1e-9,
+      );
+      assert.equal(look.visible, true);
+    }
+  }
+});
+
+test('the off-nadir angle is the angle between nadir and the line of sight', () => {
+  // On a sphere: a target `central` radians from the sub-satellite point is
+  // seen atan(R sin γ / (R + h − R cos γ)) off nadir.
+  const R = ORBITAL_EARTH_RADIUS_M;
+  const satellite = onSphere(10, 20, R + ISS_ALT_M);
+  const nadir = nadirOrientation(satellite);
+  for (const centralDeg of [0, 0.5, 2, 5, 12]) {
+    const target = onSphere(10 + centralDeg, 20, R);
+    const γ = (centralDeg * Math.PI) / 180;
+    const expected =
+      (Math.atan2(R * Math.sin(γ), R + ISS_ALT_M - R * Math.cos(γ)) * 180) /
+      Math.PI;
+    const look = focusLook(nadir, satellite, target);
+    near(look.offNadirDeg, expected, `${centralDeg}° away`, 1e-9);
+  }
+  // Straight below reads zero, a real angle and not a missing one.
+  const below = focusLook(nadir, satellite, onSphere(10, 20, R));
+  near(below.offNadirDeg, 0, 'straight below', 1e-9);
+  near(below.yawDeg, 0, 'no east', 1e-9);
+  near(below.pitchDeg, 0, 'no north', 1e-9);
+  assert.equal(focusInReach(below), true);
+});
+
+test('the reach is the arrows’ ±45° on each axis, facing the satellite', () => {
+  assert.equal(focusInReach({ yawDeg: 45, pitchDeg: -45, visible: true }), true);
+  assert.equal(focusInReach({ yawDeg: 45.01, pitchDeg: 0, visible: true }), false);
+  assert.equal(focusInReach({ yawDeg: 0, pitchDeg: -45.01, visible: true }), false);
+  assert.equal(focusInReach({ yawDeg: 0, pitchDeg: 0, visible: false }), false);
+  assert.equal(focusInReach(null), false);
+  assert.equal(focusInReach({ yawDeg: Number.NaN, pitchDeg: 0 }), false);
+
+  // From geostationary height the far side of the Earth lies within a few
+  // degrees of nadir, but it faces away.
+  const satellite = satelliteAt(0, 0, 35_786_000);
+  const nadir = nadirOrientation(satellite);
+  const farSide = geodeticToEcef(0, 100, 0);
+  const look = focusLook(nadir, satellite, farSide);
+  assert.ok(Math.abs(look.yawDeg) < 45 && Math.abs(look.pitchDeg) < 45);
+  assert.equal(look.visible, false);
+  assert.equal(focusInReach(look), false);
+  // A point near the sub-satellite point faces it.
+  assert.equal(focusInReach(focusLook(nadir, satellite, geodeticToEcef(5, 5))), true);
+});
+
+test('a target slides out of reach as the satellite passes it', () => {
+  const target = geodeticToEcef(0, 10, 0);
+  const inReach = [];
+  for (let lon = 10; lon >= -5; lon -= 1) {
+    const satellite = satelliteAt(0, lon);
+    inReach.push(focusInReach(focusLook(nadirOrientation(satellite), satellite, target)));
+  }
+  assert.equal(inReach[0], true, 'overhead');
+  assert.equal(inReach.at(-1), false, '15° of longitude behind');
+  // Once out, it stays out: the reach ends once, not on and off.
+  const firstOut = inReach.indexOf(false);
+  assert.ok(firstOut > 0);
+  assert.ok(inReach.slice(firstOut).every((value) => value === false));
+});
+
+test('the turn onto a target eases on the slower focus clock and lands', () => {
+  assert.equal(
+    focusEaseDtMs(ORBITAL_FOCUS_EASE_TAU_MS),
+    LOOK_EASE_TAU_MS,
+    'one focus time constant is one look time constant',
+  );
+  assert.equal(focusEaseDtMs(Number.NaN), 0);
+  assert.equal(focusEaseDtMs(-5), 0);
+  let remainder = { yawDeg: -30, pitchDeg: 20 };
+  let previous = Math.hypot(remainder.yawDeg, remainder.pitchDeg);
+  let frames = 0;
+  while ((remainder.yawDeg || remainder.pitchDeg) && frames < 500) {
+    const before = remainder;
+    remainder = easeFocusRemainder(remainder, 16);
+    const size = Math.hypot(remainder.yawDeg, remainder.pitchDeg);
+    assert.ok(size < previous, 'always closer');
+    // No axis moves more than a tenth of the way in a frame, but for the
+    // last few hundredths of a degree it lands on: a turn, not a cut.
+    for (const axis of ['yawDeg', 'pitchDeg']) {
+      const step = Math.abs(before[axis] - remainder[axis]);
+      assert.ok(
+        step <= Math.max(Math.abs(before[axis]) * 0.1, 0.06),
+        `frame ${frames} ${axis}`,
+      );
+    }
+    previous = size;
+    frames += 1;
+  }
+  assert.deepEqual(remainder, { yawDeg: 0, pitchDeg: 0 }, 'lands exactly');
+  // About three time constants close 95%; landing takes a little longer.
+  assert.ok(frames * 16 > 2 * ORBITAL_FOCUS_EASE_TAU_MS, `${frames} frames`);
+  assert.ok(frames * 16 < 12 * ORBITAL_FOCUS_EASE_TAU_MS, `${frames} frames`);
+  assert.deepEqual(
+    easeFocusRemainder({ yawDeg: 10, pitchDeg: -4 }, 16, { immediate: true }),
+    { yawDeg: 0, pitchDeg: 0 },
+    'reduced motion cuts',
+  );
+});
+
+test('the reach list keeps points in reach or in frame, nearest first, bounded', () => {
+  const satellite = satelliteAt(0, 0);
+  const nadir = nadirOrientation(satellite);
+  const candidates = [];
+  // A row of points eastward, 0.1° apart: those up to ~3.7° are within the
+  // 45° tilt, the rest beyond it.
+  for (let i = 0; i < 80; i += 1)
+    candidates.push({ key: `east-${i}`, position: geodeticToEcef(0, i * 0.1) });
+  candidates.push({ key: 'far-side', position: geodeticToEcef(0, 180) });
+  const entries = pointsInReach(candidates, { nadir, satellite });
+  assert.ok(entries.every((entry) => entry.key !== 'far-side'));
+  const angles = entries.map((entry) => entry.offNadirDeg);
+  assert.deepEqual(angles, [...angles].sort((a, b) => a - b), 'nearest first');
+  assert.equal(entries[0].key, 'east-0');
+  assert.equal(entries[0].offNadirDeg, 0);
+  // Only those within the 45° tilt are listed.
+  assert.ok(entries.length > 0 && entries.length < 80);
+  for (const entry of entries) assert.ok(Math.abs(entry.look.yawDeg) <= 45);
+  const beyond = focusLook(nadir, satellite, candidates[entries.length].position);
+  assert.ok(Math.abs(beyond.yawDeg) > 45, 'the next one east is past the reach');
+  assert.deepEqual(pointsInReach([], { nadir, satellite }), []);
+});
+
+test('the horizon is the ground’s own: the WGS84 surface normal, not the centre line', () => {
+  const target = geodeticToEcef(45, 0);
+  const enu = Cesium.Transforms.eastNorthUpToFixedFrame(target);
+  const satelliteAtElevation = (elevationDeg) => {
+    const e = Cesium.Math.toRadians(elevationDeg);
+    const local = new Cesium.Cartesian3(0, -Math.cos(e) * 4e7, Math.sin(e) * 4e7);
+    return Cesium.Matrix4.multiplyByPoint(enu, local, new Cesium.Cartesian3());
+  };
+  const below = satelliteAtElevation(-0.1);
+  assert.equal(focusLook(nadirOrientation(below), below, target).visible, false);
+  const above = satelliteAtElevation(0.1);
+  assert.equal(focusLook(nadirOrientation(above), above, target).visible, true);
+});

src/cockpitOrbitalSatellites.js

@@ -0,0 +1,74 @@
+/**
+ * The camera's hop from the satellite the orbital view rides to another.
+ * No DOM, Cesium or i18n dependencies: vectors are plain `{x, y, z}` objects
+ * in Earth-fixed (ECEF) metres.
+ */
+
+/** The most nearby satellites asked for the orbital rows, nearest first. */
+export const ORBITAL_SATELLITES_MAX = 8;
+
+/** How long the camera takes to hop to another satellite, ms. */
+export const ORBITAL_HOP_MS = 1200;
+
+function finiteVector(v) {
+  return (
+    Boolean(v) &&
+    Number.isFinite(v.x) &&
+    Number.isFinite(v.y) &&
+    Number.isFinite(v.z)
+  );
+}
+
+/**
+ * Where the camera is part-way through a hop: along the great circle
+ * between the two positions (never through the Earth), its distance from the
+ * centre interpolated linearly. The circle is the one through both ends, so
+ * the path moves smoothly as the destination does, however far round it
+ * lies; only exactly opposite ends, which no single circle joins, turn about
+ * a fixed axis square to them.
+ * @param {{x: number, y: number, z: number}} from
+ * @param {{x: number, y: number, z: number}} to
+ * @param {number} progress Eased, 0..1.
+ * @returns {{x: number, y: number, z: number}|null}
+ */
+export function hopPosition(from, to, progress) {
+  if (!finiteVector(from) || !finiteVector(to)) return null;
+  const p = Math.min(1, Math.max(0, Number.isFinite(progress) ? progress : 1));
+  const ra = Math.hypot(from.x, from.y, from.z);
+  const rb = Math.hypot(to.x, to.y, to.z);
+  if (!(ra > 0) || !(rb > 0)) return null;
+  const a = { x: from.x / ra, y: from.y / ra, z: from.z / ra };
+  const b = { x: to.x / rb, y: to.y / rb, z: to.z / rb };
+  const cosine = a.x * b.x + a.y * b.y + a.z * b.z;
+  // The direction the circle leaves `a` in: `b` less its part along `a`.
+  let c = {
+    x: b.x - cosine * a.x,
+    y: b.y - cosine * a.y,
+    z: b.z - cosine * a.z,
+  };
+  let rc = Math.hypot(c.x, c.y, c.z);
+  const r = ra + (rb - ra) * p;
+  const omega = Math.atan2(rc, cosine);
+  if (!(rc > 1e-12)) {
+    if (cosine > 0) return { x: a.x * r, y: a.y * r, z: a.z * r };
+    // Opposite ends: set off square to `a`, northward (or, near a pole,
+    // toward the prime meridian).
+    const pole =
+      Math.abs(a.z) < 0.9 ? { x: 0, y: 0, z: 1 } : { x: 1, y: 0, z: 0 };
+    const along = pole.x * a.x + pole.y * a.y + pole.z * a.z;
+    c = {
+      x: pole.x - along * a.x,
+      y: pole.y - along * a.y,
+      z: pole.z - along * a.z,
+    };
+    rc = Math.hypot(c.x, c.y, c.z);
+  }
+  const angle = p * omega;
+  const cos = Math.cos(angle);
+  const sin = Math.sin(angle) / rc;
+  return {
+    x: (a.x * cos + c.x * sin) * r,
+    y: (a.y * cos + c.y * sin) * r,
+    z: (a.z * cos + c.z * sin) * r,
+  };
+}

src/cockpitOrbitalSatellites.test.mjs

@@ -0,0 +1,73 @@
+// src/cockpitOrbitalSatellites.test.mjs — the camera's hop from one ridden
+// satellite to another.
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import * as Cesium from 'cesium';
+import { hopPosition } from './cockpitOrbitalSatellites.js';
+
+const at = (lat, lon, alt) => Cesium.Cartesian3.fromDegrees(lon, lat, alt);
+
+test('the hop follows the great circle and lands on the satellite', () => {
+  const from = at(0, 0, 400_000);
+  const to = at(0, 90, 800_000);
+  const start = hopPosition(from, to, 0);
+  for (const axis of ['x', 'y', 'z'])
+    assert.ok(Math.abs(start[axis] - from[axis]) < 1e-6, axis);
+  const end = hopPosition(from, to, 1);
+  for (const axis of ['x', 'y', 'z'])
+    assert.ok(Math.abs(end[axis] - to[axis]) < 1e-6, axis);
+  // Half-way it is above the Earth, between the two heights, not on the
+  // chord through it.
+  const mid = hopPosition(from, to, 0.5);
+  const radius = Math.hypot(mid.x, mid.y, mid.z);
+  const ra = Cesium.Cartesian3.magnitude(from);
+  const rb = Cesium.Cartesian3.magnitude(to);
+  assert.ok(Math.abs(radius - (ra + rb) / 2) < 1e-6);
+  assert.ok(Math.abs(Math.atan2(mid.y, mid.x) - Math.PI / 4) < 1e-9);
+  assert.equal(hopPosition(null, to, 0.5), null);
+});
+
+test('a hop to the opposite side goes round the Earth, not through it', () => {
+  const from = at(0, 0, 400_000);
+  const to = at(0, 180, 400_000);
+  const radius = Cesium.Cartesian3.magnitude(from);
+  for (const p of [0.25, 0.5, 0.75]) {
+    const point = hopPosition(from, to, p);
+    assert.ok(
+      Math.abs(Math.hypot(point.x, point.y, point.z) - radius) < 1e-3,
+      `p=${p}`,
+    );
+  }
+  const end = hopPosition(from, to, 1);
+  for (const axis of ['x', 'y', 'z'])
+    assert.ok(Math.abs(end[axis] - to[axis]) < 1e-3, axis);
+});
+
+test('a hop to nearly the opposite side moves smoothly as the destination does', () => {
+  const r = 6_778_137;
+  const from = { x: r, y: 0, z: 0 };
+  const near = (delta) => ({
+    x: -r * Math.cos(delta),
+    y: r * Math.sin(delta),
+    z: 0,
+  });
+  const mid = (delta) => hopPosition(from, near(delta), 0.5);
+  const [a, b] = [mid(0.999e-6), mid(1.001e-6)];
+  assert.ok(
+    Math.hypot(a.x - b.x, a.y - b.y, a.z - b.z) < 1,
+    'no jump between neighbours',
+  );
+  for (const delta of [1e-3, 1e-6, 1e-9]) {
+    const to = near(delta);
+    const end = hopPosition(from, to, 1);
+    assert.ok(
+      Math.hypot(end.x - to.x, end.y - to.y, end.z - to.z) < 1e-3,
+      `lands at ${delta}`,
+    );
+    const half = mid(delta);
+    assert.ok(
+      Math.abs(Math.hypot(half.x, half.y, half.z) - r) < 1e-3,
+      `round at ${delta}`,
+    );
+  }
+});

src/cockpitRadar.js

@@ -0,0 +1,166 @@
+/**
+ * Bridge radar policy: the range steps, the range rings and the heading-up
+ * projection of nearby AIS vessels onto the radar's range circle. Pure: no
+ * DOM, no Cesium and no translated text; the Cockpit words the labels.
+ */
+import {
+  bearingBetweenCoordinates,
+  normalizeHeading,
+  relativeBearing,
+} from './cockpitMath.js';
+import { greatCircleMeters } from './geoDistance.js';
+
+/** Metres in one international nautical mile. */
+export const METRES_PER_NM = 1852;
+
+/** The radar's range steps in nautical miles, shortest first. */
+export const RADAR_RANGES_NM = Object.freeze([3, 6, 12, 24]);
+
+/** The range the radar opens on. */
+export const DEFAULT_RADAR_RANGE_NM = 3;
+
+/** At most this many contacts are drawn, nearest first. */
+export const RADAR_MAX_CONTACTS = 60;
+
+/** Range rings divide the range into this many equal steps. */
+export const RADAR_RING_COUNT = 4;
+
+/**
+ * Normalize a range to one of the radar's steps.
+ * @param {number} rangeNm Requested range in nautical miles.
+ * @returns {number} The range when it is a step, else the default range.
+ */
+export function radarRangeNm(rangeNm) {
+  return RADAR_RANGES_NM.includes(rangeNm) ? rangeNm : DEFAULT_RADAR_RANGE_NM;
+}
+
+/**
+ * The range after this one; the longest range wraps to the shortest.
+ * @param {number} rangeNm Current range in nautical miles.
+ * @returns {number} The next range step.
+ */
+export function nextRadarRange(rangeNm) {
+  const index = RADAR_RANGES_NM.indexOf(radarRangeNm(rangeNm));
+  return RADAR_RANGES_NM[(index + 1) % RADAR_RANGES_NM.length];
+}
+
+/**
+ * Range ring distances at each quarter of the range, innermost first.
+ * @param {number} rangeNm Range in nautical miles.
+ * @returns {number[]} Ring distances in nautical miles; the last is the range.
+ */
+export function radarRingsNm(rangeNm) {
+  const range = radarRangeNm(rangeNm);
+  return Array.from(
+    { length: RADAR_RING_COUNT },
+    (_, index) => (range * (index + 1)) / RADAR_RING_COUNT,
+  );
+}
+
+/**
+ * The search radius for a range, in metres.
+ * @param {number} rangeNm Range in nautical miles.
+ * @returns {number}
+ */
+export function radarRangeM(rangeNm) {
+  return radarRangeNm(rangeNm) * METRES_PER_NM;
+}
+
+const round4 = (value) => Math.round(value * 1e4) / 1e4;
+
+/**
+ * Project vessel contacts onto a heading-up radar.
+ *
+ * Positions are fractions of the range circle: x to the right (starboard),
+ * y up (ahead), both in [-1, 1]. Contacts outside the range, or without a
+ * position, are left out; the rest come nearest first, at most `maxCount`.
+ * @param {{latitude: number, longitude: number, headingDeg: number}} own
+ *   Own ship position and the heading the radar is drawn up from.
+ * @param {Array<{id: string, name?: string, latitude: number,
+ *   longitude: number, course?: number|null, color?: string,
+ *   stale?: boolean}>} contacts Nearby vessels.
+ * @param {{rangeNm?: number, maxCount?: number}} [options]
+ * @returns {Array<{id: string, name: string, x: number, y: number,
+ *   distanceNm: number, relativeBearingDeg: number,
+ *   relativeCourseDeg: number|null, color: string, stale: boolean}>}
+ *   relativeBearingDeg and relativeCourseDeg are clockwise from the bow in
+ *   [-180, 180).
+ */
+export function projectRadarContacts(own, contacts, options = {}) {
+  const rangeNm = radarRangeNm(options.rangeNm ?? DEFAULT_RADAR_RANGE_NM);
+  const cap =
+    Number.isFinite(options.maxCount) && options.maxCount > 0
+      ? Math.floor(options.maxCount)
+      : RADAR_MAX_CONTACTS;
+  const lat = Number(own?.latitude);
+  const lon = Number(own?.longitude);
+  if (
+    !Number.isFinite(lat) ||
+    !Number.isFinite(lon) ||
+    !Array.isArray(contacts)
+  )
+    return [];
+  const heading = normalizeHeading(own.headingDeg ?? 0);
+  const projected = [];
+  for (const contact of contacts) {
+    const toLat = Number(contact?.latitude);
+    const toLon = Number(contact?.longitude);
+    const distanceNm =
+      greatCircleMeters({ lat, lon }, { lat: toLat, lon: toLon }) /
+      METRES_PER_NM;
+    if (!Number.isFinite(distanceNm) || distanceNm > rangeNm) continue;
+    const bearing = bearingBetweenCoordinates(lat, lon, toLat, toLon);
+    const relativeBearingDeg =
+      bearing === null ? 0 : relativeBearing(bearing, heading);
+    const radians = (relativeBearingDeg * Math.PI) / 180;
+    const fraction = distanceNm / rangeNm;
+    const course =
+      contact.course === null || contact.course === undefined
+        ? NaN
+        : Number(contact.course);
+    projected.push({
+      id: String(contact.id),
+      name: String(contact.name || contact.id),
+      x: round4(Math.sin(radians) * fraction),
+      y: round4(Math.cos(radians) * fraction),
+      distanceNm,
+      relativeBearingDeg,
+      relativeCourseDeg: Number.isFinite(course)
+        ? relativeBearing(course, heading)
+        : null,
+      color: contact.color || '',
+      stale: contact.stale === true,
+    });
+  }
+  projected.sort((a, b) => a.distanceNm - b.distanceNm);
+  return projected.slice(0, cap);
+}
+
+/**
+ * The radar presentation without its worded labels.
+ * @param {{latitude: number, longitude: number, headingDeg: number,
+ *   courseDeg?: number|null}} own Own ship; `courseDeg` is course over ground.
+ * @param {Array<object>} contacts See {@link projectRadarContacts}.
+ * @param {number} rangeNm Range in nautical miles.
+ * @returns {{rangeNm: number, ringsNm: number[], headingDeg: number,
+ *   ownRelativeCourseDeg: number|null, contacts: Array<object>}}
+ */
+export function radarPicture(own, contacts, rangeNm) {
+  const range = radarRangeNm(rangeNm);
+  const headingDeg = normalizeHeading(own?.headingDeg ?? 0);
+  const course =
+    own?.courseDeg === null || own?.courseDeg === undefined
+      ? NaN
+      : Number(own.courseDeg);
+  return {
+    rangeNm: range,
+    ringsNm: radarRingsNm(range),
+    headingDeg,
+    ownRelativeCourseDeg: Number.isFinite(course)
+      ? relativeBearing(course, headingDeg)
+      : null,
+    contacts: projectRadarContacts({ ...own, headingDeg }, contacts, {
+      rangeNm: range,
+    }),
+  };
+}

src/cockpitRadar.test.mjs

@@ -0,0 +1,140 @@
+// src/cockpitRadar.test.mjs — the bridge radar's range steps, rings and
+// heading-up contact projection.
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import {
+  DEFAULT_RADAR_RANGE_NM,
+  METRES_PER_NM,
+  RADAR_MAX_CONTACTS,
+  RADAR_RANGES_NM,
+  nextRadarRange,
+  projectRadarContacts,
+  radarPicture,
+  radarRangeM,
+  radarRingsNm,
+} from './cockpitRadar.js';
+
+const OWN = Object.freeze({ latitude: 54.5, longitude: 10.2, headingDeg: 0 });
+/** One nautical mile of latitude, in degrees. */
+const NM_LAT = 1 / 60;
+/** One nautical mile of longitude at 54.5°N, in degrees. */
+const NM_LON = 1 / (60 * Math.cos((54.5 * Math.PI) / 180));
+
+function contact(id, northNm, eastNm, extra = {}) {
+  return {
+    id,
+    name: id,
+    latitude: OWN.latitude + northNm * NM_LAT,
+    longitude: OWN.longitude + eastNm * NM_LON,
+    course: null,
+    color: '#fff',
+    stale: false,
+    ...extra,
+  };
+}
+
+test('the range steps 3, 6, 12, 24 NM, opens on 3 and wraps', () => {
+  assert.deepEqual(RADAR_RANGES_NM, [3, 6, 12, 24]);
+  assert.equal(DEFAULT_RADAR_RANGE_NM, 3);
+  assert.equal(nextRadarRange(3), 6);
+  assert.equal(nextRadarRange(6), 12);
+  assert.equal(nextRadarRange(12), 24);
+  assert.equal(nextRadarRange(24), 3);
+  assert.equal(nextRadarRange(7), 6, 'an unknown range steps from the default');
+  assert.equal(radarRangeM(6), 6 * METRES_PER_NM);
+});
+
+test('range rings sit at each quarter of the range', () => {
+  assert.deepEqual(radarRingsNm(6), [1.5, 3, 4.5, 6]);
+  assert.deepEqual(radarRingsNm(24), [6, 12, 18, 24]);
+});
+
+test('a contact dead ahead is straight up the scope', () => {
+  const [ahead] = projectRadarContacts(OWN, [contact('A', 3, 0)], {
+    rangeNm: 6,
+  });
+  assert.ok(Math.abs(ahead.x) < 0.01, `x ${ahead.x}`);
+  assert.ok(Math.abs(ahead.y - 0.5) < 0.01, `y ${ahead.y}`);
+  assert.ok(Math.abs(ahead.distanceNm - 3) < 0.02);
+  assert.ok(Math.abs(ahead.relativeBearingDeg) < 0.5);
+});
+
+test('heading-up turns the picture with the bow', () => {
+  // Heading east: a contact to the north is on the port beam, one to the
+  // south on the starboard beam, one to the east dead ahead.
+  const own = { ...OWN, headingDeg: 90 };
+  const byId = Object.fromEntries(
+    projectRadarContacts(own, [
+      contact('N', 2, 0),
+      contact('S', -2, 0),
+      contact('E', 0, 2),
+    ]).map((entry) => [entry.id, entry]),
+  );
+  assert.ok(byId.N.x < -0.3 && Math.abs(byId.N.y) < 0.02, 'north is to port');
+  assert.ok(
+    byId.S.x > 0.3 && Math.abs(byId.S.y) < 0.02,
+    'south is to starboard',
+  );
+  assert.ok(Math.abs(byId.E.x) < 0.02 && byId.E.y > 0.3, 'east is ahead');
+  assert.ok(Math.abs(byId.S.relativeBearingDeg - 90) < 1);
+  assert.ok(Math.abs(byId.N.relativeBearingDeg + 90) < 1);
+});
+
+test('a contact to starboard is right of the centre', () => {
+  const [starboard] = projectRadarContacts(OWN, [contact('B', 0, 1.5)]);
+  assert.ok(starboard.x > 0.2, `x ${starboard.x}`);
+  assert.ok(Math.abs(starboard.y) < 0.01);
+});
+
+test('course is drawn relative to the bow and stays null when unknown', () => {
+  const own = { ...OWN, headingDeg: 90 };
+  const [crossing, drifting] = projectRadarContacts(own, [
+    contact('A', 1, 0, { course: 180 }),
+    contact('B', 2, 0, { course: null }),
+  ]);
+  assert.equal(crossing.relativeCourseDeg, 90);
+  assert.equal(drifting.relativeCourseDeg, null);
+});
+
+test('contacts beyond the range are left out', () => {
+  const contacts = projectRadarContacts(
+    OWN,
+    [contact('in', 5.9, 0), contact('out', 6.2, 0), contact('far', 0, 30)],
+    { rangeNm: 6 },
+  );
+  assert.deepEqual(
+    contacts.map((entry) => entry.id),
+    ['in'],
+  );
+  assert.ok(contacts.every((entry) => Math.hypot(entry.x, entry.y) <= 1));
+});
+
+test('contacts come nearest first, capped', () => {
+  const many = Array.from({ length: RADAR_MAX_CONTACTS + 15 }, (_, index) =>
+    contact(`V${index}`, 0, 5.5 - index * 0.07),
+  );
+  const contacts = projectRadarContacts(OWN, many, { rangeNm: 6 });
+  assert.equal(contacts.length, RADAR_MAX_CONTACTS);
+  for (let index = 1; index < contacts.length; index += 1)
+    assert.ok(contacts[index - 1].distanceNm <= contacts[index].distanceNm);
+  assert.equal(
+    projectRadarContacts(OWN, many, { rangeNm: 6, maxCount: 3 }).length,
+    3,
+    'a smaller cap is honoured',
+  );
+});
+
+test('a picture carries the range, rings, heading and own course over ground', () => {
+  const picture = radarPicture(
+    { ...OWN, headingDeg: 350, courseDeg: 10 },
+    [contact('A', 1, 0)],
+    12,
+  );
+  assert.equal(picture.rangeNm, 12);
+  assert.deepEqual(picture.ringsNm, [3, 6, 9, 12]);
+  assert.equal(picture.headingDeg, 350);
+  assert.equal(picture.ownRelativeCourseDeg, 20);
+  assert.equal(picture.contacts.length, 1);
+  assert.ok(picture.contacts[0].x > 0, 'north is to starboard of 350°');
+  assert.equal(radarPicture(OWN, [], 6).ownRelativeCourseDeg, null);
+});

src/cockpitSignalFocus.test.mjs

@@ -147,6 +147,40 @@ const snapshot = (distanceM = 2000) => ({
   ],
 });
 
+test('a feed-off row leads the rebuilt rows and the list stays five long', async (t) => {
+  const f = fixture(t);
+  const crowded = {
+    ...snapshot(),
+    cohorts: [
+      {
+        id: 'flights',
+        count: 6,
+        nearest: [1, 2, 3, 4, 5, 6].map((n) => ({
+          id: `n${n}`,
+          label: `N${n}`,
+          distanceM: n * 1000,
+        })),
+      },
+    ],
+  };
+  updateCockpitSignals.call(f.owner, crowded, 0, {
+    title: 'MILITARY FEED OFF · PARTIAL PICTURE',
+    detail: 'NEARBY AIRCRAFT INCOMPLETE · NOT AN ALL-CLEAR',
+  });
+  await nextTick();
+  assert.equal(f.owner.signalItems.length, 5);
+  assert.equal(f.owner.signalItems[0].key, 'feed-status');
+  assert.equal(f.owner.signalItems[0].tone, 'warning');
+  assert.equal(f.owner.signalItems[0].target, null);
+  assert.match(f.list.textContent, /MILITARY FEED OFF · PARTIAL PICTURE/);
+  updateCockpitSignals.call(f.owner, crowded, 0);
+  assert.equal(
+    f.owner.signalItems.some((item) => item.key === 'feed-status'),
+    false,
+    'with the feed back, the row goes',
+  );
+});
+
 test('rows render the signals the controller presents', async (t) => {
   const f = fixture(t);
   await render(f, [

src/cockpitSubjects.js

@@ -0,0 +1,170 @@
+/**
+ * Camera policy for first-person subjects other than aircraft: where a
+ * vessel's bridge eye sits and how its reported fix advances between feed
+ * refreshes. No DOM or i18n dependencies, so the policy is unit-testable.
+ */
+import { projectGroundArcLatLon } from './data/motionModel.js';
+
+/** Bridge cameras look along the horizon; a ship's eye is already high. */
+export const VESSEL_BRIDGE_PITCH_DEG = -2;
+
+/** The AIS antenna usually sits on the bridge, so the eye is not moved forward. */
+export const VESSEL_BRIDGE_FORWARD_OFFSET_M = 0;
+
+/** Clearance over the shared ground floor for a camera that floats on water. */
+export const VESSEL_BRIDGE_MIN_CLEARANCE_M = 2;
+
+/** Eye height used when the vessel layer knows no height for the type. */
+export const VESSEL_DEFAULT_EYE_HEIGHT_M = 12;
+
+/**
+ * A reported fix older than this stops advancing: the vessel holds where the
+ * last projection left it instead of sailing on through a feed outage.
+ */
+export const VESSEL_DEAD_RECKON_MAX_S = 180;
+
+/**
+ * The vessel layer floats every ship on the geoid (mean sea level), but a
+ * river or lake can sit well above it: the Seine through Paris is ~27 m up,
+ * which put a bridge eye under the water. The bridge reads the rendered
+ * surface around its ship instead: probes on a ring this far out, plus one
+ * at the ship itself.
+ */
+export const VESSEL_WATERLINE_PROBE_RADIUS_M = 30;
+
+/** Probes on the ring around the ship. */
+export const VESSEL_WATERLINE_PROBE_COUNT = 8;
+
+/** How often the bridge reads the water under its ship again, ms. */
+export const VESSEL_WATERLINE_REFRESH_MS = 5000;
+
+/** A surface less than this above sea level is the sea itself, metres. */
+export const VESSEL_WATERLINE_MIN_RISE_M = 2;
+
+/** Highest navigable water trusted from a sample (Lake Titicaca ~3,810 m). */
+export const VESSEL_WATERLINE_MAX_RISE_M = 4000;
+
+/**
+ * Where to read the surface around a ship: the ship's own position, then a
+ * ring of probes around it.
+ * @param {number} latitude
+ * @param {number} longitude
+ * @returns {Array<{lat: number, lon: number}>}
+ */
+export function waterlineProbePoints(
+  latitude,
+  longitude,
+  radiusM = VESSEL_WATERLINE_PROBE_RADIUS_M,
+  count = VESSEL_WATERLINE_PROBE_COUNT,
+) {
+  if (!Number.isFinite(latitude) || !Number.isFinite(longitude)) return [];
+  const points = [{ lat: latitude, lon: longitude }];
+  const metresPerDegLat = 111_320;
+  const metresPerDegLon =
+    metresPerDegLat * Math.max(0.01, Math.cos((latitude * Math.PI) / 180));
+  for (let i = 0; i < count; i += 1) {
+    const bearing = (2 * Math.PI * i) / count;
+    points.push({
+      lat: latitude + (radiusM * Math.cos(bearing)) / metresPerDegLat,
+      lon: longitude + (radiusM * Math.sin(bearing)) / metresPerDegLon,
+    });
+  }
+  return points;
+}
+
+/**
+ * The water surface a bridge floats on, ellipsoidal metres. Quays, bridges,
+ * moored boats and the ship's own model all stand above the water, so the
+ * lowest probe is the water. A lowest probe barely above sea level is the
+ * sea; one implausibly high is a bad sample. Either way the geoid stands.
+ * @param {number} seaSurfaceM The geoid sea surface the layer floats ships on.
+ * @param {Array<number|null|undefined>} sampleHeightsM Rendered-surface probes.
+ * @returns {number}
+ */
+export function vesselWaterlineM(seaSurfaceM, sampleHeightsM) {
+  const heights = (sampleHeightsM || []).filter(Number.isFinite);
+  if (!Number.isFinite(seaSurfaceM) || !heights.length) return seaSurfaceM;
+  const lowest = Math.min(...heights);
+  const rise = lowest - seaSurfaceM;
+  return rise >= VESSEL_WATERLINE_MIN_RISE_M &&
+    rise <= VESSEL_WATERLINE_MAX_RISE_M
+    ? lowest
+    : seaSurfaceM;
+}
+
+/**
+ * Camera placement for a vessel subject, in the shape the Cockpit camera
+ * reads for every subject kind.
+ * @param {{eyeHeightM?: number|null}} info Vessel subject info.
+ * @returns {{forwardM: number, upM: number, pitchDeg: number, minClearanceM: number}}
+ */
+export function vesselCameraProfile(info) {
+  return {
+    forwardM: VESSEL_BRIDGE_FORWARD_OFFSET_M,
+    upM: Number.isFinite(info?.eyeHeightM)
+      ? info.eyeHeightM
+      : VESSEL_DEFAULT_EYE_HEIGHT_M,
+    pitchDeg: VESSEL_BRIDGE_PITCH_DEG,
+    minClearanceM: VESSEL_BRIDGE_MIN_CLEARANCE_M,
+  };
+}
+
+/**
+ * How old a vessel's fix is now, seconds, or null without a fix time.
+ *
+ * The fix time is on the AIS feed's clock and `nowMs` on this client's, so
+ * comparing them directly would turn a client clock running minutes fast
+ * into minutes of age (every bridge projecting its full limit and reading
+ * STALE FEED). With the time this client first received the fix (client
+ * clock) and the newest fix in that refresh (feed clock), the age is the
+ * time since the fix arrived plus how far it trailed that newest fix; each
+ * part is read on one clock. A fix the feed keeps re-serving keeps its first
+ * receipt, so it ages into STALE FEED. The age leaves out the newest fix's
+ * own delay before the refresh, typically seconds: a feed that was already
+ * stalled when the bridge first saw it ages from then. Without them it falls
+ * back to the clock difference, never negative.
+ * @param {{fixEpochMs: number|null, receivedAtMs?: number|null,
+ *   feedEpochMs?: number|null}} fix
+ * @param {number} nowMs Wall-clock time, ms.
+ * @returns {number|null}
+ */
+export function vesselFixAgeSec(fix, nowMs) {
+  const { fixEpochMs, receivedAtMs, feedEpochMs } = fix || {};
+  if (!Number.isFinite(fixEpochMs) || !Number.isFinite(nowMs)) return null;
+  if (Number.isFinite(receivedAtMs) && Number.isFinite(feedEpochMs))
+    return (
+      Math.max(0, (nowMs - receivedAtMs) / 1000) +
+      Math.max(0, (feedEpochMs - fixEpochMs) / 1000)
+    );
+  return Math.max(0, (nowMs - fixEpochMs) / 1000);
+}
+
+/**
+ * Advance a vessel's last reported fix along its course over ground.
+ *
+ * The vessel layer redraws a ship only when the feed refreshes, so its icon
+ * stands still between fixes. A camera converging on that still point would
+ * sail backwards against its own motion. Projecting the fix forward gives the
+ * Cockpit anchor a moving target, and the bounded age keeps a silent feed from
+ * carrying the ship away indefinitely.
+ * @param {{latitude: number, longitude: number, courseDeg: number|null,
+ *   speedMps: number|null, fixEpochMs: number|null,
+ *   receivedAtMs?: number|null, feedEpochMs?: number|null}} fix Last
+ *   report; its age is `vesselFixAgeSec`.
+ * @param {number} nowMs Wall-clock time, ms.
+ * @returns {{latitude: number, longitude: number, ageSec: number|null}}
+ */
+export function deadReckonVesselFix(fix, nowMs) {
+  const { latitude, longitude, courseDeg, speedMps } = fix || {};
+  const ageSec = vesselFixAgeSec(fix, nowMs);
+  if (ageSec === null) return { latitude, longitude, ageSec: null };
+  const { lat, lon } = projectGroundArcLatLon(
+    latitude,
+    longitude,
+    courseDeg,
+    speedMps,
+    0,
+    Math.min(ageSec, VESSEL_DEAD_RECKON_MAX_S),
+  );
+  return { latitude: lat, longitude: lon, ageSec };
+}

src/cockpitSubjects.test.mjs

@@ -0,0 +1,137 @@
+// src/cockpitSubjects.test.mjs — the vessel camera profile and dead
+// reckoning of AIS fixes between feed refreshes.
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import {
+  VESSEL_BRIDGE_MIN_CLEARANCE_M,
+  VESSEL_BRIDGE_PITCH_DEG,
+  VESSEL_DEAD_RECKON_MAX_S,
+  VESSEL_DEFAULT_EYE_HEIGHT_M,
+  VESSEL_WATERLINE_PROBE_RADIUS_M,
+  deadReckonVesselFix,
+  vesselFixAgeSec,
+  vesselCameraProfile,
+  vesselWaterlineM,
+  waterlineProbePoints,
+} from './cockpitSubjects.js';
+
+const EARTH_M_PER_DEG_LAT = 111_195;
+
+test('the vessel camera profile puts the eye at the bridge, looking at the horizon', () => {
+  assert.deepEqual(vesselCameraProfile({ eyeHeightM: 30 }), {
+    forwardM: 0,
+    upM: 30,
+    pitchDeg: VESSEL_BRIDGE_PITCH_DEG,
+    minClearanceM: VESSEL_BRIDGE_MIN_CLEARANCE_M,
+  });
+});
+
+test('a vessel with no known eye height uses the default', () => {
+  for (const info of [{}, { eyeHeightM: null }, null]) {
+    assert.equal(vesselCameraProfile(info).upM, VESSEL_DEFAULT_EYE_HEIGHT_M);
+  }
+});
+
+test('a fix advances along course over ground for its age', () => {
+  const fixEpochMs = 1_000_000;
+  const advanced = deadReckonVesselFix(
+    {
+      latitude: 0,
+      longitude: 0,
+      courseDeg: 0,
+      speedMps: 10,
+      fixEpochMs,
+    },
+    fixEpochMs + 60_000,
+  );
+  assert.equal(advanced.ageSec, 60);
+  // Sixty seconds north at 10 m/s.
+  assert.ok(
+    Math.abs(advanced.latitude * EARTH_M_PER_DEG_LAT - 600) < 2,
+    `expected ~600 m north, got ${advanced.latitude * EARTH_M_PER_DEG_LAT}`,
+  );
+  assert.ok(Math.abs(advanced.longitude) < 1e-9);
+});
+
+test('projection stops at the dead-reckoning limit', () => {
+  const fixEpochMs = 0;
+  const at = (ageSec) =>
+    deadReckonVesselFix(
+      { latitude: 0, longitude: 0, courseDeg: 90, speedMps: 5, fixEpochMs },
+      fixEpochMs + ageSec * 1000,
+    );
+  const limit = at(VESSEL_DEAD_RECKON_MAX_S);
+  const later = at(VESSEL_DEAD_RECKON_MAX_S * 4);
+  assert.equal(later.longitude, limit.longitude);
+  assert.equal(later.ageSec, VESSEL_DEAD_RECKON_MAX_S * 4);
+});
+
+test('a fix without time, course or speed stays where it was reported', () => {
+  const fix = {
+    latitude: 54.3,
+    longitude: 10.1,
+    courseDeg: null,
+    speedMps: 6,
+    fixEpochMs: 0,
+  };
+  assert.deepEqual(deadReckonVesselFix(fix, 30_000), {
+    latitude: 54.3,
+    longitude: 10.1,
+    ageSec: 30,
+  });
+  assert.deepEqual(
+    deadReckonVesselFix({ ...fix, courseDeg: 90, fixEpochMs: null }, 30_000),
+    { latitude: 54.3, longitude: 10.1, ageSec: null },
+  );
+});
+
+test('waterline probes ring the ship at the probe radius', () => {
+  const points = waterlineProbePoints(48.859, 2.293);
+  assert.equal(points.length, 9);
+  assert.deepEqual(points[0], { lat: 48.859, lon: 2.293 });
+  for (const point of points.slice(1)) {
+    const northM = (point.lat - 48.859) * 111_320;
+    const eastM =
+      (point.lon - 2.293) * 111_320 * Math.cos((48.859 * Math.PI) / 180);
+    assert.ok(
+      Math.abs(Math.hypot(northM, eastM) - VESSEL_WATERLINE_PROBE_RADIUS_M) <
+        0.01,
+    );
+  }
+  assert.deepEqual(waterlineProbePoints(Number.NaN, 2), []);
+});
+
+test('the waterline is the lowest probe when it stands clear of the sea', () => {
+  // The Seine at the Eiffel Tower: geoid 44.6 m, water about 71 m.
+  assert.equal(vesselWaterlineM(44.6, [80, 71.2, 75, null, 90]), 71.2);
+  // Swell and tile noise are the sea itself.
+  assert.equal(vesselWaterlineM(44.6, [45.5, 46]), 44.6);
+  // Under the sea surface (a dock, a bad tile) never sinks the ship.
+  assert.equal(vesselWaterlineM(44.6, [30, 71]), 44.6);
+  // Nothing sampled, or implausibly high.
+  assert.equal(vesselWaterlineM(44.6, [undefined, Number.NaN]), 44.6);
+  assert.equal(vesselWaterlineM(44.6, [9000]), 44.6);
+});
+
+test("a fix's age is read on each clock, so a fast client clock adds none", () => {
+  const fixEpochMs = 1_800_000_000_000;
+  // The refresh's newest fix is 10 s newer than this one; the client, its
+  // clock five minutes fast, received the refresh 5 s ago.
+  const receivedAtMs = fixEpochMs + 12_000 + 300_000;
+  const fix = {
+    latitude: 0,
+    longitude: 0,
+    courseDeg: 90,
+    speedMps: 5,
+    fixEpochMs,
+    receivedAtMs,
+    feedEpochMs: fixEpochMs + 10_000,
+  };
+  assert.equal(vesselFixAgeSec(fix, receivedAtMs + 5000), 15);
+  assert.equal(deadReckonVesselFix(fix, receivedAtMs + 5000).ageSec, 15);
+  // Without receive data the clocks are compared, never below zero.
+  const bare = { fixEpochMs };
+  assert.equal(vesselFixAgeSec(bare, fixEpochMs + 60_000), 60);
+  assert.equal(vesselFixAgeSec(bare, fixEpochMs - 60_000), 0);
+  assert.equal(vesselFixAgeSec({ fixEpochMs: null }, fixEpochMs), null);
+});

src/cockpitTracking.js

@@ -65,7 +65,8 @@ export function enterCockpitWithTracking({
         );
       }
     }
-    if (!entryError) entered = Boolean(cockpitView.enter());
+    // This transaction selects aircraft; a selected vessel must not stand in.
+    if (!entryError) entered = Boolean(cockpitView.enter({ kind: 'aircraft' }));
   } catch (error) {
     entryThrew = true;
     entryError = error instanceof Error ? error : new Error(String(error));

src/contextModePolicy.js

@@ -411,30 +411,73 @@ export function contextRestoreLayerIds(snapshot = {}) {
   return restored;
 }
 
+/** The layers an aircraft Cockpit subject can come from. */
+export const COCKPIT_AIRCRAFT_LAYER_IDS = Object.freeze([
+  'flights',
+  'military',
+]);
+
 /**
- * Cockpit entry belongs to the operational Contacts context bundle. A tracked
- * aircraft alone is not sufficient: both observed-flight feeds must still be
- * active so the cockpit's surrounding-contact picture is not presented as a
- * complete context view when one source is disabled.
+ * Cockpit entry needs only the aircraft it rides: that aircraft's own layer
+ * (Live Flights for a civilian, Military Flights for a military aircraft) must
+ * be on. Contacts and the other feeds are not required. When a source the
+ * surrounding picture uses is off, the Cockpit's Contact card and Live
+ * Signals say the picture is partial instead of blocking entry, so a partial
+ * picture is never presented as complete. A Context mode change in flight
+ * still owns the camera, so entry waits it out.
  *
- * @param {object} input Current context and dependency visibility.
- * @param {string|null} input.contextMode Active Context mode.
- * @param {boolean} input.contextModeChanging Whether the Context transaction is unsettled.
- * @param {boolean} input.flightsEnabled Whether Live Flights is enabled.
- * @param {boolean} input.militaryEnabled Whether Military Flights is enabled.
+ * @param {object} input Current subject and Context state.
+ * @param {string|null} input.subjectLayerId Layer of the tracked aircraft
+ *   ('flights' or 'military'), or null with none tracked.
+ * @param {boolean} input.subjectLayerEnabled Whether that layer is enabled.
+ * @param {boolean} input.contextModeChanging Whether a Context transaction is unsettled.
  * @returns {boolean} Whether cockpit entry may be offered or activated.
  */
 export function cockpitEntryAllowed({
-  contextMode,
+  subjectLayerId,
+  subjectLayerEnabled,
   contextModeChanging,
-  flightsEnabled,
-  militaryEnabled,
 }) {
   return (
-    contextMode === 'flights' &&
+    COCKPIT_AIRCRAFT_LAYER_IDS.includes(subjectLayerId) &&
+    Boolean(subjectLayerEnabled) &&
+    !contextModeChanging
+  );
+}
+
+/**
+ * Whether the selected vessel's bridge view can be entered. Like aircraft
+ * Cockpit it needs only its own layer, Live AIS Vessels, with a vessel
+ * selected. A Context mode change in flight still owns the camera, so entry
+ * waits it out.
+ * @param {{vesselsEnabled: boolean, contextModeChanging: boolean}} state
+ * @returns {boolean}
+ */
+export function bridgeEntryAllowed({ vesselsEnabled, contextModeChanging }) {
+  return Boolean(vesselsEnabled) && !contextModeChanging;
+}
+
+/**
+ * Whether the tracked satellite's orbital view can be entered. Like the
+ * bridge it needs only its own layer, Satellites, with a satellite tracked.
+ * A Context mode change in flight still owns the camera, so entry waits it
+ * out. A subject the satellites layer marks as not enterable (debris:
+ * rocket bodies, fragments, dead satellites; `satelliteClassEnterable` in
+ * src/layers/satellites/classes.js) can be tracked but is never ridden: it is
+ * no mission and has no view to offer.
+ * @param {{satellitesEnabled: boolean, contextModeChanging: boolean,
+ *   subjectEnterable?: boolean}} state
+ * @returns {boolean}
+ */
+export function orbitEntryAllowed({
+  satellitesEnabled,
+  contextModeChanging,
+  subjectEnterable = true,
+}) {
+  return (
+    Boolean(satellitesEnabled) &&
     !contextModeChanging &&
-    Boolean(flightsEnabled) &&
-    Boolean(militaryEnabled)
+    subjectEnterable !== false
   );
 }
 

src/contextModePolicy.test.mjs

@@ -1,6 +1,8 @@
 import { test } from 'node:test';
 import assert from 'node:assert/strict';
 import {
+  bridgeEntryAllowed,
+  orbitEntryAllowed,
   cockpitEntryAllowed,
   contextAllowedLayerIds,
   contextLayerEnableBlockReason,
@@ -400,37 +402,56 @@ test('explicit layer intent finishing during restore overrides the stale queued
   }
 });
 
-test('cockpit entry requires Contacts context with both aircraft feeds enabled', () => {
+test("cockpit entry needs only the tracked aircraft's own layer", () => {
   assert.equal(cockpitEntryAllowed({
-    contextMode: 'flights',
+    subjectLayerId: 'flights',
+    subjectLayerEnabled: true,
     contextModeChanging: false,
-    flightsEnabled: true,
-    militaryEnabled: true,
-  }), true);
+  }), true, 'a civilian needs Live Flights alone: no Contacts, no Military');
   assert.equal(cockpitEntryAllowed({
-    contextMode: 'flights',
+    subjectLayerId: 'military',
+    subjectLayerEnabled: true,
+    contextModeChanging: false,
+  }), true, 'a military aircraft needs Military Flights alone');
+  assert.equal(cockpitEntryAllowed({
+    subjectLayerId: 'flights',
+    subjectLayerEnabled: true,
     contextModeChanging: true,
-    flightsEnabled: true,
-    militaryEnabled: true,
-  }), false, 'Cockpit remains unavailable until Contacts activation settles');
+  }), false, 'Cockpit remains unavailable until a Context mode change settles');
   assert.equal(cockpitEntryAllowed({
-    contextMode: null,
+    subjectLayerId: 'military',
+    subjectLayerEnabled: false,
     contextModeChanging: false,
-    flightsEnabled: true,
-    militaryEnabled: true,
-  }), false, 'ordinary layer selection is not an operational Contacts context');
+  }), false, "the ridden aircraft's own layer is required");
   assert.equal(cockpitEntryAllowed({
-    contextMode: 'flights',
+    subjectLayerId: null,
+    subjectLayerEnabled: false,
     contextModeChanging: false,
-    flightsEnabled: true,
-    militaryEnabled: false,
-  }), false, 'the military contact feed is required');
+  }), false, 'there is no aircraft to ride');
   assert.equal(cockpitEntryAllowed({
-    contextMode: 'flights',
+    subjectLayerId: 'ais-live-vessels',
+    subjectLayerEnabled: true,
     contextModeChanging: false,
-    flightsEnabled: false,
-    militaryEnabled: true,
-  }), false, 'the civilian contact feed is required');
+  }), false, "a vessel is the bridge gate's subject, not Cockpit's");
+});
+
+test('bridge entry needs only Live AIS Vessels', () => {
+  assert.equal(bridgeEntryAllowed({ vesselsEnabled: true, contextModeChanging: false }), true);
+  assert.equal(bridgeEntryAllowed({ vesselsEnabled: false, contextModeChanging: false }), false);
+  assert.equal(bridgeEntryAllowed({ vesselsEnabled: true, contextModeChanging: true }), false);
+});
+
+test('orbital entry needs only Satellites', () => {
+  assert.equal(orbitEntryAllowed({ satellitesEnabled: true, contextModeChanging: false }), true);
+  assert.equal(orbitEntryAllowed({ satellitesEnabled: false, contextModeChanging: false }), false);
+  assert.equal(orbitEntryAllowed({ satellitesEnabled: true, contextModeChanging: true }), false);
+});
+
+test('debris can be tracked but never ridden in orbit', () => {
+  const on = { satellitesEnabled: true, contextModeChanging: false };
+  assert.equal(orbitEntryAllowed({ ...on, subjectEnterable: false }), false);
+  assert.equal(orbitEntryAllowed({ ...on, subjectEnterable: true }), true);
+  assert.equal(orbitEntryAllowed(on), true, 'no subject read yet');
 });
 
 test('context teardown guard restores coordination state after success and failure', async () => {

src/creditAttribution.test.mjs

@@ -229,13 +229,30 @@ const GUARDED_PROPS = new Set([
 
 // Custom properties allowed inside a modelled offset. Each is a pinned-tray
 // stack height, proven non-negative below, so evaluating them at 0 is a
-// conservative floor rather than a guess.
+// conservative floor rather than a guess. The world timeline's lift raises
+// the dock, its trays and the credit together, so it moves no gap either.
 const VETTED_VARS = new Set([
   '--dock-pinned-stack-height',
   '--dock-lower-pinned-height',
   '--dock-location-pinned-height',
   '--dock-presets-pinned-height',
+  '--world-timeline-lift',
 ]);
+// Custom properties CSS sets to a fixed length besides their 0 default. The
+// clearance checks run at each length CSS gives them, not only at 0.
+const FIXED_LENGTH_VARS = new Set(['--world-timeline-lift']);
+const LIFTS_PX = [0, 66, 80];
+let liftPx = 0;
+function eachLift(check) {
+  for (const lift of LIFTS_PX) {
+    liftPx = lift;
+    try {
+      check(lift);
+    } finally {
+      liftPx = 0;
+    }
+  }
+}
 
 /** Rules whose final compound targets a modelled element (pseudo-elements aside). */
 function ownBoxEntries() {
@@ -315,6 +332,7 @@ function toPx(value, viewportHeight, where) {
     if (term.startsWith('var(')) {
       const name = term.slice(4, term.lastIndexOf(')')).split(',')[0].trim();
       assert.ok(VETTED_VARS.has(name), `unvetted custom property ${name} in ${where}: "${value}"`);
+      if (name === '--world-timeline-lift') total += liftPx;
       continue; // proven non-negative; 0 is the conservative floor
     }
     assert.match(term, /^-?[\d.]+(px|rem|vh)$/, `unmodelled length term "${term}" in ${where}: "${value}"`);
@@ -444,7 +462,8 @@ test('custom properties inside modelled offsets are provably non-negative', () =
   assert.ok(declared.length >= VETTED_VARS.size, 'every vetted custom property needs a CSS default');
   for (const decl of declared) {
     assert.doesNotMatch(decl.value, /-\s*\d/, `${decl.prop} has a negative CSS default: ${decl.value}`);
-    assert.match(decl.value, /^(0|0px)$/, `${decl.prop} default is not a vetted shape: ${decl.value}`);
+    const shape = FIXED_LENGTH_VARS.has(decl.prop) ? /^(0|\d+px)$/ : /^(0|0px)$/;
+    assert.match(decl.value, shape, `${decl.prop} default is not a vetted shape: ${decl.value}`);
   }
   const layout = fs.readFileSync(new URL('./ui/panelLayoutController.js', import.meta.url), 'utf8');
   const start = layout.indexOf('_updateCommandDockTrayStack() {');
@@ -517,16 +536,18 @@ test('every open dock tray clears the required credit at every modelled viewport
   // number: the dock is anchored at 2vh down to 721px and re-anchors to a flat
   // 8px at 720px, while the credit keeps its 2vh base throughout.
   const failures = [];
-  for (const scenario of TRAY_SCENARIOS) {
-    for (const width of WIDTHS.filter((w) => w <= 900)) {
-      for (const height of HEIGHTS) {
-        const clearance = trayBottomPx(scenario, width, height) - creditTopPx(width, height);
-        if (clearance < MIN_CLEARANCE_PX) {
-          failures.push(`${scenario.name} @ ${width}x${height}: ${clearance.toFixed(1)}px`);
+  eachLift((lift) => {
+    for (const scenario of TRAY_SCENARIOS) {
+      for (const width of WIDTHS.filter((w) => w <= 900)) {
+        for (const height of HEIGHTS) {
+          const clearance = trayBottomPx(scenario, width, height) - creditTopPx(width, height);
+          if (clearance < MIN_CLEARANCE_PX) {
+            failures.push(`${scenario.name} @ ${width}x${height} lift ${lift}: ${clearance.toFixed(1)}px`);
+          }
         }
       }
     }
-  }
+  });
   assert.deepEqual(failures, [], `a dock tray re-enters the credit band:\n  ${failures.join('\n  ')}\n`);
 });
 
@@ -566,21 +587,24 @@ test('the full-width context rail clears the required credit at every modelled v
       'none',
       `at ${width}px the rail is height-capped, so its bottom anchor no longer decides its floor`,
     );
-    for (const height of HEIGHTS) {
-      const rail = resolve(['#right-context-rail'], 'bottom', width, 'context rail');
-      const clearance = toPx(rail.decl.value, height, 'rail bottom') - creditTopPx(width, height);
-      if (clearance < MIN_CLEARANCE_PX) failures.push(`${width}x${height}: ${clearance.toFixed(1)}px`);
-    }
+    eachLift((lift) => {
+      for (const height of HEIGHTS) {
+        const rail = resolve(['#right-context-rail'], 'bottom', width, 'context rail');
+        const clearance = toPx(rail.decl.value, height, 'rail bottom') - creditTopPx(width, height);
+        if (clearance < MIN_CLEARANCE_PX) failures.push(`${width}x${height} lift ${lift}: ${clearance.toFixed(1)}px`);
+      }
+    });
   }
   assert.deepEqual(failures, [], `context rail re-enters the credit band at ${failures.join(', ')}`);
 });
 
 test('the dock anchor changes at 720px — the 2vh cancellation is band-limited', () => {
-  assert.equal(resolve(['#command-dock'], 'bottom', 800, 'dock').decl.value, '2vh');
-  assert.equal(resolve(['#command-dock'], 'bottom', 720, 'dock').decl.value, '8px');
+  const lift = 'var(--world-timeline-lift, 0px)';
+  assert.equal(resolve(['#command-dock'], 'bottom', 800, 'dock').decl.value, `calc(2vh + ${lift})`);
+  assert.equal(resolve(['#command-dock'], 'bottom', 720, 'dock').decl.value, `calc(8px + ${lift})`);
   assert.equal(
     resolve(CREDIT_SELECTORS, 'bottom', 720, 'credit').decl.value,
-    'calc(2vh + 5rem)',
+    `calc(2vh + 5rem + ${lift})`,
     'the credit keeps its 2vh base below 720px — that asymmetry is the whole hazard',
   );
 });

src/data/aisLiveVessels.test.mjs

@@ -989,6 +989,22 @@ test('vessel interaction wire: trail pick does not deselect', () => {
   }
 });
 
+test('vessel interaction wire: a click on open water keeps the ship the bridge rides', () => {
+  const harness = installWireHarness({ id: 'gev-trailing-contact' });
+  try {
+    aisLiveVesselsLayer.setCockpitSubject(harness.record.mmsi);
+    harness.handler.click({ position: { x: 10, y: 20 } });
+    assert.equal(aisLiveVesselsLayer.getSelectedInfo()?.mmsi, harness.record.mmsi);
+    assert.equal(harness.trail.clearCalls, 0);
+    // Released, the same click deselects as it always has.
+    aisLiveVesselsLayer.setCockpitSubject(null);
+    harness.handler.click({ position: { x: 10, y: 20 } });
+    assert.equal(aisLiveVesselsLayer.getSelectedInfo(), null);
+  } finally {
+    harness.cleanup();
+  }
+});
+
 test('vessel interaction wire: only the gev-trail: namespace receives the trail no-op', () => {
   const harness = installWireHarness({ id: 'gev-trailing-contact' });
   try {

src/data/cctv.js

@@ -67,6 +67,8 @@ export const _extractPickedCameraIdForTest =
 export const _setCctvCoverageStateForTest = layer._setCctvCoverageStateForTest;
 export const focusCctvRecord = layer.focusCctvRecord;
 export const maybeAutoHop = layer.maybeAutoHop;
+export const openingCameraId = layer.openingCameraId;
+export const reopenNearestCamera = layer.reopenNearestCamera;
 export const cctvCycleIndex = layer.cctvCycleIndex;
 export {
   CCTV_CALIBRATION_STORAGE_KEY_V1,

src/data/cctv.test.mjs

@@ -61,6 +61,8 @@ import cctvLayer, {
   materializeCctvActiveCoverageEntities,
   materializeCctvVisibleCoverageEntities,
   maybeAutoHop,
+  openingCameraId,
+  reopenNearestCamera,
   prioritizeActiveCctvGeometryRecord,
   processCctvGeometryDrainBatch,
   processCctvGeometryQueueBatch,
@@ -1296,6 +1298,120 @@ test('CCTV null-active coverage, auto-hop, cycling, and panel targets stay hones
   }
 });
 
+test('CCTV opens on the camera nearest the viewer, not the first in the catalog', () => {
+  // QA 2026-11-05: at King's Cross, turning CCTV on showed a Sydney camera,
+  // the first catalog record, instead of the TfL camera 0.3 km away.
+  const viewer = makeDeselectViewer();
+  viewer.camera.positionCartographic = Cesium.Cartographic.fromDegrees(
+    -0.1209,
+    51.5295,
+    187,
+  );
+  viewer.camera.positionWC = Cesium.Cartesian3.fromDegrees(
+    -0.1209,
+    51.5295,
+    187,
+  );
+  const sydney = makeDeselectRecord('au-sydney');
+  sydney.camera = { ...sydney.camera, lat: -34.03, lon: 151.11 };
+  const london = makeDeselectRecord('gb-kings-cross');
+  london.camera = { ...london.camera, lat: 51.5318, lon: -0.1209 };
+  try {
+    _setCctvCoverageStateForTest({
+      viewer,
+      records: [sydney, london],
+      activeCameraId: null,
+      enabled: false,
+    });
+    assert.equal(openingCameraId(), 'gb-kings-cross');
+    _setCctvCoverageStateForTest({
+      viewer: null,
+      records: [sydney, london],
+      activeCameraId: null,
+      enabled: false,
+    });
+    assert.equal(
+      openingCameraId(),
+      'au-sydney',
+      'with no viewer position the first record is the fallback',
+    );
+    _setCctvCoverageStateForTest({ viewer, records: [], enabled: false });
+    assert.equal(openingCameraId(), null);
+  } finally {
+    _setCctvCoverageStateForTest({ enabled: false });
+  }
+});
+
+test('the opening camera follows a shared view that lands after CCTV turned on, until someone picks one', () => {
+  // A share link turns CCTV on before its flight lands, so enable() picks
+  // from the startup view; the flight's settled move re-picks near London.
+  const viewer = makeDeselectViewer();
+  viewer.camera.positionCartographic = Cesium.Cartographic.fromDegrees(
+    -0.1209,
+    51.5295,
+    187,
+  );
+  const sydney = makeDeselectRecord('au-sydney');
+  sydney.camera = { ...sydney.camera, lat: -34.03, lon: 151.11 };
+  const london = makeDeselectRecord('gb-kings-cross');
+  london.camera = { ...london.camera, lat: 51.5318, lon: -0.1209 };
+  for (const record of [sydney, london])
+    Object.assign(record, {
+      groundResolved: {},
+      groundSamples: {},
+      groundPrior: 0,
+      frustumGeometry: null,
+      frustumPositions: null,
+      probeClampRangeM: null,
+    });
+  _setCctvOverlayHostForTest({
+    setEntries() {},
+    setVisible() {},
+    clearSource() {},
+  });
+  // Activation builds the projection canvas and frame image.
+  const originalDocument = globalThis.document;
+  const originalImage = globalThis.Image;
+  globalThis.document = {
+    createElement: () => ({ getContext: () => null }),
+  };
+  globalThis.Image = class {};
+  try {
+    _setCctvCoverageStateForTest({
+      viewer,
+      records: [sydney, london],
+      activeCameraId: 'au-sydney',
+      enabled: true,
+      openingCameraProvisional: true,
+    });
+    assert.equal(reopenNearestCamera(), true);
+    assert.equal(cctvLayer.getUIState().activeCameraId, 'gb-kings-cross');
+    assert.equal(reopenNearestCamera(), false, 'already the nearest');
+
+    // Someone chooses a camera: settled moves leave it alone.
+    setActiveCamera('au-sydney');
+    assert.equal(reopenNearestCamera(), false);
+    assert.equal(cctvLayer.getUIState().activeCameraId, 'au-sydney');
+
+    // A deselect is a choice too.
+    _setCctvCoverageStateForTest({
+      viewer,
+      records: [sydney, london],
+      activeCameraId: 'au-sydney',
+      enabled: true,
+      openingCameraProvisional: true,
+    });
+    deactivateActiveCamera();
+    assert.equal(reopenNearestCamera(), false);
+    assert.equal(cctvLayer.getUIState().activeCameraId, null);
+  } finally {
+    globalThis.document = originalDocument;
+    globalThis.Image = originalImage;
+    _setCctvOverlayHostForTest();
+    _setCctvCoverageStateForTest({ enabled: false });
+  }
+});
+
 test('CCTV disable clears and hides its shared-host source through the real layer lifecycle', () => {
   const calls = [];
   _setCctvOverlayHostForTest({

src/data/cctvCalgary.test.mjs

@@ -12,7 +12,7 @@ import {
   CALGARY_IMAGE_ORIGIN,
   CALGARY_MAX_CATALOG_BYTES,
   DEFAULT_CALGARY_ROWS_URL,
-  DEFAULT_CCTV_MAX_SOURCES,
+  CCTV_SHARED_SOURCE_SLOTS,
 } from '../../server/providers/cctv/constants.js';
 import { CAMERA_CODE_MAX_CHARS } from '../../server/providers/cctv/normalize.js';
 import { allocateSourceCap } from '../../server/providers/cctv/cap.js';
@@ -384,6 +384,6 @@ test('CCTV_CALGARY_ENABLED=0 keeps the lane from being loaded at all', async (t)
   }
 });
 
-test('the shipped catalog ceiling is not raised to make room for this pack', () => {
-  assert.equal(DEFAULT_CCTV_MAX_SOURCES, 4000);
+test('the shared catalog slots are not raised to make room for this pack', () => {
+  assert.equal(CCTV_SHARED_SOURCE_SLOTS, 4000);
 });

src/data/cctvCatalogCap.test.mjs

@@ -6,9 +6,12 @@ import {
 } from '../../server/providers/cctv/cap.js';
 import {
   CCTV_MAX_SOURCES_CEILING,
+  CCTV_SHARED_SOURCE_SLOTS,
   CCTV_SOURCE_CACHE_MS,
   DEFAULT_CCTV_MAX_SOURCES,
+  WORLD_CCTV_SOURCE_COUNT,
 } from '../../server/providers/cctv/constants.js';
+import { QUEBEC_CAMERA_SOURCE_COUNT } from '../../server/providers/cctv/quebec.js';
 import { createCctvCatalog } from '../../server/providers/cctv/catalog.js';
 
 const pack = (name, count, prefix = name) => ({
@@ -99,6 +102,68 @@ test('duplicate ids resolve last-pack-wins and count against the winning pack',
   ]);
 });
 
+/** Shared packs plus two reserved ones, shaped like the default catalog. */
+const reservedFixture = () => [
+  ...Array.from({ length: 20 }, (_, i) => pack(`shared${i}`, 250)),
+  { ...pack('quebec', 1120), reservedCount: 1120 },
+  { ...pack('world', 2230), reservedCount: 2230 },
+];
+const keptByName = (packs) =>
+  Object.fromEntries(packs.map(({ name, kept }) => [name, kept]));
+
+test('the default cap is the shared floor plus the reserved Québec and World packs', () => {
+  assert.equal(
+    DEFAULT_CCTV_MAX_SOURCES,
+    CCTV_SHARED_SOURCE_SLOTS +
+      QUEBEC_CAMERA_SOURCE_COUNT +
+      WORLD_CCTV_SOURCE_COUNT,
+  );
+});
+
+test('at the default cap reserved packs are whole and shared packs keep the floor', () => {
+  const { sources, packs } = allocateSourceCap(
+    reservedFixture(),
+    DEFAULT_CCTV_MAX_SOURCES,
+  );
+  const kept = keptByName(packs);
+  assert.equal(sources.length, DEFAULT_CCTV_MAX_SOURCES);
+  assert.equal(kept.quebec, 1120);
+  assert.equal(kept.world, 2230);
+  for (let i = 0; i < 20; i++) assert.equal(kept[`shared${i}`], 200);
+  assert.match(
+    sources[0].id,
+    /^shared0-/,
+    'the first camera stays in a shared pack',
+  );
+});
+
+test('a cap at the shared floor reserves nothing and thins every pack evenly', () => {
+  const { packs } = allocateSourceCap(reservedFixture(), 4000);
+  const kept = keptByName(packs);
+  // 22 lanes share 4,000 round-robin: nobody is wiped out by the reservation.
+  for (const count of Object.values(kept))
+    assert.ok(count >= 181 && count <= 182);
+});
+
+test('a small cap (dev-secure 48) still reaches the shared packs first', () => {
+  const { sources, packs } = allocateSourceCap(reservedFixture(), 48);
+  const kept = keptByName(packs);
+  assert.equal(sources.length, 48);
+  for (let i = 0; i < 20; i++) assert.ok(kept[`shared${i}`] >= 2);
+  assert.match(sources[0].id, /^shared0-/);
+});
+
+test('reservations fill only the room above the floor, round-robin between reserved packs', () => {
+  const { packs } = allocateSourceCap(reservedFixture(), 4100);
+  const kept = keptByName(packs);
+  const shared = Object.entries(kept)
+    .filter(([name]) => name.startsWith('shared'))
+    .reduce((sum, [, count]) => sum + count, 0);
+  // 100 reserved slots split between Québec and World, then 4,000 round-robin.
+  assert.ok(shared >= 4000 - 2 * 182, `shared packs kept ${shared}`);
+  assert.equal(shared + kept.quebec + kept.world, 4100);
+});
+
 test('resolveCatalogCap bounds the env value and falls back to the default', () => {
   assert.equal(resolveCatalogCap(undefined), DEFAULT_CCTV_MAX_SOURCES);
   assert.equal(resolveCatalogCap('nonsense'), DEFAULT_CCTV_MAX_SOURCES);

src/data/cctvDriveBcSource.test.mjs

@@ -14,6 +14,8 @@ import {
   DEFAULT_ONTARIO_MAX_SOURCES,
   DEFAULT_FINTRAFFIC_MAX_SOURCES,
   DEFAULT_TXDOT_MAX_SOURCES,
+  DEFAULT_OTTAWA_MAX_SOURCES,
+  CCTV_SHARED_SOURCE_SLOTS,
   DEFAULT_TALLINN_MAX_SOURCES,
   DEFAULT_TARKTEE_MAX_SOURCES,
   DEFAULT_NSW_MAX_SOURCES,
@@ -222,7 +224,7 @@ test('CCTV catalog merges DriveBC cameras and CCTV_DRIVEBC_ENABLED=0 skips the r
   );
 });
 
-test('default caps of the original packs fit inside the default catalog cap', () => {
+test('default caps of the original packs fit inside the shared catalog slots', () => {
   // Every default pack at its own cap (Warendorf ships 1 curated camera).
   const packs =
     DEFAULT_AUSTIN_MAX_SOURCES +
@@ -231,15 +233,18 @@ test('default caps of the original packs fit inside the default catalog cap', ()
     DEFAULT_ONTARIO_MAX_SOURCES +
     DEFAULT_FINTRAFFIC_MAX_SOURCES +
     DEFAULT_DRIVEBC_MAX_SOURCES +
+    DEFAULT_OTTAWA_MAX_SOURCES +
     DEFAULT_TXDOT_MAX_SOURCES +
     DEFAULT_TALLINN_MAX_SOURCES +
     DEFAULT_TARKTEE_MAX_SOURCES +
     DEFAULT_NSW_MAX_SOURCES +
     DEFAULT_CATALONIA_MAX_SOURCES +
     1;
+  // The reserved Québec and World packs sit above the shared floor, so the
+  // shared packs must fit the floor itself, not the whole default cap.
   assert.ok(
-    packs <= DEFAULT_CCTV_MAX_SOURCES,
-    `default packs (${packs}) would be thinned by the catalog cap (${DEFAULT_CCTV_MAX_SOURCES})`,
+    packs <= CCTV_SHARED_SOURCE_SLOTS,
+    `default packs (${packs}) would be thinned by the shared slots (${CCTV_SHARED_SOURCE_SLOTS})`,
   );
   assert.ok(
     DEFAULT_CCTV_MAX_SOURCES <= CCTV_MAX_SOURCES_CEILING,

src/data/cctvHk.test.mjs

@@ -10,7 +10,7 @@ import {
   parseHkCameraLocationsXml,
 } from '../../server/providers/cctv/sources.js';
 import {
-  DEFAULT_CCTV_MAX_SOURCES,
+  CCTV_SHARED_SOURCE_SLOTS,
   DEFAULT_HK_CAMERAS_URL,
   DEFAULT_HK_MAX_SOURCES,
   HK_ANCHORS,
@@ -396,8 +396,8 @@ test('CCTV_HK_ENABLED=0 keeps the lane from being loaded at all', async (t) => {
   }
 });
 
-test('the shipped catalog ceiling is not raised to make room for this pack', () => {
-  assert.equal(DEFAULT_CCTV_MAX_SOURCES, 4000);
+test('the shared catalog slots are not raised to make room for this pack', () => {
+  assert.equal(CCTV_SHARED_SOURCE_SLOTS, 4000);
 });
 
 test('the HK pack default sits above the full TD catalog and anchors the New Territories', () => {
@@ -406,7 +406,7 @@ test('the HK pack default sits above the full TD catalog and anchors the New Ter
     'default cap should keep nearly all published TD cameras',
   );
   assert.ok(
-    DEFAULT_HK_MAX_SOURCES <= DEFAULT_CCTV_MAX_SOURCES,
+    DEFAULT_HK_MAX_SOURCES <= CCTV_SHARED_SOURCE_SLOTS,
     'a single pack must not outgrow the catalog-wide ceiling alone',
   );
   const places = HK_ANCHORS.map(

src/data/cctvHlsStream.test.mjs

@@ -10,6 +10,77 @@ const playlist =
   '#EXTM3U\n#EXT-X-MEDIA-SEQUENCE:12\n#EXTINF:2,\na.ts\n#EXTINF:2,\nb.ts\n#EXTINF:2,\nc.ts\n';
 const base = 'https://camera.example/live/list.m3u8';
 
+test('high-resolution HLS segments play while the retained session cache stays bounded', async (t) => {
+  // Giroc publishes roughly ten-second TS segments; one measured 6,437,120
+  // bytes. The former 4 MiB download cap rejected it before playback began.
+  const segmentBytes = 6_437_120;
+  const master =
+    '#EXTM3U\n#EXT-X-STREAM-INF:BANDWIDTH=4570000\ntracks-v1a1/mono.m3u8\n';
+  const media =
+    '#EXTM3U\n#EXT-X-MEDIA-SEQUENCE:100\n' +
+    [0, 1, 2, 3, 4].map((i) => `#EXTINF:10.272,\n${i}.ts\n`).join('');
+  const manager = createHlsPuller({
+    limits: { ...HLS_LIMITS, pollMs: 100000 },
+    fetchImpl: async (url) => {
+      if (url === base) return new Response(master);
+      if (url === 'https://camera.example/live/tracks-v1a1/mono.m3u8')
+        return new Response(media);
+      const match =
+        /^https:\/\/camera\.example\/live\/tracks-v1a1\/([0-4])\.ts$/.exec(url);
+      if (!match) throw new Error('Unexpected playlist reference');
+      // No Content-Length: the actual streamed bytes must also be accepted.
+      return new Response(Buffer.alloc(segmentBytes, Number(match[1])));
+    },
+  });
+  t.after(() => manager.shutdown());
+  const entry = await manager.ensure('giroc', base);
+  await entry.polling;
+  const result = await manager.buildPlaylist(entry, 'giroc');
+  assert.ok(result, 'large valid segments should produce a playable playlist');
+  assert.match(result, /#EXT-X-MEDIA-SEQUENCE:2\n/);
+  assert.equal(manager.getSegment('giroc', entry.token, 0), null);
+  const newest = manager.getSegment('giroc', entry.token, 4);
+  assert.equal(newest.length, segmentBytes);
+  assert.equal(newest[0], 4);
+  assert.deepEqual(manager.stats(), { sessions: 1, bytes: 19_311_360 });
+});
+
+test('HLS downloads still reject declared and chunked bodies above 8 MiB', async () => {
+  for (const declared of [true, false]) {
+    let chunks = 0;
+    let cancelled = false;
+    await assert.rejects(
+      fetchHlsBytes(base, {
+        maxBytes: HLS_LIMITS.segmentBytes,
+        fetchImpl: async () =>
+          new Response(
+            declared
+              ? 'small body'
+              : new ReadableStream({
+                  pull(controller) {
+                    // Each chunk fits on its own; only their cumulative size
+                    // crosses the cap. Leave it open to verify cancellation.
+                    controller.enqueue(
+                      Buffer.alloc(4 * 1024 * 1024 + (++chunks === 2 ? 1 : 0)),
+                    );
+                  },
+                  cancel() {
+                    cancelled = true;
+                  },
+                }),
+            {
+              headers: declared
+                ? { 'content-length': String(8 * 1024 * 1024 + 1) }
+                : {},
+            },
+          ),
+      }),
+      /HLS response too large/,
+    );
+    if (!declared) assert.equal(cancelled, true);
+  }
+});
+
 test('playlist parser uses sequence, refuses escaping and unsupported references', () => {
   assert.deepEqual(
     parseHlsMedia(playlist, base).map((s) => s.seq),

src/data/cctvHouston.test.mjs

@@ -7,7 +7,7 @@ import {
   loadHoustonSourcesFromOpenData,
 } from '../../server/providers/cctv/sources.js';
 import {
-  DEFAULT_CCTV_MAX_SOURCES,
+  CCTV_SHARED_SOURCE_SLOTS,
   DEFAULT_HOUSTON_MAX_SOURCES,
   HOUSTON_CAMERAS_URL,
   HOUSTON_GROUND_ELEVATION_M,
@@ -387,8 +387,8 @@ test('Houston stays unloaded unless CCTV_HOUSTON_ENABLED=1', async (t) => {
   }
 });
 
-test('the shipped catalog ceiling is not raised to make room for this pack', () => {
-  assert.equal(DEFAULT_CCTV_MAX_SOURCES, 4000);
+test('the shared catalog slots are not raised to make room for this pack', () => {
+  assert.equal(CCTV_SHARED_SOURCE_SLOTS, 4000);
   assert.equal(DEFAULT_HOUSTON_MAX_SOURCES, 250);
 });
 

src/data/cctvIceland.test.mjs

@@ -0,0 +1,429 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { createCctvCatalog } from '../../server/providers/cctv/catalog.js';
+import {
+  DEFAULT_ICELAND_MAX_SOURCES,
+  ICELAND_CAMERAS_URL,
+  ICELAND_IMAGE_ORIGIN,
+  ICELAND_MAX_CATALOG_BYTES,
+} from '../../server/providers/cctv/constants.js';
+import { fetchWithinHost } from '../../server/providers/cctv/media.js';
+import { isLikelyIcelandCoordinate } from '../../server/providers/cctv/normalize.js';
+import {
+  icelandCameraToSource,
+  icelandHeadingFromDescription,
+  loadIcelandSourcesFromOpenData,
+} from '../../server/providers/cctv/sources.js';
+
+/** Set (or, for `undefined`, delete) environment variables for one test. */
+function withEnv(t, env) {
+  for (const [name, value] of Object.entries(env)) {
+    const previous = process.env[name];
+    t.after(() => {
+      if (previous === undefined) delete process.env[name];
+      else process.env[name] = previous;
+    });
+    if (value === undefined) delete process.env[name];
+    else process.env[name] = value;
+  }
+}
+
+/** One row shaped like the live `vefmyndavelar2014_1` payload. */
+const row = (over = {}) => ({
+  Maelist_nr: 7001,
+  Myndavel: 'Hellisheiði',
+  Vegheiti: 'Hringvegur',
+  NrVegur: '1',
+  Skyring: 'Hellisheiði séð til vesturs',
+  Slod: `${ICELAND_IMAGE_ORIGIN}hellisheidi_1.jpg`,
+  PntX: 395000,
+  PntY: 390000,
+  Breidd: 64.0136,
+  Lengd: -21.4,
+  ...over,
+});
+
+/** A live response body plus a flag that flips when the stream is cancelled. */
+const streamingResponse = (init = {}) => {
+  const state = { cancelled: false };
+  const body = new ReadableStream({
+    start(controller) {
+      controller.enqueue(new TextEncoder().encode('['));
+    },
+    cancel() {
+      state.cancelled = true;
+    },
+  });
+  return { response: new Response(body, init), state };
+};
+
+const json = (value) =>
+  new Response(JSON.stringify(value), {
+    status: 200,
+    headers: { 'Content-Type': 'application/json' },
+  });
+
+test('an Iceland row maps to a source on the pinned frame directory', () => {
+  const source = icelandCameraToSource(row());
+  assert.equal(source.id, 'is-vegagerdin-hellisheidi_1');
+  assert.equal(source.name, 'Hellisheiði séð til vesturs');
+  assert.equal(source.city, 'Iceland');
+  assert.equal(source.cityId, 'iceland');
+  assert.equal(source.provider, 'Vegagerðin (IRCA)');
+  assert.equal(source.lat, 64.0136);
+  assert.equal(source.lon, -21.4);
+  assert.equal(source.headingDeg, 270);
+  assert.equal(source.headingConfidence, 'high');
+  assert.equal(source.pitchDeg, -24);
+  assert.equal(source.fovDeg, 56);
+  assert.equal(source.rangeM, 210);
+  assert.equal(source.mountHeightM, 10);
+  assert.equal(source.feedType, 'image');
+  assert.equal(source.sourceKind, 'iceland-vegagerdin');
+  assert.equal(source.code, 'HELLISHEIÐI');
+  assert.match(source.license, /CC BY 4\.0/);
+  assert.ok(source.url.startsWith(ICELAND_IMAGE_ORIGIN));
+  assert.equal(source.snapshotUrl, source.url);
+});
+
+test('a view that states no facing takes the low-confidence id-hash pose', () => {
+  const source = icelandCameraToSource(
+    row({
+      Skyring: 'Hellisheiði séð niður á veg',
+      Slod: `${ICELAND_IMAGE_ORIGIN}hellisheidi_2.jpg`,
+    }),
+  );
+  assert.equal(source.headingConfidence, 'low');
+  assert.equal(source.headingDeg % 22.5, 0);
+  assert.equal(
+    source.headingDeg,
+    icelandCameraToSource(
+      row({ Slod: `${ICELAND_IMAGE_ORIGIN}hellisheidi_2.jpg` }),
+    ).headingDeg,
+    'the fallback depends on the id, not on the text',
+  );
+});
+
+test('the label collapses the feed’s doubled spaces and repeated words', () => {
+  assert.equal(
+    icelandCameraToSource(
+      row({ Skyring: 'Strandarheiði séð niður á veg til  til austurs' }),
+    ).name,
+    'Strandarheiði séð niður á veg til austurs',
+  );
+  const label = (Skyring) => icelandCameraToSource(row({ Skyring })).name;
+  // Repeats of words with Icelandic letters collapse too.
+  assert.equal(
+    label('Hellisheiði séð séð til austurs'),
+    'Hellisheiði séð til austurs',
+  );
+  assert.equal(label('Brú á á Jökulsá'), 'Brú á Jökulsá');
+  // A word ending in a letter the next word starts with is not a repeat.
+  for (const text of [
+    'Þverá Árnessýslu',
+    'brú Úlfarsá',
+    'Vesturlandsvegur við Elliðaá Ártúnsbrekku',
+  ])
+    assert.equal(label(text), text);
+});
+
+test('a row with no label, station or station number is named by its frame', () => {
+  const source = icelandCameraToSource(
+    row({ Skyring: '', Myndavel: '', Maelist_nr: undefined }),
+  );
+  assert.equal(source.name, 'Vegagerðin hellisheidi_1');
+});
+
+test('only an explicit facing sets a heading', () => {
+  const cases = [
+    ['Hellisheiði séð til vesturs', 270],
+    ['Holtavörðuheiði til norðurs', 0],
+    ['Klettsháls í suður', 180],
+    ['Arnarneshæð séð austur', 90],
+    ['Bústaðabrú séð norður Kringlumýrarbraut', 0],
+    ['Staður séð til norðausturs', 45],
+    ['Staður séð til suðausturs', 135],
+    ['Staður séð í suðvestur', 225],
+    ['Staður séð til norðvesturs', 315],
+    ['STAÐUR SÉÐ TIL VESTURS', 270],
+    ['Brú séð til austurs og Selfoss', 90], // "og" then a place, not a facing
+    ['Staður séð til austurs og Vesturlandsvegur', 90],
+  ];
+  for (const [text, heading] of cases) {
+    assert.equal(icelandHeadingFromDescription(text), heading, text);
+  }
+  for (const text of [
+    '',
+    null,
+    'Gautsdalur niður á veg',
+    'Miklabraut austur', // a road direction, not a facing
+    'Biskupsháls - norður',
+    'Hringtorg norðan Selfoss',
+    'Norðurárdalur niður á veg', // a place name that contains a cardinal
+    'Staður séð til suðurlands', // a longer word, not "suður"
+    'Staður séð til norðurs og til suðurs', // two facings: ambiguous
+    'Staður séð til austurs og vesturs', // the second facing shares "til"
+    'Staður séð í norður og suður',
+    'Staður séð í norður og í suður',
+    'Norðfjarðargöng séð til Eskifjarðar',
+  ]) {
+    assert.ok(Number.isNaN(icelandHeadingFromDescription(text)), String(text));
+  }
+});
+
+test('rows off the pinned directory, or with unusable frames or places, are dropped', () => {
+  const bad = [
+    { Slod: 'https://example.com/vgdata/vefmyndavelar/a_1.jpg' },
+    { Slod: 'http://www.vegagerdin.is/vgdata/vefmyndavelar/a_1.jpg' },
+    { Slod: 'https://user:[email protected]/vgdata/vefmyndavelar/a_1.jpg' },
+    { Slod: 'https://www.vegagerdin.is:8443/vgdata/vefmyndavelar/a_1.jpg' },
+    { Slod: 'https://www.vegagerdin.is/vgdata/other/a_1.jpg' },
+    { Slod: 'https://www.vegagerdin.is/vgdata/vefmyndavelar/../x/a_1.jpg' },
+    { Slod: 'https://www.vegagerdin.is/vgdata/vefmyndavelar/a%2Fb_1.jpg' },
+    { Slod: 'https://www.vegagerdin.is/vgdata/vefmyndavelar/a_1.php' },
+    { Slod: 'https://www.vegagerdin.is/vgdata/vefmyndavelar/a_1' },
+    { Slod: 'https://www.vegagerdin.is/vgdata/vefmyndavelar/' },
+    { Slod: 'https://www.vegagerdin.is/vgdata/vefmyndavelar/a b_1.jpg' },
+    { Slod: '' },
+    { Slod: null },
+    { Breidd: 0, Lengd: 0 },
+    { Breidd: null, Lengd: null },
+    { Breidd: '64.01', Lengd: '-21.4' },
+    { Breidd: '64.01' }, // each coordinate must be a number on its own
+    { Lengd: '-21.4' },
+    { Breidd: 59.9, Lengd: 10.7 }, // Oslo
+    { Breidd: 64.01, Lengd: 21.4 }, // wrong hemisphere
+  ];
+  for (const over of bad) {
+    assert.equal(icelandCameraToSource(row(over)), null, JSON.stringify(over));
+  }
+  assert.equal(icelandCameraToSource(null), null);
+  assert.equal(icelandCameraToSource({}), null);
+  assert.equal(isLikelyIcelandCoordinate(64.1466, -21.9426), true);
+  assert.equal(isLikelyIcelandCoordinate(66.3, -14.0), true);
+});
+
+test('the Iceland loader reads the list with redirects refused and keeps the nearest cameras', async (t) => {
+  t.mock.method(console, 'log', () => {});
+  t.mock.method(console, 'warn', () => {});
+  withEnv(t, { CCTV_ICELAND_MAX_SOURCES: '8' });
+  const rows = Array.from({ length: 12 }, (_, i) =>
+    row({
+      Maelist_nr: 8000 + i,
+      Slod: `${ICELAND_IMAGE_ORIGIN}far_${i}.jpg`,
+      Skyring: `Far ${i}`,
+      Breidd: 66.2,
+      Lengd: -15.9 + i * 0.01,
+    }),
+  );
+  // Reykjavík cameras come last in the feed but first in the priority order.
+  // A frame the feed repeats keeps its last row, as the other packs do.
+  rows.push(row({ Slod: `${ICELAND_IMAGE_ORIGIN}rvk_1.jpg`, Skyring: 'Old' }));
+  rows.push(
+    row({
+      Slod: `${ICELAND_IMAGE_ORIGIN}rvk_1.jpg`,
+      Skyring: 'Kringlumýrarbraut',
+      Breidd: 64.1466,
+      Lengd: -21.9426,
+    }),
+  );
+  const seen = [];
+  t.mock.method(globalThis, 'fetch', async (url, init) => {
+    seen.push([String(url), init.redirect]);
+    return json(rows);
+  });
+  const sources = await loadIcelandSourcesFromOpenData();
+  assert.deepEqual(seen, [[ICELAND_CAMERAS_URL, 'manual']]);
+  assert.equal(sources.length, 8);
+  assert.equal(sources[0].id, 'is-vegagerdin-rvk_1');
+  assert.equal(sources[0].name, 'Kringlumýrarbraut');
+  assert.equal(sources[0].lat, 64.1466);
+  assert.equal(
+    new Set(sources.map((s) => s.id)).size,
+    sources.length,
+    'a frame the feed repeats collapses to one camera',
+  );
+  assert.equal(sources.available, 13);
+});
+
+test('the default Iceland cap is DEFAULT_ICELAND_MAX_SOURCES', async (t) => {
+  t.mock.method(console, 'log', () => {});
+  withEnv(t, { CCTV_ICELAND_MAX_SOURCES: undefined });
+  const rows = Array.from(
+    { length: DEFAULT_ICELAND_MAX_SOURCES + 40 },
+    (_, i) => row({ Slod: `${ICELAND_IMAGE_ORIGIN}cam_${i}.jpg` }),
+  );
+  t.mock.method(globalThis, 'fetch', async () => json(rows));
+  assert.equal(
+    (await loadIcelandSourcesFromOpenData()).length,
+    DEFAULT_ICELAND_MAX_SOURCES,
+  );
+});
+
+test('CCTV_ICELAND_MAX_SOURCES is clamped to 8..600 and ignored when not a number', async (t) => {
+  t.mock.method(console, 'log', () => {});
+  withEnv(t, { CCTV_ICELAND_MAX_SOURCES: undefined });
+  const rows = Array.from({ length: 650 }, (_, i) =>
+    row({ Slod: `${ICELAND_IMAGE_ORIGIN}cam_${i}.jpg` }),
+  );
+  t.mock.method(globalThis, 'fetch', async () => json(rows));
+  for (const [value, expected] of [
+    ['0', 8],
+    ['3', 8],
+    ['1000', 600],
+    ['abc', DEFAULT_ICELAND_MAX_SOURCES],
+  ]) {
+    process.env.CCTV_ICELAND_MAX_SOURCES = value;
+    assert.equal(
+      (await loadIcelandSourcesFromOpenData()).length,
+      expected,
+      value,
+    );
+  }
+});
+
+test('a redirect on the Iceland frame host stays inside vefmyndavelar/', async () => {
+  const frame = `${ICELAND_IMAGE_ORIGIN}hellisheidi_1.jpg`;
+  const redirectTo = (location) => async (url) =>
+    url === frame
+      ? new Response(null, { status: 302, headers: { location } })
+      : new Response('frame', { headers: { 'content-type': 'image/jpeg' } });
+  for (const location of [
+    '/vgdata/other/x.jpg',
+    '/vgdata/vefmyndavelar/../x.jpg',
+    '/',
+  ])
+    assert.equal(
+      await fetchWithinHost(frame, {}, redirectTo(location)),
+      null,
+      location,
+    );
+  const followed = await fetchWithinHost(
+    frame,
+    {},
+    redirectTo('/vgdata/vefmyndavelar/hellisheidi_1b.jpg'),
+  );
+  assert.equal(await followed.text(), 'frame');
+});
+
+test('the Iceland loader fails soft on HTTP errors, bad payloads and network errors', async (t) => {
+  t.mock.method(console, 'log', () => {});
+  t.mock.method(console, 'warn', () => {});
+  t.mock.method(
+    globalThis,
+    'fetch',
+    async () => new Response('x', { status: 503 }),
+  );
+  assert.deepEqual(await loadIcelandSourcesFromOpenData(), []);
+  t.mock.restoreAll();
+  t.mock.method(console, 'log', () => {});
+  t.mock.method(console, 'warn', () => {});
+  t.mock.method(globalThis, 'fetch', async () => json({ rows: [] }));
+  assert.deepEqual(await loadIcelandSourcesFromOpenData(), []);
+  t.mock.method(
+    globalThis,
+    'fetch',
+    async () => new Response('<html>', { status: 200 }),
+  );
+  assert.deepEqual(await loadIcelandSourcesFromOpenData(), []);
+  t.mock.method(globalThis, 'fetch', async () => {
+    throw new Error('network down');
+  });
+  assert.deepEqual(await loadIcelandSourcesFromOpenData(), []);
+});
+
+test('the Iceland catalog fetch refuses redirects and oversized bodies', async (t) => {
+  t.mock.method(console, 'warn', () => {});
+  const redirected = streamingResponse({
+    status: 302,
+    headers: {
+      location: 'http://gagnaveita.vegagerdin.is/api/vefmyndavelar2014_1',
+    },
+  });
+  t.mock.method(globalThis, 'fetch', async () => redirected.response);
+  assert.deepEqual(await loadIcelandSourcesFromOpenData(), []);
+  assert.equal(
+    redirected.state.cancelled,
+    true,
+    'the redirect body is cancelled',
+  );
+
+  t.mock.restoreAll();
+  t.mock.method(console, 'warn', () => {});
+  const failed = streamingResponse({ status: 500 });
+  t.mock.method(globalThis, 'fetch', async () => failed.response);
+  assert.deepEqual(await loadIcelandSourcesFromOpenData(), []);
+  assert.equal(failed.state.cancelled, true, 'the error body is cancelled');
+
+  const valid = JSON.stringify([row()]);
+  t.mock.restoreAll();
+  t.mock.method(console, 'warn', () => {});
+  t.mock.method(globalThis, 'fetch', async () => {
+    return new Response(valid, {
+      headers: { 'content-length': String(ICELAND_MAX_CATALOG_BYTES + 1) },
+    });
+  });
+  assert.deepEqual(await loadIcelandSourcesFromOpenData(), []);
+
+  t.mock.restoreAll();
+  t.mock.method(console, 'warn', () => {});
+  t.mock.method(globalThis, 'fetch', async () => {
+    const padded = valid + ' '.repeat(ICELAND_MAX_CATALOG_BYTES + 1024);
+    return new Response(
+      new ReadableStream({
+        start(controller) {
+          controller.enqueue(new TextEncoder().encode(padded));
+          controller.close();
+        },
+      }),
+    );
+  });
+  assert.deepEqual(await loadIcelandSourcesFromOpenData(), []);
+});
+
+test('CCTV catalog merges Iceland cameras and CCTV_ICELAND_ENABLED=0 skips the request', async (t) => {
+  t.mock.method(console, 'log', () => {});
+  t.mock.method(console, 'warn', () => {});
+  const sourceRoot = fs.mkdtempSync(
+    path.join(os.tmpdir(), 'gev-cctv-catalog-iceland-'),
+  );
+  t.after(() => fs.rmSync(sourceRoot, { recursive: true, force: true }));
+  withEnv(t, {
+    CCTV_SOURCES_FILE: undefined,
+    CCTV_SOURCES_JSON: undefined,
+    CCTV_FORCE_AUSTIN: undefined,
+    CCTV_PREFER_AUSTIN: undefined,
+    CCTV_MAX_SOURCES: undefined,
+    CCTV_CALTRANS_DISTRICTS: undefined,
+    CCTV_TFL_ENABLED: undefined,
+    CCTV_ICELAND_ENABLED: undefined,
+    CCTV_ICELAND_MAX_SOURCES: undefined,
+  });
+  const requested = [];
+  t.mock.method(globalThis, 'fetch', async (url, init) => {
+    requested.push([String(url), init.redirect]);
+    if (String(url) !== ICELAND_CAMERAS_URL) {
+      return new Response('unavailable', { status: 503 });
+    }
+    return json([row()]);
+  });
+
+  const sources = await createCctvCatalog({ sourceRoot })();
+  assert.deepEqual(
+    sources.map((source) => source.id),
+    ['is-vegagerdin-hellisheidi_1'],
+  );
+
+  process.env.CCTV_ICELAND_ENABLED = '0';
+  requested.length = 0;
+  assert.deepEqual(await createCctvCatalog({ sourceRoot })(), []);
+  assert.ok(requested.length > 0, 'the other live packs still load');
+  assert.equal(
+    requested.some(([url]) => url === ICELAND_CAMERAS_URL),
+    false,
+    'a disabled pack makes no request',
+  );
+});

src/data/cctvNyc.test.mjs

@@ -8,7 +8,7 @@ import {
   nycCameraToSource,
 } from '../../server/providers/cctv/sources.js';
 import {
-  DEFAULT_CCTV_MAX_SOURCES,
+  CCTV_SHARED_SOURCE_SLOTS,
   DEFAULT_NYC_MAX_SOURCES,
   NYC_CAMERAS_URL,
   NYC_GROUND_ELEVATION_M,
@@ -375,8 +375,8 @@ for (const [label, flag] of [
   });
 }
 
-test('the shipped catalog ceiling is not raised to make room for this pack', () => {
-  assert.equal(DEFAULT_CCTV_MAX_SOURCES, 4000);
+test('the shared catalog slots are not raised to make room for this pack', () => {
+  assert.equal(CCTV_SHARED_SOURCE_SLOTS, 4000);
   assert.equal(DEFAULT_NYC_MAX_SOURCES, 250);
 });
 

src/data/cctvOttawa.test.mjs

@@ -0,0 +1,255 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { createCctvCatalog } from '../../server/providers/cctv/catalog.js';
+import {
+  OTTAWA_CAMERAS_URL,
+  OTTAWA_IMAGE_ORIGIN,
+} from '../../server/providers/cctv/constants.js';
+import {
+  fallbackHeadingFromId,
+  pinnedCameraUrl,
+} from '../../server/providers/cctv/normalize.js';
+import {
+  _resetOttawaCertificateWarningForTest,
+  loadOttawaSourcesFromOpenData,
+  ottawaAuthorizedFrameUrl,
+} from '../../server/providers/cctv/ottawa.js';
+
+const CERT = { OTTAWA_CAMERA_CERTIFICATE: 'CERT123' };
+
+/** Set (or, for `undefined`, delete) environment variables for one test. */
+function withEnv(t, env) {
+  for (const [name, value] of Object.entries(env)) {
+    const previous = process.env[name];
+    t.after(() => {
+      if (previous === undefined) delete process.env[name];
+      else process.env[name] = previous;
+    });
+    if (value === undefined) delete process.env[name];
+    else process.env[name] = value;
+  }
+}
+
+/** Silence the loader's progress and failure logging. */
+function quiet(t) {
+  t.mock.method(console, 'log', () => {});
+  t.mock.method(console, 'warn', () => {});
+}
+
+/** One documented `/map/service/camera` row carrying the fields the loader reads. */
+function ottawaRow(number, lat, lon, overrides = {}) {
+  return {
+    id: number + 10000,
+    camera_number: number,
+    name: `Camera ${number}`,
+    name_french: `Caméra ${number}`,
+    cameraOwner: 'CITY',
+    latitude: lat,
+    longitude: lon,
+    ...overrides,
+  };
+}
+
+/** The feed's envelope around its rows. */
+const ottawaPayload = (rows) => Response.json({ cameras: rows });
+
+test('without OTTAWA_CAMERA_CERTIFICATE the Ottawa pack is skipped with no request, logged once', async (t) => {
+  _resetOttawaCertificateWarningForTest();
+  const lines = [];
+  t.mock.method(console, 'warn', (line) => lines.push(String(line)));
+  const fetchMock = t.mock.method(globalThis, 'fetch', async () => {
+    throw new Error('no request expected');
+  });
+  assert.deepEqual(await loadOttawaSourcesFromOpenData({}, {}), []);
+  assert.deepEqual(
+    await loadOttawaSourcesFromOpenData({}, { OTTAWA_CAMERA_CERTIFICATE: '  ' }),
+    [],
+  );
+  assert.equal(fetchMock.mock.callCount(), 0);
+  assert.equal(lines.length, 1);
+  assert.match(lines[0], /OTTAWA_CAMERA_CERTIFICATE/);
+});
+
+test('Ottawa frame URLs are signed only inside the opendata camera path', () => {
+  assert.equal(
+    ottawaAuthorizedFrameUrl('https://traffic.ottawa.ca/opendata/camera?c=16', CERT),
+    'https://traffic.ottawa.ca/opendata/camera?c=16&certificate=CERT123&id=gev',
+  );
+  assert.equal(
+    ottawaAuthorizedFrameUrl('https://traffic.ottawa.ca/opendata/camera?c=16', {}),
+    '',
+    'no certificate, no signed URL',
+  );
+  for (const url of [
+    'https://traffic.ottawa.ca/opendata/camera?c=16x',
+    'https://traffic.ottawa.ca/opendata/other?c=16',
+    'https://traffic.ottawa.ca/map/camera?id=16',
+    'https://traffic.ottawa.ca.evil.test/opendata/camera?c=16',
+    'http://traffic.ottawa.ca/opendata/camera?c=16',
+  ])
+    assert.equal(ottawaAuthorizedFrameUrl(url, CERT), '', url);
+});
+
+test('Ottawa loader keeps in-city cameras and builds keyless frame URLs from the camera number', async (t) => {
+  quiet(t);
+  withEnv(t, { CCTV_OTTAWA_MAX_SOURCES: undefined });
+  const requested = [];
+  t.mock.method(globalThis, 'fetch', async (url) => {
+    requested.push(String(url));
+    return ottawaPayload([
+      ottawaRow(2025, 45.341343, -75.81467, {
+        name: '(MTO) Hwy 416 NB ramp to Hwy 417 East',
+        cameraOwner: 'MTO',
+      }),
+      ottawaRow(1, 45.4215, -75.6972, {
+        name: 'Bank St at Somerset St',
+        camera_owner: 'CITY',
+        cameraOwner: undefined,
+      }),
+      ottawaRow(1, 45.4216, -75.6973, { name: 'duplicate number' }),
+      ottawaRow(0, 45.4215, -75.6972),
+      ottawaRow(-3, 45.4215, -75.6972),
+      ottawaRow(7, null, -75.7),
+      ottawaRow(8, 45.4, null),
+      ottawaRow(9, 43.6532, -79.3832, { description: 'Toronto' }),
+      ottawaRow(10, 45.9, -75.7),
+    ]);
+  });
+
+  const cameras = await loadOttawaSourcesFromOpenData({}, CERT);
+
+  assert.deepEqual(requested, [OTTAWA_CAMERAS_URL]);
+  assert.deepEqual(cameras.map((camera) => camera.id).sort(), [
+    'ottawa-1',
+    'ottawa-2025',
+  ]);
+
+  const mto = cameras.find((camera) => camera.id === 'ottawa-2025');
+  const city = cameras.find((camera) => camera.id === 'ottawa-1');
+  assert.equal(mto.url, 'https://traffic.ottawa.ca/opendata/camera?c=2025');
+  assert.doesNotMatch(mto.url, /certificate/, 'the catalog URL carries no key');
+  assert.equal(mto.snapshotUrl, mto.url);
+  assert.equal(mto.frameRefreshMs, 60000, 'the API allows one fetch a minute');
+  assert.equal(city.name, 'Bank St at Somerset St');
+  assert.equal(mto.name, '(MTO) Hwy 416 NB ramp to Hwy 417 East');
+  assert.equal(mto.city, 'Ottawa');
+  assert.equal(mto.provider, 'City of Ottawa');
+  assert.equal(mto.feedType, 'image');
+  assert.equal(mto.sourceKind, 'ottawa-traffic');
+  assert.equal(mto.headingConfidence, 'low');
+  assert.equal(
+    mto.headingDeg,
+    fallbackHeadingFromId('ottawa-2025'),
+    'the feed publishes no bearing, so the id-hash fallback is deterministic',
+  );
+  assert.match(mto.license, /City of Ottawa/);
+  assert.equal(
+    mto.credit,
+    'Ministry of Transportation of Ontario (MTO) camera',
+    'a provincial camera carried on the city feed names its owner',
+  );
+  assert.equal(city.credit, '', 'a city camera carries no partner credit');
+});
+
+test('Ottawa loader keeps the cameras nearest downtown under its cap', async (t) => {
+  quiet(t);
+  withEnv(t, { CCTV_OTTAWA_MAX_SOURCES: '8' });
+  const rows = [
+    // Far suburbs come first in payload order, so only distance can drop them.
+    ...[45.55, 45.54, 45.53, 45.52].map((lat, i) =>
+      ottawaRow(100 + i, lat, -76.1),
+    ),
+    ...[45.42, 45.421, 45.422, 45.423, 45.424, 45.425, 45.426, 45.427].map(
+      (lat, i) => ottawaRow(200 + i, lat, -75.7),
+    ),
+  ];
+  t.mock.method(globalThis, 'fetch', async () => ottawaPayload(rows));
+
+  const cameras = await loadOttawaSourcesFromOpenData({}, CERT);
+
+  assert.equal(cameras.length, 8);
+  assert.deepEqual(
+    cameras.map((camera) => camera.id).filter((id) => /^ottawa-10\d$/.test(id)),
+    [],
+    'the far-suburb cameras are the ones dropped',
+  );
+});
+
+test('Ottawa loader fails soft on HTTP errors, unexpected payloads and network errors', async (t) => {
+  quiet(t);
+  let respond;
+  t.mock.method(globalThis, 'fetch', (...args) => respond(...args));
+  for (respond of [
+    async () => new Response('unavailable', { status: 503 }),
+    async () => Response.json({ cameras: [] }),
+    async () => Response.json([ottawaRow(1, 45.4215, -75.6972)]),
+    async () => {
+      throw new TypeError('fetch failed');
+    },
+  ]) {
+    assert.deepEqual(await loadOttawaSourcesFromOpenData({}, CERT), []);
+  }
+});
+
+test('CCTV catalog merges Ottawa cameras with a certificate and CCTV_OTTAWA_ENABLED=0 skips the request', async (t) => {
+  quiet(t);
+  const sourceRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'gev-cctv-ottawa-'));
+  t.after(() => fs.rmSync(sourceRoot, { recursive: true, force: true }));
+  withEnv(t, {
+    CCTV_SOURCES_FILE: undefined,
+    CCTV_SOURCES_JSON: undefined,
+    CCTV_FORCE_AUSTIN: undefined,
+    CCTV_PREFER_AUSTIN: undefined,
+    CCTV_MAX_SOURCES: undefined,
+    CCTV_OTTAWA_ENABLED: undefined,
+    CCTV_OTTAWA_MAX_SOURCES: undefined,
+    CCTV_QUEBEC_ENABLED: '0',
+    CCTV_WORLD_CAMERAS_ENABLED: '0',
+    OTTAWA_CAMERA_CERTIFICATE: 'CERT123',
+  });
+  const requested = [];
+  t.mock.method(globalThis, 'fetch', async (url) => {
+    requested.push(String(url));
+    // Every other live pack is down; only Ottawa answers.
+    return String(url) === OTTAWA_CAMERAS_URL
+      ? ottawaPayload([ottawaRow(1, 45.4215, -75.6972)])
+      : new Response('unavailable', { status: 503 });
+  });
+
+  const sources = await createCctvCatalog({ sourceRoot })();
+  assert.deepEqual(
+    sources.map((source) => source.id),
+    ['ottawa-1'],
+  );
+  assert.equal(sources[0].url, 'https://traffic.ottawa.ca/opendata/camera?c=1');
+
+  process.env.CCTV_OTTAWA_ENABLED = '0';
+  requested.length = 0;
+  assert.deepEqual(await createCctvCatalog({ sourceRoot })(), []);
+  assert.ok(requested.length > 0, 'the other live packs still load');
+  assert.equal(
+    requested.includes(OTTAWA_CAMERAS_URL),
+    false,
+    'a disabled pack makes no request',
+  );
+});
+
+test('Ottawa frames stay inside the city image directory', () => {
+  assert.ok(
+    pinnedCameraUrl(
+      'https://traffic.ottawa.ca/opendata/camera?c=309',
+      OTTAWA_IMAGE_ORIGIN,
+    ),
+  );
+  for (const url of [
+    'https://traffic.ottawa.ca.evil.test/opendata/camera?c=309',
+    'https://traffic.ottawa.ca/map/camera?id=309',
+    'https://user:[email protected]/opendata/camera?c=309',
+    'https://traffic.ottawa.ca:8443/opendata/camera?c=309',
+    'http://traffic.ottawa.ca/opendata/camera?c=309',
+  ])
+    assert.equal(pinnedCameraUrl(url, OTTAWA_IMAGE_ORIGIN), null, url);
+});

src/data/cctvProxy.test.mjs

@@ -313,3 +313,234 @@ test('CCTV upstream frame fetch accepts only raster image types and sends their
     assert.equal(state.cancelled, true, `${contentType}: body cancelled`);
   }
 });
+
+function multipartResponse(contentType, chunks, { onCancel = () => {} } = {}) {
+  let nextChunk = 0;
+  const body = new ReadableStream(
+    {
+      pull(controller) {
+        if (nextChunk >= chunks.length) {
+          controller.close();
+          return;
+        }
+        controller.enqueue(chunks[nextChunk++]);
+      },
+      cancel() {
+        onCancel();
+      },
+    },
+    { highWaterMark: 0 },
+  );
+  return new Response(body, {
+    status: 200,
+    headers: { 'Content-Type': contentType },
+  });
+}
+
+function jpegPart(boundary, body, contentType = 'image/jpeg', length = body.length) {
+  return Buffer.concat([
+    Buffer.from(
+      '--' +
+        boundary +
+        '\r\nContent-Type: ' +
+        contentType +
+        '\r\nContent-Length: ' +
+        length +
+        '\r\n\r\n',
+    ),
+    body,
+    Buffer.from('\r\n'),
+  ]);
+}
+
+test('CCTV upstream frame fetch extracts only the first JPEG from MJPEG', async () => {
+  const boundary = 'DIGIEVER';
+  const first = Buffer.from([0xff, 0xd8, 0x11, 0x22, 0xff, 0xd9]);
+  const second = Buffer.from([0xff, 0xd8, 0x33, 0x44, 0xff, 0xd9]);
+  for (const type of [
+    'multipart/x-mixed-replace; boundary=DIGIEVER',
+    'multipart/x-mixed-replace; boundary="DIGIEVER"',
+  ]) {
+    let cancelled = false;
+    const result = await fetchCctvImageFromUpstream(
+      'https://cctv-ss02.thb.gov.tw/T62-9K+020',
+      {
+        allowMjpeg: true,
+        maxBytes: 1024,
+        fetchImpl: async () =>
+          multipartResponse(
+            type,
+            [
+              jpegPart(boundary, first),
+              jpegPart(boundary, second),
+              Buffer.from('--' + boundary + '--\r\n'),
+            ],
+            { onCancel: () => { cancelled = true; } },
+          ),
+      },
+    );
+    assert.equal(result?.contentType, 'image/jpeg', type);
+    assert.deepEqual(result?.body, first, type);
+    assert.equal(cancelled, true, type);
+  }
+});
+
+test('CCTV upstream frame fetch rejects malformed and non-JPEG MJPEG parts', async () => {
+  const jpeg = Buffer.from([0xff, 0xd8, 0x01, 0x02, 0xff, 0xd9]);
+  for (const [type, chunks] of [
+    ['multipart/x-mixed-replace', []],
+    [
+      'multipart/x-mixed-replace; boundary=DIGIEVER',
+      [jpegPart('DIGIEVER', jpeg, 'image/png')],
+    ],
+  ]) {
+    let cancelled = false;
+    const result = await fetchCctvImageFromUpstream(
+      'https://cctv-ss02.thb.gov.tw/T62-9K+020',
+      {
+        allowMjpeg: true,
+        fetchImpl: async () =>
+          multipartResponse(type, chunks, { onCancel: () => { cancelled = true; } }),
+      },
+    );
+    assert.equal(result, null, type);
+    assert.equal(cancelled, true, type);
+  }
+});
+
+test('CCTV upstream frame fetch rejects truncated or oversized MJPEG parts', async () => {
+  const boundary = 'DIGIEVER';
+  const full = Buffer.from([0xff, 0xd8, 0x01, 0x02, 0xff, 0xd9]);
+  const truncated = Buffer.from([0xff, 0xd8, 0x01, 0x02]);
+  for (const [chunks, maxBytes] of [
+    [jpegPart(boundary, truncated, 'image/jpeg', full.length), 1024],
+    [jpegPart(boundary, full), 5],
+  ]) {
+    let cancelled = false;
+    const result = await fetchCctvImageFromUpstream(
+      'https://cctv-ss02.thb.gov.tw/T62-9K+020',
+      {
+        allowMjpeg: true,
+        maxBytes,
+        fetchImpl: async () =>
+          multipartResponse(
+            'multipart/x-mixed-replace; boundary=' + boundary,
+            [chunks],
+            { onCancel: () => { cancelled = true; } },
+          ),
+      },
+    );
+    assert.equal(result, null);
+    assert.equal(cancelled, true);
+  }
+});
+
+test('CCTV upstream frame fetch does not cross into a later part when the first JPEG is truncated', async () => {
+  const boundary = 'DIGIEVER';
+  const truncated = Buffer.from([0xff, 0xd8, 0x01, 0x02]);
+  const valid = Buffer.from([0xff, 0xd8, 0x03, 0x04, 0xff, 0xd9]);
+  const wire = Buffer.concat([
+    Buffer.from(
+      '--' + boundary + '\r\nContent-Type: image/jpeg\r\n\r\n',
+    ),
+    truncated,
+    Buffer.from(
+      '\r\n--' +
+        boundary +
+        '\r\nContent-Type: image/jpeg\r\nContent-Length: ' +
+        valid.length +
+        '\r\n\r\n',
+    ),
+    valid,
+    Buffer.from('\r\n--' + boundary + '--\r\n'),
+  ]);
+  let cancelled = false;
+
+  const result = await fetchCctvImageFromUpstream(
+    'https://cctv-ss02.thb.gov.tw/T62-9K+020',
+    {
+      allowMjpeg: true,
+      maxBytes: 1024,
+      fetchImpl: async () =>
+        multipartResponse(
+          'multipart/x-mixed-replace; boundary=' + boundary,
+          [wire],
+          { onCancel: () => { cancelled = true; } },
+        ),
+    },
+  );
+
+  assert.equal(result, null);
+  assert.equal(cancelled, true);
+});
+test('CCTV upstream frame fetch ignores MJPEG unless the source is registered as MJPEG', async () => {
+  const boundary = 'DIGIEVER';
+  const jpeg = Buffer.from([0xff, 0xd8, 0x11, 0x22, 0xff, 0xd9]);
+  let cancelled = false;
+  const result = await fetchCctvImageFromUpstream(
+    'https://cctv-ss02.thb.gov.tw/T62-9K+020',
+    {
+      fetchImpl: async () =>
+        multipartResponse(
+          'multipart/x-mixed-replace; boundary=' + boundary,
+          [jpegPart(boundary, jpeg)],
+          { onCancel: () => { cancelled = true; } },
+        ),
+    },
+  );
+  assert.equal(result, null);
+  assert.equal(cancelled, true);
+});
+
+test('CCTV upstream frame fetch accepts a CRLF preamble and a boundary that already starts with --', async () => {
+  const jpeg = Buffer.from([0xff, 0xd8, 0x11, 0x22, 0xff, 0xd9]);
+  for (const [type, wire] of [
+    [
+      'multipart/x-mixed-replace; boundary=DIGIEVER',
+      Buffer.concat([Buffer.from('\r\n'), jpegPart('DIGIEVER', jpeg)]),
+    ],
+    [
+      'multipart/x-mixed-replace; boundary=--myboundary',
+      Buffer.concat([
+        Buffer.from(
+          '--myboundary\r\nContent-Type: image/jpeg\r\nContent-Length: ' +
+            jpeg.length +
+            '\r\n\r\n',
+        ),
+        jpeg,
+        Buffer.from('\r\n--myboundary\r\n'),
+      ]),
+    ],
+  ]) {
+    const result = await fetchCctvImageFromUpstream(
+      'https://cctv-ss02.thb.gov.tw/T62-9K+020',
+      {
+        allowMjpeg: true,
+        fetchImpl: async () => multipartResponse(type, [wire]),
+      },
+    );
+    assert.deepEqual(result?.body, jpeg, type);
+  }
+});
+
+test('CCTV MJPEG part without Content-Length ends at the next delimiter, not at an inner JPEG end marker', async () => {
+  const boundary = 'DIGIEVER';
+  // An EXIF thumbnail's own FF D9 sits inside the image.
+  const jpeg = Buffer.from([0xff, 0xd8, 0x01, 0xff, 0xd9, 0x02, 0x03, 0xff, 0xd9]);
+  const wire = Buffer.concat([
+    Buffer.from('--' + boundary + '\r\nContent-Type: image/jpeg\r\n\r\n'),
+    jpeg,
+    Buffer.from('\r\n--' + boundary + '\r\nContent-Type: image/jpeg\r\n\r\n'),
+  ]);
+  // Delivered one byte at a time, as a trickling upstream would.
+  const chunks = [...wire].map((byte) => Buffer.from([byte]));
+  const result = await fetchCctvImageFromUpstream(
+    'https://cctv-ss02.thb.gov.tw/T62-9K+020',
+    {
+      allowMjpeg: true,
+      fetchImpl: async () =>
+        multipartResponse('multipart/x-mixed-replace; boundary=' + boundary, chunks),
+    },
+  );
+  assert.deepEqual(result?.body, jpeg);
+});

src/data/cctvTaiwan.test.mjs

@@ -182,6 +182,86 @@ test('loader deduplicates cameras that share a camera number', async (t) => {
   ]);
 });
 
+test('falls back to Highway Bureau MJPEG cameras when the Freeway catalog fails', async (t) => {
+  const highwayUrl = 'https://cctv-maintain.thb.gov.tw/opendataCCTVs.xml';
+  const requests = [];
+  t.mock.method(console, 'log', () => {});
+  t.mock.method(console, 'warn', () => {});
+  t.mock.method(globalThis, 'fetch', async (url, options) => {
+    const href = String(url);
+    requests.push(href);
+    assert.equal(options.redirect, 'manual');
+    if (href === TAIWAN_FREEWAY_CCTV_URL)
+      return new Response('', { status: 503 });
+    if (href === highwayUrl) {
+      return new Response(
+        cctvXml(
+          block({
+            id: 'CCTV-14-0620-009-002',
+            stream: 'https://cctv-ss02.thb.gov.tw:443/T62-9K+020',
+            lat: '24.9967',
+            lon: '121.4521',
+          }),
+        ),
+        { headers: { 'content-type': 'application/xml' } },
+      );
+    }
+    throw new Error('Unexpected Taiwan feed URL: ' + href);
+  });
+
+  const sources = await loadTaiwanSources();
+
+  assert.deepEqual(requests, [TAIWAN_FREEWAY_CCTV_URL, highwayUrl]);
+  assert.equal(sources.length, 1);
+  assert.equal(sources[0].id, 'tw-thb-cctv-14-0620-009-002');
+  assert.equal(sources[0].cityId, 'taiwan');
+  assert.equal(sources[0].provider, 'Highway Bureau, MOTC');
+  assert.equal(sources[0].feedType, 'mjpeg');
+  assert.equal(sources[0].sourceKind, 'taiwan-highway-motc');
+  assert.equal(new URL(sources[0].url).hostname, 'cctv-ss02.thb.gov.tw');
+  assert.equal(new URL(sources[0].url).pathname, '/T62-9K+020');
+});
+
+test('the Highway Bureau fallback registers only approved HTTPS camera servers', async (t) => {
+  const highwayUrl = 'https://cctv-maintain.thb.gov.tw/opendataCCTVs.xml';
+  t.mock.method(console, 'log', () => {});
+  t.mock.method(console, 'warn', () => {});
+  t.mock.method(globalThis, 'fetch', async (url) => {
+    if (String(url) === TAIWAN_FREEWAY_CCTV_URL)
+      return new Response('', { status: 503 });
+    if (String(url) === highwayUrl) {
+      return new Response(
+        cctvXml(
+          block({
+            id: 'CCTV-14-0620-009-001',
+            stream: 'https://cctv-ss09.thb.gov.tw/T62-9K+019',
+          }),
+          block({
+            id: 'CCTV-14-0620-009-003',
+            stream: 'http://cctv-ss02.thb.gov.tw/T62-9K+021',
+          }),
+          block({
+            id: 'CCTV-14-0620-009-004',
+            stream: 'https://cctv-ss02.thb.gov.tw:8443/T62-9K+022',
+          }),
+          block({
+            id: 'CCTV-14-0620-009-002',
+            stream: 'https://cctv-ss02.thb.gov.tw:443/T62-9K+020',
+          }),
+        ),
+        { headers: { 'content-type': 'application/xml' } },
+      );
+    }
+    throw new Error('Unexpected Taiwan feed URL: ' + String(url));
+  });
+
+  const sources = await loadTaiwanSources();
+
+  assert.deepEqual(
+    sources.map((source) => source.id),
+    ['tw-thb-cctv-14-0620-009-002'],
+  );
+});
 test('a redirected or failed catalog contributes an empty pack', async (t) => {
   t.mock.method(console, 'warn', () => {});
   for (const status of [302, 503]) {
@@ -214,13 +294,17 @@ test('the Taiwan pack is in the catalog by default', async (t) => {
   );
 });
 
-test('CCTV_TAIWAN_ENABLED=0 makes no Freeway Bureau request', async (t) => {
+test('CCTV_TAIWAN_ENABLED=0 makes no Taiwan catalog request', async (t) => {
   const { requested, sources } = await runCatalogWithTaiwanFlag(t, '0');
   assert.ok(requested.length > 0, 'the other packs still refreshed');
   assert.equal(
     requested.some((href) => href.includes('freeway.gov.tw')),
     false,
   );
+  assert.equal(
+    requested.some((href) => href.includes('cctv-maintain.thb.gov.tw')),
+    false,
+  );
   assert.ok(!sources.some((c) => c.cityId === 'taiwan'));
 });
 
@@ -250,12 +334,12 @@ test('a failed download is not retried until the backoff ends', async (t) => {
   t.mock.method(Date, 'now', () => 1_000_000);
   assert.deepEqual(await loadTaiwanSources(), []);
   assert.deepEqual(await loadTaiwanSources(), []);
-  assert.equal(calls, 1, 'the second refresh made no request');
+  assert.equal(calls, 2, 'the second refresh made no request');
   Date.now.mock.mockImplementation(
     () => 1_000_000 + TAIWAN_RETRY_AFTER_FAILURE_MS + 1,
   );
   await loadTaiwanSources();
-  assert.equal(calls, 2, 'the backoff ends after an hour');
+  assert.equal(calls, 4, 'the backoff ends after an hour');
 });
 
 test('a failed download serves the last good table', async (t) => {

src/data/cctvToronto.test.mjs

@@ -10,7 +10,7 @@ import {
   TORONTO_RESCU_LIST_URL,
   TORONTO_RESCU_IMAGE_ORIGIN,
   TORONTO_MAX_CATALOG_BYTES,
-  DEFAULT_CCTV_MAX_SOURCES,
+  CCTV_SHARED_SOURCE_SLOTS,
 } from '../../server/providers/cctv/constants.js';
 import { CAMERA_CODE_MAX_CHARS } from '../../server/providers/cctv/normalize.js';
 import { allocateSourceCap } from '../../server/providers/cctv/cap.js';
@@ -418,6 +418,6 @@ test('CCTV_TORONTO_ENABLED=0 keeps the lane from being loaded at all', async (t)
   }
 });
 
-test('the shipped catalog ceiling is not raised to make room for this pack', () => {
-  assert.equal(DEFAULT_CCTV_MAX_SOURCES, 4000);
+test('the shared catalog slots are not raised to make room for this pack', () => {
+  assert.equal(CCTV_SHARED_SOURCE_SLOTS, 4000);
 });

src/data/cctvWorldQuebec.test.mjs

@@ -0,0 +1,316 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import {
+  DEFAULT_WORLD_CCTV_SOURCE_FILE,
+  WORLD_CCTV_SOURCE_COUNT,
+} from '../../server/providers/cctv/constants.js';
+import {
+  isMlitRiverAdjustmentImage,
+  loadWorldCameraSources,
+} from '../../server/providers/cctv/worldCameras.js';
+import {
+  loadQuebecSources,
+  QUEBEC_CAMERA_SOURCE_COUNT,
+  quebec511VideoUrl,
+  quebecBrowserVideoEnabled,
+} from '../../server/providers/cctv/quebec.js';
+import { cctvProxy } from '../../server/providers/cctv.js';
+
+const REPO_ROOT = path.resolve(import.meta.dirname, '../..');
+const JPEG = Buffer.from([0xff, 0xd8, 0xff, 0xe0, 0x00, 0x10, 0xff, 0xd9]);
+
+/** Silence the loaders' progress and failure logging. */
+function quiet(t) {
+  t.mock.method(console, 'log', () => {});
+  t.mock.method(console, 'warn', () => {});
+}
+
+/** Set (or, for `undefined`, delete) environment variables for one test. */
+function withEnv(t, env) {
+  for (const [name, value] of Object.entries(env)) {
+    const previous = process.env[name];
+    t.after(() => {
+      if (previous === undefined) delete process.env[name];
+      else process.env[name] = previous;
+    });
+    if (value === undefined) delete process.env[name];
+    else process.env[name] = value;
+  }
+}
+
+/** A temporary source root holding the given World and Québec catalogs. */
+function sourceRoot(t, { world = [], quebec = null } = {}) {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'gev-cctv-world-'));
+  t.after(() => fs.rmSync(root, { recursive: true, force: true }));
+  const worldFile = path.join(root, DEFAULT_WORLD_CCTV_SOURCE_FILE);
+  fs.mkdirSync(path.dirname(worldFile), { recursive: true });
+  fs.writeFileSync(worldFile, JSON.stringify(world));
+  if (quebec) {
+    fs.mkdirSync(path.join(root, 'public'), { recursive: true });
+    fs.writeFileSync(
+      path.join(root, 'public/quebec-cameras.json'),
+      JSON.stringify({ cameras: quebec }),
+    );
+  }
+  return root;
+}
+
+const oregonRow = (overrides = {}) => ({
+  id: 'world-or-764',
+  name: '3rd St at Harwood MP18.35',
+  provider: 'TripCheck (ODOT)',
+  lat: 44.3029,
+  lon: -120.8549,
+  sourceKind: 'tripcheck-odot',
+  url: 'https://www.tripcheck.com/roadcams/cams/Harwood_pid3527.jpg',
+  snapshotUrl: 'https://www.tripcheck.com/roadcams/cams/Harwood_pid3527.jpg',
+  ...overrides,
+});
+
+test('the shipped World catalog loads every curated row', (t) => {
+  quiet(t);
+  const sources = loadWorldCameraSources({ sourceRoot: REPO_ROOT });
+  assert.equal(sources.length, WORLD_CCTV_SOURCE_COUNT);
+  const byKind = Object.groupBy(sources, (source) => source.sourceKind);
+  // Iceland comes from the live Iceland pack, never a second World copy.
+  assert.equal(byKind['vegagerdin-road'], undefined);
+  assert.equal(byKind['tripcheck-odot'].length, 1176);
+  assert.equal(byKind['mlit-river'].length, 1054);
+  for (const source of byKind['mlit-river'])
+    assert.equal(source.frameRefreshMs, 10 * 60 * 1000);
+});
+
+test('the World loader accepts a pinned row and rejects anything outside its policy', (t) => {
+  quiet(t);
+  const rejected = [
+    ['unknown kind', { sourceKind: 'nzta-journeys' }],
+    [
+      'Iceland duplicates the Iceland pack',
+      {
+        sourceKind: 'vegagerdin-road',
+        lat: 64.291877,
+        lon: -15.028035,
+        url: 'https://www.vegagerdin.is/vgdata/vefmyndavelar/almannaskard_1.jpg',
+        snapshotUrl: 'https://www.vegagerdin.is/vgdata/vefmyndavelar/almannaskard_1.jpg',
+      },
+    ],
+    ['wrong id prefix', { id: 'world-jp-river-7075' }],
+    ['outside bounds', { lat: 40, lon: -15 }],
+    ['other host', { url: 'https://evil.test/roadcams/cams/a.jpg' }],
+    ['other directory', { url: 'https://www.tripcheck.com/other/a.jpg' }],
+    ['query string', { url: oregonRow().url + '?x=1' }],
+    ['not a jpg', { url: 'https://www.tripcheck.com/roadcams/cams/a.png' }],
+    ['plain http', { url: oregonRow().url.replace('https:', 'http:') }],
+    [
+      'url and snapshot differ',
+      { snapshotUrl: 'https://www.tripcheck.com/roadcams/cams/b.jpg' },
+    ],
+  ];
+  const root = sourceRoot(t, {
+    world: [
+      oregonRow(),
+      oregonRow(), // duplicate id
+      ...rejected.map(([, overrides], i) =>
+        oregonRow({ id: `world-or-${9000 + i}`, ...overrides }),
+      ),
+    ],
+  });
+  const sources = loadWorldCameraSources({ sourceRoot: root });
+  assert.deepEqual(
+    sources.map((source) => source.id),
+    ['world-or-764'],
+  );
+  assert.equal(sources[0].frameRefreshMs, 5 * 60 * 1000);
+  assert.equal(sources[0].feedType, 'image');
+});
+
+test('the World loader fails soft on a missing or malformed catalog', (t) => {
+  quiet(t);
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'gev-cctv-world-'));
+  t.after(() => fs.rmSync(root, { recursive: true, force: true }));
+  assert.deepEqual(loadWorldCameraSources({ sourceRoot: root }), []);
+  const file = path.join(root, DEFAULT_WORLD_CCTV_SOURCE_FILE);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, '{not json');
+  assert.deepEqual(loadWorldCameraSources({ sourceRoot: root }), []);
+});
+
+test('only the exact MLIT adjustment image is recognised', () => {
+  assert.equal(isMlitRiverAdjustmentImage({ ok: true, body: JPEG }), false);
+  assert.equal(isMlitRiverAdjustmentImage(null), false);
+  assert.equal(isMlitRiverAdjustmentImage({ ok: false, body: JPEG }), false);
+});
+
+test('the shipped Québec catalog loads every location', (t) => {
+  quiet(t);
+  const sources = loadQuebecSources({ sourceRoot: REPO_ROOT });
+  assert.equal(sources.length, QUEBEC_CAMERA_SOURCE_COUNT);
+  for (const source of sources) {
+    assert.equal(source.url, '', 'the server never fetches Québec media');
+    assert.equal(source.snapshotUrl, '');
+  }
+});
+
+test('the Québec loader maps ids by kind, keeps https viewer links, and splits the MTQ credit', (t) => {
+  quiet(t);
+  const at = { lat: 45.51651, lon: -73.5502 };
+  const root = sourceRoot(t, {
+    quebec: [
+      { id: '3735', kind: 'traffic', name: 'Route 136', viewerUrl: 'https://www.quebec511.info/Carte/Fenetres/FenetreVideo.html?id=3735', ...at },
+      { id: 'mtl-465', kind: 'montreal', name: 'Montréal 465', viewerUrl: 'http://ville.montreal.qc.ca/x', ...at },
+      { id: 'web-1', kind: 'webcam', name: 'Tremblant', operator: 'Station Mont-Tremblant', viewerUrl: 'https://user:[email protected]/', ...at },
+      { id: 'abc', kind: 'traffic', ...at }, // non-numeric traffic id
+      { id: '3735', kind: 'traffic', ...at }, // duplicate
+      { id: '9', kind: 'traffic', lat: 40, lon: -73.5 }, // outside Québec
+    ],
+  });
+  const sources = loadQuebecSources({ sourceRoot: root });
+  const byId = new Map(sources.map((source) => [source.id, source]));
+  assert.deepEqual([...byId.keys()], ['qc-511-3735', 'qc-mtl-465', 'qc-web-1']);
+
+  const mtq = byId.get('qc-511-3735');
+  assert.equal(mtq.sourceKind, 'quebec-511-browser');
+  assert.match(mtq.credit, /Locations: MTQ · CC BY 4\.0/);
+  assert.match(mtq.credit, /Video: Québec 511/);
+  assert.doesNotMatch(mtq.license, /^Données Québec \/ MTQ, CC BY 4\.0$/);
+  assert.equal(byId.get('qc-mtl-465').sourceUrl, '', 'http viewer links are dropped');
+  assert.equal(byId.get('qc-web-1').sourceUrl, '', 'credentialed links are dropped');
+  assert.equal(
+    quebec511VideoUrl('qc-511-3735'),
+    'https://www.quebec511.info/Carte/Fenetres/camera.ashx?id=3735&format=mp4',
+  );
+  assert.equal(quebec511VideoUrl('qc-mtl-465'), '');
+});
+
+test('Québec 511 browser video is opt-in', () => {
+  assert.equal(quebecBrowserVideoEnabled({}), false);
+  assert.equal(quebecBrowserVideoEnabled({ CCTV_QUEBEC_VIDEO_ENABLED: '0' }), false);
+  assert.equal(quebecBrowserVideoEnabled({ CCTV_QUEBEC_VIDEO_ENABLED: ' 1 ' }), true);
+});
+
+/** Mount the real proxy with a fixed fetch, and drive requests through it. */
+function mount(t, root, respond) {
+  withEnv(t, {
+    CCTV_SOURCES_FILE: 'absent-source-file.json',
+    CCTV_SOURCES_JSON: undefined,
+    CCTV_FORCE_AUSTIN: '0',
+    CCTV_MAX_SOURCES: undefined,
+    // A configured key makes any Street View fallback observable.
+    GOOGLE_MAPS_SERVER_API_KEY: 'test-google-key',
+  });
+  const requests = [];
+  t.mock.method(globalThis, 'fetch', async (url, init = {}) => {
+    requests.push(String(url));
+    return respond(String(url), init) || new Response('down', { status: 503 });
+  });
+  let handler;
+  cctvProxy({ sourceRoot: root }).configureServer({
+    middlewares: {
+      use(_route, fn) {
+        handler = fn;
+      },
+    },
+  });
+  const call = async (url) => {
+    const res = {
+      writeHead(status, headers) {
+        Object.assign(this, { status, headers });
+      },
+      end(body) {
+        this.body = body;
+      },
+      on() {},
+      once() {},
+    };
+    await handler({ url, method: 'GET', headers: {}, on() {} }, res);
+    return res;
+  };
+  return { call, requests };
+}
+
+test('/sources lists Québec browser media only when the operator opts in', async (t) => {
+  quiet(t);
+  const root = sourceRoot(t, {
+    quebec: [{ id: '3735', kind: 'traffic', name: 'Route 136', lat: 45.5, lon: -73.5 }],
+  });
+  withEnv(t, { CCTV_QUEBEC_VIDEO_ENABLED: undefined });
+  const app = mount(t, root, () => null);
+  const off = JSON.parse((await app.call('/sources')).body).sources;
+  assert.equal(off.find((s) => s.id === 'qc-511-3735').browserMediaUrl, '');
+
+  process.env.CCTV_QUEBEC_VIDEO_ENABLED = '1';
+  const on = JSON.parse((await app.call('/sources')).body).sources;
+  assert.match(on.find((s) => s.id === 'qc-511-3735').browserMediaUrl, /camera\.ashx\?id=3735&format=mp4$/);
+});
+
+test('a World frame is fetched once per refresh floor and the cooldown never spends Street View', async (t) => {
+  quiet(t);
+  const root = sourceRoot(t, { world: [oregonRow()] });
+  let answer = () => new Response(JPEG, { headers: { 'content-type': 'image/jpeg' } });
+  const app = mount(t, root, (url) =>
+    url === oregonRow().url ? answer() : null,
+  );
+  const frame = '/frame/world-or-764';
+  const upstreamHits = () =>
+    app.requests.filter((url) => url === oregonRow().url).length;
+
+  const first = await app.call(frame);
+  assert.equal(first.headers['X-CCTV-Source'], 'upstream-image');
+  const second = await app.call(frame);
+  assert.equal(second.headers['X-CCTV-Source'], 'upstream-image');
+  assert.equal(upstreamHits(), 1, 'the second view reuses the cached frame');
+
+  // A camera whose first fetch fails is inside its failure backoff: it gets
+  // the placeholder, not Google Street View, and no second upstream request.
+  const failRoot = sourceRoot(t, { world: [oregonRow()] });
+  answer = () => new Response('down', { status: 503 });
+  const failing = mount(t, failRoot, (url) =>
+    url === oregonRow().url ? answer() : null,
+  );
+  const failed = await failing.call(frame);
+  assert.notEqual(failed.headers['X-CCTV-Source'], 'upstream-image');
+  const retry = await failing.call(frame);
+  assert.equal(retry.headers['X-CCTV-Source'], 'synthetic');
+  assert.equal(
+    failing.requests.filter((url) => url === oregonRow().url).length,
+    1,
+    'the backoff holds the provider cadence',
+  );
+  assert.equal(
+    failing.requests.filter((url) => url.includes('maps.googleapis.com/maps/api/streetview')).length,
+    1,
+    'only the first miss, outside any cooldown, may try Street View',
+  );
+});
+
+test('Ottawa frames are signed with the certificate at fetch time only', async (t) => {
+  quiet(t);
+  const root = sourceRoot(t);
+  withEnv(t, { OTTAWA_CAMERA_CERTIFICATE: 'CERT123' });
+  const app = mount(t, root, (url) => {
+    if (url === 'https://traffic.ottawa.ca/map/service/camera')
+      return Response.json({
+        cameras: [
+          { camera_number: 16, name: 'Bank & Hunt Club', latitude: 45.35, longitude: -75.65, cameraOwner: 'CITY' },
+        ],
+      });
+    if (url.startsWith('https://traffic.ottawa.ca/opendata/camera'))
+      return new Response(JPEG, { headers: { 'content-type': 'image/jpeg' } });
+    return null;
+  });
+  const sources = JSON.parse((await app.call('/sources')).body).sources;
+  const ottawa = sources.find((source) => source.id === 'ottawa-16');
+  assert.ok(ottawa);
+  assert.doesNotMatch(JSON.stringify(sources), /CERT123/, 'no catalog field carries the certificate');
+
+  const frame = await app.call('/frame/ottawa-16');
+  assert.equal(frame.headers['X-CCTV-Source'], 'upstream-image');
+  await app.call('/frame/ottawa-16');
+  const hits = app.requests.filter((url) => url.includes('/opendata/camera'));
+  assert.deepEqual(hits, [
+    'https://traffic.ottawa.ca/opendata/camera?c=16&certificate=CERT123&id=gev',
+  ], 'one signed request per camera per minute');
+});

src/data/dataCredits.js

@@ -34,6 +34,14 @@ export const OPENMAPTILES_CREDIT = {
   html: 'Vector tiles: <a href="https://openfreemap.org" target="_blank" rel="noopener">OpenFreeMap</a> © <a href="https://openmaptiles.org" target="_blank" rel="noopener">OpenMapTiles</a>',
 };
 
+/** Conditional Salish Sea coverage; registered when its sightings first render. */
+export const ACARTIA_CREDIT = Object.freeze({
+  key: 'acartia',
+  html:
+    'Wildlife sightings: <a href="https://acartia.io" target="_blank" rel="noopener">Acartia</a> (CC BY 4.0; each provider credited per sighting) · ' +
+    '<a href="https://www.bewhalewise.org" target="_blank" rel="noopener">Be Whale Wise</a>',
+});
+
 const osmDisplays = new WeakMap();
 
 function updateOsmDisplay(viewer, state) {
@@ -135,10 +143,23 @@ export const DATA_CREDITS = [
   {
     key: 'celestrak',
     html:
-      'Satellites (TLEs): CelesTrak ' +
+      'Satellites (TLEs and SATCAT): CelesTrak ' +
       '(<a href="https://celestrak.org" target="_blank" rel="noopener">celestrak.org</a>), ' +
       'Dr. T.S. Kelso',
   },
+  {
+    key: 'ucs-satellite-database',
+    html:
+      'Satellite operators and purposes: ' +
+      '<a href="https://www.ucsusa.org/satellite_database" target="_blank" rel="noopener">UCS Satellite Database</a> ' +
+      '(UCS-Satellite-Database 5-1-2023), Union of Concerned Scientists',
+  },
+  {
+    key: 'imaging-sensors',
+    html:
+      'Imaging sensor swaths: operator and agency specifications, ' +
+      'cited per platform',
+  },
   {
     key: 'launch-library-2',
     html:
@@ -188,6 +209,10 @@ export const DATA_CREDITS = [
       '<a href="https://adds-faa.opendata.arcgis.com/" target="_blank" rel="noopener">FAA Special Use Airspace</a>' +
       ' (prohibited and restricted zones; informational only)',
   },
+  {
+    key: 'inaturalist',
+    html: 'Wildlife sightings: <a href="https://www.inaturalist.org" target="_blank" rel="noopener">iNaturalist</a> contributors (licences per record; photos credited on each card)',
+  },
   OSM_CREDIT,
   OPENMAPTILES_CREDIT,
   {
@@ -287,6 +312,38 @@ export const DATA_CREDITS = [
       'CCTV static data (MOTC 2.0), released under the ' +
       '<a href="https://data.gov.tw/license" target="_blank" rel="noopener">Open Government Data License, Taiwan (Version 1.0)</a>',
   },
+  {
+    key: 'ottawa-cctv',
+    html:
+      'Traffic cameras (Ottawa, with an access certificate): ' +
+      '<a href="https://traffic.ottawa.ca/en/traffic-map-data-lists-and-resources/about-the-data" target="_blank" rel="noopener">City of Ottawa Traffic Camera Images API</a>',
+  },
+  {
+    key: 'quebec-cctv',
+    html:
+      'Camera locations (Québec): Ministère des Transports et de la Mobilité durable via ' +
+      '<a href="https://www.donneesquebec.ca/" target="_blank" rel="noopener">Données Québec</a> ' +
+      '(<a href="https://creativecommons.org/licenses/by/4.0/" target="_blank" rel="noopener">CC BY 4.0</a>); ' +
+      'Montréal camera locations © OpenStreetMap contributors (ODbL). ' +
+      'Video (when enabled) and linked webcam pages stay with ' +
+      '<a href="https://www.quebec511.info/" target="_blank" rel="noopener">Québec 511</a> and each operator, under their own terms',
+  },
+  {
+    key: 'tripcheck-cctv',
+    html:
+      'Road camera stills (Oregon): camera courtesy of ODOT, via ' +
+      '<a href="https://www.tripcheck.com/" target="_blank" rel="noopener">TripCheck</a>; ' +
+      'partner cameras (counties, cities, Caltrans, WSDOT) are named in the camera label',
+  },
+  {
+    key: 'mlit-river-cctv',
+    html:
+      'River camera stills (Japan): 出典：国土交通省 ' +
+      '<a href="https://www.river.go.jp/" target="_blank" rel="noopener">川の防災情報</a> ' +
+      '(Ministry of Land, Infrastructure, Transport and Tourism; ' +
+      '<a href="https://www.river.go.jp/kawabou/kwb_apend/html/caution.html" target="_blank" rel="noopener">terms</a>), ' +
+      'fetched on view, at most every ten minutes per camera',
+  },
   {
     key: 'calgary-cctv',
     html:
@@ -309,6 +366,15 @@ export const DATA_CREDITS = [
       '(Llicència oberta d’ús d’informació - Catalunya); some cameras are supplied by partners ' +
       '(Ajuntament de Barcelona, Ajuntament de Terrassa), each named in the CCTV panel',
   },
+  {
+    key: 'iceland-cctv',
+    html:
+      'CCTV cameras &amp; frames (Iceland): road camera images, fetched live, from the ' +
+      '<a href="https://www.vegagerdin.is/" target="_blank" rel="noopener">Icelandic Road and Coastal Administration (Vegagerðin)</a> — ' +
+      '<a href="https://creativecommons.org/licenses/by/4.0/" target="_blank" rel="noopener">CC BY 4.0</a> ' +
+      '(<a href="https://www.vegagerdin.is/vegagerdin/gagnasafn/vefthjonustur/terms-and-conditions" target="_blank" rel="noopener">terms</a>); ' +
+      'no endorsement by IRCA is implied',
+  },
   {
     key: 'kingcounty-cctv',
     html:
@@ -333,6 +399,14 @@ export const DATA_CREDITS = [
       '<a href="https://data.gov.hk/en-data/dataset/hk-td-tis_2-traffic-snapshot-images" target="_blank" rel="noopener">Transport Department / DATA.GOV.HK</a> ' +
       '(<a href="https://data.gov.hk/en/terms-and-conditions" target="_blank" rel="noopener">Terms of Use</a> — attribution required)',
   },
+  {
+    key: 'webcamromania-cctv',
+    html:
+      'Giroc camera (when configured): ' +
+      '<a href="https://webcamromania.ro/webcam-orase/webcam-giroc/" target="_blank" rel="noopener">Webcam Romania</a>. ' +
+      'Video rights remain with the camera operator; ' +
+      '<a href="https://webcamromania.ro/termeni-si-conditii/" target="_blank" rel="noopener">provider terms</a> apply.',
+  },
   {
     key: 'vegvesen-cctv',
     html:
@@ -599,20 +673,40 @@ export const OSM_PLACES_CREDIT = {
 /**
  * Per-feed transit credit, registered the first time that feed's vehicles
  * render (see `src/data/transitFeeds.js` for the license of each).
- * @param {{ id: string, attribution: string, license: string, licenseUrl: string }} feed
+ *
+ * Two optional registry fields serve licences that ask for more than a name:
+ * `sourceUrl` links the attribution to the publisher (Warsaw asks for a link
+ * to its API), and `creditDated` adds the UTC date of the data, from the feed
+ * header or else the fetch time (Warsaw and Poznań ask for the download or
+ * update date). A dated credit is keyed by its date, so a new day registers a
+ * new line instead of keeping yesterday's.
+ * @param {{ id: string, attribution: string, license: string, licenseUrl: string,
+ *   sourceUrl?: string, creditDated?: boolean }} feed
+ * @param {{ feedTimestamp?: number|null, fetchedAt?: number|null }} [snapshot]
+ *   `feedTimestamp` in epoch seconds, `fetchedAt` in epoch ms.
  * @returns {{ key: string, html: string }}
  */
-export function transitFeedCredit(feed) {
+export function transitFeedCredit(feed, snapshot = null) {
   const escape = (text) =>
     String(text)
       .replaceAll('&', '&amp;')
       .replaceAll('<', '&lt;')
       .replaceAll('>', '&gt;')
       .replaceAll('"', '&quot;');
+  const source = feed.sourceUrl
+    ? `<a href="${escape(feed.sourceUrl)}" target="_blank" rel="noopener">${escape(feed.attribution)}</a>`
+    : escape(feed.attribution);
+  const dataMs = Number.isFinite(snapshot?.feedTimestamp)
+    ? snapshot.feedTimestamp * 1000
+    : snapshot?.fetchedAt;
+  const date =
+    feed.creditDated === true && Number.isFinite(dataMs) && dataMs > 0
+      ? new Date(dataMs).toISOString().slice(0, 10)
+      : null;
   return {
-    key: `transit-${feed.id}`,
+    key: date ? `transit-${feed.id}-${date}` : `transit-${feed.id}`,
     html:
-      `Transit (${escape(feed.attribution)}): ` +
+      `Transit (${source}${date ? `, data of ${date}` : ''}): ` +
       `<a href="${escape(feed.licenseUrl)}" target="_blank" rel="noopener">${escape(feed.license)}</a>`,
   };
 }

src/data/dataCredits.test.mjs

@@ -1,6 +1,11 @@
 import { test } from 'node:test';
 import assert from 'node:assert/strict';
-import { DATA_CREDITS, NYC_DOT_DISCLAIMER } from './dataCredits.js';
+import {
+  DATA_CREDITS,
+  NYC_DOT_DISCLAIMER,
+  transitFeedCredit,
+} from './dataCredits.js';
+import { getTransitFeed } from './transitFeeds.js';
 
 test('every credit carries a unique key and some markup to render', () => {
   const keys = DATA_CREDITS.map((entry) => entry.key);
@@ -38,6 +43,29 @@ test('adsbdb is credited and carries its published route-data restriction', () =
   assert.match(credit.html, /href="https:\/\/www\.adsbdb\.com"/);
 });
 
+test('the UCS Satellite Database is acknowledged with its version and webpage', () => {
+  // UCS database manual, section 3: references name the version (the Excel
+  // file's name) and link www.ucsusa.org/satellite_database.
+  const credit = DATA_CREDITS.find(
+    (entry) => entry.key === 'ucs-satellite-database',
+  );
+  assert.ok(credit, 'the satellite classes and operators come from UCS');
+  assert.match(credit.html, /UCS-Satellite-Database 5-1-2023/);
+  assert.match(
+    credit.html,
+    /href="https:\/\/www\.ucsusa\.org\/satellite_database"/,
+  );
+});
+
+test('the imaging sensor swaths credit operator and agency specifications', () => {
+  // Each sensor-pack entry cites its operator's or agency's own pages;
+  // no aggregator database is credited.
+  const credit = DATA_CREDITS.find((entry) => entry.key === 'imaging-sensors');
+  assert.ok(credit, 'the orbital zoom caps come from the sensor pack');
+  assert.match(credit.html, /operator and agency specifications/);
+  assert.doesNotMatch(credit.html, /OSCAR|wmo\.int/);
+});
+
 test('OpenStreetMap has one generic data credit with separate tile and names distributors', () => {
   const osm = DATA_CREDITS.filter((entry) =>
     entry.html.includes('openstreetmap.org/copyright'),
@@ -153,3 +181,38 @@ test('every Street Level imagery source is in the attribution lightbox', () => {
       `${key} has no credit`,
     );
 });
+
+test('the PR #1506 camera packs are credited with their sources and terms', () => {
+  const html = (key) => DATA_CREDITS.find((entry) => entry.key === key)?.html;
+  assert.match(html('ottawa-cctv') || '', /traffic\.ottawa\.ca/);
+  assert.match(html('quebec-cctv') || '', /CC BY 4\.0/);
+  assert.match(html('quebec-cctv') || '', /OpenStreetMap contributors/);
+  assert.match(html('tripcheck-cctv') || '', /courtesy of ODOT/);
+  // MLIT's terms ask for the source in this form, with the page link.
+  assert.match(html('mlit-river-cctv') || '', /出典：国土交通省/);
+  assert.match(
+    html('mlit-river-cctv') || '',
+    /href="https:\/\/www\.river\.go\.jp\//,
+  );
+});
+
+test('Warsaw and Poznań credits carry the data date their licences ask for', () => {
+  const warsaw = getTransitFeed('ztm-warszawa');
+  // 2026-11-09T06:00:00Z as a GTFS-RT header timestamp (seconds).
+  const credit = transitFeedCredit(warsaw, { feedTimestamp: 1_794_204_000 });
+  assert.match(credit.html, /, data of 2026-11-09\)/);
+  assert.match(credit.html, /href="http:\/\/api\.um\.warszawa\.pl"/);
+  assert.equal(credit.key, 'transit-ztm-warszawa-2026-11-09');
+  // Without a feed timestamp the fetch time is the download date.
+  const poznan = transitFeedCredit(getTransitFeed('ztm-poznan'), {
+    feedTimestamp: null,
+    fetchedAt: Date.UTC(2026, 10, 10, 12),
+  });
+  assert.match(poznan.html, /data of 2026-11-10/);
+  // Undated feeds keep one credit line for the session.
+  const mbta = transitFeedCredit(getTransitFeed('mbta'), {
+    feedTimestamp: 1_794_204_000,
+  });
+  assert.equal(mbta.key, 'transit-mbta');
+  assert.doesNotMatch(mbta.html, /data of/);
+});

src/data/firmsCards.test.mjs

@@ -45,7 +45,7 @@ test('buildFireCard: title carries FRP, detail carries conf/age/satellite', () =
   assert.equal(card.details.length, 1);
   assert.equal(card.details[0], 'high · 2h · N20');
   assert.equal(card.selected, false);
-  assert.equal(card.accent, accentForSeverity('red'), 'FRP 1520 is red-hot');
+  assert.equal(card.accent, accentForSeverity('white-hot'), 'FRP 1520 is white-hot');
   assert.deepEqual(card.position, { x: 1, y: 2, z: 3 }, 'uses the candidate position untouched');
 });
 
@@ -69,11 +69,27 @@ test('buildFireCard: power that rounds to 10 MW drops the decimal', () => {
   assert.equal(selected.title, 'FIRE · 10 MW');
 });
 
-test('buildFireCard: SNPP satellite code renders as SNPP, weak fire is not red', () => {
+test('buildFireCard: SNPP satellite code renders as SNPP, weak fire is an ember', () => {
   const card = buildFireCard({ fire: fire({ satellite: 'N', frp: 0.8, confidence: 0.3 }), position: {} }, NOW);
   assert.match(card.details[0], /SNPP$/);
   assert.equal(card.title, '▲ 0.8 MW');
-  assert.notEqual(card.accent, accentForSeverity('red'));
+  assert.equal(card.accent, accentForSeverity('ember'));
+});
+
+test('buildFireCard: accent steps through the FRP ramp at 5 · 20 · 50 · 100 · 300 MW', () => {
+  const accentAt = (frp) =>
+    buildFireCard({ fire: fire({ frp }), position: {} }, NOW).accent;
+  assert.equal(accentAt(4.9), accentForSeverity('ember'));
+  assert.equal(accentAt(5), accentForSeverity('red'));
+  assert.equal(accentAt(20), accentForSeverity('flame'));
+  assert.equal(accentAt(50), accentForSeverity('orange'));
+  assert.equal(accentAt(100), accentForSeverity('gold'));
+  assert.equal(accentAt(300), accentForSeverity('white-hot'));
+  // Confidence never moves the color: a low-confidence 864 MW fire stays red.
+  assert.equal(
+    buildFireCard({ fire: fire({ frp: 864, confidence: 0.3 }), position: {} }, NOW).accent,
+    accentForSeverity('white-hot'),
+  );
 });
 
 test('buildSelectedFireCard: full detail card with coords, selected flag, no fade', () => {
@@ -93,12 +109,12 @@ test('buildCellCard: plural noun, max FRP and newest age, accent passthrough', (
   const candidate = {
     cell: { count: 14, maxFrp: 210.4, newestAcqMs: NOW - 3 * H, night: 2 },
     position: { x: 0, y: 0, z: 0 },
-    accent: accentForSeverity('orange'),
+    accent: accentForSeverity('gold'),
   };
   const card = buildCellCard(candidate, NOW);
   assert.equal(card.title, '14 FIRES');
   assert.equal(card.details[0], 'max 210 MW · new 3h');
-  assert.equal(card.accent, accentForSeverity('orange'));
+  assert.equal(card.accent, accentForSeverity('gold'));
 });
 
 test('buildCellCard: the count picks the plural form of the language', () => {
@@ -150,7 +166,7 @@ test('buildCellCard: singular noun and missing-age omission', () => {
   const card = buildCellCard(candidate, NOW);
   assert.equal(card.title, '1 FIRE');
   assert.equal(card.details[0], 'max 9.9 MW');
-  assert.equal(card.accent, accentForSeverity('yellow'), 'missing accent defaults to yellow');
+  assert.equal(card.accent, accentForSeverity('ember'), 'missing accent defaults to the weakest stop');
 });
 
 test('FIRMS host policy keeps ambient cards bounded and selected cards protected', () => {

src/data/firmsHeatRaster.js

@@ -0,0 +1,209 @@
+/**
+ * Snap Map–style heat raster for the Active Fires far-zoom bands: detections
+ * are linearly binned on an equirectangular grid (row 0 = north, column
+ * 0 = 180°W), blurred, normalized on a log scale and mapped through
+ * HEAT_PALETTE. Pure: no Cesium, no DOM, so the whole pipeline is unit-tested
+ * in node.
+ */
+
+/** Below this normalized heat nothing is painted: empty land stays empty. */
+export const HEAT_FLOOR = 0.03;
+
+/**
+ * The FRP marker ramp as a continuous glow, from a red edge through orange
+ * and gold to a pale white-hot core. The edge is a bright red, not the
+ * markers' dark ember, and starts more than half opaque: most of the world
+ * sits low on a scale set by the hottest regions, and a dark translucent red
+ * vanishes into forest and savanna imagery.
+ */
+export const HEAT_PALETTE = Object.freeze([
+  { at: 0.0, rgb: [232, 58, 30], alpha: 0 },
+  { at: 0.08, rgb: [232, 58, 30], alpha: 0.58 },
+  { at: 0.25, rgb: [242, 86, 34], alpha: 0.7 },
+  { at: 0.45, rgb: [248, 122, 40], alpha: 0.76 },
+  { at: 0.65, rgb: [252, 166, 52], alpha: 0.82 },
+  { at: 0.82, rgb: [254, 208, 92], alpha: 0.87 },
+  { at: 1.0, rgb: [255, 245, 190], alpha: 0.92 },
+]);
+
+export function heatColorAt(t) {
+  if (!(t > HEAT_FLOOR)) return [0, 0, 0, 0];
+  const v = Math.min(1, t);
+  let i = 1;
+  while (i < HEAT_PALETTE.length - 1 && HEAT_PALETTE[i].at < v) i += 1;
+  const a = HEAT_PALETTE[i - 1];
+  const b = HEAT_PALETTE[i];
+  const k = (v - a.at) / (b.at - a.at || 1);
+  const mix = (p, q) => Math.round(p + (q - p) * k);
+  return [
+    mix(a.rgb[0], b.rgb[0]),
+    mix(a.rgb[1], b.rgb[1]),
+    mix(a.rgb[2], b.rgb[2]),
+    Math.round((a.alpha + (b.alpha - a.alpha) * k) * 255),
+  ];
+}
+
+/** Weight of a detection with no or zero FRP, in megawatts. */
+export const HEAT_MIN_WEIGHT_MW = 0.5;
+
+/**
+ * Heat is radiated power, not a head count: each detection adds its FRP in
+ * megawatts. Weak fires carry little power, so raising the minimum-FRP slider
+ * removes most detections without dimming the areas where strong fires burn
+ * (a count-based heat collapsed there and the hot spots faded).
+ */
+const defaultWeight = (fire) =>
+  Math.max(HEAT_MIN_WEIGHT_MW, Number(fire.frp) || 0);
+
+/**
+ * Linear binning (Wand 1994): each detection's weight is shared between the
+ * four pixel centres around it in proportion to closeness, instead of
+ * dropping whole into one pixel. Spots then sit at the true position rather
+ * than snapping by up to half a pixel (~10 km), and a lone weak fire blurs
+ * into a round spot instead of a square or a plus sign. Longitude wraps;
+ * rows beyond the poles fold back onto the edge row.
+ */
+export function binFires(fires, { width, height, weight = defaultWeight }) {
+  const grid = new Float32Array(width * height);
+  const row = (y) => Math.min(height - 1, Math.max(0, y)) * width;
+  const col = (x) => ((x % width) + width) % width;
+  for (const fire of fires) {
+    if (!Number.isFinite(fire.lat) || !Number.isFinite(fire.lon)) continue;
+    const fx = ((fire.lon + 180) / 360) * width - 0.5;
+    const fy = ((90 - fire.lat) / 180) * height - 0.5;
+    const x0 = Math.floor(fx);
+    const y0 = Math.floor(fy);
+    const tx = fx - x0;
+    const ty = fy - y0;
+    const w = weight(fire);
+    const top = row(y0);
+    const bottom = row(y0 + 1);
+    const left = col(x0);
+    const right = col(x0 + 1);
+    grid[top + left] += w * (1 - tx) * (1 - ty);
+    grid[top + right] += w * tx * (1 - ty);
+    grid[bottom + left] += w * (1 - tx) * ty;
+    grid[bottom + right] += w * tx * ty;
+  }
+  return grid;
+}
+
+function kernel(sigma) {
+  const radius = Math.max(1, Math.ceil(sigma * 3));
+  const k = new Float32Array(radius * 2 + 1);
+  let sum = 0;
+  for (let i = -radius; i <= radius; i++) {
+    k[i + radius] = Math.exp(-(i * i) / (2 * sigma * sigma));
+    sum += k[i + radius];
+  }
+  for (let i = 0; i < k.length; i++) k[i] /= sum;
+  return { k, radius };
+}
+
+export function blurGaussian(grid, width, height, sigma) {
+  const { k, radius } = kernel(sigma);
+  const tmp = new Float32Array(grid.length);
+  const out = new Float32Array(grid.length);
+  for (let y = 0; y < height; y++) {
+    const row = y * width;
+    for (let x = 0; x < width; x++) {
+      const v = grid[row + x];
+      if (v === 0) continue;
+      for (let i = -radius; i <= radius; i++) {
+        const xx = (((x + i) % width) + width) % width; // longitude wraps
+        tmp[row + xx] += v * k[i + radius];
+      }
+    }
+  }
+  for (let y = 0; y < height; y++) {
+    for (let x = 0; x < width; x++) {
+      const v = tmp[y * width + x];
+      if (v === 0) continue;
+      for (let i = -radius; i <= radius; i++) {
+        const yy = Math.min(height - 1, Math.max(0, y + i)); // poles clamp
+        out[yy * width + x] += v * k[i + radius];
+      }
+    }
+  }
+  return out;
+}
+
+/** Bins of the log-density histogram used to find the reference quantile. */
+const QUANTILE_BINS = 4096;
+
+/**
+ * The p-quantile of the non-zero values, from a histogram of log1p(value):
+ * one linear pass instead of sorting ~350k burning pixels (a sort cost
+ * 200 ms+ and dominated the build). Bin width on the log axis is
+ * max/4096, far finer than the 256-step palette it feeds.
+ */
+function percentileOfNonZero(values, p) {
+  let count = 0;
+  let max = 0;
+  for (let i = 0; i < values.length; i++) {
+    const v = values[i];
+    if (v > 0) {
+      count += 1;
+      if (v > max) max = v;
+    }
+  }
+  if (!count) return 0;
+  const logMax = Math.log1p(max);
+  const bins = new Uint32Array(QUANTILE_BINS);
+  const toBin = (QUANTILE_BINS - 1) / logMax;
+  for (let i = 0; i < values.length; i++) {
+    const v = values[i];
+    if (v > 0) bins[Math.floor(Math.log1p(v) * toBin)] += 1;
+  }
+  const target = Math.floor(p * (count - 1));
+  let seen = 0;
+  for (let b = 0; b < QUANTILE_BINS; b++) {
+    seen += bins[b];
+    if (seen > target) return Math.expm1((b + 1) / toBin);
+  }
+  return max;
+}
+
+/** HEAT_PALETTE sampled at 256 steps, so the per-pixel walk is one lookup. */
+const LUT_STEPS = 256;
+let paletteLut = null;
+function heatLut() {
+  if (!paletteLut) {
+    paletteLut = new Uint8ClampedArray(LUT_STEPS * 4);
+    for (let i = 0; i < LUT_STEPS; i++) {
+      paletteLut.set(heatColorAt(i / (LUT_STEPS - 1)), i * 4);
+    }
+  }
+  return paletteLut;
+}
+
+export function buildHeatRaster(
+  fires,
+  { width, height, sigmaPx, percentile = 0.995 },
+) {
+  const density = blurGaussian(
+    binFires(fires, { width, height }),
+    width,
+    height,
+    sigmaPx,
+  );
+  const reference = percentileOfNonZero(density, percentile);
+  const rgba = new Uint8ClampedArray(width * height * 4);
+  if (reference > 0) {
+    const lut = heatLut();
+    const scale = (LUT_STEPS - 1) / Math.log1p(reference);
+    for (let i = 0; i < density.length; i++) {
+      const d = density[i];
+      if (d <= 0) continue;
+      const step = Math.min(LUT_STEPS - 1, Math.round(Math.log1p(d) * scale));
+      const l = step * 4;
+      if (lut[l + 3] === 0) continue;
+      const o = i * 4;
+      rgba[o] = lut[l];
+      rgba[o + 1] = lut[l + 1];
+      rgba[o + 2] = lut[l + 2];
+      rgba[o + 3] = lut[l + 3];
+    }
+  }
+  return { width, height, rgba, reference };
+}

src/data/firmsHeatRaster.test.mjs

@@ -0,0 +1,118 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import {
+  HEAT_MIN_WEIGHT_MW,
+  HEAT_PALETTE,
+  heatColorAt,
+  binFires,
+  blurGaussian,
+  buildHeatRaster,
+} from './firmsHeatRaster.js';
+
+const fire = (lat, lon, frp = 10) => ({ lat, lon, frp });
+
+test('palette runs ember to white-hot and starts fully transparent', () => {
+  assert.equal(HEAT_PALETTE[0].at, 0);
+  assert.equal(HEAT_PALETTE.at(-1).at, 1);
+  assert.deepEqual(heatColorAt(0), [0, 0, 0, 0]);
+  assert.equal(heatColorAt(0.01)[3], 0, 'below the floor nothing is painted');
+  const low = heatColorAt(0.15);
+  const high = heatColorAt(1);
+  assert.ok(low[0] > low[1] && low[1] > low[2], 'low heat is red');
+  assert.ok(low[3] >= 0.5 * 255, 'low heat stays visible on any imagery');
+  assert.ok(high[1] > low[1] && high[2] > low[2], 'the core is paler');
+  assert.ok(high[3] > low[3], 'hotter is more opaque');
+  for (let i = 1; i <= 100; i++) {
+    const [r, , b] = heatColorAt(i / 100);
+    assert.ok(r >= b, `no cold hue at ${i}%`);
+  }
+});
+
+test('binFires puts a detection at a pixel centre wholly in that pixel', () => {
+  // 4×2 grid: pixel centres at lon −135/−45/45/135, lat ±45.
+  const grid = binFires([fire(45, -135, 1), fire(-45, 135, 1)], {
+    width: 4,
+    height: 2,
+  });
+  assert.equal(grid[0], 1, 'north-west pixel');
+  assert.equal(grid[7], 1, 'south-east pixel');
+  assert.equal(
+    grid.reduce((a, b) => a + b, 0),
+    2,
+  );
+});
+
+test('binFires shares a detection between the pixels around it', () => {
+  const between = binFires([fire(45, 0, 1)], { width: 4, height: 2 });
+  assert.equal(between[1], 0.5, 'half to the pixel west of it');
+  assert.equal(between[2], 0.5, 'half to the pixel east of it');
+  const quarter = binFires([fire(45, -112.5, 1)], { width: 4, height: 2 });
+  assert.equal(quarter[0], 0.75, 'closer centre takes more');
+  assert.equal(quarter[1], 0.25);
+  const wrapped = binFires([fire(45, 180, 1)], { width: 4, height: 2 });
+  assert.equal(wrapped[3], 0.5, 'the antimeridian wraps');
+  assert.equal(wrapped[0], 0.5);
+  const polar = binFires([fire(90, -135, 1)], { width: 4, height: 2 });
+  assert.equal(polar[0], 1, 'beyond the last row folds back onto it');
+});
+
+test('binFires weights each detection by its radiative power', () => {
+  const grid = binFires(
+    [fire(45, 45, 250), fire(45, 45, 0), fire(45, 45, Number.NaN)],
+    { width: 4, height: 2 },
+  );
+  assert.equal(grid[2], 250 + 2 * HEAT_MIN_WEIGHT_MW);
+});
+
+test('filtering out weak fires keeps a strong fire hot', () => {
+  const strong = fire(0.1, 0.1, 300);
+  const weak = Array.from({ length: 40 }, () => fire(0.1, 0.1, 2));
+  const reference = Array.from({ length: 10 }, () => fire(20.1, 20.1, 100));
+  const options = { width: 360, height: 180, sigmaPx: 2 };
+  const pixel = ((90 - 0.1) | 0) * 360 + ((0.1 + 180) | 0);
+  const red = (r) => r.rgba[pixel * 4];
+  const alpha = (r) => r.rgba[pixel * 4 + 3];
+  const unfiltered = buildHeatRaster([strong, ...weak, ...reference], options);
+  const filtered = buildHeatRaster([strong, ...reference], options);
+  assert.ok(alpha(filtered) > 0);
+  assert.ok(
+    alpha(filtered) >= alpha(unfiltered) * 0.9,
+    `alpha ${alpha(unfiltered)} -> ${alpha(filtered)}`,
+  );
+  assert.ok(
+    red(filtered) >= red(unfiltered) * 0.9,
+    `red ${red(unfiltered)} -> ${red(filtered)}`,
+  );
+});
+
+test('blurGaussian keeps mass and wraps across the antimeridian', () => {
+  const w = 16;
+  const h = 8;
+  const grid = new Float32Array(w * h);
+  grid[3 * w + 0] = 1;
+  const out = blurGaussian(grid, w, h, 1.5);
+  const sum = out.reduce((a, b) => a + b, 0);
+  assert.ok(Math.abs(sum - 1) < 1e-3, `mass ${sum}`);
+  assert.ok(out[3 * w + (w - 1)] > 0, 'spills to the east edge');
+});
+
+test('buildHeatRaster is transparent where there are no fires', () => {
+  const r = buildHeatRaster([fire(40, -120), fire(40.1, -120.1)], {
+    width: 360,
+    height: 180,
+    sigmaPx: 2,
+  });
+  assert.equal(r.rgba.length, 360 * 180 * 4);
+  const alphaAt = (lat, lon) => {
+    const x = Math.floor(((lon + 180) / 360) * 360);
+    const y = Math.floor(((90 - lat) / 180) * 180);
+    return r.rgba[(y * 360 + x) * 4 + 3];
+  };
+  assert.ok(alphaAt(40, -120) > 0, 'blob over the fires');
+  assert.equal(alphaAt(-30, 60), 0, 'empty far away');
+});
+
+test('buildHeatRaster with no fires is fully transparent', () => {
+  const r = buildHeatRaster([], { width: 8, height: 4, sigmaPx: 1 });
+  assert.ok(r.rgba.every((v) => v === 0));
+});

src/data/firmsIntensity.js

@@ -0,0 +1,212 @@
+/**
+ * @module firmsIntensity
+ * @description Fire intensity policy shared by the Active Fires layer and the
+ * agent fire tool: the six-stop ember → white-hot FRP color ramp, the log-scale
+ * slider that doubles as its legend, and the one filter every consumer
+ * (markers, cards, heat cells, the top-fires query, `get_active_fires`) runs
+ * before anything is rendered or selected. Pure — no Cesium, no DOM.
+ *
+ * The ramp (`FRP_RAMP`, stepped, not interpolated) runs like a fire cooling
+ * down: a dim ember for weak fires through red, orange and gold to a pale
+ * white-hot core, lightness rising with power, so the brightest marks are the
+ * strongest fires. No cold hues: ~90% of detections are under 20 MW and a
+ * blue start painted most of the map blue. The thresholds are GEV's own, set
+ * on a real week's percentiles so every color appears: Portolan's
+ * 0/10/50/200/500/1000 MW leaves one hottest fire a week (HAL-675).
+ */
+
+/**
+ * Stepped FRP ramp, weakest first. A detection takes the LAST stop whose
+ * `minFrp` it reaches. Names key the glow-sprite cache and the card accents.
+ */
+export const FRP_RAMP = Object.freeze([
+  Object.freeze({ name: 'ember', minFrp: 0, hex: '#9e2a1b' }),
+  Object.freeze({ name: 'red', minFrp: 5, hex: '#d2401f' }),
+  Object.freeze({ name: 'flame', minFrp: 20, hex: '#f06a28' }),
+  Object.freeze({ name: 'orange', minFrp: 50, hex: '#fb9a2e' }),
+  Object.freeze({ name: 'gold', minFrp: 100, hex: '#fdc84a' }),
+  Object.freeze({ name: 'white-hot', minFrp: 300, hex: '#fff3b0' }),
+]);
+
+/** Slider ticks: the ramp thresholds, so slider, legend and markers agree. */
+export const FRP_SLIDER_TICKS = Object.freeze(
+  FRP_RAMP.map((stop) => stop.minFrp),
+);
+
+/** Minimum-FRP values the share codec accepts, in whole megawatts. */
+export const MIN_FRP_MW_MIN = 0;
+export const MIN_FRP_MW_MAX = 10_000;
+
+/** Confidence switch positions; VIIRS reports only low / nominal / high. */
+export const FIRMS_CONFIDENCE_MODES = Object.freeze(['all', 'nominal', 'high']);
+
+/**
+ * Normalized-confidence floor for a switch position. The thresholds match
+ * `confidenceBucket` in the layer model (0.3 / 0.6 / 0.9 after firmsAdapt).
+ */
+const CONFIDENCE_FLOOR = Object.freeze({ all: 0, nominal: 0.45, high: 0.75 });
+
+export const DEFAULT_FIRE_FILTER = Object.freeze({
+  minFrp: 0,
+  confidence: 'all',
+});
+
+/**
+ * The ramp stop for a fire radiative power.
+ * @param {number} frp Megawatts; non-finite or negative reads as 0.
+ * @returns {{name: string, minFrp: number, hex: string}}
+ */
+export function frpRampStop(frp) {
+  const value = Number.isFinite(frp) ? Math.max(0, frp) : 0;
+  let stop = FRP_RAMP[0];
+  for (const candidate of FRP_RAMP) {
+    if (value >= candidate.minFrp) stop = candidate;
+    else break;
+  }
+  return stop;
+}
+
+/** `#rrggbb` → `[r, g, b]` in 0..255. */
+export function hexToRgb(hex) {
+  const text = String(hex).replace('#', '');
+  return [0, 2, 4].map((offset) =>
+    Number.parseInt(text.slice(offset, offset + 2), 16),
+  );
+}
+
+/**
+ * Log-scale slider axis: position 0 means "no minimum" (0 MW), and the rest
+ * of the track runs 1 MW → SLIDER_MAX_MW logarithmically. The axis floor is 1
+ * MW because the median detection is ~6 MW and a sub-megawatt floor hides
+ * nothing worth a tick.
+ */
+export const SLIDER_MAX_MW = 1000;
+const LOG_MAX = Math.log10(SLIDER_MAX_MW);
+
+/**
+ * Track position in 0..1 for a minimum FRP.
+ * @param {number} minFrp Megawatts.
+ * @returns {number}
+ */
+export function sliderPositionForFrp(minFrp) {
+  if (!Number.isFinite(minFrp) || minFrp < 1) return 0;
+  return Math.min(1, Math.log10(minFrp) / LOG_MAX);
+}
+
+/**
+ * Minimum FRP for a track position, rounded to whole megawatts so a slider
+ * value and its share-link form are the same number.
+ * @param {number} position 0..1.
+ * @returns {number}
+ */
+export function frpForSliderPosition(position) {
+  const p = Number.isFinite(position) ? Math.max(0, Math.min(1, position)) : 0;
+  if (p <= 0) return 0;
+  const frp = Math.pow(10, p * LOG_MAX);
+  return Math.max(1, Math.round(frp));
+}
+
+/**
+ * CSS `linear-gradient` painting the stepped ramp along the log axis, so the
+ * slider track IS the legend: the color under the thumb is the color of the
+ * weakest fire still shown.
+ * @returns {string}
+ */
+export function rampTrackGradient() {
+  const parts = [];
+  FRP_RAMP.forEach((stop, index) => {
+    const start = sliderPositionForFrp(stop.minFrp) * 100;
+    const next = FRP_RAMP[index + 1];
+    const end = next ? sliderPositionForFrp(next.minFrp) * 100 : 100;
+    parts.push(`${stop.hex} ${start.toFixed(2)}% ${end.toFixed(2)}%`);
+  });
+  return `linear-gradient(90deg, ${parts.join(', ')})`;
+}
+
+/**
+ * Minimum FRP → whole megawatts inside the codec bounds, or null.
+ * @param {*} value
+ * @returns {?number}
+ */
+export function normalizeMinFrp(value) {
+  const number =
+    typeof value === 'number'
+      ? value
+      : typeof value === 'string' && value.trim() !== ''
+        ? Number(value)
+        : NaN;
+  if (!Number.isFinite(number)) return null;
+  const rounded = Math.round(number);
+  return rounded >= MIN_FRP_MW_MIN && rounded <= MIN_FRP_MW_MAX
+    ? rounded
+    : null;
+}
+
+/**
+ * Confidence mode → one of FIRMS_CONFIDENCE_MODES, or null.
+ * @param {*} value
+ * @returns {?string}
+ */
+export function normalizeConfidenceMode(value) {
+  const text = String(value ?? '')
+    .trim()
+    .toLowerCase();
+  return FIRMS_CONFIDENCE_MODES.includes(text) ? text : null;
+}
+
+/**
+ * Sanitize a partial filter against the current one; unknown or invalid
+ * fields keep their current value.
+ * @param {Object} [params]
+ * @param {{minFrp: number, confidence: string}} [current]
+ * @returns {{minFrp: number, confidence: string}}
+ */
+export function normalizeFireFilter(
+  params = {},
+  current = DEFAULT_FIRE_FILTER,
+) {
+  const minFrp = normalizeMinFrp(params?.minFrp);
+  const confidence = normalizeConfidenceMode(params?.confidence);
+  return {
+    minFrp: minFrp === null ? current.minFrp : minFrp,
+    confidence: confidence === null ? current.confidence : confidence,
+  };
+}
+
+/**
+ * Whether one fire passes the filter. `confidence` is the normalized 0..1
+ * value firmsAdapt produces; `frp` is megawatts.
+ * @param {{frp: number, confidence: number}} fire
+ * @param {{minFrp: number, confidence: string}} filter
+ * @returns {boolean}
+ */
+export function firePassesFilter(fire, filter = DEFAULT_FIRE_FILTER) {
+  const frp = Number.isFinite(fire?.frp) ? fire.frp : 0;
+  if (frp < (filter.minFrp || 0)) return false;
+  const floor = CONFIDENCE_FLOOR[filter.confidence] ?? 0;
+  if (floor <= 0) return true;
+  const confidence = Number.isFinite(fire?.confidence) ? fire.confidence : 0;
+  return confidence >= floor;
+}
+
+/**
+ * The fires that pass the filter, in input order. Returns the SAME array when
+ * the filter is the default, so callers can tell "nothing hidden" cheaply.
+ * @template T
+ * @param {Array<T>} fires Internal records (normalized confidence).
+ * @param {{minFrp: number, confidence: string}} filter
+ * @returns {Array<T>}
+ */
+export function filterFires(fires, filter = DEFAULT_FIRE_FILTER) {
+  if (!Array.isArray(fires)) return [];
+  if (isDefaultFireFilter(filter)) return fires;
+  return fires.filter((fire) => firePassesFilter(fire, filter));
+}
+
+/** True when the filter hides nothing. */
+export function isDefaultFireFilter(filter) {
+  return (
+    !(filter?.minFrp > 0) &&
+    (filter?.confidence === 'all' || filter?.confidence == null)
+  );
+}

src/data/firmsIntensity.test.mjs

@@ -0,0 +1,221 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import {
+  DEFAULT_FIRE_FILTER,
+  FIRMS_CONFIDENCE_MODES,
+  FRP_RAMP,
+  FRP_SLIDER_TICKS,
+  filterFires,
+  firePassesFilter,
+  frpForSliderPosition,
+  frpRampStop,
+  hexToRgb,
+  isDefaultFireFilter,
+  normalizeConfidenceMode,
+  normalizeFireFilter,
+  normalizeMinFrp,
+  rampTrackGradient,
+  sliderPositionForFrp,
+} from './firmsIntensity.js';
+
+test('the ramp has six ember → white-hot stops at 0 · 5 · 20 · 50 · 100 · 300 MW', () => {
+  assert.deepEqual(
+    FRP_RAMP.map((stop) => [stop.name, stop.minFrp, stop.hex]),
+    [
+      ['ember', 0, '#9e2a1b'],
+      ['red', 5, '#d2401f'],
+      ['flame', 20, '#f06a28'],
+      ['orange', 50, '#fb9a2e'],
+      ['gold', 100, '#fdc84a'],
+      ['white-hot', 300, '#fff3b0'],
+    ],
+  );
+  assert.deepEqual([...FRP_SLIDER_TICKS], [0, 5, 20, 50, 100, 300]);
+  assert.ok(Object.isFrozen(FRP_RAMP));
+});
+
+test('every stop is warm and each is lighter than the one below', () => {
+  const luma = ([r, g, b]) => 0.2126 * r + 0.7152 * g + 0.0722 * b;
+  let previous = -1;
+  for (const stop of FRP_RAMP) {
+    const rgb = hexToRgb(stop.hex);
+    assert.ok(rgb[0] >= rgb[2], `${stop.name} has no cold hue`);
+    assert.ok(
+      luma(rgb) > previous,
+      `${stop.name} is lighter than the stop below`,
+    );
+    previous = luma(rgb);
+  }
+});
+
+test('a detection takes the last stop it reaches; garbage reads as 0 MW', () => {
+  assert.equal(frpRampStop(0).name, 'ember');
+  assert.equal(frpRampStop(4.99).name, 'ember');
+  assert.equal(frpRampStop(5).name, 'red');
+  assert.equal(frpRampStop(19.9).name, 'red');
+  assert.equal(frpRampStop(20).name, 'flame');
+  assert.equal(frpRampStop(50).name, 'orange');
+  assert.equal(frpRampStop(100).name, 'gold');
+  assert.equal(frpRampStop(299.9).name, 'gold');
+  assert.equal(frpRampStop(300).name, 'white-hot');
+  assert.equal(frpRampStop(1246).name, 'white-hot');
+  assert.equal(frpRampStop(NaN).name, 'ember');
+  assert.equal(frpRampStop(-3).name, 'ember');
+  assert.equal(frpRampStop(undefined).name, 'ember');
+});
+
+test('hex stops convert to the "r, g, b" accents the cards paint', () => {
+  assert.deepEqual(hexToRgb('#9e2a1b'), [158, 42, 27]);
+  assert.deepEqual(hexToRgb('d1382a'), [209, 56, 42]);
+});
+
+test('the log slider pins 0 MW at the left and runs 1 → 1000 MW; values round-trip', () => {
+  assert.equal(sliderPositionForFrp(0), 0);
+  assert.equal(sliderPositionForFrp(0.5), 0);
+  assert.equal(sliderPositionForFrp(1), 0);
+  assert.ok(Math.abs(sliderPositionForFrp(10) - 1 / 3) < 1e-9);
+  assert.ok(Math.abs(sliderPositionForFrp(100) - 2 / 3) < 1e-9);
+  assert.equal(sliderPositionForFrp(1000), 1);
+  assert.equal(sliderPositionForFrp(5000), 1, 'clamped past the axis end');
+  assert.equal(frpForSliderPosition(0), 0);
+  assert.equal(frpForSliderPosition(1), 1000);
+  assert.equal(frpForSliderPosition(-1), 0);
+  assert.equal(frpForSliderPosition(2), 1000);
+  for (const frp of FRP_SLIDER_TICKS) {
+    assert.equal(
+      frpForSliderPosition(sliderPositionForFrp(frp)),
+      frp,
+      `tick ${frp} MW round-trips through the axis`,
+    );
+  }
+  // Ticks spread along the track instead of bunching at one end.
+  const positions = FRP_SLIDER_TICKS.map(sliderPositionForFrp);
+  for (let i = 1; i < positions.length; i += 1) {
+    assert.ok(positions[i] - positions[i - 1] >= 0.09, `tick gap ${i}`);
+  }
+});
+
+test('the track gradient is the stepped ramp on the log axis, so it doubles as the legend', () => {
+  const gradient = rampTrackGradient();
+  assert.match(gradient, /^linear-gradient\(90deg, /);
+  assert.match(gradient, /#9e2a1b 0\.00% 23\.3\d%/);
+  assert.match(gradient, /#d2401f 23\.3\d% 43\.3\d%/);
+  assert.match(gradient, /#fff3b0 82\.5\d% 100\.00%\)$/);
+  assert.equal(gradient.match(/#/g).length, FRP_RAMP.length);
+});
+
+test('minimum FRP normalizes to whole megawatts inside the codec bounds', () => {
+  assert.equal(normalizeMinFrp(0), 0);
+  assert.equal(normalizeMinFrp(19.6), 20);
+  assert.equal(normalizeMinFrp('100'), 100);
+  assert.equal(normalizeMinFrp(10000), 10000);
+  assert.equal(normalizeMinFrp(10001), null);
+  assert.equal(normalizeMinFrp(-1), null);
+  assert.equal(normalizeMinFrp('abc'), null);
+  assert.equal(normalizeMinFrp(''), null);
+  assert.equal(normalizeMinFrp(null), null);
+  assert.equal(normalizeMinFrp(NaN), null);
+});
+
+test('confidence modes are exactly all / nominal / high', () => {
+  assert.deepEqual([...FIRMS_CONFIDENCE_MODES], ['all', 'nominal', 'high']);
+  assert.equal(normalizeConfidenceMode(' High '), 'high');
+  assert.equal(normalizeConfidenceMode('nominal'), 'nominal');
+  assert.equal(normalizeConfidenceMode('low'), null);
+  assert.equal(normalizeConfidenceMode(0.9), null);
+  assert.equal(normalizeConfidenceMode(undefined), null);
+});
+
+test('a partial filter patches the current one and invalid fields keep their value', () => {
+  assert.deepEqual(normalizeFireFilter(), DEFAULT_FIRE_FILTER);
+  assert.deepEqual(normalizeFireFilter({ minFrp: 20 }), {
+    minFrp: 20,
+    confidence: 'all',
+  });
+  assert.deepEqual(
+    normalizeFireFilter(
+      { confidence: 'high' },
+      { minFrp: 50, confidence: 'all' },
+    ),
+    { minFrp: 50, confidence: 'high' },
+  );
+  assert.deepEqual(
+    normalizeFireFilter(
+      { minFrp: 'nope', confidence: 'medium' },
+      { minFrp: 50, confidence: 'nominal' },
+    ),
+    { minFrp: 50, confidence: 'nominal' },
+  );
+  assert.equal(isDefaultFireFilter(DEFAULT_FIRE_FILTER), true);
+  assert.equal(isDefaultFireFilter({ minFrp: 0, confidence: 'all' }), true);
+  assert.equal(isDefaultFireFilter({ minFrp: 1, confidence: 'all' }), false);
+  assert.equal(isDefaultFireFilter({ minFrp: 0, confidence: 'high' }), false);
+});
+
+test('the filter keeps a fire at or above the floor and at or above the confidence mode', () => {
+  const low = { frp: 864, confidence: 0.3 };
+  const nominal = { frp: 20, confidence: 0.6 };
+  const high = { frp: 2, confidence: 0.9 };
+  assert.equal(firePassesFilter(low), true, 'default shows everything');
+  assert.equal(
+    firePassesFilter(nominal, { minFrp: 20, confidence: 'all' }),
+    true,
+  );
+  assert.equal(
+    firePassesFilter(nominal, { minFrp: 21, confidence: 'all' }),
+    false,
+  );
+  assert.equal(
+    firePassesFilter(low, { minFrp: 0, confidence: 'nominal' }),
+    false,
+  );
+  assert.equal(
+    firePassesFilter(nominal, { minFrp: 0, confidence: 'nominal' }),
+    true,
+  );
+  assert.equal(
+    firePassesFilter(high, { minFrp: 0, confidence: 'nominal' }),
+    true,
+  );
+  assert.equal(
+    firePassesFilter(nominal, { minFrp: 0, confidence: 'high' }),
+    false,
+  );
+  assert.equal(firePassesFilter(high, { minFrp: 0, confidence: 'high' }), true);
+  assert.equal(
+    firePassesFilter(high, { minFrp: 5, confidence: 'high' }),
+    false,
+  );
+  // Missing numbers read as 0, never as a pass-through.
+  assert.equal(firePassesFilter({}, { minFrp: 1, confidence: 'all' }), false);
+  assert.equal(
+    firePassesFilter({ frp: 10 }, { minFrp: 0, confidence: 'nominal' }),
+    false,
+  );
+});
+
+test('filterFires returns the same array for the default filter and preserves order otherwise', () => {
+  const fires = [
+    { frp: 864, confidence: 0.3 },
+    { frp: 20, confidence: 0.6 },
+    { frp: 2, confidence: 0.9 },
+    { frp: 120, confidence: 0.9 },
+  ];
+  assert.equal(filterFires(fires), fires);
+  assert.equal(filterFires(fires, { minFrp: 0, confidence: 'all' }), fires);
+  assert.deepEqual(
+    filterFires(fires, { minFrp: 20, confidence: 'all' }).map((f) => f.frp),
+    [864, 20, 120],
+  );
+  assert.deepEqual(
+    filterFires(fires, { minFrp: 0, confidence: 'high' }).map((f) => f.frp),
+    [2, 120],
+  );
+  assert.deepEqual(
+    filterFires(fires, { minFrp: 100, confidence: 'nominal' }).map(
+      (f) => f.frp,
+    ),
+    [120],
+  );
+  assert.deepEqual(filterFires(null, { minFrp: 1, confidence: 'all' }), []);
+});

src/data/firmsInteraction.test.mjs

@@ -15,6 +15,7 @@ import { WORLD_FOCUS_REQUEST_EVENT } from '../worldFocus.js';
 import { readLayerSource } from '../testSupport/readLayerSource.mjs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { HEAT_REBUILD_MS } from '../layers/firms/policy.js';
 
 const LAYER_SOURCE = readLayerSource(
   path.join(path.dirname(fileURLToPath(import.meta.url)), 'firmsHeatmap.js'),
@@ -393,3 +394,153 @@ test('disable cancels a pending source and a late response cannot repopulate the
     assert.equal(h.layer.getStats().loading, false);
   } finally { h.layer.destroy(h.viewer); h.cleanup(); }
 });
+
+test('the heatmap is preloaded under the markers before the first zoom-out', (t) => {
+  t.mock.timers.enable({ apis: ['setTimeout'] });
+  const priorDocument = globalThis.document;
+  globalThis.document = {
+    createElement: () => ({
+      getContext: () => ({
+        createImageData: (w, hh) => ({ data: new Uint8ClampedArray(w * hh * 4) }),
+        putImageData() {},
+        createRadialGradient: () => ({ addColorStop() {} }),
+        fillRect() {},
+      }),
+      toDataURL: () => 'data:image/png;base64,AAAA',
+    }),
+  };
+  const h = harness({
+    withDataSource: true,
+    cameraPosition: Cesium.Cartesian3.fromDegrees(-98, 30, 1_000_000),
+  });
+  h.viewer.camera = { positionCartographic: { height: 1_000_000 } };
+  h.viewer.scene.primitives = { add() {}, remove() {}, raiseToTop() {}, contains: () => true };
+  h.viewer.scene.frameState = { mode: Cesium.SceneMode.SCENE3D };
+  const added = [];
+  try {
+    h.layer.attachShellServices({
+      imageryHost: () => ({
+        kind: 'globe',
+        collection: {
+          addImageryProvider: (provider) => {
+            const layer = { provider, show: true, alpha: 1 };
+            added.push(layer);
+            return layer;
+          },
+          remove() {},
+          raiseToTop() {},
+        },
+      }),
+    });
+    h.layer._renderLodForTest('close');
+    assert.equal(added.length, 0, 'the markers paint first; the build trails');
+    t.mock.timers.tick(HEAT_REBUILD_MS);
+    assert.equal(added.length, 1, 'then the heatmap is draped');
+    assert.equal(added[0].alpha, 0, 'invisible until the hand-off');
+    assert.equal(added[0].show, true, 'but mapped onto the globe tiles');
+  } finally {
+    h.layer.destroy(h.viewer);
+    h.cleanup();
+    if (priorDocument === undefined) delete globalThis.document;
+    else globalThis.document = priorDocument;
+  }
+});
+
+test('far zoom drapes one heatmap and the hand-off cross-fades it with the markers', () => {
+  // A canvas stub for the heat drape and the detection glow sprites.
+  const priorDocument = globalThis.document;
+  const restoreDocument = () => {
+    if (priorDocument === undefined) delete globalThis.document;
+    else globalThis.document = priorDocument;
+  };
+  globalThis.document = {
+    createElement: () => ({
+      getContext: () => ({
+        createImageData: (w, hh) => ({
+          data: new Uint8ClampedArray(w * hh * 4),
+        }),
+        putImageData() {},
+        createRadialGradient: () => ({ addColorStop() {} }),
+        fillRect() {},
+      }),
+      toDataURL: () => 'data:image/png;base64,AAAA',
+    }),
+  };
+  const h = harness({
+    fires: [makeFire(), makeFire({ index: 8, lat: 30.6, lon: -98.3, frp: 12 })],
+    withDataSource: true,
+    cameraPosition: Cesium.Cartesian3.fromDegrees(-98, 30, 12_000_000),
+  });
+  const added = [];
+  const removed = [];
+  let markers = null;
+  // The fade reads the camera height; the cull reads scene.camera.
+  const setHeight = (height) => {
+    h.viewer.camera = { positionCartographic: { height } };
+  };
+  setHeight(12_000_000);
+  h.viewer.scene.primitives = {
+    add(primitive) {
+      markers = primitive;
+    },
+    remove() {},
+    raiseToTop() {},
+    contains: () => true,
+  };
+  h.viewer.scene.frameState = { mode: Cesium.SceneMode.SCENE3D };
+  try {
+    const collection = {
+      addImageryProvider: (provider) => {
+        const layer = { provider, show: true, alpha: 1 };
+        added.push(layer);
+        return layer;
+      },
+      remove: (layer, destroy) => removed.push({ layer, destroy }),
+      raiseToTop() {},
+    };
+    h.layer.attachShellServices({
+      imageryHost: () => ({ kind: 'globe', collection }),
+    });
+    h.layer._renderLodForTest('global');
+    assert.equal(added.length, 1, 'one heat imagery layer');
+    assert.equal(added[0].show, true);
+    assert.equal(added[0].alpha, 1);
+    assert.equal(h.layer._entityCountForTest(), 0, 'no rectangle entities');
+    assert.ok(h.published.length > 0, 'the far band still paints cards');
+    assert.equal(markers.length, 2, 'the markers are built under the heatmap');
+    assert.equal(markers.show, false, 'and hidden while the heatmap is whole');
+
+    h.layer._renderLodForTest('regional');
+    assert.equal(added.length, 1, 'switching far bands reuses the raster');
+
+    setHeight(1_000_000);
+    h.layer._renderLodForTest('close');
+    assert.equal(added.length, 1, 'the markers band keeps the same heat layer');
+    assert.equal(added[0].show, true, 'still mapped onto the globe tiles');
+    assert.equal(added[0].alpha, 0, 'faded out under the markers');
+    assert.equal(markers.show, true);
+    assert.equal(markers.get(0).color.alpha, 1);
+
+    // Mid hand-off both are drawn, half each, in either band.
+    setHeight(4_500_000);
+    h.layer._applyHandoffFadeForTest();
+    assert.equal(added[0].alpha, 0.5);
+    assert.equal(markers.show, true);
+    assert.equal(markers.get(0).color.alpha, 0.5);
+    h.layer._renderLodForTest('regional');
+    assert.equal(added[0].alpha, 0.5);
+    assert.equal(markers.get(1).color.alpha, 0.5, 'rebuilt markers get the fade');
+
+    h.layer.disable();
+    assert.equal(added[0].show, false, 'disable hides the heatmap');
+
+    h.layer.destroy(h.viewer);
+    assert.deepEqual(
+      removed.map((entry) => [entry.layer, entry.destroy]),
+      [[added[0], true]],
+    );
+  } finally {
+    h.cleanup();
+    restoreDocument();
+  }
+});

src/data/firmsLabels.js

@@ -4,6 +4,8 @@
  * dedicated card canvas moved into the shared world-overlay host.
  */
 
+import { FRP_RAMP, hexToRgb } from './firmsIntensity.js';
+
 /** Shipped ambient FIRMS card ceiling. Selected fires bypass this cohort. */
 export const FIRMS_AMBIENT_COHORT_LIMIT = 18;
 export const FIRMS_OVERLAY_SOURCE_ID = 'firms';
@@ -23,20 +25,23 @@ export function fireDetectionKey(fire) {
   return `firms:${lat}:${lon}:${acq}:${source}`;
 }
 
-/** Severity accent palette — matches the FIRMS glow-sprite color stops. */
-const ACCENT_RGB = Object.freeze({
-  red: '224, 82, 82',
-  orange: '240, 178, 62',
-  yellow: '244, 227, 108',
-});
+/**
+ * Severity accent palette — the FIRMS glow-sprite color stops (the six-stop
+ * FRP ramp in firmsIntensity.js) as "r, g, b" strings for card accents.
+ */
+const ACCENT_RGB = Object.freeze(
+  Object.fromEntries(
+    FRP_RAMP.map((stop) => [stop.name, hexToRgb(stop.hex).join(', ')]),
+  ),
+);
 
 /**
- * Severity stop name → "r, g, b" accent string (defaults to yellow).
- * @param {string} stopName - 'red' | 'orange' | 'yellow'.
+ * Severity stop name → "r, g, b" accent string (defaults to the weakest stop).
+ * @param {string} stopName - A FRP_RAMP stop name ('ember' … 'white-hot').
  * @returns {string}
  */
 export function accentForSeverity(stopName) {
-  return ACCENT_RGB[stopName] || ACCENT_RGB.yellow;
+  return ACCENT_RGB[stopName] || ACCENT_RGB[FRP_RAMP[0].name];
 }
 
 /**

src/data/firmsLabels.test.mjs

@@ -9,11 +9,16 @@ import {
   formatFrpMw,
 } from './firmsLabels.js';
 
-test('FIRMS formatting helpers retain the shipped severity palette', () => {
-  assert.equal(accentForSeverity('red'), '224, 82, 82');
-  assert.equal(accentForSeverity('orange'), '240, 178, 62');
-  assert.equal(accentForSeverity('yellow'), '244, 227, 108');
-  assert.equal(accentForSeverity('chartreuse'), accentForSeverity('yellow'));
+test('FIRMS card accents are the six FRP ramp stops, weakest as the fallback', () => {
+  // Ember #9e2a1b … white-hot #fff3b0, lightness rising with power.
+  assert.equal(accentForSeverity('ember'), '158, 42, 27');
+  assert.equal(accentForSeverity('red'), '210, 64, 31');
+  assert.equal(accentForSeverity('flame'), '240, 106, 40');
+  assert.equal(accentForSeverity('orange'), '251, 154, 46');
+  assert.equal(accentForSeverity('gold'), '253, 200, 74');
+  assert.equal(accentForSeverity('white-hot'), '255, 243, 176');
+  assert.equal(accentForSeverity('blue'), accentForSeverity('ember'));
+  assert.equal(accentForSeverity('chartreuse'), accentForSeverity('ember'));
 });
 
 test('FIRMS power that rounds to 10 MW drops the decimal', () => {

src/data/fixtures/README.md

@@ -1,5 +1,10 @@
 # Test fixtures
 
+- `photon-moscow-search.json` - Photon responses for `Москва`, captured
+  2026-11-05 with and without a proximity bias near the Tajikistan namesake.
+  The fixture is trimmed to the fields the keyless geocoder consumes and is
+  used only by offline search tests. Data from OpenStreetMap contributors,
+  ODbL 1.0 (https://www.openstreetmap.org/copyright).
 - `tomtom-flow-austin-12-935-1686.pbf` — one real TomTom traffic-flow vector
   tile (Mapbox Vector Tile protobuf, layer `"Traffic flow"`), downtown Austin
   z12 x935 y1686, captured 2026-07-16 from

src/data/fixtures/photon-moscow-search.json

@@ -0,0 +1,110 @@
+{
+  "biased": {
+    "features": [
+      {
+        "geometry": {
+          "type": "Point",
+          "coordinates": [71.8339931, 38.948412]
+        },
+        "properties": {
+          "name": "Москва",
+          "country": "Тоҷикистон"
+        }
+      },
+      {
+        "geometry": {
+          "type": "Point",
+          "coordinates": [37.6063916, 55.625578]
+        },
+        "properties": {
+          "name": "Москва",
+          "country": "Россия"
+        }
+      },
+      {
+        "geometry": {
+          "type": "Point",
+          "coordinates": [37.6174782, 55.7505412]
+        },
+        "properties": {
+          "name": "Москва",
+          "country": "Россия"
+        }
+      },
+      {
+        "geometry": {
+          "type": "Point",
+          "coordinates": [37.0536908, 55.7098009]
+        },
+        "properties": {
+          "name": "Москва",
+          "country": "Россия"
+        }
+      },
+      {
+        "geometry": {
+          "type": "Point",
+          "coordinates": [32.163334, 56.917778]
+        },
+        "properties": {
+          "name": "Москва",
+          "country": "Россия"
+        }
+      }
+    ]
+  },
+  "unbiased": {
+    "features": [
+      {
+        "geometry": {
+          "type": "Point",
+          "coordinates": [37.6063916, 55.625578]
+        },
+        "properties": {
+          "name": "Москва",
+          "country": "Россия"
+        }
+      },
+      {
+        "geometry": {
+          "type": "Point",
+          "coordinates": [37.6174782, 55.7505412]
+        },
+        "properties": {
+          "name": "Москва",
+          "country": "Россия"
+        }
+      },
+      {
+        "geometry": {
+          "type": "Point",
+          "coordinates": [37.0536908, 55.7098009]
+        },
+        "properties": {
+          "name": "Москва",
+          "country": "Россия"
+        }
+      },
+      {
+        "geometry": {
+          "type": "Point",
+          "coordinates": [32.163334, 56.917778]
+        },
+        "properties": {
+          "name": "Москва",
+          "country": "Россия"
+        }
+      },
+      {
+        "geometry": {
+          "type": "Point",
+          "coordinates": [71.8339931, 38.948412]
+        },
+        "properties": {
+          "name": "Москва",
+          "country": "Тоҷикистон"
+        }
+      }
+    ]
+  }
+}

src/data/focusAllocations.test.mjs

@@ -13,7 +13,7 @@ import { isCalibratedAllocationRuntime } from '../../scripts/run-unit-tests.mjs'
  */
 test('converged focus treatment stays within the GC-bracketed allocation budget', (t) => {
   if (!isCalibratedAllocationRuntime()) {
-    return t.skip(`allocation budgets are calibrated for Node 24; running ${process.versions.node}`);
+    return t.skip(`allocation budgets are calibrated for Node 24 or 26; running ${process.versions.node}`);
   }
   const result = spawnSync(
     process.execPath,

src/data/imagingSensors.js

@@ -0,0 +1,25 @@
+/**
+ * @file The bundled imaging-sensor pack: swath and resolution for the main
+ * Earth-observation platforms, matched to satellites by NORAD number or name.
+ *
+ * Data: `local_data/imaging_sensors/imaging_sensors.json`; sources, licences
+ * and curation in that folder's README. Loaded once, on demand, by the
+ * satellites layer; a failed load is retried after a cooldown rather than
+ * remembered for the session.
+ *
+ * @module data/imagingSensors
+ */
+
+import { indexImagingSensors } from '../layers/satellites/sensors.js';
+import { loadBundledJson } from './bundledJson.js';
+import { createRetryableLoader } from './retryableLoad.js';
+
+const PACK_URL = new URL(
+  './local_data/imaging_sensors/imaging_sensors.json',
+  import.meta.url,
+);
+
+/** The pack, loaded and indexed once. */
+export const loadImagingSensors = createRetryableLoader(async () =>
+  indexImagingSensors(await loadBundledJson(PACK_URL)),
+);

src/data/infrastructure.test.mjs

@@ -82,7 +82,7 @@ test('infrastructure factory preserves identity and creates independent state wi
 
 test('dataset URLs still name the complete bundled sources', () => {
   for (const [file, count] of [
-    ['datacenters', 4351],
+    ['datacenters', 4352],
     ['dams', 704],
   ]) {
     const lines = readFileSync(

src/data/layerState.js

@@ -2,6 +2,7 @@
 // Local, not i18n/marker.js: the token-ledger tests run this file in isolation.
 const msg = (text) => text;
 import { normalizeIdSwitches, patchRequestedIdSwitches } from './idSwitches.js';
+import { normalizeSatelliteClassMask } from './satelliteClassMask.js';
 import reservationRows from './layerStateTokenReservations.json' with { type: 'json' };
 
 const VALID_DISPOSITIONS = new Set([
@@ -298,12 +299,46 @@ function satelliteFilterOption() {
 }
 
 const OPTION_GROUPS = Object.freeze({
+  // Active Fires intensity filter (HAL-676). `minFrp` is whole megawatts on
+  // the codec side; the panel's log slider rounds to it. Both default to
+  // "show everything": many of the strongest fires are rated low confidence.
+  // The bounds and modes mirror MIN_FRP_MW_MAX / FIRMS_CONFIDENCE_MODES in
+  // firmsIntensity.js (pinned by layerState.test); spelled out here because
+  // this file runs in isolation in the token-ledger tests.
+  'local-firms': Object.freeze([
+    boundedIntegerOption('minFrp', 'f', 0, { min: 0, max: 10000 }),
+    enumOption('confidence', 'c', 'all', ['all', 'nominal', 'high'], {
+      all: 'a',
+      nominal: 'n',
+      high: 'h',
+    }),
+  ]),
+  'wildlife-sightings': Object.freeze([
+    booleanOption('confirmed', 'c', false),
+    enumOption(
+      'taxa',
+      't',
+      'all',
+      ['all', 'Aves', 'Mammalia', 'whales', 'Insecta', 'Plantae'],
+      {
+        all: 'a',
+        Aves: 'b',
+        Mammalia: 'm',
+        whales: 'w',
+        Insecta: 'i',
+        Plantae: 'p',
+      },
+    ),
+  ]),
   traffic: Object.freeze([
     enumOption('roadMode', 'r', null, ['tomtom', 'osm', 'hybrid'], {
       tomtom: 't',
       osm: 'o',
       hybrid: 'h',
     }),
+    // Street Traffic row toggles: flow-colored road lines, moving dots.
+    booleanOption('lines', 'l', false),
+    booleanOption('dots', 'd', true),
   ]),
   'weather-lightning': Object.freeze([
     enumOption('opacity', 'o', 'strong', ['light', 'strong'], {
@@ -382,6 +417,16 @@ const OPTION_GROUPS = Object.freeze({
       dense: 'd',
     }),
     integerOption('selectedSatTrackingId', 't', null),
+    // Every class but Starlink shows by default (satellites/classes.js).
+    Object.freeze({
+      key: 'classes',
+      token: 'k',
+      defaultValue: 'sitpd',
+      normalize: normalizeSatelliteClassMask,
+      encode: (value) => value,
+      decode: (value) =>
+        typeof value === 'string' ? normalizeSatelliteClassMask(value) : null,
+    }),
   ]),
   cctv: Object.freeze([
     enumOption('coverageMode', 'c', 'on', ['off', 'on', 'viewshed'], {
@@ -626,7 +671,12 @@ export const LAYER_STATE_REGISTRY = Object.freeze([
     token: 'd',
     disposition: 'enabled-only',
   }),
-  Object.freeze({ id: 'local-firms', token: 'w', disposition: 'enabled-only' }),
+  Object.freeze({
+    id: 'local-firms',
+    token: 'w',
+    disposition: 'enabled+options',
+    optionOwner: 'local-firms',
+  }),
   Object.freeze({
     id: 'military',
     token: 'm',
@@ -714,6 +764,12 @@ export const LAYER_STATE_REGISTRY = Object.freeze([
     disposition: 'enabled+options',
     optionOwner: 'weather-satellite',
   }),
+  Object.freeze({
+    id: 'wildlife-sightings',
+    token: '9',
+    disposition: 'enabled+options',
+    optionOwner: 'wildlife-sightings',
+  }),
   Object.freeze({
     id: 'wind',
     token: 'k',

src/data/layerState.test.mjs

@@ -29,6 +29,7 @@ import radioLayer from './radio.js';
 import { stampInitialShareGesture } from '../navigationPolicy.js';
 import { MAX_SINCE_DAYS } from '../layers/streetLevel/policy.js';
 import { SINCE_STOPS } from '../ui/streetLevelPresentation.js';
+import { FIRMS_CONFIDENCE_MODES, MIN_FRP_MW_MAX } from './firmsIntensity.js';
 
 function deferred() {
   let resolve;
@@ -202,8 +203,8 @@ function encode(state) {
 
 test('production registry is exact, canonical, and rejects incomplete contracts', async () => {
   assert.equal(validateLayerStateRegistry(), true);
-  assert.equal(REGISTERED_LAYER_IDS.length, 35);
-  assert.equal(new Set(REGISTERED_LAYER_IDS).size, 35);
+  assert.equal(REGISTERED_LAYER_IDS.length, 36);
+  assert.equal(new Set(REGISTERED_LAYER_IDS).size, 36);
   assert.ok(REGISTERED_LAYER_IDS.includes('transit'));
   assert.deepEqual(REGISTERED_LAYER_IDS, [...REGISTERED_LAYER_IDS].sort());
   assert.deepEqual(LEGACY_LAYER_STATE_TOKENS, {
@@ -242,7 +243,7 @@ test('production registry is exact, canonical, and rejects incomplete contracts'
   for (const [id, token] of Object.entries(LEGACY_LAYER_STATE_TOKENS)) {
     assert.equal(LAYER_STATE_TOKEN_RESERVATIONS[id], token);
   }
-  assert.equal(nextLayerStateToken(), '9');
+  assert.equal(nextLayerStateToken(), '00');
   assert.equal(
     nextLayerStateToken({
       ...LAYER_STATE_TOKEN_RESERVATIONS,
@@ -305,8 +306,8 @@ test('production registry is exact, canonical, and rejects incomplete contracts'
   assert.equal(
     validateLayerStateAllocations(LAYER_STATE_TOKEN_RESERVATIONS, {
       ...LAYER_STATE_TOKEN_RESERVATIONS,
-      future: '9',
-      next: '00',
+      future: '00',
+      next: '01',
     }),
     true,
   );
@@ -314,12 +315,13 @@ test('production registry is exact, canonical, and rejects incomplete contracts'
     () =>
       validateLayerStateAllocations(LAYER_STATE_TOKEN_RESERVATIONS, {
         ...LAYER_STATE_TOKEN_RESERVATIONS,
-        future: '00',
+        future: '01',
       }),
-    /next free token 9/,
+    /next free token 00/,
   );
   const beforeLastDigit = { ...digitsExhausted };
   delete beforeLastDigit['prior-9'];
+  delete beforeLastDigit['wildlife-sightings'];
   assert.equal(
     validateLayerStateAllocations(beforeLastDigit, {
       ...beforeLastDigit,
@@ -968,6 +970,41 @@ test('a direct Context selection promotes its owned tracker layer before persist
   coordinator.destroy();
 });
 
+test('a satellite class choice is saved, shared and restored', async () => {
+  const storage = memoryStorage();
+  const manager = productionManager();
+  const coordinator = new LayerStateCoordinator(manager, shareSink(), {
+    storage,
+  });
+  await coordinator.start();
+  await manager.setEnabled('satellites', true, { origin: 'user' });
+  assert.equal(
+    coordinator.getDurableState().options.satellites.classes,
+    'sitpd',
+    'every class but Starlink by default',
+  );
+  manager.setLayerParams(
+    'satellites',
+    { classes: { debris: false } },
+    { origin: 'user' },
+  );
+  const durable = coordinator.getDurableState();
+  assert.equal(durable.options.satellites.classes, 'sitp');
+  assert.equal(
+    new URLSearchParams(encode(durable)).get('lo')?.includes('s.k.sitp'),
+    true,
+  );
+  coordinator.destroy();
+
+  // A reload hands the layer its letters back (the layer decodes them:
+  // src/data/satelliteClass.test.mjs).
+  const reloaded = productionManager();
+  const next = new LayerStateCoordinator(reloaded, shareSink(), { storage });
+  await next.start();
+  assert.equal(reloaded.getLayerParams('satellites')?.classes, 'sitp');
+  next.destroy();
+});
+
 test('explicit Flight to Satellite replacement keeps the new Satellite ID durable', async () => {
   const manager = productionManager();
   const coordinator = new LayerStateCoordinator(manager, shareSink(), {
@@ -2694,6 +2731,32 @@ test('the recent-imagery split is share-link only: never stored locally, and a s
   );
 });
 
+test('wildlife confirmed and every taxa preset round-trip through the full share codec', () => {
+  assert.equal(
+    LAYER_STATE_REGISTRY.find(({ id }) => id === 'wildlife-sightings').token,
+    '9',
+  );
+  for (const taxa of [
+    'all',
+    'Aves',
+    'Mammalia',
+    'whales',
+    'Insecta',
+    'Plantae',
+  ]) {
+    const state = normalizeLayerState({
+      enabledLayerIds: ['wildlife-sightings'],
+      options: { 'wildlife-sightings': { confirmed: true, taxa } },
+    });
+    const encoded = encode(state);
+    assert.doesNotMatch(encoded, /undefined/);
+    assert.deepEqual(
+      decodeLayerStateParams(new URLSearchParams(encoded)),
+      state,
+    );
+  }
+});
+
 test('drone restrictions uses digit 8 without colliding with fire perimeters', () => {
   const decoded = decodeLayerStateParams(new URLSearchParams('v=2&l=8.2'));
   assert.deepEqual(decoded.enabledLayerIds, [
@@ -3007,9 +3070,156 @@ test('Clear All cancels a saved restore still waiting to start', async () => {
   gate.resolve();
   const results = await restore;
   for (const id of ['earthquakes', 'flights']) {
-    assert.equal(results.find((result) => result.layerId === id).succeeded, false);
+    assert.equal(
+      results.find((result) => result.layerId === id).succeeded,
+      false,
+    );
   }
   assert.deepEqual([...manager.getEnabledLayerIds()], []);
   assert.equal(enabledLayerParam(sink), '');
   coordinator.destroy();
 });
+
+/** Active Fires options decoded from a v2 link with these `lo` assignments. */
+function firmsOptions(lo) {
+  const params = new URLSearchParams([
+    ['v', '2'],
+    ['l', 'w'],
+  ]);
+  if (lo) params.set('lo', lo);
+  return decodeLayerStateParams(params).options['local-firms'];
+}
+
+test('Active Fires: the intensity filter rides share token w and round-trips', () => {
+  const state = createDefaultLayerState();
+  assert.deepEqual(state.options['local-firms'], {
+    minFrp: 0,
+    confidence: 'all',
+  });
+  state.enabledLayerIds = ['local-firms'];
+  state.options['local-firms'] = { minFrp: 20, confidence: 'high' };
+  const encoded = encode(state);
+  assert.equal(new URLSearchParams(encoded).get('l'), 'w');
+  // Other owners write their own explicit defaults into `lo` too (flights 3D,
+  // wind overlay); the fire assignments ride beside them.
+  const assignments = new URLSearchParams(encoded).get('lo').split('_');
+  assert.ok(assignments.includes('w.f.20'), assignments.join(' '));
+  assert.ok(assignments.includes('w.c.h'), assignments.join(' '));
+  const decoded = decodeLayerStateParams(new URLSearchParams(encoded));
+  assert.deepEqual(decoded.options['local-firms'], {
+    minFrp: 20,
+    confidence: 'high',
+  });
+  assert.deepEqual(
+    parseStoredLayerState(serializeStoredLayerState(state)).options[
+      'local-firms'
+    ],
+    state.options['local-firms'],
+  );
+  // Defaults are omitted from the link: a plain `l=w` is "show everything".
+  const plain = createDefaultLayerState();
+  plain.enabledLayerIds = ['local-firms'];
+  assert.equal(
+    new URLSearchParams(encode(plain))
+      .get('lo')
+      .split('_')
+      .filter((assignment) => assignment.startsWith('w.')).length,
+    0,
+  );
+  assert.deepEqual(firmsOptions(''), { minFrp: 0, confidence: 'all' });
+});
+
+test('Active Fires: the codec accepts whole megawatts in bounds and the three confidence codes', () => {
+  // The codec spells its bounds out (it runs in isolation in the ledger
+  // tests); they must stay the layer's.
+  assert.equal(MIN_FRP_MW_MAX, 10000);
+  assert.deepEqual([...FIRMS_CONFIDENCE_MODES], ['all', 'nominal', 'high']);
+  assert.equal(firmsOptions('w.f.300').minFrp, 300);
+  assert.equal(firmsOptions('w.f.10000').minFrp, 10000);
+  assert.equal(firmsOptions('w.f.10001').minFrp, 0, 'out of bounds → default');
+  assert.equal(firmsOptions('w.f.-5').minFrp, 0);
+  assert.equal(
+    firmsOptions('w.f.2.5').minFrp,
+    0,
+    'a third segment is rejected',
+  );
+  assert.equal(firmsOptions('w.c.a').confidence, 'all');
+  assert.equal(firmsOptions('w.c.n').confidence, 'nominal');
+  assert.equal(firmsOptions('w.c.h').confidence, 'high');
+  assert.equal(
+    firmsOptions('w.c.x').confidence,
+    'all',
+    'unknown code → default',
+  );
+  assert.deepEqual(firmsOptions('w.c.n_w.f.5'), {
+    minFrp: 5,
+    confidence: 'nominal',
+  });
+});
+
+// An application built without a layer (a smaller catalog) receives a link or
+// saved state from a build that has it: the layer is neither restored nor
+// stored nor carried into the links this application shares.
+function managerWithout(withheld) {
+  const manager = new DataLayerManager({});
+  for (const id of REGISTERED_LAYER_IDS)
+    if (!withheld.includes(id)) manager.register(fakeLayer(id));
+  manager.finalizeRegistrations(
+    LAYER_STATE_REGISTRY.filter(({ id }) => !withheld.includes(id)),
+  );
+  return manager;
+}
+
+test('layers the application did not register are never restored, stored or shared', async () => {
+  const manager = managerWithout(['earthquakes']);
+  const storage = memoryStorage();
+  const share = shareSink();
+  const coordinator = new LayerStateCoordinator(manager, share, { storage });
+  const incoming = createDefaultLayerState();
+  incoming.enabledLayerIds = ['earthquakes', 'traffic'];
+  await coordinator.start({ shareLayerState: incoming });
+
+  assert.deepEqual(coordinator.getDurableState().enabledLayerIds, ['traffic']);
+  assert.deepEqual(share.provider().enabledLayerIds, ['traffic']);
+  assert.equal(manager.layers.has('earthquakes'), false);
+
+  await manager.setEnabled('cctv', true, { origin: 'user' });
+  const [[, written]] = storage.writes;
+  assert.deepEqual(parseStoredLayerState(written).enabledLayerIds, [
+    'cctv',
+    'traffic',
+  ]);
+  assert.deepEqual(share.provider().enabledLayerIds, ['cctv', 'traffic']);
+
+  await coordinator.applyShareLayerState({ shareLayerState: incoming });
+  assert.deepEqual(coordinator.getDurableState().enabledLayerIds, ['traffic']);
+  coordinator.destroy();
+
+  const saved = createDefaultLayerState();
+  saved.enabledLayerIds = ['earthquakes', 'traffic'];
+  const local = new LayerStateCoordinator(
+    managerWithout(['earthquakes']),
+    shareSink(),
+    { storage: memoryStorage(serializeStoredLayerState(saved)) },
+  );
+  await local.start();
+  assert.equal(local.source, 'local');
+  assert.deepEqual(local.getDurableState().enabledLayerIds, ['traffic']);
+  local.destroy();
+});
+
+test('an application with every layer registered keeps every requested layer', async () => {
+  const coordinator = new LayerStateCoordinator(
+    productionManager(),
+    shareSink(),
+    { storage: memoryStorage() },
+  );
+  const incoming = createDefaultLayerState();
+  incoming.enabledLayerIds = ['earthquakes', 'traffic'];
+  await coordinator.start({ shareLayerState: incoming });
+  assert.deepEqual(coordinator.getDurableState().enabledLayerIds, [
+    'earthquakes',
+    'traffic',
+  ]);
+  coordinator.destroy();
+});

src/data/layerStateCoordinator.js

@@ -106,9 +106,7 @@ export class LayerStateCoordinator {
   } = {}) {
     if (this._destroyed)
       throw new Error('Layer-state coordinator is destroyed');
-    let selected = shareLayerState
-      ? normalizeLayerState(shareLayerState)
-      : null;
+    let selected = shareLayerState ? this._normalize(shareLayerState) : null;
     if (selected) {
       this._source = 'share';
       this._shareCreatedAtMs = Number.isFinite(shareCreatedAtMs)
@@ -124,7 +122,7 @@ export class LayerStateCoordinator {
         /* best effort */
       }
       if (stored) {
-        selected = stored;
+        selected = this._normalize(stored);
         this._source = 'local';
       }
     } else {
@@ -163,9 +161,7 @@ export class LayerStateCoordinator {
     for (const controller of this._restoreControllers.values())
       controller.abort('superseded-by-share-navigation');
     this._revokePendingTrackingWatch('superseded-by-share-navigation');
-    const selected = shareLayerState
-      ? normalizeLayerState(shareLayerState)
-      : null;
+    const selected = shareLayerState ? this._normalize(shareLayerState) : null;
     this._source = selected ? 'share' : 'legacy-share';
     this._shareCreatedAtMs =
       selected && Number.isFinite(shareCreatedAtMs) ? shareCreatedAtMs : null;
@@ -182,6 +178,25 @@ export class LayerStateCoordinator {
     return this._source;
   }
 
+  /**
+   * Canonical layer state holding only the layers this application
+   * registered. An application built without a layer never restores, stores
+   * or shares it, even when a link or saved state from a build that has it
+   * names it. Filtering before normalizing lets normalization drop options
+   * that depend on a layer that is not here (a tracked selection).
+   */
+  _normalize(candidate) {
+    const input = candidate && typeof candidate === 'object' ? candidate : {};
+    return normalizeLayerState({
+      ...input,
+      enabledLayerIds: Array.isArray(input.enabledLayerIds)
+        ? input.enabledLayerIds.filter((id) =>
+            this.dataManager.layers.has(String(id)),
+          )
+        : [],
+    });
+  }
+
   getDurableState() {
     return cloneLayerState(this._durableState);
   }
@@ -345,7 +360,7 @@ export class LayerStateCoordinator {
   }
 
   _commitExplicit(candidate) {
-    this._durableState = normalizeLayerState(candidate);
+    this._durableState = this._normalize(candidate);
     const serialized = serializeStoredLayerState(this._durableState);
     try {
       if (this.storage?.getItem?.(LAYER_STATE_STORAGE_KEY) !== serialized) {
@@ -478,7 +493,7 @@ export class LayerStateCoordinator {
       ...this._durableState.options[selected.optionOwner],
       [selected.optionKey]: null,
     };
-    this._durableState = normalizeLayerState({
+    this._durableState = this._normalize({
       ...this._durableState,
       options: {
         ...this._durableState.options,

src/data/layerStateTokenLedger.test.mjs

@@ -97,14 +97,24 @@ function withPublishedBase(
   }
 }
 
+const preWildlifeRows = reservationRows.filter(
+  ([id]) => id !== 'wildlife-sightings',
+);
+
 function writeCodecFixture(cwd, rows, entries) {
-  const providerCodec = path.join(cwd, 'src/data/idSwitches.js');
-  mkdirSync(path.dirname(providerCodec), { recursive: true });
-  writeFileSync(
-    providerCodec,
-    readFileSync(new URL('./idSwitches.js', import.meta.url)),
-  );
-  const source = readFileSync(CODEC_SOURCE_PATH, 'utf8');
+  mkdirSync(path.join(cwd, 'src/data'), { recursive: true });
+  // The codec's own imports, beside it.
+  for (const name of ['idSwitches.js', 'satelliteClassMask.js'])
+    writeFileSync(
+      path.join(cwd, 'src/data', name),
+      readFileSync(new URL(`./${name}`, import.meta.url)),
+    );
+  let source = readFileSync(CODEC_SOURCE_PATH, 'utf8');
+  if (!rows.some(([id]) => id === 'wildlife-sightings'))
+    source = source.replace(
+      /  Object\.freeze\(\{\s*id: 'wildlife-sightings',[\s\S]*?\}\),\n/,
+      '',
+    );
   const registryEnd = ']);\n\nexport const REGISTERED_LAYER_IDS';
   assert.equal(source.split(registryEnd).length, 2);
   const additions = entries
@@ -128,7 +138,7 @@ test('reservation ledger is complete, pinned, and rejects duplicate or malformed
     { ...parseLayerStateTokenReservations(reservationRows) },
     { ...LAYER_STATE_TOKEN_RESERVATIONS },
   );
-  assert.equal(Object.keys(LAYER_STATE_TOKEN_RESERVATIONS).length, 35);
+  assert.equal(Object.keys(LAYER_STATE_TOKEN_RESERVATIONS).length, 36);
   assert.deepEqual(
     { ...LAYER_STATE_TOKEN_RESERVATIONS },
     {
@@ -140,6 +150,7 @@ test('reservation ledger is complete, pinned, and rejects duplicate or malformed
       'sea-marks': '6',
       'ski-pistes': '7',
       'drone-airspace': '8',
+      'wildlife-sightings': '9',
     },
   );
   assert.throws(
@@ -165,9 +176,9 @@ test('reservation ledger is complete, pinned, and rejects duplicate or malformed
     /Duplicate layer-state token reservation/,
   );
   assert.equal(
-    parseLayerStateTokenReservations([...reservationRows, ['future', '9']])
+    parseLayerStateTokenReservations([...reservationRows, ['future', '00']])
       .future,
-    '9',
+    '00',
   );
   assert.throws(
     () =>
@@ -185,7 +196,7 @@ test('reservation ledger is complete, pinned, and rejects duplicate or malformed
 
 test('published retired digits and competing PRs advance the merge-time allocation', () => {
   withPublishedBase(
-    { rows: [...reservationRows, ['retired-layer', '9']] },
+    { rows: [...preWildlifeRows, ['retired-layer', '9']] },
     (cwd) => {
       const published = readPublishedLayerStateReservations('HEAD', cwd);
       assert.equal(nextLayerStateToken(published), '00');
@@ -217,7 +228,7 @@ test('published retired digits and competing PRs advance the merge-time allocati
 });
 
 test('PR B manually replaces provisional 9 with 00 after PR A publishes 9', () => {
-  withPublishedBase({ rows: [...reservationRows, ['pr-a', '9']] }, (cwd) => {
+  withPublishedBase({ rows: [...preWildlifeRows, ['pr-a', '9']] }, (cwd) => {
     mkdirSync(path.join(cwd, 'scripts'));
     const fixtureChecker = path.join(
       cwd,
@@ -238,7 +249,7 @@ test('PR B manually replaces provisional 9 with 00 after PR A publishes 9', () =
 
     writeCodecFixture(
       cwd,
-      [...reservationRows, ['pr-b', '9']],
+      [...preWildlifeRows, ['pr-b', '9']],
       [{ id: 'pr-b', token: '9' }],
     );
     const beforeRebase = runCheck();
@@ -247,7 +258,7 @@ test('PR B manually replaces provisional 9 with 00 after PR A publishes 9', () =
 
     writeCodecFixture(
       cwd,
-      [...reservationRows, ['pr-a', '9'], ['pr-b', '9']],
+      [...preWildlifeRows, ['pr-a', '9'], ['pr-b', '9']],
       [
         { id: 'pr-a', token: '9' },
         { id: 'pr-b', token: '9' },
@@ -259,7 +270,7 @@ test('PR B manually replaces provisional 9 with 00 after PR A publishes 9', () =
 
     const published = readPublishedLayerStateReservations('HEAD', cwd);
     assert.equal(nextLayerStateToken(published), '00');
-    const validBaselineRows = [...reservationRows, ['pr-a', '9']];
+    const validBaselineRows = [...preWildlifeRows, ['pr-a', '9']];
     writeCodecFixture(cwd, validBaselineRows, [{ id: 'pr-a', token: '9' }]);
     const helper = spawnSync(
       process.execPath,
@@ -275,7 +286,7 @@ test('PR B manually replaces provisional 9 with 00 after PR A publishes 9', () =
     );
     writeCodecFixture(
       cwd,
-      [...reservationRows, ['pr-a', '9'], ['pr-b', '00']],
+      [...preWildlifeRows, ['pr-a', '9'], ['pr-b', '00']],
       [
         { id: 'pr-a', token: '9' },
         { id: 'pr-b', token: '00' },
@@ -290,7 +301,7 @@ test('PR B manually replaces provisional 9 with 00 after PR A publishes 9', () =
 test('allocation batches cross the last digit and base-36 pair boundaries in order', () => {
   const digitRows = [...'9'].map((digit) => [`retired-${digit}`, digit]);
   const allDigits = parseLayerStateTokenReservations([
-    ...reservationRows,
+    ...preWildlifeRows,
     ...digitRows,
   ]);
   const beforeNine = { ...allDigits };
@@ -349,7 +360,7 @@ test('an isolated valid two-character fixture round-trips an l field beyond the
       token,
     }));
     const fixtureRows = [
-      ...reservationRows,
+      ...preWildlifeRows,
       ...priorDigits,
       ...fixtureLayers.map(({ id, token }) => [id, token]),
     ];
@@ -358,13 +369,13 @@ test('an isolated valid two-character fixture round-trips an l field beyond the
     assert.equal(codec.validateLayerStateRegistry(), true);
     assert.equal(
       nextLayerStateToken(
-        parseLayerStateTokenReservations([...reservationRows, ...priorDigits]),
+        parseLayerStateTokenReservations([...preWildlifeRows, ...priorDigits]),
       ),
       '00',
     );
     assert.equal(
       validateLayerStateAllocations(
-        LAYER_STATE_TOKEN_RESERVATIONS,
+        parseLayerStateTokenReservations(preWildlifeRows),
         codec.LAYER_STATE_TOKEN_RESERVATIONS,
       ),
       true,
@@ -395,7 +406,7 @@ test('checker reads a complete future base ledger and rejects retired-token reus
     },
     (cwd) => {
       const published = readPublishedLayerStateReservations('HEAD', cwd);
-      assert.equal(Object.keys(published).length, 36);
+      assert.equal(Object.keys(published).length, 37);
       assert.equal(published['retired-layer'], '00');
       assert.throws(
         () =>

src/data/layerStateTokenReservations.json

@@ -33,5 +33,6 @@
   ["weather-lightning", "l"],
   ["weather-radar", "v"],
   ["weather-satellite", "o"],
+  ["wildlife-sightings", "9"],
   ["wind", "k"]
 ]

src/data/lifecycle.js

@@ -2385,11 +2385,27 @@ export class LayerLifecycle {
   /**
    * Ask presentation to repaint layer rows now, for data that lands outside
    * the manager tick (Transit's proximity polls, Directions' route steps).
+   * @param {string} [layerId] - The layer whose row changed.
    */
-  refreshLayerStats() {
+  refreshLayerStats(layerId) {
+    this._dropRecoveredRefreshError(layerId);
     this._publishActivity({ type: 'status' });
   }
 
+  /**
+   * Drop a tick failure the layer's stats no longer report (the camera left
+   * that feed) instead of showing it until the next tick.
+   */
+  _dropRecoveredRefreshError(layerId) {
+    const entry = layerId ? this.layers.get(layerId) : null;
+    if (!entry?.managerRefreshError || entry.refreshing) return;
+    const failure = refreshFailureFromStats(
+      this._moduleStats(entry),
+      entry.module.name || layerId,
+    );
+    if (!failure) entry.managerRefreshError = null;
+  }
+
   _publishActivity(change) {
     for (const callback of this._activityListeners) {
       try {

src/data/local_data/datacenters/README.md

@@ -5,7 +5,7 @@ layer.
 
 - Source: OpenStreetMap contributors
 - License: Open Database License (ODbL) 1.0
-- Feature count: 4,351
+- Feature count: 4,352
 - Runtime file: `datacenters.geojsonl`
 
 The public-release snapshot removes contact-oriented tags such as email, phone,
@@ -16,3 +16,12 @@ ODbL 1.0 with the required OpenStreetMap attribution.
 
 The original extraction date and query were not recorded alongside this
 snapshot. Future refreshes should record both before replacing the file.
+
+## Norway refresh
+
+Features inside Geofabrik's Norway boundary (`norway.poly`, with Svalbard) come
+from a newer extract than the rest of the file. Contact tags are dropped as above.
+
+- Extract: Geofabrik `norway-261005.osm.pbf`, OSM data
+  2026-10-05T20:21:35Z, MD5 `1d2cfdeb98980fce11b8891d0f9146c0`
+- Filter: `osmium tags-filter nwr/telecom=data_center nwr/building=data_center`

src/data/local_data/datacenters/datacenters.geojsonl

@@ -3770,15 +3770,15 @@
 {"id":939340882,"type":"Feature","geometry":{"type":"Polygon","coordinates":[[[21.021364183,52.315373019],[21.02232433,52.315435883],[21.022363641,52.315209656],[21.021403578,52.315146875],[21.021364183,52.315373019]]]},"properties":{"id":11407,"tags":{"name":"T-Mobile Warszawa-Szlachecka","telecom":"data_center","building":"office","building:levels":"3"},"type":"data_center","osm_id":939340882}}
 {"id":1005973518,"type":"Feature","geometry":{"type":"Polygon","coordinates":[[[21.021325375,52.315595978],[21.022285857,52.315658423],[21.02232433,52.315435883],[21.021364183,52.315373019],[21.021325375,52.315595978]]]},"properties":{"id":11976,"tags":{"telecom":"data_center","building":"office","building:levels":"3"},"type":"data_center","osm_id":1005973518}}
 {"id":1156823776,"type":"Feature","geometry":{"type":"Polygon","coordinates":[[[21.115130857,52.235385942],[21.115189866,52.236349777],[21.115232027,52.236667954],[21.115818174,52.237174556],[21.116175578,52.237468677],[21.117262124,52.236985628],[21.11728157,52.236976576],[21.117262795,52.236960985],[21.117340495,52.236926033],[21.117360276,52.2369433],[21.117447532,52.236904491],[21.11804097,52.236654459],[21.118030996,52.236645742],[21.118041054,52.236641719],[21.116603055,52.235624072],[21.116518984,52.235676375],[21.115986231,52.235696659],[21.115954966,52.235361551],[21.115130857,52.235385942]]]},"properties":{"id":15342,"tags":{"name":"Atman Data Center Warsaw-1","telecom":"data_center","website":"https://www.atman.pl"},"type":"data_center","osm_id":1156823776}}
-{"id":7405586142,"type":"Feature","geometry":{"type":"Point","coordinates":[5.598350034,58.860111293]},"properties":{"id":24849,"tags":{"name":"Maan Group","telecom":"data_center","operator":"Privat"},"type":"data_center","osm_id":7405586142}}
+{"id":7405586142,"type":"Feature","geometry":{"type":"Point","coordinates":[5.5983501,58.8601113]},"properties":{"id":24849,"tags":{"name":"Maan Group","opening_hours":"24/7","operator":"Privat","telecom":"data_center"},"type":"data_center","osm_id":7405586142}}
 {"id":481615983,"type":"Feature","geometry":{"type":"Polygon","coordinates":[[[9.572510149,56.481777951],[9.574069938,56.484921751],[9.57465357,56.48483349],[9.574639572,56.484805243],[9.574700676,56.484795939],[9.574714925,56.484824857],[9.575298557,56.484736595],[9.57454888,56.483225422],[9.574609229,56.483216369],[9.574510155,56.483016629],[9.574449722,56.483025849],[9.573738769,56.481592795],[9.573155137,56.481680972],[9.573170643,56.481712321],[9.573109539,56.481721625],[9.573093781,56.48168969],[9.572510149,56.481777951]]]},"properties":{"id":7881,"tags":{"telecom":"data_center","building":"data_center","operator":"Apple","wikidata":"Q19721053","wikipedia":"en:Foulum Data Center","description":"Apple Datacenter"},"type":"data_center","osm_id":481615983}}
 {"id":618756435,"type":"Feature","geometry":{"type":"Polygon","coordinates":[[[10.500360092,57.318668738],[10.500399236,57.318671672],[10.500382891,57.318734871],[10.500552038,57.318744175],[10.500545249,57.318787677],[10.500501495,57.318785666],[10.500458999,57.318957746],[10.500970295,57.31899647],[10.501009187,57.318847189],[10.501084959,57.318852888],[10.50111966,57.318719197],[10.500843896,57.318698159],[10.500865521,57.318615178],[10.500859235,57.318614759],[10.500869461,57.318575699],[10.500954537,57.318582153],[10.501022347,57.31832223],[10.500736691,57.318300437],[10.500669133,57.318559689],[10.500674162,57.318560025],[10.500664272,57.318598498],[10.500383981,57.318577124],[10.500360092,57.318668738]]]},"properties":{"id":8842,"tags":{"ref":"AAL01-01","name":"Prime Data Centers - Saeby Campus AAL01","telecom":"data_center","website":"https://primedatacenters.com/locations/saeby/","building":"industrial","operator":"Prime Data Centers"},"type":"data_center","osm_id":618756435}}
-{"id":-14367602,"type":"Feature","geometry":{"type":"Polygon","coordinates":[[[11.002243225,59.633471864],[11.003903261,59.633446551],[11.007046726,59.633399696],[11.006983443,59.632420941],[11.006982772,59.63227057],[11.006911023,59.632265289],[11.006852936,59.632253973],[11.006765848,59.632228576],[11.00671782,59.632205275],[11.006119687,59.632213573],[11.006119352,59.632202592],[11.006118933,59.63219245],[11.005930424,59.632194378],[11.005923635,59.632120869],[11.005980799,59.632120031],[11.005979542,59.632104524],[11.005977027,59.63206865],[11.00597225,59.631998242],[11.005412171,59.632035541],[11.005286945,59.632043839],[11.00527848,59.632044342],[11.003707962,59.632147272],[11.003107483,59.63219178],[11.002741864,59.632235533],[11.002729375,59.63223788],[11.002345987,59.632309294],[11.002308352,59.632316251],[11.002302066,59.632477351],[11.002277088,59.632913881],[11.002243225,59.633471864]]]},"properties":{"id":107,"tags":{"name":"STACK Infrastructure OSL04","type":"multipolygon","telecom":"data_center","website":"https://www.stackinfra.com","operator":"Stack Infrastructure","operator:wikidata":"Q115477173"},"type":"data_center","osm_id":-14367602}}
+{"id":-14367602,"type":"Feature","geometry":{"type":"Polygon","coordinates":[[[11.0022433,59.6334719],[11.0022771,59.6329139],[11.0023021,59.6324774],[11.0023084,59.6323163],[11.002346,59.6323093],[11.0027294,59.6322379],[11.0027419,59.6322356],[11.0031075,59.6321918],[11.003708,59.6321473],[11.0052785,59.6320444],[11.005287,59.6320439],[11.0054122,59.6320356],[11.0059723,59.6319983],[11.0059771,59.6320687],[11.0059796,59.6321046],[11.0059808,59.6321201],[11.0059237,59.6321209],[11.0059305,59.6321944],[11.006119,59.6321925],[11.0061194,59.6322026],[11.0061197,59.6322136],[11.0067179,59.6322053],[11.0067659,59.6322286],[11.006853,59.632254],[11.0069111,59.6322653],[11.0069828,59.6322706],[11.0069835,59.632421],[11.0070468,59.6333997],[11.0039033,59.6334466],[11.0022433,59.6334719]]]},"properties":{"id":107,"tags":{"landuse":"industrial","name":"STACK Infrastructure OSL04","operator":"Stack Infrastructure","operator:wikidata":"Q115477173","telecom":"data_center","website":"https://www.stackinfra.com","type":"multipolygon"},"type":"data_center","osm_id":-14367602}}
 {"id":1028687251,"type":"Feature","geometry":{"type":"Polygon","coordinates":[[[11.004111886,59.632578437],[11.004142983,59.633037262],[11.004275166,59.633034999],[11.004274998,59.63303173],[11.00505133,59.633019157],[11.005056443,59.633099372],[11.005224416,59.63309669],[11.005190637,59.632562344],[11.005060885,59.632564439],[11.005060969,59.632567457],[11.004587978,59.632575419],[11.00458538,59.632536527],[11.004459819,59.632538623],[11.004462418,59.632576844],[11.004242476,59.6325807],[11.004242141,59.632576174],[11.004111886,59.632578437]]]},"properties":{"id":12226,"tags":{"building":"data_center","ref:bygningsnr":"300783262"},"type":"data_center","osm_id":1028687251}}
 {"id":1164840308,"type":"Feature","geometry":{"type":"Polygon","coordinates":[[[11.002600126,59.632599392],[11.002631223,59.633058217],[11.00276349,59.633055954],[11.002763238,59.633052685],[11.00353957,59.633040196],[11.003544683,59.633120327],[11.00371274,59.633117645],[11.003678961,59.632583382],[11.003549042,59.632585478],[11.003549293,59.632588495],[11.003076135,59.632596458],[11.00307362,59.632557566],[11.002948143,59.632559661],[11.002950657,59.632597883],[11.002730716,59.632601571],[11.002730465,59.632597129],[11.002600126,59.632599392]]]},"properties":{"id":15459,"tags":{"building":"data_center","ref:bygningsnr":"300783262"},"type":"data_center","osm_id":1164840308}}
 {"id":1164840309,"type":"Feature","geometry":{"type":"Polygon","coordinates":[[[11.005613672,59.632723444],[11.005644769,59.633182269],[11.005776951,59.633179922],[11.005776784,59.633176737],[11.006553199,59.633164164],[11.006558229,59.633244463],[11.006726286,59.633241781],[11.006692423,59.632707351],[11.006562671,59.632709446],[11.006562839,59.632712464],[11.006089764,59.632720426],[11.006087166,59.632681534],[11.005961772,59.632683797],[11.005964287,59.632721851],[11.005744262,59.632725623],[11.005743927,59.632721181],[11.005613672,59.632723444]]]},"properties":{"id":15460,"tags":{"building":"data_center","ref:bygningsnr":"300783262"},"type":"data_center","osm_id":1164840309}}
-{"id":935092287,"type":"Feature","geometry":{"type":"Polygon","coordinates":[[[10.991467366,59.759024056],[10.992780978,59.759406942],[10.992773937,59.759423957],[10.992948197,59.759474248],[10.993073842,59.759363859],[10.993022293,59.759348939],[10.993291688,59.759112653],[10.993128827,59.759065547],[10.993181885,59.759019027],[10.993083062,59.758990445],[10.992976947,59.759083484],[10.992845519,59.759045346],[10.992813584,59.759073342],[10.9927876,59.759065798],[10.993409789,59.758524243],[10.99263002,59.758297094],[10.991938848,59.758898663],[10.991693594,59.758827165],[10.991467366,59.759024056]]]},"properties":{"id":11377,"tags":{"name":"Green Mountain Ytre Enebakk","telecom":"data_center","website":"https://greenmountain.no/","building":"warehouse","ref:bygningsnr":"300752944"},"type":"data_center","osm_id":935092287}}
-{"id":1161764012,"type":"Feature","geometry":{"type":"Polygon","coordinates":[[[10.992826324,59.757448761],[10.994530281,59.757601396],[10.994634888,59.757303168],[10.992928332,59.757152545],[10.992826324,59.757448761]]]},"properties":{"id":15426,"tags":{"name":"Green Mountain Ytre Enebakk","telecom":"data_center","website":"https://greenmountain.no/","building":"industrial"},"type":"data_center","osm_id":1161764012}}
+{"id":935092287,"type":"Feature","geometry":{"type":"Polygon","coordinates":[[[10.9914674,59.7590241],[10.9916936,59.7588272],[10.9919389,59.7588987],[10.9926301,59.7582971],[10.9934098,59.7585243],[10.9927876,59.7590658],[10.9928136,59.7590734],[10.9928456,59.7590454],[10.992977,59.7590835],[10.9930831,59.7589905],[10.9931819,59.7590191],[10.9931289,59.7590656],[10.9932917,59.7591127],[10.9930223,59.759349],[10.9930739,59.7593639],[10.9929482,59.7594743],[10.992774,59.759424],[10.992781,59.759407],[10.9914674,59.7590241]]]},"properties":{"id":11377,"tags":{"building":"warehouse","name":"Green Mountain Ytre Enebakk","ref:bygningsnr":"300752944","source":"Norway Orthophoto 2024;https://greenmountain.no/data-center/osl1-enebakk/","telecom":"data_center","website":"https://greenmountain.no/"},"type":"data_center","osm_id":935092287}}
+{"id":1161764012,"type":"Feature","geometry":{"type":"Polygon","coordinates":[[[10.9928264,59.7574488],[10.9929284,59.7571526],[10.9946349,59.7573032],[10.9945303,59.7576014],[10.9928264,59.7574488]]]},"properties":{"id":15426,"tags":{"building":"industrial","name":"Green Mountain Ytre Enebakk","source":"Norway Orthophoto 2024;https://greenmountain.no/data-center/osl1-enebakk/","telecom":"data_center","website":"https://greenmountain.no/"},"type":"data_center","osm_id":1161764012}}
 {"id":30724580,"type":"Feature","geometry":{"type":"Polygon","coordinates":[[[10.808790995,59.924984985],[10.808893925,59.925031923],[10.80893793,59.92500594],[10.808982941,59.925025972],[10.809042955,59.92501298],[10.809083943,59.925031923],[10.809012948,59.925077856],[10.80926583,59.925189755],[10.80955115,59.925025972],[10.809676543,59.925081293],[10.81032899,59.924701928],[10.809890365,59.924508138],[10.80982155,59.924515347],[10.809691631,59.924457847],[10.808820667,59.924557592],[10.809099365,59.924699581],[10.808806418,59.924865291],[10.808918149,59.924914828],[10.808875988,59.924937962],[10.808790995,59.924984985]]]},"properties":{"id":261,"tags":{"name":"Stack Infrastructure OSLO1A","telecom":"data_center","building":"office","operator":"Stack Infrastructure","ref:bygningsnr":"80877293","building:levels":"4","operator:wikidata":"Q115477173"},"type":"data_center","osm_id":30724580}}
 {"id":80871917,"type":"Feature","geometry":{"type":"Polygon","coordinates":[[[10.83408892,59.938588981],[10.834305927,59.938720996],[10.834575992,59.938720996],[10.834574987,59.938736],[10.834581943,59.938736922],[10.834579932,59.938771958],[10.834736925,59.938771958],[10.834734997,59.93893792],[10.836717988,59.938944961],[10.836717988,59.938983937],[10.836817984,59.938983937],[10.83681899,59.938944961],[10.836844974,59.938944961],[10.836846985,59.938774976],[10.836841956,59.938774976],[10.836842962,59.938744968],[10.836849919,59.938744968],[10.836851931,59.938653941],[10.836683957,59.938652935],[10.836684125,59.938640278],[10.836686975,59.938414973],[10.83490297,59.938406926],[10.834899953,59.938646984],[10.834812949,59.938645978],[10.83481496,59.938551933],[10.834579932,59.938550927],[10.834580938,59.938564925],[10.834567946,59.938564925],[10.834567946,59.938551933],[10.834089926,59.938549922],[10.83408892,59.938588981]]]},"properties":{"id":1464,"tags":{"name":"Bulk Data Centers Oslo Internet Exchange","telecom":"data_center","website":"https://bulkinfrastructure.com/data-centers/locations/os-ix","building":"industrial","ref:bygningsnr":"80709943"},"type":"data_center","osm_id":80871917}}
 {"id":12158409495,"type":"Feature","geometry":{"type":"Point","coordinates":[9.689363435,62.59439936]},"properties":{"id":28723,"tags":{"name":"VisBook AS","telecom":"data_center","website":"https://visbook.com/"},"type":"data_center","osm_id":12158409495}}
@@ -4349,3 +4349,4 @@
 {"id":540895898,"type":"Feature","geometry":{"type":"Polygon","coordinates":[[[101.71747909,56.303855963],[101.71782015,56.304420065],[101.721113819,56.303806929],[101.720772759,56.303242994],[101.71747909,56.303855963]]]},"properties":{"id":8271,"tags":{"name":"Битривер Рус","name:en":"Bitriver Rus","name:ru":"Битривер Рус","telecom":"data_center","website":"https://bitriver.farm/","building":"data_center"},"type":"data_center","osm_id":540895898}}
 {"id":1082803064,"type":"Feature","geometry":{"type":"Polygon","coordinates":[[[123.948021193,47.340264299],[123.948354625,47.340268239],[123.948490663,47.340269831],[123.948488568,47.340349292],[123.948809762,47.340353064],[123.948811942,47.340267485],[123.948918643,47.340268658],[123.948922918,47.340137817],[123.948023959,47.340126082],[123.948021193,47.340264299]]]},"properties":{"id":13377,"tags":{"name":"联通云数据中心·齐齐哈尔","name:en":"Unicom Data Center of Qiqihar","name:zh":"联通云数据中心·齐齐哈尔","telecom":"data_center","building":"yes","name:zh-Hans":"联通云数据中心·齐齐哈尔","name:zh-Hant":"聯通雲數據中心·齊齊哈爾"},"type":"data_center","osm_id":1082803064}}
 {"id":442479059,"type":"Feature","geometry":{"type":"Polygon","coordinates":[[[142.76019226,46.910096898],[142.760192427,46.910325724],[142.760447656,46.910328155],[142.760460397,46.910102263],[142.76019226,46.910096898]]]},"properties":{"id":7471,"tags":{"telecom":"data_center","building":"yes"},"type":"data_center","osm_id":442479059}}
+{"id":1551029155,"type":"Feature","geometry":{"type":"Polygon","coordinates":[[[7.1069147,62.8627625],[7.1071207,62.8621617],[7.1075917,62.8616616],[7.1088647,62.8620476],[7.1106308,62.862645],[7.1098655,62.8632827],[7.1089604,62.8630042],[7.1086734,62.8632156],[7.1069147,62.8627625]]]},"properties":{"id":29471,"tags":{"layer":"-1","loc_name":"Troll Housing Klempertåsen","name":"Troll Housing","operator":"Troll Housing AS","telecom":"data_center","website":"https://www.trollhousing.no/"},"type":"data_center","osm_id":1551029155}}

src/data/local_data/imaging_sensors/README.md

@@ -0,0 +1,63 @@
+# Imaging sensor pack
+
+Swath widths and ground resolutions for 46 Earth-observation platforms and
+constellations, matched to satellites by NORAD catalog number or by their
+CelesTrak name. The orbital view draws a satellite's sensor swath to scale and
+lets it zoom past 8x only as far as that swath (`src/layers/satellites/sensors.js`,
+`src/data/imagingSensors.js`, `orbitalMaxZoom` in `src/cockpitOrbital.js`).
+
+| File | Content | Entries |
+|------|---------|---------|
+| `imaging_sensors.json` | Platform, match rule, operator, instruments, altitude, imaging modes (swath km, best ground resolution m), narrowest standard swath, sources, unverified fields | 46 |
+
+**Compiled:** 2026-11-04, by hand from the pages cited per entry (`sources`).
+Each match pattern was checked against CelesTrak's active list that day.
+Altitude is the nominal value from a cited source; where none was found it is
+the median altitude of the matching satellites from CelesTrak GP data, noted in
+`unverified`. The app zooms on the live altitude, not this one.
+
+**Narrowest standard swath** is the narrowest continuous standard imaging swath
+or scene width (cross-track); for a geostationary imager, the narrower side of
+its smallest standard scan area. Some listed modes are left out of it:
+
+- Sampling modes: SAR wave vignettes, and Himawari's Landmark Area scans
+  (1000 × 500 km), so Himawari's narrowest is the 1000 km Target Area.
+- Generations the operator has retired: PlanetScope's Dove Classic and Dove-R
+  (about 25 km scenes, imagery until April 2022 per Planet) stay in `modes`,
+  while its narrowest is the SuperDove's 32.5 km. The `^FLOCK ` name rule
+  would also match those older Doves.
+
+**Unverified values.** A value not confirmed on an opened page is named in the
+entry's `unverified` list. `swathConfirmed` is false when the narrowest swath is
+missing or unverified; such a platform keeps the base 1–8x zoom steps:
+
+- Landsat 9 (swath inferred from Landsat 8), ResourceSat-2 (LISS-3 swath),
+  SuperView Neo-1 (12 km from search snippets only), BlackSky and Meteosat
+  MTG FCI (no swath found).
+
+## Sources and licences
+
+The values are individual specification facts, each cited from the
+operator's or agency's official pages listed per entry in `sources`. No text or
+images are copied. The main sources:
+
+- **Operator and agency pages and spec sheets** (NASA, USGS, NOAA/NESDIS,
+  ESA SentiWiki and Earth Online, EUMETSAT, JAXA, ISRO/NRSC, INPE, CSA, DLR,
+  JMA, ASI, KARI, China's Ministry of Natural Resources (LASAC), Planet,
+  Vantor (formerly Maxar) datasheet pages, L3Harris, China Siwei, BlackSky,
+  Airbus and KOMPSAT-5 via the Disasters Charter, ICEYE, Capella, Umbra,
+  Satellogic, Chang Guang).
+- **Academic papers and proceedings** (Sensors papers on Gaofen-3, KARI's
+  ACRS 2012 paper on KOMPSAT-3, CAST's IAC-16 abstract on Gaofen-2).
+- **eoPortal** (ESA's mission directory, an institutional source): a swath
+  read there counts as confirmed. It is cited beside the operator's and
+  agency's pages, and alone for values they do not give (the wider modes of
+  Gaofen-3 and COSMO-SkyMed Second Generation, and a few other entries).
+  Gaofen-1 takes eoPortal's 69 km PMS and 830 km WFV swaths by maintainer
+  choice; a 2019 Chinese lecture and a Sensors paper give 60 and 800 km.
+- **CEOS MIM Database** (https://database.eohandbook.com): CC BY 4.0 since
+  7 September 2026, with the credit "CEOS MIM Database,
+  https://database.eohandbook.com". No entry relies on it yet; credit it if
+  values are taken from it later.
+
+Listed in DATA_SOURCES.md and in the app's Data attribution popover.

src/data/local_data/imaging_sensors/imaging_sensors.json

@@ -0,0 +1 @@
+{"version":1,"generated":"2026-11-04","entries":[{"id":"landsat-8-9","label":"Landsat 8 / Landsat 9","match":{"norad":[39084,49260],"nameRegex":"^LANDSAT [89]$"},"operator":"NASA / USGS","sensor":"OLI / OLI-2 / TIRS / TIRS-2","type":"multispectral / thermal","altitudeKm":705,"modes":[{"name":"OLI / OLI-2 · Standard scene","swathKm":185,"gsdM":15},{"name":"TIRS / TIRS-2 · Standard scene","swathKm":185,"gsdM":100}],"narrowestSwathKm":185,"swathConfirmed":false,"sources":["https://www.usgs.gov/landsat-missions/landsat-8","https://www.usgs.gov/landsat-missions/landsat-9"],"unverified":["Landsat 9 swath (inferred from Landsat 8)"]},{"id":"sentinel-2","label":"Sentinel-2A/B/C","match":{"norad":[40697,42063,60989],"nameRegex":"^SENTINEL-2[A-D]$"},"operator":"ESA / EU Copernicus","sensor":"MSI","type":"multispectral","altitudeKm":786,"modes":[{"name":"MSI · Nominal","swathKm":290,"gsdM":10}],"narrowestSwathKm":290,"swathConfirmed":true,"sources":["https://sentiwiki.copernicus.eu/web/s2-mission"],"unverified":[]},{"id":"sentinel-1","label":"Sentinel-1A/C/D","match":{"norad":[39634,62261,66315],"nameRegex":"^SENTINEL-1[A-D]$"},"operator":"ESA / EU Copernicus","sensor":"C-SAR","type":"SAR","altitudeKm":693,"modes":[{"name":"C-SAR · Stripmap (SM)","swathKm":80,"gsdM":5},{"name":"C-SAR · Interferometric Wide (IW)","swathKm":250,"gsdM":5},{"name":"C-SAR · Extra Wide (EW)","swathKm":400,"gsdM":20},{"name":"C-SAR · Wave (WV)","swathKm":null,"gsdM":5}],"narrowestSwathKm":80,"swathConfirmed":true,"sources":["https://sentiwiki.copernicus.eu/web/s1-mission"],"unverified":[]},{"id":"sentinel-3","label":"Sentinel-3A/B/C","match":{"norad":[41335,43437,100690],"nameRegex":"^SENTINEL-3[A-D]$"},"operator":"ESA / EUMETSAT (Copernicus)","sensor":"OLCI / SLSTR","type":"multispectral / thermal","altitudeKm":814.5,"modes":[{"name":"OLCI · Full resolution","swathKm":1270,"gsdM":300},{"name":"SLSTR · Nadir view","swathKm":1400,"gsdM":500},{"name":"SLSTR · Oblique view","swathKm":740,"gsdM":500}],"narrowestSwathKm":740,"swathConfirmed":true,"sources":["https://sentiwiki.copernicus.eu/web/s3-mission"],"unverified":[]},{"id":"terra-aqua-modis","label":"Terra / Aqua","match":{"norad":[25994,27424],"nameRegex":"^(TERRA|AQUA)$"},"operator":"NASA","sensor":"MODIS","type":"multispectral","altitudeKm":705,"modes":[{"name":"MODIS · Cross-track scan","swathKm":2330,"gsdM":250}],"narrowestSwathKm":2330,"swathConfirmed":true,"sources":["https://ladsweb.modaps.eosdis.nasa.gov/missions-and-measurements/modis/"],"unverified":["Aqua altitude (assumed same as Terra)"]},{"id":"viirs","label":"Suomi NPP / NOAA-20 / NOAA-21","match":{"norad":[37849,43013,54234],"nameRegex":"^(SUOMI NPP|NOAA 2[01] \\(JPSS-[12]\\))$"},"operator":"NASA / NOAA (JPSS)","sensor":"VIIRS","type":"multispectral","altitudeKm":830,"modes":[{"name":"VIIRS · Cross-track scan","swathKm":3000,"gsdM":375}],"narrowestSwathKm":3000,"swathConfirmed":true,"sources":["https://ladsweb.modaps.eosdis.nasa.gov/missions-and-measurements/viirs/","https://www.earthdata.nasa.gov/data/catalog/laads-vj102img-2.1"],"unverified":[]},{"id":"goes-abi","label":"GOES-16/17/18/19 (GOES-R series)","match":{"norad":[41866,43226,51850,60133],"nameRegex":"^GOES 1[6-9]$"},"operator":"NOAA / NASA","sensor":"ABI","type":"multispectral","altitudeKm":35786,"modes":[{"name":"ABI · Full disk","swathKm":null,"gsdM":500},{"name":"ABI · CONUS","swathKm":3000,"gsdM":500},{"name":"ABI · Mesoscale sector","swathKm":1000,"gsdM":500}],"narrowestSwathKm":1000,"swathConfirmed":true,"sources":["https://www.nesdis.noaa.gov/advanced-baseline-imager-scan-mode-information"],"unverified":["altitudeKm (standard GEO value)"]},{"id":"himawari-ahi","label":"Himawari-8 / Himawari-9","match":{"norad":[40267,41836],"nameRegex":"^HIMAWARI-[89]$"},"operator":"JMA","sensor":"AHI","type":"multispectral","altitudeKm":35786,"modes":[{"name":"AHI · Full Disk","swathKm":11000,"gsdM":500},{"name":"AHI · Japan Area","swathKm":2400,"gsdM":500},{"name":"AHI · Target Area","swathKm":1000,"gsdM":500},{"name":"AHI · Landmark Area","swathKm":500,"gsdM":500}],"narrowestSwathKm":1000,"swathConfirmed":true,"sources":["https://www.data.jma.go.jp/mscweb/en/himawari89/space_segment/spsg_ahi.html"],"unverified":["altitudeKm (standard GEO value)"]},{"id":"mtg-fci","label":"Meteosat Third Generation imager (Meteosat-12 / MTG-I2)","match":{"norad":[54743,100530],"nameRegex":"^(METEOSAT-12|MTG-I\\d)"},"operator":"EUMETSAT","sensor":"FCI","type":"multispectral","altitudeKm":35786,"modes":[{"name":"FCI · Full disc","swathKm":null,"gsdM":1000},{"name":"FCI · Rapid scan (Europe, 1/4 disc)","swathKm":null,"gsdM":500}],"narrowestSwathKm":null,"swathConfirmed":false,"sources":["https://www.esa.int/Applications/Observing_the_Earth/Meteorological_missions/Meteosat/About_Meteosat_Third_Generation","https://www-cdn.eumetsat.int/files/2020-04/pdf_mtg_goesr_ws_1.pdf"],"unverified":["narrowestSwathKm","altitudeKm (standard GEO value)"]},{"id":"gaofen-1","label":"GaoLine truncated

src/data/local_data/natural_earth/README.md

@@ -10,6 +10,7 @@ range geometry with no network dependency.
 | `marine.json` | `ne_10m_geography_marine_polys` (seas, gulfs, straits, bays, …) | 292 named |
 | `countries.json` | `ne_10m_admin_0_countries` (countries) | 256 |
 | `states_provinces.json` | `ne_10m_admin_1_states_provinces` (states, provinces and other first-level units) | 4,587 named |
+| `populated_places.json` | `ne_10m_populated_places_simple` (cities and towns, as points) | 7,342 |
 
 **Source:** Natural Earth 10m physical vectors, via the canonical
 [nvkelso/natural-earth-vector](https://github.com/nvkelso/natural-earth-vector)
@@ -103,3 +104,23 @@ Includes England, Scotland, Wales and Northern Ireland from
 `ne_10m_admin_0_map_units.geojson` at the same commit (SHA-256
 `57da82be755f4afccd8f3b14251bb2752f5df1395f47d2d86f817470c4a48862`).
 Result: 945,843 bytes; 260 features, 2,088 parts, 122,788 vertices.
+
+## Populated places (`populated_places.json`)
+
+The orbital view's "near <city>" (`src/data/placeBelow.js`): from 8x it
+names the most prominent place within half the view's width.
+
+**Source:** `geojson/ne_10m_populated_places_simple.geojson` at the pinned
+commit `ca96624a56bd078437bca8184e78163e5039ad19` (SHA-256
+`fd3fa867a320cbd5c5b6bb5bc550afeec2939fb2cef688e508007282a55ac42f`, the file
+the admin-1 build already reads), fetched 2026-11-04. Public domain, as above.
+
+**Regenerate:** `node scripts/build-admin-packs.mjs --only places`.
+
+**Schema:** `meta` (source, URL, hash, license, curation) and `places[]`, each
+`[name, latitude, longitude, scalerank, rank_max]`: `scalerank` 0 (most
+prominent) to 10, `rank_max` the population class (0 to 14, higher is
+larger). Sorted by `scalerank`, then `rank_max` descending, then name.
+
+**Curation:** every place kept; all other attributes dropped; coordinates
+rounded to 3 decimals (~110 m). Result: 229,461 bytes (98,444 with gzip -9).

src/data/local_data/natural_earth/populated_places.json

@@ -0,0 +1 @@
+{"meta":{"title":"Natural Earth populated places","source":"ne_10m_populated_places_simple","url":"https://raw.githubusercontent.com/nvkelso/natural-earth-vector/ca96624a56bd078437bca8184e78163e5039ad19/geojson/ne_10m_populated_places_simple.geojson","sha256":"fd3fa867a320cbd5c5b6bb5bc550afeec2939fb2cef688e508007282a55ac42f","commit":"ca96624a56bd078437bca8184e78163e5039ad19","license":"Public domain (https://www.naturalearthdata.com/about/terms-of-use/)","schema":"places[]: [name, latitude, longitude, scalerank (0 most prominent .. 10), rank_max (population class, 0..14; higher is larger)]","decimals":3,"curation":{"decimals":3},"script":"scripts/build-admin-packs.mjs"},"places":[["Beijing",39.931,116.386,0,14],["Cairo",30.052,31.248,0,14],["Istanbul",41.107,29.008,0,14],["Kolkata",22.497,88.323,0,14],["Los Angeles",33.992,-118.182,0,14],["Mexico City",19.444,-99.133,0,14],["Moscow",55.754,37.614,0,14],["Mumbai",19.019,72.855,0,14],["New York",40.752,-73.982,0,14],["Rio de Janeiro",-22.923,-43.227,0,14],["São Paulo",-23.557,-46.627,0,14],["Shanghai",31.218,121.435,0,14],["Tokyo",35.687,139.749,0,14],["Bogota",4.598,-74.085,0,13],["Hong Kong",22.307,114.183,0,13],["Jakarta",-6.172,106.827,0,13],["Lagos",6.445,3.39,0,13],["London",51.502,-0.119,0,13],["Paris",48.869,2.331,0,13],["Santiago",-33.448,-70.669,0,13],["Singapore",1.295,103.854,0,13],["Cape Town",-33.918,18.433,0,12],["Nairobi",-1.281,36.815,0,12],["Riyadh",24.643,46.771,0,12],["Rome",41.898,12.481,0,12],["Sydney",-33.918,151.183,0,12],["Washington,  D.C.",38.901,-77.011,0,12],["Buenos Aires",-34.601,-58.399,1,14],["Manila",14.606,120.98,1,14],["Ōsaka",34.752,135.458,1,14],["Baghdad",33.341,44.392,1,13],["Bangkok",13.752,100.515,1,13],["Bengaluru",12.972,77.558,1,13],["Chicago",41.832,-87.752,1,13],["Kinshasa",-4.328,15.313,1,13],["Lima",-12.046,-77.052,1,13],["Madrid",40.402,-3.685,1,13],["Miami",25.79,-80.226,1,13],["Seoul",37.568,126.998,1,13],["Taipei",25.036,121.568,1,13],["Tehran",35.674,51.422,1,13],["Toronto",43.702,-79.422,1,13],["Addis Ababa",9.035,38.698,1,12],["Amsterdam",52.352,4.915,1,12],["Athens",37.985,23.731,1,12],["Atlanta",33.832,-84.402,1,12],["Auckland",-36.848,174.763,1,12],["Berlin",52.524,13.4,1,12],["Caracas",10.503,-66.919,1,12],["Casablanca",33.602,-7.618,1,12],["Chengdu",30.672,104.068,1,12],["Dakar",14.718,-17.475,1,12],["Denver",39.741,-104.986,1,12],["Dubai",25.232,55.278,1,12],["Geneva",46.21,6.14,1,12],["Houston",29.822,-95.342,1,12],["Johannesburg",-26.168,28.028,1,12],["Kabul",34.519,69.181,1,12],["Kyiv",50.435,30.515,1,12],["Melbourne",-37.818,144.973,1,12],["Monterrey",25.672,-100.332,1,12],["San Francisco",37.769,-122.417,1,12],["Stockholm",59.353,18.095,1,12],["Tashkent",41.314,69.293,1,12],["Ürümqi",43.807,87.573,1,12],["Vancouver",49.275,-123.124,1,12],["Vienna",48.202,16.365,1,12],["New Delhi",28.6,77.2,1,10],["Delhi",28.672,77.228,2,14],["Dhaka",23.725,90.407,2,14],["Karachi",24.872,66.988,2,14],["Ahmedabad",23.032,72.578,2,13],["Chennai",13.092,80.278,2,13],["Chongqing",29.567,106.593,2,13],["Guangzhou",23.147,113.323,2,13],["Ho Chi Minh City",10.782,106.693,2,13],["Hyderabad",17.402,78.478,2,13],["Lahore",31.562,74.348,2,13],["Luanda",-8.836,13.232,2,13],["Philadelphia",40.002,-75.172,2,13],["Shenzhen",22.554,114.12,2,13],["Tianjin",39.132,117.198,2,13],["Wuhan",30.582,114.268,2,13],["Abidjan",5.322,-4.042,2,12],["Accra",5.552,-0.219,2,12],["Aleppo",36.232,37.168,2,12],["Alexandria",31.202,29.948,2,12],["Algiers",36.765,3.049,2,12],["Ankara",39.929,32.862,2,12],["Bandung",-6.948,107.568,2,12],["Baotou",40.654,109.82,2,12],["Barcelona",41.385,2.181,2,12],["Belém",-1.448,-48.482,2,12],["Boston",42.332,-71.072,2,12],["Brasília",-15.781,-47.918,2,12],["Brussels",50.835,4.331,2,12],["Bucharest",44.435,26.098,2,12],["Budapest",47.502,19.081,2,12],["Cali",3.402,-76.502,2,12],["Changchun",43.867,125.338,2,12],["Changsha",28.202,112.968,2,12],["Chattogram",22.332,91.798,2,12],["Curitiba",-25.418,-49.322,2,12],["Dallas",32.822,-96.842,2,12],["Damascus",33.502,36.298,2,12],["Dar es Salaam",-6.798,39.266,2,12],["Detroit",42.332,-83.082,2,12],["Dongguan",23.051,113.743,2,12],["Dublin",53.335,-6.251,2,12],["Durban",-29.863,30.978,2,12],["Edmonton",53.552,-113.502,2,12],["Fortaleza",-3.748,-38.582,2,12],["Frankfurt",50.1,8.675,2,12],["Fuzhou",26.082,119.298,2,12],["Goiânia",-16.718,-49.302,2,12],["Guadalajara",20.672,-103.332,2,12],["Guayaquil",-2.218,-79.922,2,12],["Guiyang",26.582,106.718,2,12],["Hamburg",53.552,9.998,2,12],["Hangzhou",30.252,120.168,2,12],["Hanoi",21.035,105.848,2,12],["Harbin",45.752,126.648,2,12],["Havana",23.134,-82.366,2,12],["Helsinki",60.178,24.932,2,12],["Hiroshima",34.39,132.441,2,12],["Jaipur",26.923,75.808,2,12],["Jeddah",21.519,39.217,2,12],["Jinan",36.677,116.993,2,12],["Kano",12.002,8.518,2,12],["Kanpur",26.462,80.318,2,12],["Khartoum",15.59,32.532,2,12],["København",55.681,12.562,2,12],["Kuala Lumpur",3.169,101.698,2,12],["Kunming",25.072,102.678,2,12],["Kuwait City",29.372,4Line truncated

src/data/local_data/owner_flags/README.md

@@ -0,0 +1,18 @@
+# Owner flags
+
+`owner_flags.png` is one sheet of every owner country a satellite can be
+marked with (`OWNER_COUNTRY_CODES` in `src/layers/satellites/classes.js`),
+drawn at 40 × 30 px (twice the orbital readout's 20 × 15) in sorted code
+order, 16 to a row, each followed by 2 transparent pixels so a scaled flag
+never smooths into its neighbour. `src/ui/ownerFlag.js` loads it once at startup and draws
+each flag from its cell; the layout is `src/ui/ownerFlagSheet.js`.
+
+**Source:** the 4:3 SVGs of [flag-icons](https://github.com/lipis/flag-icons)
+7.5.0 (a devDependency, used only to build the sheet).
+
+**License:** flag-icons is MIT licensed (© Panayiotis Lipiridis). Country
+flags themselves are not copyrightable designs in most jurisdictions.
+
+**Regenerate:** `node scripts/build-owner-flags.mjs` (after adding an owner
+country, or updating flag-icons). With the same flag-icons and sharp versions
+a rerun reproduces both files byte for byte.

src/data/local_data/ucs_satellites/README.md

@@ -0,0 +1,50 @@
+# UCS Satellite Database pack
+
+Offline operator, owner-country and purpose records for active satellites,
+keyed by NORAD catalog number. The satellites layer joins them to CelesTrak's
+positions to file each satellite under a class (stations, imaging, telecom,
+probes) and to name its operator and owner country
+(`src/data/ucsSatellites.js`, `src/layers/satellites/classes.js`).
+
+| File | Source dataset | Records |
+|------|----------------|---------|
+| `ucs_satellites.json` | UCS Satellite Database, release **UCS-Satellite-Database 5-1-2023** (data current through 2023-05-01) | 3,564 |
+
+**Source:** Union of Concerned Scientists, https://www.ucsusa.org/satellite_database.
+The same release is mirrored on Hugging Face as
+`juliensimon/ucs-satellite-database` (identical rows). UCS has paused updates
+since this release, so satellites launched after May 2023 are not in it; the
+layer classifies those from CelesTrak SATCAT, CelesTrak groups and name
+patterns instead.
+
+**License:** free, unrestricted use. Section 3 of the UCS database manual:
+"The Database is free and its use is unrestricted. We request that its use be
+acknowledged and referenced in written materials. References should include
+the version of the Database that was used, which is indicated by the name of
+the Excel file, and a link to or URL for the webpage
+www.ucsusa.org/satellite_database."
+
+**Acknowledgement:** "Satellite operators and purposes: UCS Satellite Database
+(UCS-Satellite-Database 5-1-2023), https://www.ucsusa.org/satellite_database".
+It is also listed in the app's Data attribution popover and in
+DATA_SOURCES.md.
+
+**Build:** `python scripts/build-ucs-satellites.py "<path>/UCS-Satellite-Database 5-1-2023.xlsx"`
+(openpyxl). The file's `meta` header records the curation.
+
+**Curation:**
+
+- Kept columns: Operator/Owner, Country of Operator/Owner and Purpose, the
+  ones the layer reads. Everything else (detailed purpose, users, orbits,
+  masses, contractors, launch data, sources) is left out.
+- Repeated text is stored once in `strings`; each record is
+  `[noradId, operator, operatorCountry, purpose]` with string-table indexes,
+  `0` meaning empty.
+- The 3,996 Starlink rows are dropped: every Starlink object is classed and
+  credited to SpaceX by name, so they would only add size.
+- Rows without a readable, positive NORAD number are dropped and counted apart
+  from duplicate NORAD numbers (the first row of a duplicate is kept); both
+  counts are 0 in this release.
+- Owner countries stay as UCS writes them ("USA", "USA/Japan", "ESA",
+  "Multinational"); `src/layers/satellites/classes.js` normalises them, together with
+  CelesTrak SATCAT owner codes, in one table.

src/data/local_data/ucs_satellites/ucs_satellites.json

@@ -0,0 +1 @@
+{"meta":{"source":"Union of Concerned Scientists Satellite Database","version":"UCS-Satellite-Database 5-1-2023","url":"https://www.ucsusa.org/satellite_database","dataCurrentTo":"2023-05-01","license":"Free, unrestricted use; acknowledgement requested (UCS database manual, section 3)","curation":{"sourceRows":7560,"starlinkRowsDropped":3996,"invalidNoradDropped":0,"duplicateNoradDropped":0,"columns":{"operator":"Operator/Owner","operatorCountry":"Country of Operator/Owner","purpose":"Purpose"}},"recordCount":3564},"fields":["noradId","operator","operatorCountry","purpose"],"strings":{"operator":["","Hera Systems","AAC Clyde Space","Aalto University","University of Aalborg","Asia Broadcast Satellite Ltd.","Asher Space Research Institute at Technion/Israeli Aircraft Industries","Austrian Space Forum (OEWF)/Spire","National Reconnaissance Office (NRO)","US Air Force","Department of Homeland Security","European Space Agency (ESA)","Aerospace Corporation","EUTELSAT S.A.","Aurora Insight","Center for Atmospheric Sciences, Hampton University/NASA","Norwegian Coastal Admnistration","AISTech","Al Yah Satellite Communications Co. (YAHSAT)","Al-Farabi Kazakh National University","Algerian Space Agency (ASAL)","Astro Live Experiences","University of Brasilia","US Air Force Institute of Technology","Algerian Space Agency (ASAL)/UK Space Agency","Hispamar (subsidiary of Hispasat - Spain)","National Institute for Space Research (INPE)","SES S.A.","Moscow State University","Space-Communication Ltd.","AMSAT-NA","Agency for Defense Development","ANDESITE - Boston University","Centre National d'Etudes Spatiales (CNES)","AngoSat","Telesat Canada Ltd. (BCE, Inc.)","Aprize Satellite, Argentina","APT Satellite Holdings Ltd.","Arab Satellite Communications Org. (ASCO)","University of South Florida, Institute of Applied Engineering (IAE).","Norwegian Defence Research Establishment","Aoyama Gakuin University in Tokyo","Naval Physical and Oceanographic Laboratory","Planetary Resources","ArSat","Aerospacelab","Istanbul Technical University","Asia Satellite Telecommunications Co. Ltd.","1Worldspace","Japan Space Systems","Chiba Institute of Technology","Astranis","Astrocast","Telemetry Tracking and Command Network (ISTRAC) Centre","DirecTV, Inc.","PointView Tech","Centre National d'Etudes Spatiales (CNES)/Agenzia Spaziale Italiana (ASI)","Microspace Rapid Pvt Ltd.","Azercosmos","Bangladesh Telecommunication Regulatory Commission (BTRC)","Tianyi Research Institute","Ministry of Defense","Space Development Agency","Central European Institute of Technology","Technical University Berlin","Chinese Ministry of National Defense","21st Century Aerospace Technology (21AT)","Beijing Landview Mapping Information Technology Co. Ltd (BLMIT)","Changsha Tianyi space science and Technology Research Institute Co., Ltd. (Spacety)","Belintersat","Institute of Space Sensor Technology and Planetary Exploration","Norwegian Defence Research Establishment (FFI)/","German Aerospace Center (DLR)","Salish Kootenai College","National Academy of Sciences","BlackSky Global","NanoAvionics","AST SpaceMobile","Embratel Star One","SpaceQuest, Ltd.","Bank Rakyat Indonesia (BRI)","University of Toronto, Institute for Aerospace Studies","BRITE Consortium","UnseenLabs","AstroForge","Broadcasting Satellite System Corp.","Broadcasting Satellite System Corp./Sky Perfect JSAT Corporation","Defence Science and Technology Group/University of New South Wales","China Academy of Space Technology (CAST)","Satellogic S.A.","Bulsatcom","Capital Technology University","Centre National d'Etudes Spatiales (CNES)/NASA","University of Louisiana at Lafayette","Capella Space","Indian Space Research Organization (ISRO)","Korea Aerospace Research Institute (KARI)","Canadian Space Agency","China National Space Administration (CNSA)/National Institute for Space Research (Brazil)","Surrey Satellite Technology Ltd.","Earth-i/Surrey Satellite Technology Ltd.","Canon Electronics","Air Force Research Laboratory","Fleet Space Technologies","Beijing Future Navigation Technology Co. Ltd.","NASA Goddard Space Flight Center","Ministry of Armed Forces","Defense Innovation Unit/Cesium Astro","China National Space Administration (CNSA)/National Centre for Space Studies (CNES)","TELNET Holding","National Aeronautics and Space Administration (NASA) Goddard Space Flight Center","Spacety Aerospace Company","Shanghai Engineering Center for Microsatellites","Spacety Co. Ltd.","Nanjing University","Epic Aerospace","University of Florida","Chinese Academy of Sciences","GeoOptics Inc.","GeoOptics, Inc.","Ciel Satellite Group","University of California-Berkeley/Imperial College-London","Laboratory for Atmospheric and Space Physics, University of Colorado, Boulder","Utah State University","Unknown US agency","National Aeronautics and Space Administration (NASA)/Colorado State University","Department of Defense/Missile Defense Agency","FH Aachen","Armed Forces","Plan-S","US Air Force/ US Navy/NASA","Astro Digital","TaLine truncated

src/data/manager.js

@@ -15,16 +15,6 @@ export class DataLayerManager extends LayerLifecycle {
     this._presentation.refresh();
   }
 
-  /**
-   * Repaint the toggle panel now. For layers whose data arrives outside their
-   * manager tick (camera-driven loads such as Transit's proximity polls), so a
-   * row shows its count when the data lands instead of at the next interval.
-   * One DOM pass; skipped while the document is hidden.
-   */
-  refreshLayerStats() {
-    this._refreshTogglePanel();
-  }
-
   _buildMetaText(layer) {
     return this._presentation.panel._buildMetaText(layer);
   }

src/data/manager.test.mjs

@@ -2677,6 +2677,31 @@ test('refreshLayerStats reaches presentation through the bare lifecycle', async
   assert.deepEqual(changes, ['status']);
 });
 
+test('refreshLayerStats(layerId) drops a tick failure the layer no longer reports', async () => {
+  const { LayerLifecycle } = await import('./lifecycle.js');
+  const lifecycle = new LayerLifecycle({});
+  let stats = { count: 0, error: 'Feed unavailable' };
+  lifecycle.register({
+    id: 'feed',
+    name: 'Feed',
+    getStats: () => stats,
+    async update() {},
+  });
+  const entry = lifecycle.layers.get('feed');
+  entry.enabled = true;
+  entry.initialized = true;
+  entry.managerRefreshError = 'Feed unavailable';
+
+  lifecycle.refreshLayerStats('feed');
+  assert.equal(entry.managerRefreshError, 'Feed unavailable');
+
+  stats = { count: 0 };
+  lifecycle.refreshLayerStats();
+  assert.equal(entry.managerRefreshError, 'Feed unavailable');
+  lifecycle.refreshLayerStats('feed');
+  assert.equal(entry.managerRefreshError, null);
+});
+
 test('periodic polls pause hidden, catch up once when due, and dispose visibility listeners', async (t) => {
   const listeners = new Set();
   const doc = {

src/data/militaryAwareness.test.mjs

@@ -98,6 +98,7 @@ function installAwarenessRuntime({
   // status its module never emits guards nothing. See the settled-but-fetching
   // tests below, which use militaryInstallations' genuine first-fetch readout.
   layerStats = {},
+  subscribe = undefined,
 } = {}) {
   const originalWindow = globalThis.window;
   const originalDocument = globalThis.document;
@@ -215,6 +216,7 @@ function installAwarenessRuntime({
     setEnabled,
     getLayerLifecycleState,
     layers,
+    ...(subscribe ? { subscribe } : {}),
   });
   militaryAwarenessLayer.setParams({ passive: true });
   militaryAwarenessLayer.init(viewer);
@@ -383,6 +385,54 @@ test('Contacts does not claim a dependency already enabling for the user', async
   }
 });
 
+test('a dependency the user adopts stays on when Contacts turns off', async () => {
+  // A direct selection, or the Cockpit riding one of its aircraft, promotes a
+  // layer Contacts turned on into the user's own (adoptLayerVisibility). The
+  // coordinator must give it up, or its OFF release tears the layer down —
+  // and the track or the Cockpit with it — before Context restores it.
+  const calls = [];
+  const subscribers = new Set();
+  const runtime = installAwarenessRuntime({
+    isEnabled: () => false,
+    isEffectivelyEnabled: () => false,
+    setEnabled: (layerId, enabled) => {
+      calls.push({ layerId, enabled });
+      return Promise.resolve(true);
+    },
+    subscribe: (listener) => {
+      subscribers.add(listener);
+      return () => subscribers.delete(listener);
+    },
+  });
+
+  try {
+    militaryAwarenessLayer.setParams({ passive: false });
+    await nextTurn();
+    for (const listener of subscribers)
+      listener({
+        type: 'visibility',
+        layerId: 'flights',
+        enabled: true,
+        origin: 'user',
+        adopted: true,
+        adoptedFromSelection: true,
+      });
+    await militaryAwarenessLayer.disable();
+    const released = calls
+      .filter(({ enabled }) => !enabled)
+      .map(({ layerId }) => layerId)
+      .sort();
+    assert.deepEqual(
+      released,
+      AWARENESS_DEPENDENCIES.filter((layerId) => layerId !== 'flights').sort(),
+      'the adopted layer is the user\'s now; the rest are still released',
+    );
+  } finally {
+    runtime.restore();
+  }
+  assert.equal(subscribers.size, 0, 'destroy drops the manager subscription');
+});
+
 test('operational awareness becomes ready after aircraft while deferred sources keep loading', async () => {
   let enabled = false;
   let releaseAircraft;

src/data/placeBelow.js

@@ -0,0 +1,472 @@
+/**
+ * What a ground point is over, offline: on land the country (Natural Earth
+ * admin-0) and its first-level division (admin-1: "Sichuan, China"), plus,
+ * when asked for a radius, the most prominent populated place within it
+ * ("near Chengdu"); else the smallest named sea, gulf, strait, channel,
+ * sound or bay, else the ocean (`marine.json` carries the seven oceans).
+ * Bays narrower than a satellite frame cares about — fjords, lagoons,
+ * inlets, reefs and rivers — are skipped, so a pass reads "Bay of Bengal",
+ * not a harbour.
+ *
+ * PURE data module: no Cesium, node-testable. Each pack loads lazily on the
+ * first lookup that needs it (divisions on the first land hit, places on the
+ * first radius) and is indexed once, and the loading status names them while
+ * one is on its way (`placePacksStatus`); a country's division rings are decoded
+ * the first time a point falls inside it. A failed load is retried later
+ * (see `createRetryableLoader`). No network.
+ */
+
+import { loadBundledJson } from './bundledJson.js';
+import { createRetryableLoader } from './retryableLoad.js';
+import { containsAnchor, decodeRing } from './adminBoundaries.js';
+import { greatCircleKm } from '../geoDistance.js';
+
+/** Marine feature classes named as the place below; oceans come last. */
+const MARINE_KINDS = new Set([
+  'sea',
+  'gulf',
+  'strait',
+  'channel',
+  'sound',
+  'bay',
+]);
+
+const PACKS = {
+  countries: new URL(
+    './local_data/natural_earth/countries.json',
+    import.meta.url,
+  ),
+  marine: new URL('./local_data/natural_earth/marine.json', import.meta.url),
+  divisions: new URL(
+    './local_data/natural_earth/states_provinces.json',
+    import.meta.url,
+  ),
+  places: new URL(
+    './local_data/natural_earth/populated_places.json',
+    import.meta.url,
+  ),
+};
+
+/**
+ * The packs on their way now, and those that failed in the current load (or
+ * the last one): a load starts with no failures, so a retry that lands is
+ * not blamed for a pack that failed before. (A load that does not need the
+ * failed pack clears it too; the next lookup that needs it tries it again.)
+ */
+const loadingPacks = new Set();
+const failedPacks = new Set();
+// One lookup loads its packs one after another (countries and seas, then
+// divisions, then places): the status holds them as one load until the
+// lookup ends, rather than ending and starting a batch between packs.
+let lookupsInFlight = 0;
+let lookupLoaded = false;
+const loadingListeners = new Set();
+
+function notifyLoading() {
+  for (const listener of [...loadingListeners]) {
+    try {
+      listener();
+    } catch {
+      /* A status listener never breaks a lookup. */
+    }
+  }
+}
+
+/** Whether the status shows a load on its way. */
+function loadingNow() {
+  return loadingPacks.size > 0 || (lookupLoaded && lookupsInFlight > 0);
+}
+
+/**
+ * A pack load that the loading status follows: on its way while it runs,
+ * and failed, if it fails, until the next load starts.
+ * @template T
+ * @param {string} name
+ * @param {() => Promise<T>} load
+ * @returns {() => Promise<T>}
+ */
+export function reportedPlacePackLoad(name, load) {
+  return async () => {
+    // A fresh load forgets earlier failures: it ends on what it loads.
+    if (!loadingNow()) failedPacks.clear();
+    if (lookupsInFlight > 0) lookupLoaded = true;
+    loadingPacks.add(name);
+    notifyLoading();
+    try {
+      return await load();
+    } catch (error) {
+      failedPacks.add(name);
+      throw error;
+    } finally {
+      loadingPacks.delete(name);
+      notifyLoading();
+    }
+  };
+}
+
+/**
+ * The place packs' state for the loading status. The packs load lazily, on
+ * the first lookup that needs them, so the status says so meanwhile, and
+ * says when one would not load.
+ * @returns {{loading: boolean, failed: boolean}}
+ */
+export function placePacksStatus() {
+  return {
+    loading: loadingNow(),
+    failed: failedPacks.size > 0,
+  };
+}
+
+/**
+ * Hear each start and end of a place pack load.
+ * @param {() => void} listener
+ * @returns {() => void} Stops listening.
+ */
+export function onPlacePacksLoadingChange(listener) {
+  loadingListeners.add(listener);
+  return () => loadingListeners.delete(listener);
+}
+
+/** Test seam: count pack loads (lazy-loading contract). */
+export const placePackLoads = { divisions: 0, places: 0 };
+
+/** The zoom from which the view names the populated place it shows. */
+export const NEAR_PLACE_MIN_ZOOM = 8;
+
+/**
+ * How far from the sub-satellite point a populated place may lie and still
+ * be named: half the view's smaller ground dimension from
+ * NEAR_PLACE_MIN_ZOOM on, so the place is in the picture whichever way it
+ * lies; null below it or without a size.
+ * @param {number} zoom Optical zoom.
+ * @param {number} widthKm The view's ground width, km.
+ * @param {number} [heightKm] The view's ground height, km; the width when
+ *   not given.
+ * @returns {number|null}
+ */
+export function nearPlaceRadiusKm(zoom, widthKm, heightKm = widthKm) {
+  if (!(zoom >= NEAR_PLACE_MIN_ZOOM)) return null;
+  const smallerKm = Math.min(widthKm, heightKm);
+  return Number.isFinite(smallerKm) && smallerKm > 0 ? smallerKm / 2 : null;
+}
+
+/** Shortest wait between two lookups, ms. */
+export const PLACE_LOOKUP_MIN_MS = 2000;
+/** Ground travel that makes a fresh lookup worth it, km. */
+export const PLACE_LOOKUP_MIN_MOVE_KM = 20;
+
+function boxOf(parts) {
+  let west = Infinity;
+  let south = Infinity;
+  let east = -Infinity;
+  let north = -Infinity;
+  for (const part of parts)
+    for (const ring of part)
+      for (const [lon, lat] of ring) {
+        if (lon < west) west = lon;
+        if (lon > east) east = lon;
+        if (lat < south) south = lat;
+        if (lat > north) north = lat;
+      }
+  return [west, south, east, north];
+}
+
+function inBox([west, south, east, north], lat, lon) {
+  return lat >= south && lat <= north && lon >= west && lon <= east;
+}
+
+/** Planar ring area in degrees², shrunk by cos(latitude): enough to rank. */
+function ringRank(ring) {
+  let sum = 0;
+  let latSum = 0;
+  for (let i = 0, j = ring.length - 1; i < ring.length; j = i, i += 1) {
+    sum += (ring[j][0] - ring[i][0]) * (ring[j][1] + ring[i][1]);
+    latSum += ring[i][1];
+  }
+  const meanLat = ring.length ? latSum / ring.length : 0;
+  return (Math.abs(sum) / 2) * Math.cos((meanLat * Math.PI) / 180);
+}
+
+async function readPlaces() {
+  const [countries, marine] = await Promise.all([
+    loadBundledJson(PACKS.countries),
+    loadBundledJson(PACKS.marine),
+  ]);
+  const decimals = countries.meta?.decimals ?? 3;
+  const land = [];
+  for (const feature of countries.features || []) {
+    const parts = (feature.polygons || []).map((part) =>
+      part.map((ring) => decodeRing(ring, decimals)),
+    );
+    if (!parts.length) continue;
+    land.push({
+      name: feature.name,
+      // Natural Earth writes -99 for units without an ISO code.
+      countryCode: /^[A-Z]{2}$/.test(feature.iso2 || '') ? feature.iso2 : null,
+      parts,
+      box: boxOf(parts),
+    });
+  }
+  const water = [];
+  for (const feature of marine.features || []) {
+    const kind = feature.featurecla;
+    if (kind !== 'ocean' && !MARINE_KINDS.has(kind)) continue;
+    // Marine rings are stored outer-only and plain [lon, lat].
+    const parts = (feature.polygons || []).map((ring) => [ring]);
+    if (!parts.length) continue;
+    water.push({
+      name: feature.name,
+      kind: kind === 'ocean' ? 'ocean' : 'sea',
+      parts,
+      box: boxOf(parts),
+      rank: parts.reduce((sum, [ring]) => sum + ringRank(ring), 0),
+    });
+  }
+  return { land, water };
+}
+const loadPlaces = createRetryableLoader(
+  reportedPlacePackLoad('places', readPlaces),
+);
+
+/** Divisions grouped by country code; rings decoded per country on demand. */
+async function readDivisions() {
+  placePackLoads.divisions += 1;
+  const pack = await loadBundledJson(PACKS.divisions);
+  const decimals = pack.meta?.decimals ?? 3;
+  const byCountry = new Map();
+  for (const feature of pack.features || []) {
+    if (!feature.name || !/^[A-Z]{2}$/.test(feature.iso2 || '')) continue;
+    const list = byCountry.get(feature.iso2) || [];
+    list.push({ feature, decimals: feature.d ?? decimals });
+    byCountry.set(feature.iso2, list);
+  }
+  return { byCountry, decoded: new Map() };
+}
+const loadDivisions = createRetryableLoader(
+  reportedPlacePackLoad('divisions', readDivisions),
+);
+
+/** The first-level division holding a point inside country `code`, or null. */
+async function divisionAt(code, lat, lon) {
+  if (!code) return null;
+  const { byCountry, decoded } = await loadDivisions();
+  let units = decoded.get(code);
+  if (!units) {
+    units = (byCountry.get(code) || []).map(({ feature, decimals }) => {
+      const parts = (feature.polygons || []).map((part) =>
+        part.map((ring) => decodeRing(ring, decimals)),
+      );
+      return { name: feature.name, parts, box: boxOf(parts) };
+    });
+    decoded.set(code, units);
+  }
+  for (const unit of units)
+    if (inBox(unit.box, lat, lon) && containsAnchor(unit.parts, lat, lon))
+      return unit.name;
+  return null;
+}
+
+async function readPopulatedPlaces() {
+  placePackLoads.places += 1;
+  const pack = await loadBundledJson(PACKS.places);
+  return (pack.places || []).filter(
+    (row) =>
+      Array.isArray(row) &&
+      row[0] &&
+      Number.isFinite(row[1]) &&
+      Number.isFinite(row[2]),
+  );
+}
+const loadPopulatedPlaces = createRetryableLoader(
+  reportedPlacePackLoad('populated-places', readPopulatedPlaces),
+);
+
+/**
+ * The most prominent populated place within `radiusKm` of a point (lowest
+ * Natural Earth scalerank, then the larger population class, then the
+ * nearer), or null.
+ * @returns {Promise<string|null>}
+ */
+export async function nearPlace(lat, lon, radiusKm) {
+  if (!(radiusKm > 0) || !Number.isFinite(lat) || !Number.isFinite(lon))
+    return null;
+  const places = await loadPopulatedPlaces();
+  const latSpan = radiusKm / 111;
+  const cosLat = Math.cos((lat * Math.PI) / 180);
+  const lonSpan = cosLat > 0.01 ? latSpan / cosLat : 360;
+  let best = null;
+  for (const [name, pLat, pLon, scalerank, rankMax] of places) {
+    if (Math.abs(pLat - lat) > latSpan) continue;
+    const dLon = Math.abs(((((pLon - lon + 180) % 360) + 360) % 360) - 180);
+    if (dLon > lonSpan) continue;
+    const km = greatCircleKm({ lat, lon }, { lat: pLat, lon: pLon });
+    if (km > radiusKm) continue;
+    if (
+      !best ||
+      scalerank < best.scalerank ||
+      (scalerank === best.scalerank &&
+        (rankMax > best.rankMax || (rankMax === best.rankMax && km < best.km)))
+    )
+      best = { name, scalerank, rankMax, km };
+  }
+  return best ? best.name : null;
+}
+
+/** The division and near-place lookups `placeBelow` adds on land. */
+const DETAIL_LOOKUPS = Object.freeze({ division: divisionAt, near: nearPlace });
+
+/** A detail lookup's answer, or null when it (its pack) fails. */
+async function orNull(lookup) {
+  try {
+    return (await lookup()) ?? null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The place under a ground point.
+ * @param {number} latitude Degrees.
+ * @param {number} longitude Degrees, any wrap.
+ * @param {{nearKm?: number|null, detail?: {division: Function,
+ *   near: Function}}} [options] On land, also name the most prominent
+ *   populated place within `nearKm` (`nearPlaceRadiusKm`). `detail` replaces
+ *   the division and near-place lookups (a test seam).
+ * @returns {Promise<{kind: 'country'|'sea'|'ocean', name: string,
+ *   countryCode: string|null, division?: string|null,
+ *   near?: string|null}|null>} A country carries its first-level `division`
+ *   and the `near` place (each null when none, or when its pack failed to
+ *   load: the country still stands); a sea or ocean neither. Null when no
+ *   feature holds the point (a coastline gap left by the packs'
+ *   simplification) or it is invalid. Rejects only when the country and
+ *   marine packs fail.
+ */
+export async function placeBelow(latitude, longitude, options) {
+  lookupsInFlight += 1;
+  try {
+    return await findPlaceBelow(latitude, longitude, options);
+  } finally {
+    lookupsInFlight -= 1;
+    if (lookupsInFlight === 0 && lookupLoaded) {
+      lookupLoaded = false;
+      notifyLoading();
+    }
+  }
+}
+
+async function findPlaceBelow(
+  latitude,
+  longitude,
+  { nearKm = null, detail = DETAIL_LOOKUPS } = {},
+) {
+  if (
+    !Number.isFinite(latitude) ||
+    !Number.isFinite(longitude) ||
+    Math.abs(latitude) > 90
+  )
+    return null;
+  const lon = ((((longitude + 180) % 360) + 360) % 360) - 180;
+  const { land, water } = await loadPlaces();
+  for (const entry of land) {
+    if (
+      inBox(entry.box, latitude, lon) &&
+      containsAnchor(entry.parts, latitude, lon)
+    )
+      return {
+        kind: 'country',
+        name: entry.name,
+        countryCode: entry.countryCode,
+        division: await orNull(() =>
+          detail.division(entry.countryCode, latitude, lon),
+        ),
+        near: await orNull(() => detail.near(latitude, lon, nearKm)),
+      };
+  }
+  let best = null;
+  for (const entry of water) {
+    if (best && entry.rank >= best.rank) continue;
+    if (
+      inBox(entry.box, latitude, lon) &&
+      containsAnchor(entry.parts, latitude, lon)
+    )
+      best = entry;
+  }
+  return best ? { kind: best.kind, name: best.name, countryCode: null } : null;
+}
+
+/**
+ * Whether two radii ask for the same detail: both off, or within 20% (a
+ * zoom step at least halves the view; altitude drift moves it far less).
+ */
+function sameRadius(a, b) {
+  if (a === null || b === null) return a === b;
+  return Math.max(a, b) / Math.min(a, b) < 1.2;
+}
+
+/**
+ * Keep the place below a moving ground point current without a lookup per
+ * frame: a new lookup once at least `minIntervalMs` has passed AND the point
+ * has moved `minMoveKm` (a low orbit refreshes about every 2.6 s, a
+ * geostationary one never after the first). A new `nearKm` radius (a zoom
+ * step) looks up again at once. One lookup runs at a time; a result that
+ * arrives after `reset()` is dropped. A failed lookup reports no place (the
+ * old one would name ground the view has left) and lets the next update
+ * look up again at once.
+ * @param {{onPlace: (place: object|null) => void,
+ *   lookup?: (lat: number, lon: number,
+ *     options: {nearKm: number|null}) => Promise<object|null>,
+ *   minIntervalMs?: number, minMoveKm?: number}} options
+ */
+export function createPlaceTracker({
+  onPlace,
+  lookup = placeBelow,
+  minIntervalMs = PLACE_LOOKUP_MIN_MS,
+  minMoveKm = PLACE_LOOKUP_MIN_MOVE_KM,
+}) {
+  let generation = 0;
+  let inFlight = false;
+  let last = null;
+  return {
+    /**
+     * Offer the current ground point and the radius to name a place in.
+     * @returns {boolean} True when a lookup started.
+     */
+    update(lat, lon, nowMs, nearKm = null) {
+      if (inFlight || !Number.isFinite(lat) || !Number.isFinite(lon))
+        return false;
+      const radius = Number.isFinite(nearKm) && nearKm > 0 ? nearKm : null;
+      if (
+        last &&
+        sameRadius(last.nearKm, radius) &&
+        (nowMs - last.ms < minIntervalMs ||
+          greatCircleKm(last, { lat, lon }) < minMoveKm)
+      )
+        return false;
+      last = { lat, lon, ms: nowMs, nearKm: radius };
+      inFlight = true;
+      const token = generation;
+      Promise.resolve()
+        .then(() => lookup(lat, lon, { nearKm: radius }))
+        .then(
+          (place) => {
+            if (token !== generation) return;
+            inFlight = false;
+            onPlace(place ?? null);
+          },
+          () => {
+            if (token !== generation) return;
+            inFlight = false;
+            last = null;
+            onPlace(null);
+          },
+        );
+      return true;
+    },
+    /** Forget the point and drop any lookup still in flight. */
+    reset() {
+      generation += 1;
+      inFlight = false;
+      last = null;
+    },
+  };
+}

src/data/placeBelow.test.mjs

@@ -0,0 +1,280 @@
+// src/data/placeBelow.test.mjs — what the ground track is over, offline:
+// division and country on land (with the populated place in view from 8x),
+// the smallest named sea, else the ocean; and the tracker that keeps it
+// current without a lookup per frame.
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { readFileSync } from 'node:fs';
+import {
+  NEAR_PLACE_MIN_ZOOM,
+  PLACE_LOOKUP_MIN_MOVE_KM,
+  PLACE_LOOKUP_MIN_MS,
+  createPlaceTracker,
+  nearPlaceRadiusKm,
+  placeBelow,
+  placePackLoads,
+} from './placeBelow.js';
+
+const PLACES_PACK = new URL(
+  './local_data/natural_earth/populated_places.json',
+  import.meta.url,
+);
+
+// Runs first: the counters are module-wide.
+test('the division and place packs load only when a lookup needs them', async () => {
+  assert.deepEqual(placePackLoads, { divisions: 0, places: 0 });
+  await placeBelow(42, 51, { nearKm: 50 });
+  assert.deepEqual(placePackLoads, { divisions: 0, places: 0 }, 'at sea');
+  await placeBelow(30.9, 104.2);
+  assert.deepEqual(placePackLoads, { divisions: 1, places: 0 }, 'at 1x');
+  await placeBelow(30.9, 104.2, { nearKm: 60 });
+  await placeBelow(31.2, 104.5, { nearKm: 30 });
+  assert.deepEqual(placePackLoads, { divisions: 1, places: 1 }, 'kept');
+});
+
+test('the populated-place pack is compact rows of name, position and rank', () => {
+  const bytes = readFileSync(PLACES_PACK);
+  assert.ok(bytes.length < 300_000, `${bytes.length} bytes`);
+  const pack = JSON.parse(bytes);
+  assert.match(pack.meta.url, /nvkelso\/natural-earth-vector/);
+  assert.match(pack.meta.license, /^Public domain/);
+  assert.ok(pack.places.length > 7000);
+  for (const [name, lat, lon, scalerank, rankMax] of pack.places) {
+    assert.equal(typeof name, 'string');
+    assert.ok(Math.abs(lat) <= 90 && Math.abs(lon) <= 180, name);
+    assert.ok(Number.isInteger(scalerank) && Number.isInteger(rankMax), name);
+  }
+});
+
+test('over land the place is the division and country, with its ISO code', async () => {
+  assert.deepEqual(await placeBelow(48.85, 2.35), {
+    kind: 'country',
+    name: 'France',
+    countryCode: 'FR',
+    division: 'Paris',
+    near: null,
+  });
+  // Across the antimeridian, and with a wrapped longitude.
+  assert.equal((await placeBelow(66, -175)).countryCode, 'RU');
+  assert.equal((await placeBelow(-17.8, 178)).countryCode, 'FJ');
+  assert.equal((await placeBelow(48.85, 362.35)).countryCode, 'FR');
+});
+
+test('at 1x a point in Sichuan reads Sichuan, China, with no city', async () => {
+  assert.deepEqual(await placeBelow(30.9, 104.2), {
+    kind: 'country',
+    name: 'China',
+    countryCode: 'CN',
+    division: 'Sichuan',
+    near: null,
+  });
+  assert.equal(nearPlaceRadiusKm(1, 1400), null);
+  assert.equal(nearPlaceRadiusKm(NEAR_PLACE_MIN_ZOOM / 2, 300), null);
+});
+
+test('from 8x the most prominent populated place in view is named', async () => {
+  assert.equal(NEAR_PLACE_MIN_ZOOM, 8);
+  // An 8x view ~120 km wide: Chengdu lies ~30 km off, inside half of it.
+  const nearKm = nearPlaceRadiusKm(8, 120);
+  assert.equal(nearKm, 60);
+  const place = await placeBelow(30.9, 104.2, { nearKm });
+  assert.equal(place.division, 'Sichuan');
+  assert.equal(place.near, 'Chengdu');
+  // Deyang lies nearer this point; Chengdu still outranks it.
+  assert.equal(
+    (await placeBelow(31.1, 104.35, { nearKm: 60 })).near,
+    'Chengdu',
+  );
+});
+
+test('no city is named when none lies within half the view', async () => {
+  // ~100 km west of Chengdu, in the mountains.
+  const place = await placeBelow(30.67, 103.0, { nearKm: 30 });
+  assert.equal(place.division, 'Sichuan');
+  assert.equal(place.near, null);
+  assert.equal(nearPlaceRadiusKm(8, Number.NaN), null);
+});
+
+test('at sea the smallest named sea wins over its ocean', async () => {
+  assert.deepEqual(await placeBelow(42, 51), {
+    kind: 'sea',
+    name: 'Caspian Sea',
+    countryCode: null,
+  });
+  // A radius changes nothing at sea.
+  assert.deepEqual(await placeBelow(42, 51, { nearKm: 60 }), {
+    kind: 'sea',
+    name: 'Caspian Sea',
+    countryCode: null,
+  });
+  assert.equal((await placeBelow(15, 88)).name, 'Bay of Bengal');
+  assert.equal((await placeBelow(35, 18)).name, 'Mediterranean Sea');
+});
+
+test('open water far from any sea is the ocean', async () => {
+  assert.deepEqual(await placeBelow(0, -150), {
+    kind: 'ocean',
+    name: 'South Pacific Ocean',
+    countryCode: null,
+  });
+  assert.equal((await placeBelow(40, 179.9)).name, 'North Pacific Ocean');
+  assert.equal((await placeBelow(40, -179.9)).name, 'North Pacific Ocean');
+  assert.equal((await placeBelow(40, -40)).name, 'North Atlantic Ocean');
+});
+
+test('an invalid point has no place', async () => {
+  assert.equal(await placeBelow(Number.NaN, 0), null);
+  assert.equal(await placeBelow(91, 0), null);
+});
+
+/** A lookup whose answers the test releases by hand. */
+function manualLookup() {
+  const calls = [];
+  const lookup = (lat, lon, options) =>
+    new Promise((resolve) => calls.push({ lat, lon, options, resolve }));
+  return { calls, lookup };
+}
+const flush = () => new Promise((resolve) => setTimeout(resolve, 0));
+
+test('the tracker looks up again only after both time and distance', async () => {
+  const { calls, lookup } = manualLookup();
+  const places = [];
+  const tracker = createPlaceTracker({
+    lookup,
+    onPlace: (place) => places.push(place),
+  });
+  assert.equal(tracker.update(0, 0, 1000), true, 'the first point');
+  await flush();
+  assert.equal(tracker.update(5, 5, 1100), false, 'one lookup at a time');
+  calls[0].resolve({ kind: 'ocean', name: 'A' });
+  await flush();
+  assert.deepEqual(places, [{ kind: 'ocean', name: 'A' }]);
+  // Far enough, but too soon.
+  assert.equal(tracker.update(5, 5, 1000 + PLACE_LOOKUP_MIN_MS - 1), false);
+  // Long enough, but barely moved (a geostationary satellite).
+  assert.equal(tracker.update(0.01, 0, 1000 + PLACE_LOOKUP_MIN_MS * 5), false);
+  // Both: a low orbit ~2.6 s on.
+  const movedDeg = (PLACE_LOOKUP_MIN_MOVE_KM + 1) / 111.2;
+  assert.equal(
+    tracker.update(movedDeg, 0, 1000 + PLACE_LOOKUP_MIN_MS * 5),
+    true,
+  );
+  await flush();
+  calls[1].resolve(null);
+  await flush();
+  assert.deepEqual(places.at(-1), null, 'nothing named there is reported');
+});
+
+test('a new radius (a zoom step) looks up again at once', async () => {
+  const { calls, lookup } = manualLookup();
+  const tracker = createPlaceTracker({ lookup, onPlace: () => {} });
+  assert.equal(tracker.update(0, 0, 1000), true);
+  await flush();
+  assert.deepEqual(calls[0].lat, 0);
+  calls[0].resolve(null);
+  await flush();
+  // Same point, a moment later: only the zoom changed.
+  assert.equal(tracker.update(0, 0, 1100, 60), true, 'into 8x');
+  await flush();
+  calls[1].resolve(null);
+  await flush();
+  // Altitude drift barely moves the radius: the gate holds.
+  assert.equal(tracker.update(0, 0, 1200, 62), false);
+  assert.equal(tracker.update(0, 0, 1300, 30), true, 'to 16x');
+  await flush();
+  calls[2].resolve(null);
+  await flush();
+  assert.equal(tracker.update(0, 0, 1400, null), true, 'back below 8x');
+  await flush();
+  assert.deepEqual(
+    calls.map((call) => call.options),
+    [{ nearKm: null }, { nearKm: 60 }, { nearKm: 30 }, { nearKm: null }],
+  );
+});
+
+test('a lookup that lands after reset is dropped', async () => {
+  const { calls, lookup } = manualLookup();
+  const places = [];
+  const tracker = createPlaceTracker({
+    lookup,
+    onPlace: (place) => places.push(place),
+  });
+  tracker.update(0, 0, 0);
+  await flush();
+  tracker.reset();
+  // A new session looks up at once.
+  assert.equal(tracker.update(10, 10, 1), true);
+  await flush();
+  calls[0].resolve({ name: 'stale' });
+  calls[1].resolve({ name: 'fresh' });
+  await flush();
+  assert.deepEqual(places, [{ name: 'fresh' }]);
+});
+
+test('a failed lookup frees the tracker for the next point', async () => {
+  let fail = true;
+  const places = [];
+  const tracker = createPlaceTracker({
+    lookup: async () => {
+      if (fail) throw new Error('pack failed');
+      return { name: 'ok' };
+    },
+    onPlace: (place) => places.push(place),
+    minIntervalMs: 0,
+    minMoveKm: 0,
+  });
+  tracker.update(0, 0, 0);
+  await flush();
+  assert.deepEqual(places, [null]);
+  fail = false;
+  assert.equal(tracker.update(0, 0, 1), true);
+  await flush();
+  assert.deepEqual(places, [null, { name: 'ok' }]);
+});
+
+test('the near-place radius is half the smaller side of the view', () => {
+  assert.equal(nearPlaceRadiusKm(8, 120, 60), 30, 'landscape');
+  assert.equal(nearPlaceRadiusKm(8, 60, 120), 30, 'portrait');
+  assert.equal(nearPlaceRadiusKm(8, 120), 60, 'square without a height');
+  assert.equal(nearPlaceRadiusKm(8, 120, Number.NaN), null);
+});
+
+test('a failed division or place pack still names the country', async () => {
+  const fail = async () => {
+    throw new Error('pack failed');
+  };
+  const place = await placeBelow(30.9, 104.2, {
+    nearKm: 60,
+    detail: { division: fail, near: fail },
+  });
+  assert.equal(place.kind, 'country');
+  assert.equal(place.countryCode, 'CN');
+  assert.equal(place.division, null);
+  assert.equal(place.near, null);
+});
+
+test('a failed lookup hides the old place and looks again on the next update', async () => {
+  let fail = false;
+  const places = [];
+  const tracker = createPlaceTracker({
+    lookup: async () => {
+      if (fail) throw new Error('pack failed');
+      return { kind: 'sea', name: 'Bay of Biscay' };
+    },
+    onPlace: (place) => places.push(place),
+  });
+  assert.equal(tracker.update(45, -5, 0), true);
+  await flush();
+  assert.deepEqual(places, [{ kind: 'sea', name: 'Bay of Biscay' }]);
+  // Over France the lookup fails: the bay must not stay on the band.
+  fail = true;
+  const movedDeg = (PLACE_LOOKUP_MIN_MOVE_KM + 1) / 111.2;
+  assert.equal(tracker.update(45 + movedDeg, 0, PLACE_LOOKUP_MIN_MS), true);
+  await flush();
+  assert.equal(places.at(-1), null, 'the band hides');
+  // The next tick tries again at once, even without moving (a GEO view).
+  fail = false;
+  assert.equal(tracker.update(45 + movedDeg, 0, PLACE_LOOKUP_MIN_MS + 1), true);
+  await flush();
+  assert.deepEqual(places.at(-1), { kind: 'sea', name: 'Bay of Biscay' });
+});

src/data/placeNames.js

@@ -11,17 +11,16 @@ const FOLD = {
 };
 
 /**
- * Comparable form of a place name, shared by the bundled packs, the
- * OpenFreeMap street and grounds matchers and the Nominatim server: case
- * folded, accents removed from Latin letters only, punctuation and symbols
- * collapsed to single spaces, and a leading "the" dropped. Other scripts keep
- * their marks, so "कुल मार्ग" and "काली मार्ग" stay distinct while "São Paulo",
- * "sao paulo" and "SÃO PAULO!" meet.
+ * Script-aware fold of a place name: case folded, accents removed from Latin
+ * letters only, punctuation and symbols collapsed to single spaces. Other
+ * scripts keep their marks, so "कुल मार्ग" and "काली मार्ग" stay distinct while
+ * "São Paulo", "sao paulo" and "SÃO PAULO!" meet. Every word is kept: "The
+ * Hague" is not "Hague".
  *
  * @param {unknown} value
  * @returns {string}
  */
-export function foldPlaceName(value) {
+export function foldPlaceText(value) {
   return String(value ?? '')
     .toLowerCase()
     .replace(/[ßøæłđıœþ]/g, (c) => FOLD[c])
@@ -29,8 +28,19 @@ export function foldPlaceName(value) {
     .replace(/(\p{Script=Latin})\p{M}+/gu, '$1')
     .normalize('NFKC')
     .replace(/[^\p{L}\p{M}\p{N}]+/gu, ' ')
-    .trim()
-    .replace(/^the /, '');
+    .trim();
+}
+
+/**
+ * Comparable form of a place name, shared by the bundled packs, the
+ * OpenFreeMap street and grounds matchers and the Nominatim server:
+ * `foldPlaceText` with a leading "the" dropped.
+ *
+ * @param {unknown} value
+ * @returns {string}
+ */
+export function foldPlaceName(value) {
+  return foldPlaceText(value).replace(/^the /, '');
 }
 
 /**

src/data/placePacksLoading.test.mjs

@@ -0,0 +1,111 @@
+// src/data/placePacksLoading.test.mjs — the loading status hears the place
+// packs while they are on their way.
+import test from 'node:test';
+import assert from 'node:assert/strict';
+
+test('a place pack load is reported from its start to its end', async () => {
+  // A module of its own, so no other test has loaded the packs yet.
+  const place = await import('./placeBelow.js?loading-status');
+  const heard = [];
+  const stop = place.onPlacePacksLoadingChange(() =>
+    heard.push(place.placePacksStatus().loading),
+  );
+  assert.equal(place.placePacksStatus().loading, false);
+  const lookup = place.nearPlace(48.86, 2.35, 50);
+  assert.equal(place.placePacksStatus().loading, true, 'on its way');
+  assert.equal(await lookup, 'Paris');
+  assert.equal(place.placePacksStatus().loading, false, 'loaded');
+  assert.deepEqual(heard, [true, false]);
+  // Loaded once: a later lookup is not reported again.
+  await place.nearPlace(48.86, 2.35, 50);
+  assert.deepEqual(heard, [true, false]);
+  stop();
+});
+
+test('a pack that would not load stays failed until it loads', async () => {
+  const place = await import('./placeBelow.js?failed-status');
+  let fail = true;
+  const load = place.reportedPlacePackLoad('test', async () => {
+    if (fail) throw new Error('offline');
+    return 1;
+  });
+  await assert.rejects(load(), /offline/);
+  assert.deepEqual(place.placePacksStatus(), { loading: false, failed: true });
+  fail = false;
+  const retry = load();
+  assert.deepEqual(
+    place.placePacksStatus(),
+    { loading: true, failed: false },
+    'a retry is not a failure until it fails',
+  );
+  assert.equal(await retry, 1);
+  assert.deepEqual(place.placePacksStatus(), { loading: false, failed: false });
+});
+
+test('one lookup that loads several packs reads as one load', async () => {
+  const place = await import('./placeBelow.js?one-lookup');
+  const heard = [];
+  const stop = place.onPlacePacksLoadingChange(() => {
+    const { loading } = place.placePacksStatus();
+    if (heard.at(-1) !== loading) heard.push(loading);
+  });
+  // On land with a radius: countries and seas, then divisions, then places.
+  const found = await place.placeBelow(48.86, 2.35, { nearKm: 50 });
+  assert.equal(found.near, 'Paris');
+  assert.deepEqual(heard, [true, false], 'no gap between the packs');
+  stop();
+});
+
+/** Two stand-in packs (not real pack names) that fail while named in `fail`. */
+function standInPacks(place, fail) {
+  const pack = (name) =>
+    place.reportedPlacePackLoad(name, async () => {
+      if (fail.has(name)) throw new Error('offline');
+      return name;
+    });
+  return { first: pack('stand-in-first'), second: pack('stand-in-second') };
+}
+
+/** The statuses one lookup that loads both stand-ins reports, start to end. */
+async function lookupStatuses(place, { first, second }) {
+  const statuses = [];
+  const stop = place.onPlacePacksLoadingChange(() =>
+    statuses.push(place.placePacksStatus()),
+  );
+  await place.placeBelow(48.86, 2.35, {
+    detail: { division: async () => first(), near: async () => second() },
+  });
+  stop();
+  return statuses;
+}
+
+test('a load is not blamed for packs that failed in an earlier one', async () => {
+  const place = await import('./placeBelow.js?two-failed');
+  const fail = new Set(['stand-in-first', 'stand-in-second']);
+  const packs = standInPacks(place, fail);
+  await assert.rejects(packs.first());
+  await assert.rejects(packs.second());
+  assert.equal(place.placePacksStatus().failed, true);
+  fail.clear();
+  const statuses = await lookupStatuses(place, packs);
+  assert.deepEqual(statuses[0], { loading: true, failed: false });
+  assert.ok(
+    statuses.every((status) => status.failed === false),
+    'the earlier failures do not colour this load',
+  );
+  assert.deepEqual(place.placePacksStatus(), {
+    loading: false,
+    failed: false,
+  });
+});
+
+test('a pack that fails in a load keeps it failed when the next one lands', async () => {
+  const place = await import('./placeBelow.js?mixed');
+  const packs = standInPacks(place, new Set(['stand-in-first']));
+  const statuses = await lookupStatuses(place, packs);
+  assert.deepEqual(statuses.at(-1), { loading: false, failed: true });
+  assert.deepEqual(place.placePacksStatus(), {
+    loading: false,
+    failed: true,
+  });
+});