Files
gods-eye-view/src/annotations/annotationEngine.test.mjs
T
Said Turksever 38eb98b8f8 Take a hidden shape off the globe whole, and keep every drawn shape
Answers the review of bdbbc3d7 and the IC8 pass after it.

A shape hidden from Draw's list was only set to alpha 0, so the line's
flowing stroke, which keeps its own colour, stayed painted. Now:
- the world renderer's sync() sets every entity of a hidden mark to
  show = false, and FlowMaterialProperty follows the mark's alpha;
- the screen renderer does not project a hidden callout, so it is not drawn
  and cannot push a visible label aside;
- hiding acts at once, even before a mark's first frame, and with every
  mark hidden the annotations render hold is released after one last frame;
- fly_route skips a hidden route.

Hand-drawn shapes are never merged as duplicates: every one is drawn on
purpose and unnamed until its row names it, so a second pin dropped near
the first was dropped, or replaced the first when its colour differed. A
restyle the renderer cannot draw now also syncs the renderer.

Tests cover each: renderer show/hide and flow alpha, the screen skip, the
render hold and its last frame, a show with no fade-in, hidden routes, two
nearby pins, and the restyle rollback.
2026-11-02 16:43:39 +00:00

1095 lines
40 KiB
JavaScript

import { createStandalonePlaceSearch } from '../standalone/placeSearch.js';
// Voice-annotation resilience contract tests — pure logic, no network, no browser.
//
// Locks the 2026-07-21 field-test fixes:
// 1. A TRANSIENT (undefined) deferred-outline resolution is retried with backoff
// (the /api/overpass proxy caches the late completion, so a retry is nearly
// free) instead of silently leaving the mark a point forever. A DEFINITIVE
// miss (null) is never retried — honest point beats hammering Overpass.
// 2. targetKey normalization strips trailing locality qualifiers so "California"
// and "California, United States" dedupe while their outlines are pending
// (identity is GEOMETRY once resolved; targetKey is only the pending stand-in).
//
// Run with: npm test (node --test)
import { test } from 'node:test';
import * as Cesium from 'cesium';
import assert from 'node:assert/strict';
import {
createAnnotationEngine,
resolveOutlineWithRetry,
normalizeTargetKey,
} from './annotationEngine.js';
import { resolveAnnotationTarget } from './annotationResolver.js';
import {
getRenderGovernorDiagnostics,
installRenderGovernor,
_resetRenderGovernorForTest,
} from '../renderGovernor.js';
// A resolver that replays a scripted sequence of outcomes (undefined = transient,
// null = definitive miss, object = footprint) and counts its invocations.
function scriptedResolver(outcomes) {
const calls = { count: 0 };
const resolve = async () => {
const i = Math.min(calls.count, outcomes.length - 1);
calls.count += 1;
const out = outcomes[i];
if (out instanceof Error) throw out;
return out;
};
return { resolve, calls };
}
// Instant fake wait that records the requested backoff delays.
function fakeWait() {
const delays = [];
const waitFn = async (ms) => { delays.push(ms); };
return { waitFn, delays };
}
const FP = { ring: [[0, 0], [0, 1], [1, 1], [0, 0]], footprintKind: 'area' };
function installAnimationFrameStubs(t) {
const originalRequestAnimationFrame = globalThis.requestAnimationFrame;
const originalCancelAnimationFrame = globalThis.cancelAnimationFrame;
globalThis.requestAnimationFrame = () => 1;
globalThis.cancelAnimationFrame = () => {};
t.after(() => {
if (originalRequestAnimationFrame === undefined) delete globalThis.requestAnimationFrame;
else globalThis.requestAnimationFrame = originalRequestAnimationFrame;
if (originalCancelAnimationFrame === undefined) delete globalThis.cancelAnimationFrame;
else globalThis.cancelAnimationFrame = originalCancelAnimationFrame;
});
}
function fakeRenderer() {
const calls = { add: 0, update: 0, remove: 0 };
return {
calls,
renderer: {
add() { calls.add += 1; },
update() { calls.update += 1; },
remove() { calls.remove += 1; },
sync() {},
},
};
}
async function flushMicrotasks(rounds = 20) {
for (let i = 0; i < rounds; i += 1) await Promise.resolve();
}
function httpFailure(status, retryAfter = null) {
return {
ok: false,
status,
headers: { get: (name) => (name.toLowerCase() === 'retry-after' ? retryAfter : null) },
};
}
test('retry: first-try footprint returns immediately, no retry, no waiting', async () => {
const { resolve, calls } = scriptedResolver([FP]);
const { waitFn, delays } = fakeWait();
const fp = await resolveOutlineWithRetry(resolve, { delaysMs: [8000, 25000], waitFn });
assert.equal(fp, FP);
assert.equal(calls.count, 1);
assert.deepEqual(delays, []);
});
test('retry: a DEFINITIVE miss (null) is never retried — the honest point stands', async () => {
const { resolve, calls } = scriptedResolver([null, FP]);
const { waitFn, delays } = fakeWait();
const fp = await resolveOutlineWithRetry(resolve, { delaysMs: [8000, 25000], waitFn });
assert.equal(fp, null);
assert.equal(calls.count, 1);
assert.deepEqual(delays, []);
});
test('retry: a TRANSIENT miss (undefined) re-runs after the first backoff and can succeed', async () => {
const { resolve, calls } = scriptedResolver([undefined, FP]);
const { waitFn, delays } = fakeWait();
const fp = await resolveOutlineWithRetry(resolve, { delaysMs: [8000, 25000], waitFn });
assert.equal(fp, FP);
assert.equal(calls.count, 2);
assert.deepEqual(delays, [8000]); // waited once, succeeded on attempt 2
});
test('retry: a transient retry can still conclude with a definitive miss (no third run)', async () => {
const { resolve, calls } = scriptedResolver([undefined, null]);
const { waitFn, delays } = fakeWait();
const fp = await resolveOutlineWithRetry(resolve, { delaysMs: [8000, 25000], waitFn });
assert.equal(fp, null);
assert.equal(calls.count, 2);
assert.deepEqual(delays, [8000]);
});
test('retry: persistent transients exhaust the backoff schedule and give up as transient', async () => {
const { resolve, calls } = scriptedResolver([undefined, undefined, undefined, FP]);
const { waitFn, delays } = fakeWait();
const fp = await resolveOutlineWithRetry(resolve, { delaysMs: [8000, 25000], waitFn });
assert.equal(fp, undefined); // never found within budget — mark honestly stays a point
assert.equal(calls.count, 3); // initial + one per backoff entry
assert.deepEqual(delays, [8000, 25000]);
});
test('retry: a stale board (clear/supersede during backoff) stops retrying immediately', async () => {
const { resolve, calls } = scriptedResolver([undefined, FP]);
const { waitFn, delays } = fakeWait();
let stale = false;
const fp = await resolveOutlineWithRetry(resolve, {
delaysMs: [8000, 25000],
waitFn: async (ms) => { await waitFn(ms); stale = true; }, // goes stale mid-wait
isStale: () => stale,
});
assert.equal(fp, undefined);
assert.equal(calls.count, 1); // never re-ran against a superseded board
assert.deepEqual(delays, [8000]);
});
test('retry: a thrown resolver is a definitive miss (no retry), matching the old catch→point path', async () => {
const { resolve, calls } = scriptedResolver([new Error('boom'), FP]);
const { waitFn, delays } = fakeWait();
const fp = await resolveOutlineWithRetry(resolve, { delaysMs: [8000, 25000], waitFn });
assert.equal(fp, null);
assert.equal(calls.count, 1);
assert.deepEqual(delays, []);
});
test('outline queue: an 8-spec batch keeps at most two FIFO upgrades in flight', async (t) => {
installAnimationFrameStubs(t);
const { renderer, calls } = fakeRenderer();
const started = [];
const releases = new Map();
let inFlight = 0;
let maxInFlight = 0;
const resolveTarget = async ({ target }) => {
const index = Number(target.slice('queue-'.length));
return {
lon: index,
lat: index,
height: 0,
label: target,
source: 'fake',
ring: null,
resolveOutline: () => new Promise((resolve) => {
started.push(target);
inFlight += 1;
maxInFlight = Math.max(maxInFlight, inFlight);
releases.set(target, () => {
inFlight -= 1;
resolve({
ring: [[index, index], [index + 0.1, index], [index, index + 0.1], [index, index]],
footprintKind: 'area',
lat: index,
lon: index,
height: 0,
});
});
}),
};
};
const engine = createAnnotationEngine({ viewer: {}, renderer, resolveTarget });
let completed = 0;
const allCompleted = new Promise((resolve) => engine.onOutlineEvent(() => {
completed += 1;
if (completed === 8) resolve();
}));
const result = await engine.annotate(Array.from({ length: 8 }, (_, i) => ({
type: 'area',
target: `queue-${i}`,
footprint: true,
})));
assert.equal(result.drawn, 8);
assert.equal(calls.add, 8, 'all point renders land before queued outlines finish');
assert.deepEqual(started, ['queue-0', 'queue-1']);
for (let next = 2; next < 8; next += 1) {
releases.get(`queue-${next - 2}`)();
await flushMicrotasks();
assert.equal(started[next], `queue-${next}`, 'queued upgrades start in ask order');
}
releases.get('queue-6')();
releases.get('queue-7')();
await allCompleted;
assert.equal(maxInFlight, 2);
assert.equal(calls.update, 8);
});
test('outline queue: clear drops queued-but-unstarted upgrades without a later fetch', async (t) => {
installAnimationFrameStubs(t);
const { renderer } = fakeRenderer();
let fetchesStarted = 0;
const resolveTarget = async ({ target, signal }) => ({
lon: Number(target.slice('clear-'.length)),
lat: 10,
height: 0,
label: target,
source: 'fake',
ring: null,
resolveOutline: () => new Promise((resolve) => {
fetchesStarted += 1;
const finish = () => resolve(undefined);
if (signal.aborted) finish();
else signal.addEventListener('abort', finish, { once: true });
}),
});
const engine = createAnnotationEngine({ viewer: {}, renderer, resolveTarget });
await engine.annotate(Array.from({ length: 8 }, (_, i) => ({
type: 'area',
target: `clear-${i}`,
footprint: true,
})));
assert.equal(fetchesStarted, 2);
engine.clear();
await flushMicrotasks();
assert.equal(engine.count(), 0);
assert.equal(fetchesStarted, 2, 'the six queued upgrades were dropped on clear');
});
test('retry: HTTP 429 Retry-After 5s gets one ladder-spaced retry; a second 429 stops', async (t) => {
const originalWindow = globalThis.window;
const originalFetch = globalThis.fetch;
t.mock.timers.enable({ apis: ['setTimeout', 'Date'], now: 10_000 });
globalThis.window = { setTimeout: globalThis.setTimeout, clearTimeout: globalThis.clearTimeout };
const requestTimes = [];
globalThis.fetch = async (url) => {
// The one-time capability probe is not an outline request.
if (String(url).endsWith('/status')) return httpFailure(404);
requestTimes.push(Date.now());
return httpFailure(429, '5');
};
t.after(() => {
t.mock.timers.reset();
if (originalWindow === undefined) delete globalThis.window;
else globalThis.window = originalWindow;
globalThis.fetch = originalFetch;
});
const resolved = await resolveAnnotationTarget({
viewer: {},
target: 'PT2 rate-limit fixture',
latitude: 12.345,
longitude: 67.89,
footprint: true,
deferFootprint: true,
entityKind: 'district',
});
let settled = false;
const waits = [];
const pending = resolveOutlineWithRetry(resolved.resolveOutline, {
waitFn: (ms) => {
waits.push(ms);
return new Promise((resolve) => setTimeout(resolve, ms));
},
})
.finally(() => { settled = true; });
while (waits.length === 0) await flushMicrotasks();
assert.equal(requestTimes.length, 1);
assert.deepEqual(waits, [8000], 'the 8s ladder floor is longer than Retry-After: 5');
t.mock.timers.tick(7999);
await flushMicrotasks();
assert.equal(requestTimes.length, 1);
t.mock.timers.tick(1);
await flushMicrotasks();
// Mutation hygiene: if 429 is accidentally collapsed into ordinary transient,
// drain its forbidden second ladder timer before making the named assertions.
if (waits.length > 1) {
t.mock.timers.tick(waits[1]);
await flushMicrotasks();
}
assert.equal(requestTimes.length, 2);
assert.ok(requestTimes[1] - requestTimes[0] >= 5000, 'Retry-After is a hard minimum');
assert.equal(settled, true, 'a second 429 must not schedule the 25s ladder replay');
assert.equal(await pending, undefined);
});
test('retry: a plain HTTP 500 still exhausts the existing 8s/25s transient ladder', async (t) => {
const originalWindow = globalThis.window;
const originalFetch = globalThis.fetch;
t.mock.timers.enable({ apis: ['setTimeout', 'Date'], now: 100_000 });
globalThis.window = { setTimeout: globalThis.setTimeout, clearTimeout: globalThis.clearTimeout };
const requestTimes = [];
globalThis.fetch = async (url) => {
if (String(url).endsWith('/status'))
return Response.json({ configured: true });
requestTimes.push(Date.now());
return httpFailure(500);
};
t.after(() => {
t.mock.timers.reset();
if (originalWindow === undefined) delete globalThis.window;
else globalThis.window = originalWindow;
globalThis.fetch = originalFetch;
});
const resolved = await resolveAnnotationTarget({
viewer: {},
target: 'PT2 transient fixture',
latitude: -12.345,
longitude: -67.89,
footprint: true,
deferFootprint: true,
entityKind: 'district',
});
let settled = false;
const waits = [];
const pending = resolveOutlineWithRetry(resolved.resolveOutline, {
waitFn: (ms) => {
waits.push(ms);
return new Promise((resolve) => setTimeout(resolve, ms));
},
})
.finally(() => { settled = true; });
while (waits.length === 0) await flushMicrotasks();
assert.equal(requestTimes.length, 1);
assert.deepEqual(waits, [8000]);
t.mock.timers.tick(8000);
await flushMicrotasks();
assert.equal(requestTimes.length, 2);
assert.equal(settled, false);
assert.deepEqual(waits, [8000, 25_000]);
t.mock.timers.tick(24_999);
await flushMicrotasks();
assert.equal(requestTimes.length, 2);
t.mock.timers.tick(1);
await flushMicrotasks();
assert.equal(requestTimes.length, 3);
assert.deepEqual(requestTimes.map((at) => at - requestTimes[0]), [0, 8000, 33_000]);
assert.equal(settled, true);
assert.equal(await pending, undefined);
});
test('targetKey: trailing locality qualifiers are stripped so state names dedupe', () => {
assert.equal(normalizeTargetKey('California'), 'california');
assert.equal(normalizeTargetKey('California, United States'), 'california');
assert.equal(
normalizeTargetKey('California'),
normalizeTargetKey('California, United States'),
);
});
test('targetKey: lowercases, trims, and keeps comma-free names intact', () => {
assert.equal(normalizeTargetKey(' Texas State Capitol '), 'texas state capitol');
assert.equal(normalizeTargetKey('Lady Bird Lake'), 'lady bird lake');
});
test('targetKey: multi-qualifier names keep only the leading place name', () => {
assert.equal(normalizeTargetKey('Sixth Street, Austin, TX'), 'sixth street');
});
test('targetKey: empty / absent targets stay null (coord and pixel specs never pending-collapse)', () => {
assert.equal(normalizeTargetKey(''), null);
assert.equal(normalizeTargetKey(' '), null);
assert.equal(normalizeTargetKey(null), null);
assert.equal(normalizeTargetKey(undefined), null);
});
test('outline upgrade updates the rendered element in place without remove/add', { timeout: 5000 }, async (t) => {
const originalRequestAnimationFrame = globalThis.requestAnimationFrame;
const originalCancelAnimationFrame = globalThis.cancelAnimationFrame;
const originalWindow = globalThis.window;
const originalFetch = globalThis.fetch;
globalThis.requestAnimationFrame = () => 1;
globalThis.cancelAnimationFrame = () => {};
globalThis.window = {
__GOOGLE_MAPS_API_KEY__: 'unit-test-key',
setTimeout: globalThis.setTimeout,
clearTimeout: globalThis.clearTimeout,
};
let overpassCall = 0;
globalThis.fetch = async (url) => {
if (String(url).startsWith('/api/google/geocode')) {
return { json: async () => ({
status: 'OK',
results: [{
formatted_address: 'FB-3 Engine Texas Fixture',
types: ['administrative_area_level_1', 'political'],
address_components: [{
long_name: 'FB-3 Engine Texas Fixture',
types: ['administrative_area_level_1', 'political'],
}],
geometry: { location: { lat: 31, lng: -99 } },
}],
}) };
}
assert.equal(String(url), '/api/overpass');
overpassCall += 1;
if (overpassCall === 1) {
return {
ok: true,
json: async () => ({ elements: [{
type: 'area',
id: 54321,
tags: { name: 'FB-3 Engine Texas Fixture', admin_level: '4' },
}] }),
};
}
return {
ok: true,
json: async () => ({ elements: [{
type: 'relation',
geometry: [
{ lon: -106, lat: 25 },
{ lon: -93, lat: 25 },
{ lon: -93, lat: 36 },
{ lon: -106, lat: 36 },
{ lon: -106, lat: 25 },
],
}] }),
};
};
t.after(() => {
if (originalRequestAnimationFrame === undefined) delete globalThis.requestAnimationFrame;
else globalThis.requestAnimationFrame = originalRequestAnimationFrame;
if (originalCancelAnimationFrame === undefined) delete globalThis.cancelAnimationFrame;
else globalThis.cancelAnimationFrame = originalCancelAnimationFrame;
if (originalWindow === undefined) delete globalThis.window;
else globalThis.window = originalWindow;
globalThis.fetch = originalFetch;
});
const calls = { add: 0, update: 0, remove: 0 };
const elements = new Map();
let originalElement = null;
const renderer = {
add(anno) {
calls.add += 1;
originalElement = { id: anno.id };
elements.set(anno.id, originalElement);
},
update(anno) {
calls.update += 1;
assert.equal(elements.get(anno.id), originalElement);
},
remove() { calls.remove += 1; },
sync() {},
};
const viewer = {};
const engine = createAnnotationEngine({ viewer, renderer, placeSearch: createStandalonePlaceSearch({ resolveApiKey: () => 'unit-test-key' }) });
const upgraded = new Promise((resolve) => engine.onOutlineEvent(resolve));
const result = await engine.annotate([{
type: 'area',
target: 'FB-3 Engine Texas Fixture',
label: 'Texas',
footprint: true,
}]);
await upgraded;
assert.equal(result.drawn, 1);
assert.deepEqual(calls, { add: 1, update: 1, remove: 0 });
assert.equal(elements.get(result.ids[0]), originalElement, 'rendered element identity survives');
assert.deepEqual(engine.list()[0].anchor, { lon: -100.8, lat: 29.4, height: 0 });
assert.equal(engine.list()[0].ring.length, 5, 'the existing data-level centroid/ring snap remains');
});
// ── Renderer-throw rollback: no phantom mark, no permanent governor hold ──────
//
// The engine holds continuous render for exactly as long as a mark is live
// (annotations.size > 0). A renderer/WebGL throw that leaves an entry in the
// map therefore leaks a hold that NOTHING releases short of an explicit clear —
// the idle governor is defeated for the rest of the session. The fresh path has
// always guarded this; the duplicate-REPLACEMENT path did the renderer swap
// outside the guard. (perf rebase 2026-08-17)
function throwingRendererHarness() {
const calls = { add: 0, remove: 0 };
let failNextAdd = false;
return {
calls,
failAddOnce() { failNextAdd = true; },
renderer: {
add() {
calls.add += 1;
if (failNextAdd) { failNextAdd = false; throw new Error('WebGL context lost'); }
},
update() {},
remove() { calls.remove += 1; },
sync() {},
},
};
}
const FIXED_POINT = { lon: -97.7431, lat: 30.2672, height: 0 };
test('duplicate-replacement: a renderer throw leaves no phantom mark and no leaked hold', async (t) => {
installAnimationFrameStubs(t);
_resetRenderGovernorForTest();
t.after(() => _resetRenderGovernorForTest());
const { renderer, failAddOnce } = throwingRendererHarness();
const engine = createAnnotationEngine({
viewer: {},
renderer,
resolveTarget: async () => ({ ...FIXED_POINT }),
});
const first = await engine.annotate([{ type: 'point', target: 'Texas Capitol', label: 'Capitol' }]);
assert.equal(first.drawn, 1);
assert.equal(engine.list().length, 1);
assert.ok(
getRenderGovernorDiagnostics().holds.includes('annotations'),
'a live mark must hold continuous render',
);
// Same place, same caption, NEW colour → the duplicate-REPLACEMENT branch,
// which deletes the dup and inserts the replacement before touching the
// renderer. (A bare point dedupes on LABEL — two different captions at one
// spot are deliberately two marks — so a recolour is the way into this
// branch for a point; see findDuplicate.)
failAddOnce();
const second = await engine.annotate([
{ type: 'point', target: 'Texas Capitol', label: 'Capitol', color: 'amber' },
]);
assert.equal(second.drawn, 0, 'the failed swap is reported as a failure, not a draw');
assert.equal(second.failed, 1);
assert.equal(engine.list().length, 0, 'no phantom annotation survives the failed swap');
assert.ok(
!getRenderGovernorDiagnostics().holds.includes('annotations'),
'the annotations hold must be released — a leak defeats the idle governor permanently',
);
});
test('fresh path: a renderer throw is rolled back the same way', async (t) => {
installAnimationFrameStubs(t);
_resetRenderGovernorForTest();
t.after(() => _resetRenderGovernorForTest());
const { renderer, failAddOnce } = throwingRendererHarness();
const engine = createAnnotationEngine({
viewer: {},
renderer,
resolveTarget: async () => ({ ...FIXED_POINT }),
});
failAddOnce();
const result = await engine.annotate([{ type: 'point', target: 'Texas Capitol', label: 'Capitol' }]);
assert.equal(result.drawn, 0);
assert.equal(engine.list().length, 0, 'no phantom annotation from a failed first add');
assert.ok(
!getRenderGovernorDiagnostics().holds.includes('annotations'),
'a never-rendered mark must not hold continuous render',
);
});
// ── Rollback must also unwind PARTIAL renderer state (review round 2) ──────────
//
// The harness above throws on the FIRST statement of add(), so a rollback that
// only deletes the engine's map entry looked complete. The real renderers build
// a mark in stages — the hybrid adds world geometry before it records the route;
// the screen renderer inserts its SVG group before its last projection pass — so
// a throw part-way leaves live content the map rollback cannot reach. The next
// annotate of the same geometry then stacks a fresh mark over that orphan.
/** A renderer that puts the mark on the board BEFORE the step that fails. */
function partialStateRendererHarness() {
const live = new Map(); // stands in for world entities / SVG groups
let failNextAdd = false;
return {
live,
failAddOnce() { failNextAdd = true; },
renderer: {
add(anno) {
live.set(anno.id, anno); // partial renderer state exists NOW
if (failNextAdd) { failNextAdd = false; throw new Error('WebGL context lost'); }
},
update() {},
remove(anno) { live.delete(anno.id); },
sync() {},
},
};
}
test('fresh path: a throw AFTER partial renderer state leaves nothing on the board', async (t) => {
installAnimationFrameStubs(t);
_resetRenderGovernorForTest();
t.after(() => _resetRenderGovernorForTest());
const { renderer, failAddOnce, live } = partialStateRendererHarness();
const engine = createAnnotationEngine({
viewer: {},
renderer,
resolveTarget: async () => ({ ...FIXED_POINT }),
});
failAddOnce();
const failed = await engine.annotate([{ type: 'point', target: 'Texas Capitol', label: 'Capitol' }]);
assert.equal(failed.drawn, 0);
assert.equal(engine.list().length, 0, 'no phantom annotation');
assert.equal(live.size, 0, 'the rollback must release what the renderer had already created');
assert.ok(
!getRenderGovernorDiagnostics().holds.includes('annotations'),
'a never-rendered mark must not hold continuous render',
);
// The real cost of an orphan: re-annotating the same place stacks a second
// mark on top of the one nothing owns.
const retry = await engine.annotate([{ type: 'point', target: 'Texas Capitol', label: 'Capitol' }]);
assert.equal(retry.drawn, 1);
assert.equal(live.size, 1, 'a re-annotate must draw ONE mark, not stack over an orphan');
});
test('duplicate-replacement: a throw AFTER partial renderer state leaves nothing on the board', async (t) => {
installAnimationFrameStubs(t);
_resetRenderGovernorForTest();
t.after(() => _resetRenderGovernorForTest());
const { renderer, failAddOnce, live } = partialStateRendererHarness();
const engine = createAnnotationEngine({
viewer: {},
renderer,
resolveTarget: async () => ({ ...FIXED_POINT }),
});
const first = await engine.annotate([{ type: 'point', target: 'Texas Capitol', label: 'Capitol' }]);
assert.equal(first.drawn, 1);
assert.equal(live.size, 1);
// Recolour → the duplicate-REPLACEMENT swap: remove(dup) lands, add(anno)
// creates its state and then throws.
failAddOnce();
const swap = await engine.annotate([
{ type: 'point', target: 'Texas Capitol', label: 'Capitol', color: 'amber' },
]);
assert.equal(swap.drawn, 0);
assert.equal(engine.list().length, 0, 'no phantom annotation survives the failed swap');
assert.equal(live.size, 0, 'and no half-swapped mark survives on the board');
assert.ok(
!getRenderGovernorDiagnostics().holds.includes('annotations'),
'the annotations hold must be released',
);
const retry = await engine.annotate([
{ type: 'point', target: 'Texas Capitol', label: 'Capitol', color: 'amber' },
]);
assert.equal(retry.drawn, 1);
assert.equal(live.size, 1, 'the recoloured mark redraws once, with no orphan underneath');
});
test('destroy releases the renderer and prevents subsequent annotation work', async (t) => {
installAnimationFrameStubs(t);
const { renderer, calls } = fakeRenderer();
let destroyed = 0;
renderer.destroy = () => { destroyed++; };
const engine = createAnnotationEngine({ viewer: {}, renderer });
const drawn = await engine.annotate([{ type: 'pin', longitude: -97.74, latitude: 30.27 }]);
assert.equal(drawn.drawn, 1);
engine.destroy();
const additions = calls.add;
const result = await engine.annotate([{ type: 'pin', target: 'Must not resolve' }]);
assert.equal(result.error, 'destroyed');
assert.equal(calls.add, additions);
assert.equal(engine.count(), 0);
engine.destroy();
assert.equal(destroyed, 1);
assert.ok(!getRenderGovernorDiagnostics().holds.includes('annotations'));
});
test('a late annotation resolver cannot redraw after destruction', async (t) => {
installAnimationFrameStubs(t);
const { renderer, calls } = fakeRenderer();
renderer.destroy = () => {};
let release;
let signal;
const engine = createAnnotationEngine({
viewer: {}, renderer,
resolveTarget: (options) => {
signal = options.signal;
return new Promise((resolve) => { release = resolve; });
},
});
const pending = engine.annotate([{ type: 'pin', target: 'Pending place' }]);
engine.destroy();
assert.equal(signal.aborted, true);
release({ lon: -97.74, lat: 30.27 });
await pending;
assert.equal(calls.add, 0);
assert.equal(engine.count(), 0);
});
test('only an explicit navigation request permits resolving distant annotation targets', async (t) => {
installAnimationFrameStubs(t);
_resetRenderGovernorForTest();
t.after(() => _resetRenderGovernorForTest());
const { renderer } = throwingRendererHarness();
renderer.destroy = () => {};
const received = [];
const engine = createAnnotationEngine({ viewer: {}, renderer,
resolveTarget: async (options) => { received.push(options); return null; },
});
await engine.annotate([{ type: 'point', target: 'Remote landmark' }]);
await engine.annotate([{ type: 'point', target: 'Remote landmark' }], { flyTo: true });
assert.deepEqual(received.map(options => options.allowDistant), [false, true]);
engine.destroy();
});
// Draw's list works one hand-drawn mark at a time: hide, rename, recolour,
// frame and remove it, and hear about every change to the board.
test('hand-drawn marks: one mark can be hidden, renamed, recoloured, framed and removed', async (t) => {
installAnimationFrameStubs(t);
_resetRenderGovernorForTest();
t.after(() => _resetRenderGovernorForTest());
const { renderer, calls } = fakeRenderer();
const flights = [];
const engine = createAnnotationEngine({
viewer: { camera: { heading: 0, flyToBoundingSphere: (sphere) => flights.push(sphere) } },
renderer,
});
let changes = 0;
const unsubscribe = engine.onChange(() => { changes += 1; });
const drawn = await engine.annotate([
{ type: 'route', manual: true, path: [[-97.75, 30.26], [-97.73, 30.27]], label: '' },
{ type: 'pin', manual: true, latitude: 30.27, longitude: -97.74, label: 'Camp', color: 'amber' },
], { persist: true });
assert.equal(drawn.drawn, 2);
assert.equal(changes, 1, 'one annotate, one change');
const [line, pin] = engine.list();
assert.equal(line.manual, true);
assert.equal(line.name, null);
assert.match(line.label, /km|m$/, 'an unnamed line is labelled by its length');
assert.equal(pin.name, 'Camp');
assert.equal(engine.setHidden(pin.id, true), true);
assert.equal(pin.hidden, true);
assert.equal(changes, 2);
const addsBefore = calls.add;
assert.equal(engine.restyle(line.id, { name: 'Ridge walk', color: 'green' }), true);
assert.equal(line.name, 'Ridge walk');
assert.match(line.label, /^Ridge walk — /, 'a renamed line keeps its length');
assert.equal(line.color, 'green');
assert.equal(calls.add, addsBefore + 1, 'the new look is drawn again');
assert.equal(engine.restyle(line.id, { color: 'not-a-colour' }), true);
assert.equal(line.color, 'green', 'an unknown colour is ignored');
assert.equal(engine.frame(line.id), true);
assert.equal(flights.length, 1);
assert.equal(engine.frame('anno-missing'), false);
assert.equal(engine.remove(pin.id), true);
assert.deepEqual(engine.list().map(({ id }) => id), [line.id]);
assert.equal(engine.remove(pin.id), false);
engine.clear();
assert.equal(engine.list().length, 0);
const seen = changes;
unsubscribe();
await engine.annotate([{ type: 'pin', manual: true, latitude: 1, longitude: 1 }], { persist: true });
assert.equal(changes, seen, 'an unsubscribed listener hears nothing');
});
// The list trusts these calls to change the globe, not just the list: each
// is checked by its effect (renderer calls, alpha, camera, notifications).
test('hand-drawn marks: remove, hide, clear, expiry and framing have their effect', async (t) => {
const frames = [];
const originalRequestAnimationFrame = globalThis.requestAnimationFrame;
const originalCancelAnimationFrame = globalThis.cancelAnimationFrame;
globalThis.requestAnimationFrame = (callback) => frames.push(callback);
globalThis.cancelAnimationFrame = () => {};
let now = 1_000_000;
t.mock.method(performance, 'now', () => now);
_resetRenderGovernorForTest();
t.after(() => {
globalThis.requestAnimationFrame = originalRequestAnimationFrame;
globalThis.cancelAnimationFrame = originalCancelAnimationFrame;
_resetRenderGovernorForTest();
});
const runFrames = () => {
for (let i = 0; i < 5 && frames.length; i += 1) frames.shift()();
};
const { renderer, calls } = fakeRenderer();
const flights = [];
const engine = createAnnotationEngine({
viewer: {
camera: {
heading: 0,
flyToBoundingSphere: (sphere) => flights.push(sphere),
},
},
renderer,
});
let changes = 0;
engine.onChange(() => {
changes += 1;
});
await engine.annotate(
[
{
type: 'pin',
manual: true,
latitude: 30.27,
longitude: -97.74,
label: 'Camp',
},
{
type: 'pin',
manual: true,
latitude: 30.3,
longitude: -97.7,
label: 'Base',
},
],
{ persist: true },
);
now += 1000;
runFrames();
const [camp, base] = engine.list();
assert.equal(camp.alpha, 1);
engine.setHidden(camp.id, true);
runFrames();
assert.equal(camp.alpha, 0, 'a hidden mark is drawn at alpha 0');
assert.ok(engine.list().includes(camp), 'and stays on the board');
engine.setHidden(camp.id, false);
runFrames();
assert.equal(camp.alpha, 1, 'showing it again is immediate, with no fade-in');
const removes = calls.remove;
let seen = changes;
engine.remove(base.id);
assert.equal(calls.remove, removes + 1, 'remove takes it off the globe');
assert.equal(changes, seen + 1, 'and tells the list');
seen = changes;
engine.clear();
assert.equal(changes, seen + 1, 'a clear tells the list');
// A voice mark with a TTL: its expiry must reach the list too.
await engine.annotate(
[{ type: 'pin', latitude: 1, longitude: 1, label: 'Brief' }],
{
persist: false,
ttlMs: 2000,
},
);
seen = changes;
now += 60_000;
runFrames();
assert.equal(engine.list().length, 0, 'the mark expired');
assert.equal(changes, seen + 1, 'expiry tells the list');
// A line across the antimeridian is framed there, not on the far side.
await engine.annotate(
[
{
type: 'route',
manual: true,
path: [
[179.9, -17],
[-179.9, -17.1],
],
label: '',
},
],
{ persist: true },
);
const [line] = engine.list();
engine.frame(line.id);
const centre = Cesium.Cartographic.fromCartesian(flights.at(-1).center);
assert.ok(
Math.abs(Math.abs(Cesium.Math.toDegrees(centre.longitude)) - 180) < 0.5,
`framed at ${Cesium.Math.toDegrees(centre.longitude)}°, not near 180°`,
);
});
test('hand-drawn marks: a voice mark or a hidden mark is not taken as their duplicate', async (t) => {
installAnimationFrameStubs(t);
_resetRenderGovernorForTest();
t.after(() => _resetRenderGovernorForTest());
const { renderer } = fakeRenderer();
const engine = createAnnotationEngine({ viewer: {}, renderer });
await engine.annotate(
[
{
type: 'pin',
manual: true,
latitude: 30.27,
longitude: -97.74,
label: 'Camp',
},
],
{ persist: true },
);
const [drawn] = engine.list();
// The agent marks the same spot with the same label, briefly.
await engine.annotate(
[{ type: 'pin', latitude: 30.27, longitude: -97.74, label: 'Camp' }],
{
persist: false,
},
);
assert.equal(engine.list().length, 2, 'the voice mark is its own mark');
assert.equal(drawn.ttlMs, null, 'the drawn pin keeps persisting');
assert.equal(drawn.manual, true);
engine.setHidden(drawn.id, true);
const again = await engine.annotate(
[
{
type: 'pin',
manual: true,
latitude: 30.27,
longitude: -97.74,
label: 'Camp',
},
],
{ persist: true },
);
assert.equal(again.drawn, 1);
const visible = engine.list().filter((mark) => mark.manual && !mark.hidden);
assert.equal(
visible.length,
1,
'a pin dropped on a hidden one is a new, visible pin',
);
});
test('hand-drawn marks: only a manual mark can be restyled', async (t) => {
installAnimationFrameStubs(t);
_resetRenderGovernorForTest();
t.after(() => _resetRenderGovernorForTest());
const { renderer } = fakeRenderer();
const engine = createAnnotationEngine({
viewer: {},
renderer,
resolveTarget: async () => ({ ...FIXED_POINT }),
});
await engine.annotate([{ type: 'point', target: 'Texas Capitol', label: 'Capitol' }]);
const [voiceMark] = engine.list();
assert.equal(voiceMark.manual, false);
assert.equal(engine.restyle(voiceMark.id, { name: 'Renamed' }), false);
assert.equal(voiceMark.label, 'Capitol');
});
test('a drawn line that rounds up to the next unit is labelled in it, not as 1000 m or 10.0 km', async (t) => {
installAnimationFrameStubs(t);
const labels = [];
const renderer = { add(anno) { labels.push(anno.label); }, update() {}, remove() {}, sync() {}, destroy() {} };
const engine = createAnnotationEngine({ viewer: {}, renderer });
const metresPerDegree = (6371.0088 * 1000 * Math.PI) / 180;
for (const metres of [994, 996, 9940, 9960]) {
await engine.annotate([
{ type: 'route', manual: true, path: [[0, 0], [0, metres / metresPerDegree]] },
]);
}
assert.deepEqual(labels, ['990 m', '1.0 km', '9.9 km', '10 km']);
engine.destroy();
});
test('hand-drawn marks: two unnamed pins close together are two pins, whatever their colours', async (t) => {
installAnimationFrameStubs(t);
_resetRenderGovernorForTest();
t.after(() => _resetRenderGovernorForTest());
const { renderer } = fakeRenderer();
const engine = createAnnotationEngine({ viewer: {}, renderer });
const pin = (lon, color) => ({ type: 'pin', manual: true, latitude: 30.27, longitude: lon, label: '', color });
await engine.annotate([pin(-97.74, 'primary')], { persist: true });
await engine.annotate([pin(-97.7402, 'primary')], { persist: true });
await engine.annotate([pin(-97.7404, 'red')], { persist: true });
assert.deepEqual(
engine.list().map(({ color }) => color),
['primary', 'primary', 'red'],
'no drawn pin is dropped or replaced by the next',
);
});
test('hand-drawn marks: hiding a mark before its first frame takes it off at once', async (t) => {
installAnimationFrameStubs(t);
_resetRenderGovernorForTest();
t.after(() => _resetRenderGovernorForTest());
let syncs = 0;
const renderer = { add() {}, update() {}, remove() {}, sync() { syncs += 1; }, destroy() {} };
const engine = createAnnotationEngine({ viewer: {}, renderer });
await engine.annotate([{ type: 'pin', manual: true, latitude: 1, longitude: 1 }], { persist: true });
const [mark] = engine.list();
const before = syncs;
engine.setHidden(mark.id, true);
assert.ok(syncs > before, 'the renderer hears about it now');
assert.ok(
!getRenderGovernorDiagnostics().holds.includes('annotations'),
'and the render hold goes with the last visible mark',
);
});
test('hand-drawn marks: with every mark hidden the scene idles, and showing one wakes it', async (t) => {
installAnimationFrameStubs(t);
_resetRenderGovernorForTest();
t.after(() => _resetRenderGovernorForTest());
let renders = 0;
installRenderGovernor({ scene: { requestRenderMode: true, requestRender: () => (renders += 1) } });
const { renderer } = fakeRenderer();
const engine = createAnnotationEngine({ viewer: {}, renderer });
await engine.annotate([
{ type: 'pin', manual: true, latitude: 1, longitude: 1 },
{ type: 'pin', manual: true, latitude: 2, longitude: 2 },
], { persist: true });
const [first, second] = engine.list();
const held = () => getRenderGovernorDiagnostics().holds.includes('annotations');
assert.ok(held(), 'visible marks keep the scene drawing');
engine.setHidden(first.id, true);
assert.ok(held(), 'one visible mark is enough');
const before = renders;
engine.setHidden(second.id, true);
assert.equal(held(), false, 'every mark hidden: the scene idles');
assert.ok(renders > before, 'after one last frame that takes them off');
engine.setHidden(second.id, false);
assert.ok(held(), 'showing one wakes it again');
});
test('hand-drawn marks: a restyle the renderer cannot draw takes the mark off and says so', async (t) => {
installAnimationFrameStubs(t);
_resetRenderGovernorForTest();
t.after(() => _resetRenderGovernorForTest());
const { renderer, failAddOnce } = throwingRendererHarness();
let syncs = 0;
renderer.sync = () => (syncs += 1);
const engine = createAnnotationEngine({ viewer: {}, renderer });
await engine.annotate([{ type: 'pin', manual: true, latitude: 1, longitude: 1 }], { persist: true });
const [mark] = engine.list();
let changes = 0;
engine.onChange(() => (changes += 1));
const before = syncs;
failAddOnce();
assert.throws(() => engine.restyle(mark.id, { color: 'red' }), /WebGL context lost/);
assert.equal(engine.list().length, 0, 'no ghost row is left behind');
assert.equal(changes, 1, 'the list hears about it');
assert.ok(syncs > before, 'and the renderer is told');
});
test('hand-drawn marks: a mark shown again right after it was drawn appears at once, not fading in', async (t) => {
_resetRenderGovernorForTest();
t.after(() => _resetRenderGovernorForTest());
const queued = [];
const raf = globalThis.requestAnimationFrame;
const caf = globalThis.cancelAnimationFrame;
globalThis.requestAnimationFrame = (callback) => queued.push(callback);
globalThis.cancelAnimationFrame = () => {};
t.after(() => {
globalThis.requestAnimationFrame = raf;
globalThis.cancelAnimationFrame = caf;
});
const tick = () => queued.splice(0).forEach((callback) => callback());
const { renderer } = fakeRenderer();
const engine = createAnnotationEngine({ viewer: {}, renderer });
await engine.annotate([{ type: 'pin', manual: true, latitude: 1, longitude: 1 }], { persist: true });
const [mark] = engine.list();
engine.setHidden(mark.id, true);
tick();
assert.equal(mark.alpha, 0);
engine.setHidden(mark.id, false);
tick();
assert.equal(mark.alpha, 1, 'no fade-in after a hide');
});