From dbe026b1092988cfc846c7f3d6912ca84d66b8c5 Mon Sep 17 00:00:00 2001 From: Sameh Khamis Date: Wed, 11 Nov 2026 20:51:40 -0800 Subject: [PATCH] render: setBase's settled is stated for overlapping calls: whether, when the call resolves, its base is still the one drawn and has settled; an earlier call resolving while a later style loads, or after it fails, is settled, and one resolving after a later call changed the base is not --- docs/RENDERER-CONTRACT.md | 6 ++++-- src/render/cesium/globe.js | 5 +++-- src/render/contract/globe.d.ts | 15 +++++++++++++-- src/render/stub/index.js | 4 +++- src/render/stub/stub.test.mjs | 35 ++++++++++++++++++++++++++++++++++ 5 files changed, 58 insertions(+), 7 deletions(-) diff --git a/docs/RENDERER-CONTRACT.md b/docs/RENDERER-CONTRACT.md index 7789c2a8f..997ddeb9a 100644 --- a/docs/RENDERER-CONTRACT.md +++ b/docs/RENDERER-CONTRACT.md @@ -364,8 +364,10 @@ What it draws of the style specification: The Cesium port loads the style before the base changes (a style that fails leaves the base as it was; a later `setBase`, or disposal, aborts the load and the overtaken call changes nothing, resolving with `imagery: []` and -`settled: false`; a later call whose style fails leaves the earlier call's -base drawn, and that call settles), draws it as Web Mercator imagery under the +`settled: false`; `settled` is whether, when the call resolves, its base is +still the one drawn and has settled, so an earlier call that resolves while a +later call's style is still loading, or after that style fails, is settled, +and one that resolves after a later call changed the base is not), draws it as Web Mercator imagery under the base's other imagery (`src/render/cesium/vectorBase.js`, 256 px tiles to level 20, transparent where the style paints no opaque background; a tile whose request is cancelled, its layer removed, is not painted), and credits each source's attribution as plain text. The stub diff --git a/src/render/cesium/globe.js b/src/render/cesium/globe.js index fd5152caa..272286c5e 100644 --- a/src/render/cesium/globe.js +++ b/src/render/cesium/globe.js @@ -299,8 +299,9 @@ export function createCesiumGlobe( return { photoreal: photorealStatus, imagery: layers, - // A base a later call replaced has not settled; one whose later call - // failed is still drawn. + // Settled when its base is still the one drawn: a later call changes + // the base only once its style loads, and one whose style fails never + // does (see the contract's setBase). settled: gen === drawnGen && !disposed && isSettled('base'), }; } diff --git a/src/render/contract/globe.d.ts b/src/render/contract/globe.d.ts index ba796e51e..96fa34227 100644 --- a/src/render/contract/globe.d.ts +++ b/src/render/contract/globe.d.ts @@ -242,8 +242,19 @@ export interface GlobePort { * The last call wins: one a later `setBase` (or the renderer's disposal) * overtakes before its base changes (its vector style still loading) * changes nothing and resolves with `imagery: []`, `settled: false` and the - * photoreal status as it stands, never rejecting; one overtaken after it - * changed the base resolves with `settled: false`. + * photoreal status as it stands, never rejecting. + * + * `settled` describes the moment the call resolves: true when its base is + * still the one drawn (no later call has changed the base since) and has + * settled. A later call only changes the base once its style has loaded, + * so for a call A overtaken by a call B: + * - A resolves before B changes the base (B's style still loading): A's + * base is the one drawn, so `settled: true`; B then replaces it and + * answers for itself. + * - B changes the base before A resolves: `settled: false`. + * - B's style fails (B rejects): the base stays A's, so A resolves with + * `settled: true` whenever it resolves. + * Only the latest call's answer says what is drawn once every call is done. */ setBase(base: BaseSpec): Promise; /** `photoreal`: on, off or a new token route. */ diff --git a/src/render/stub/index.js b/src/render/stub/index.js index 87574073c..6d0decbbb 100644 --- a/src/render/stub/index.js +++ b/src/render/stub/index.js @@ -1598,7 +1598,9 @@ export function createStubRenderer(options = {}) { const layers = (base.imagery ?? []).map((spec) => addImagery(spec)); if (base.photoreal !== undefined) await globe.setPhotoreal(base.photoreal); - // A base a later call replaced has not settled. + // Settled when its base is still the one drawn: a later call changes + // the base only once its style loads, and one whose style fails never + // does (see the contract's setBase). return { photoreal: photorealStatus, imagery: layers, diff --git a/src/render/stub/stub.test.mjs b/src/render/stub/stub.test.mjs index c2b5bc2e7..836f3dbd6 100644 --- a/src/render/stub/stub.test.mjs +++ b/src/render/stub/stub.test.mjs @@ -275,3 +275,38 @@ test('a later setBase whose style fails leaves the earlier one the base, settled globalThis.fetch = original; } }); + +test('a setBase that ends while a later one’s style still loads is settled; the later one then replaces it', async () => { + const held = []; + const original = globalThis.fetch; + globalThis.fetch = () => + new Promise((resolve) => { + held.push(() => + resolve({ + ok: true, + status: 200, + json: async () => ({ version: 8, sources: {}, layers: [] }), + }), + ); + }); + try { + const r = createStubRenderer(); + const first = r.globe.setBase({ + photoreal: null, + imagery: [{ kind: 'xyz', url: 'https://a.invalid/{z}/{x}/{y}.png' }], + }); + const second = r.globe.setBase({ + vector: { styleUrl: 'https://s.invalid/x' }, + }); + const status = await first; + assert.equal(status.settled, true, 'its base is still the one drawn'); + assert.deepEqual(r.globe.imagery.list(), status.imagery); + held[0](); + const later = await second; + assert.equal(later.settled, true); + assert.deepEqual(r.globe.imagery.list(), later.imagery); + r.destroy(); + } finally { + globalThis.fetch = original; + } +});