diff --git a/changelog.d/1871-street-level-photo-followups.md b/changelog.d/1871-street-level-photo-followups.md new file mode 100644 index 0000000000..e68357f915 --- /dev/null +++ b/changelog.d/1871-street-level-photo-followups.md @@ -0,0 +1,3 @@ +- Street Level's photo viewer settles every open and mount, draws one + viewer at a time and states its view contract (manjunath22466, + samehkhamis, #1871). diff --git a/docs/CURRENT-STATE.md b/docs/CURRENT-STATE.md index 8e8490d845..1ffe45ca03 100644 --- a/docs/CURRENT-STATE.md +++ b/docs/CURRENT-STATE.md @@ -6354,8 +6354,9 @@ viewer host and hands back the canvas the panorama is drawn on (a fresh one after a lost context). Each mount and each canvas has a key of its own, so a viewer never draws on another one's elements, and of two viewers mounting at once only the later one is drawn (`photoViewers.js`): the -earlier one's mount closes. Without a subscribed view these photos cannot -open. +earlier one's mount closes. A view may draw at once or later; what it +reads (`mountKey`, `actions.supersede()`) is `ViewerAdapter.subscribeView` +in `registry.js`. Without a subscribed view these photos cannot open. Panoramax (`providers/panoramax/`) is keyless and browser-side: the meta-catalogue `api.panoramax.xyz` (CORS open) federates every instance, and diff --git a/src/layers/streetLevel/photoViewer.js b/src/layers/streetLevel/photoViewer.js index c9b9f48a11..509ee48c75 100644 --- a/src/layers/streetLevel/photoViewer.js +++ b/src/layers/streetLevel/photoViewer.js @@ -4,8 +4,14 @@ import { wrapDegrees, } from './panorama.js'; import { imageSize } from './imageSize.js'; +import { nextViewKey } from './photoViewers.js'; import { msg, t } from '../../i18n/index.js'; +// Each mount's and each canvas's key comes from `nextViewKey()`, never +// reused by any viewer: a view that sees one viewer unmount and another +// mount in the same tick still draws them fresh elements (a destroyed +// renderer leaves its canvas's context lost). + /** * EXPAND puts the viewer's wrap full screen, or (iPhone) opens it as a * popover. Each is tried on its own: a browser that cannot parse one @@ -36,14 +42,6 @@ function tooManyPixels(width, height) { ); } -/** - * Keys for each mount's and each canvas's elements, never reused by any - * viewer: a view that sees one viewer unmount and another mount in the same - * tick still draws them fresh elements (a destroyed renderer leaves its - * canvas's context lost). - */ -let viewKeys = 0; - /** Panorama texture widths: enough for a docked viewer, and for an expanded one. */ const PANO_MID_SIZE = Object.freeze([2048, 1024]); export const PANO_FULL_SIZE = Object.freeze([4096, 2048]); @@ -159,6 +157,16 @@ async function loadBitmap(url, timeoutMs, resize, failure, signal) { } } +/** + * Unmounted, superseded or left without a view before the view drew what + * was waiting on it (`undrawn`): a mount or an open that fails as closed. + */ +function undrawn() { + return Object.assign(new Error('Street-level viewer was closed'), { + undrawn: true, + }); +} + /** * A picture refused for its size (`tooLarge`): the viewer will not load * that file another way, an having no size limit at all. @@ -228,13 +236,20 @@ export function panoSizeFor(canvasPixels, fovDeg) { * each change, * or null while unmounted. A view draws it into `host` (the application's is * `StreetLevelPhotoViewer`), forwards its events to `actions` and hands each - * element back through `actions.attach(name, element)`: the panorama canvas - * to draw on, the frame and picture to measure, the root and buttons to - * keep focus. Each mount has its own `mountKey`, and a new `canvasKey` asks - * for a fresh canvas (a lost WebGL context): neither is ever reused. - * `actions.supersede()` tells a viewer another one is drawn in its place: - * it unmounts, and a mount still waiting to be drawn fails as closed. - * Mounting with no view subscribed fails. + * element back through `actions.attach(name, element)` on every draw: the + * panorama canvas to draw on, the frame and picture to measure, the root + * and buttons to keep focus. A view may draw at once, inside its listener, + * or later (Vue draws on a microtask). Each mount has its own `mountKey`, + * and a new `canvasKey` asks for a fresh canvas (a lost WebGL context): + * neither is ever reused. `actions.supersede()` tells a viewer another one + * is drawn in its place: it unmounts, and a mount still waiting to be drawn + * fails as closed. Mounting with no view subscribed fails, and a mount or + * a panorama's open waiting on a draw when the last view leaves fails as + * closed (the mount unmounts; the open leaves no photo shown). A view + * handing back another canvas element than the renderer's (one subscribed + * since) gets the panorama drawn again on it, as after a lost context; + * while several views draw, a canvas the panorama moved off is not moved + * back to, and once one view is left its canvas is taken back. * * Photos are normalized by the provider: `{id, sequenceId, lon, lat, * heading, isPano, capturedAt}` plus whatever its `sources` read. @@ -284,6 +299,17 @@ export function createPhotoViewer({ /** Waiting for the view's root (a mount), or its canvas: a fresh one, or the next draw. */ const rootWaiters = new Set(); const canvasWaiters = new Set(); + /** How many times the view has handed the canvas back (once per draw). */ + let canvasDraws = 0; + /** + * Canvases the panorama moved off while more than one view draws: one + * handed back again (a second view drawing its own) is not moved back to, + * so two views cannot take turns. Forgotten once a single view is left, + * so its canvas is taken back. + */ + let retiredCanvases = new WeakSet(); + /** The canvas moved while an open waited on its draw. */ + let canvasMoved = false; let renderer = null; /** WebGL failed once: 360° photos show their front view instead. */ let rendererFailed = false; @@ -396,22 +422,28 @@ export function createPhotoViewer({ waiters.clear(); } - /** The panorama canvas once the view has drawn it, or the open stopped. */ - function canvasReady(signal) { - if (canvas || !presented || signal?.aborted) return Promise.resolve(); + /** A draw of the canvas, or none coming: unmounted, no view, or the open stopped. */ + function canvasDrawn(drawn, signal) { + if (drawn() || !presented || !viewListeners.size || signal?.aborted) + return Promise.resolve(); return new Promise((resolve) => { canvasWaiters.add(resolve); signal?.addEventListener?.('abort', resolve, { once: true }); }); } - /** The view's next draw (it hands the canvas back each time), or none coming. */ - function nextDraw(signal) { - if (!presented || signal?.aborted) return Promise.resolve(); - return new Promise((resolve) => { - canvasWaiters.add(resolve); - signal?.addEventListener?.('abort', resolve, { once: true }); - }); + /** The panorama canvas once the view has drawn it, or the open stopped. */ + function canvasReady(signal) { + return canvasDrawn(() => Boolean(canvas), signal); + } + + /** + * A draw of the canvas after the `count`th (it hands the canvas back each + * time), or none coming. A view may draw synchronously, inside the + * presentation, before anything waits: counted, that draw is not missed. + */ + function drawnAfter(count, signal) { + return canvasDrawn(() => canvasDraws > count, signal); } function syncButtons() { @@ -469,6 +501,30 @@ export function createPhotoViewer({ const from = event?.currentTarget ?? event?.target; if (from && from !== canvas) return; event.preventDefault?.(); + dropRenderer(); + // A lost canvas hands back its lost context: the view draws a new + // element in its place and hands it back. + canvas = null; + present({ canvasKey: nextViewKey() }); + reopen(); + } + + /** + * The view drew the panorama on another canvas element than the + * renderer's (a view that subscribed since): the renderer cannot follow + * it, so the photo is drawn again on a new one, as after a lost context. + */ + function moveCanvas(element) { + dropRenderer(); + retiredCanvases.add(canvas); + canvas = element; + // An open waiting on the draw goes on, on the new canvas. + if (openingId !== null) canvasMoved = true; + else reopen(); + } + + /** Let the renderer go, keeping the user's look for the photo's reopen. */ + function dropRenderer() { const lost = renderer; renderer = null; // The new renderer starts facing the photo's heading: keep the user's look. @@ -479,11 +535,10 @@ export function createPhotoViewer({ } catch { /* already gone */ } - // A lost canvas hands back its lost context: the view draws a new - // element in its place and hands it back. - canvas = null; - present({ canvasKey: ++viewKeys }); - // Show the photo again through the core, unless a newer one is opening. + } + + /** Show the panorama again through the core, unless a newer photo is opening. */ + function reopen() { if (showing === 'pano' && photo && openingId === null) { const again = photo.id; show(null); @@ -665,9 +720,23 @@ export function createPhotoViewer({ const actions = { attach(name, element) { if (presented?.actions !== actions || !element) return; - ELEMENTS[name]?.(element); + const retired = name === 'canvas' && retiredCanvases.has(element); + if (retired) { + // Another view still draws the panorama: this draw is counted, so + // an open waiting on it goes on, but the panorama stays put. + } else if ( + name === 'canvas' && + renderer && + canvas && + element !== canvas + ) + moveCanvas(element); + else ELEMENTS[name]?.(element); if (name === 'root') wake(rootWaiters); - if (name === 'canvas') wake(canvasWaiters); + if (name === 'canvas') { + canvasDraws++; + wake(canvasWaiters); + } }, keydown: current(onKeyDown), pointerdown: current(onPointerDown), @@ -683,7 +752,7 @@ export function createPhotoViewer({ }; presented = { host, - mountKey: ++viewKeys, + mountKey: nextViewKey(), providerId, label: t( '{name} photo. ← and → step along the sequence. On a 360° photo, drag or use Shift+← →, ↑ ↓ to look around, and + − to zoom', @@ -693,7 +762,7 @@ export function createPhotoViewer({ kind: undefined, src: null, fit: renderMode === 'fill' ? 'cover' : 'contain', - canvasKey: ++viewKeys, + canvasKey: nextViewKey(), dragging: false, prevLabel: t('Previous photo in this sequence (←)'), prevDisabled: true, @@ -865,9 +934,27 @@ export function createPhotoViewer({ renderer.setView({ yaw: 0, pitch: 0, fov: PANO_FOV_DEFAULT_DEG }); photo = target; // Shown first: a hidden canvas measures 0 and would be sized 1×1. The - // view draws it shown on a microtask, and hands the canvas back then. + // view draws it shown, at once or on a microtask, and hands the canvas + // back then. + const draws = canvasDraws; + canvasMoved = false; show('pano'); - await nextDraw(signal); + await drawnAfter(draws, signal); + // The view drew it on another canvas: the panorama goes there. + if (canvasMoved && seq === openSeq && !renderer && ensureRenderer()) { + const moved = restoreView?.id === target.id ? restoreView.view : null; + restoreView = null; + if (moved) renderer.setView(moved); + } + canvasMoved = false; + // The last view left before drawing it: the canvas was never shown, and + // nothing is drawn until a view is back. + if (seq === openSeq && canvasDraws === draws && !viewListeners.size) { + image.close?.(); + photo = null; + show(null); + throw undrawn(); + } if (seq !== openSeq || !renderer) { image.close?.(); if (seq !== openSeq) return false; @@ -916,7 +1003,8 @@ export function createPhotoViewer({ if (sources.hasPano(target) && ensureRenderer()) { try { shown = await showPano(target, seq, keepView, signal); - } catch { + } catch (error) { + if (error?.undrawn) throw error; // The panorama failed: its front view is better than nothing. if (seq !== openSeq) return; shown = await showFlat(target, seq, signal); @@ -937,12 +1025,31 @@ export function createPhotoViewer({ rendererFailed = false; if (!viewListeners.size) throw new Error('Street Level photo viewer has no view to draw it'); - // Resolves once the view drew the viewer, or it was unmounted meanwhile. - const drawn = new Promise((resolve) => rootWaiters.add(resolve)); + // Resolves once the view drew the viewer, or it was unmounted, or its + // last view left, meanwhile. + const waitRoot = () => new Promise((resolve) => rootWaiters.add(resolve)); + let drawn = waitRoot(); build(host); - if (!root) await drawn; - // Unmounted or superseded before the view drew it. - if (!root) throw new Error('Street-level viewer was closed'); + // This mount's presentation: a later mount presents its own. A view + // may have unmounted it already, inside its first draw. + const mine = presented?.actions; + if (!mine) throw undrawn(); + for (;;) { + if (!root) await drawn; + const current = presented?.actions === mine; + if (root && current) return; + // Unmounted, superseded or mounted again: that is not this mount. + if (!current) throw undrawn(); + // Its last view left, and another subscribed since: it draws. + if (viewListeners.size) { + drawn = waitRoot(); + continue; + } + // No view will draw it. Unmounted, as when superseded, so a view + // subscribing later draws nothing. + adapter.unmount(); + throw undrawn(); + } }, /** Resolves once the photo is on screen and its pose was emitted. */ @@ -1029,7 +1136,17 @@ export function createPhotoViewer({ subscribeView(listener) { viewListeners.add(listener); listener(presented); - return () => viewListeners.delete(listener); + return () => { + // The last view went: a mount or an open waiting on its draw fails + // as closed. + if (!viewListeners.delete(listener)) return; + // One view left: the canvases moved off are its to hand back again. + if (viewListeners.size <= 1) retiredCanvases = new WeakSet(); + if (!viewListeners.size) { + wake(rootWaiters); + wake(canvasWaiters); + } + }; }, }; return adapter; diff --git a/src/layers/streetLevel/photoViewer.test.mjs b/src/layers/streetLevel/photoViewer.test.mjs index 97c8bf4000..1f01117957 100644 --- a/src/layers/streetLevel/photoViewer.test.mjs +++ b/src/layers/streetLevel/photoViewer.test.mjs @@ -1,7 +1,14 @@ import assert from 'node:assert/strict'; import test from 'node:test'; import { createPhotoViewer } from './photoViewer.js'; -import { fakeHost, until } from '../../testSupport/kartaViewFakes.mjs'; +import { + fakeHost, + until, + resetPhotoView, +} from '../../testSupport/kartaViewFakes.mjs'; + +// Each test draws its own viewers only. +test.beforeEach(resetPhotoView); const PHOTOS = { a: { id: 'a', sequenceId: 's', lon: 1, lat: 2, heading: 0, isPano: true }, @@ -636,3 +643,356 @@ test('a panorama reopened after a lost context waits for the view’s fresh canv ); assert.equal(shown.kind, 'pano', 'not the front view'); }); + +/** + * A panorama viewer whose sequence goes on both ways (its ‹ › present no + * change once shown), drawn by `view` alone, not by the shared fake view. + */ +function panoramaViewer() { + const images = []; + const viewer = createPhotoViewer({ + providerId: 'test', + name: 'Test', + sources: SOURCES, + getPhoto: async (id) => PHOTOS[id], + step: async () => 'b', + onStep() {}, + load: async (url) => ({ src: url }), + createRenderer: () => ({ + setImage: (image) => images.push(image.src), + setView() {}, + getView: () => ({ yaw: 0, pitch: 0, fov: 80 }), + resize() {}, + clear() {}, + destroy() {}, + }), + }); + return { viewer, images }; +} + +/** Elements a view hands back: what the viewer measures and focuses. */ +const elements = () => + Object.fromEntries( + ['root', 'picture', 'canvas', 'prev', 'next'].map((name) => [ + name, + { clientWidth: 400, clientHeight: 250 }, + ]), + ); + +/** Whether `promise` settles within a few macrotasks. */ +const settles = (promise) => + Promise.race([ + promise.then( + () => true, + () => true, + ), + new Promise((resolve) => setTimeout(() => resolve(false), 50)), + ]); + +test('a view that draws at once, inside its listener, opens a panorama', async () => { + const { viewer, images } = panoramaViewer(); + const parts = elements(); + const unsubscribe = viewer.subscribeView((view) => { + if (!view) return; + for (const [name, element] of Object.entries(parts)) + view.actions.attach(name, element); + }); + await viewer.mount(fakeHost()); + assert.equal(await settles(viewer.open('a')), true, 'not left pending'); + assert.deepEqual(images, ['a-first']); + viewer.unmount(); + unsubscribe(); +}); + +test('a panorama’s open waiting on the view’s draw fails as closed when the view leaves', async () => { + const { viewer, images } = panoramaViewer(); + const parts = elements(); + const kinds = []; + const presented = []; + // Draws the mount, then nothing more. + const unsubscribe = viewer.subscribeView((view) => { + presented.push(view); + if (!view) return; + kinds.push(view.kind); + if (kinds.length > 1) return; + for (const [name, element] of Object.entries(parts)) + view.actions.attach(name, element); + }); + await viewer.mount(fakeHost()); + const opening = viewer.open('a'); + assert.ok(await until(() => kinds.includes('pano')), 'waiting on a draw'); + unsubscribe(); + assert.equal(await settles(opening), true, 'not left pending'); + await assert.rejects(opening, /viewer was closed/); + assert.deepEqual(images, [], 'nothing uploaded to a canvas never shown'); + // A view back draws the viewer mounted, with no photo shown. + let again = null; + const resubscribe = viewer.subscribeView((view) => (again = view)); + assert.ok(again, 'still mounted'); + assert.equal(again.kind, ''); + resubscribe(); + viewer.unmount(); +}); + +test('a mount waiting on the view’s draw fails as closed when the view leaves, and is unmounted', async () => { + const { viewer } = panoramaViewer(); + const unsubscribe = viewer.subscribeView(() => {}); + const mounting = viewer.mount(fakeHost()); + unsubscribe(); + assert.equal(await settles(mounting), true, 'not left pending'); + await assert.rejects(mounting, /viewer was closed/); + let current; + const resubscribe = viewer.subscribeView((view) => (current = view)); + assert.equal(current, null, 'nothing presented'); + await assert.rejects(viewer.open('a'), /not mounted/); + resubscribe(); +}); + +test('a view handing back another canvas gets the panorama drawn again on it', async () => { + const renderers = []; + const reopened = []; + const viewer = createPhotoViewer({ + providerId: 'test', + name: 'Test', + sources: SOURCES, + getPhoto: async (id) => PHOTOS[id], + step: async () => 'b', + onStep() {}, + onReopen: (id) => { + reopened.push(id); + viewer.open(id); + }, + load: async (url) => ({ src: url }), + createRenderer: (canvas) => { + const renderer = { + canvas, + images: [], + destroyed: false, + setImage: (image) => renderer.images.push(image.src), + setView() {}, + getView: () => ({ yaw: 10, pitch: 0, fov: 80 }), + resize() {}, + clear() {}, + destroy: () => (renderer.destroyed = true), + }; + renderers.push(renderer); + return renderer; + }, + }); + const drawWith = (parts) => (view) => { + if (!view) return; + for (const [name, element] of Object.entries(parts)) + view.actions.attach(name, element); + }; + const first = elements(); + const unsubscribe = viewer.subscribeView(drawWith(first)); + await viewer.mount(fakeHost()); + await viewer.open('a'); + assert.equal(renderers[0].canvas, first.canvas); + // Another view takes over, with elements of its own. + const second = elements(); + const resubscribe = viewer.subscribeView(drawWith(second)); + unsubscribe(); + assert.ok(await until(() => renderers[1]?.images.length > 0)); + assert.deepEqual(reopened, ['a']); + assert.equal(renderers[0].destroyed, true); + assert.equal(renderers[1].canvas, second.canvas); + assert.deepEqual(renderers[1].images, ['a-first']); + viewer.unmount(); + resubscribe(); +}); + +test('the shared fake view draws only the later of two mounts, as the app does', async () => { + const one = setup(); + const two = setup(); + await one.viewer.mount(one.host); + assert.equal(one.host.children.length, 1); + await two.viewer.mount(one.host); + assert.equal(one.host.children.length, 1, 'one root, not one per viewer'); + await assert.rejects(one.viewer.open('f'), /not mounted/, 'superseded'); + two.viewer.unmount(); +}); + +test('a viewer left by an earlier test is not superseded by a later test’s', async () => { + const earlier = setup(); + await earlier.viewer.mount(earlier.host); + // As before each test. + resetPhotoView(); + const later = setup(); + await later.viewer.mount(later.host); + await tick(); + const opening = earlier.viewer.open('f'); + await until(() => earlier.loads.includes('f-first')); + earlier.release('f-first'); + await opening; + earlier.viewer.unmount(); + later.viewer.unmount(); +}); + +/** A panorama viewer whose renderers and flat loads the test reads. */ +function trackedViewer(options = {}) { + const renderers = []; + const loads = []; + const viewer = createPhotoViewer({ + providerId: 'test', + name: 'Test', + sources: SOURCES, + getPhoto: async (id) => PHOTOS[id], + step: async () => null, + onStep() {}, + load: async (url) => { + loads.push(url); + return { src: url }; + }, + createRenderer: (canvas) => { + const renderer = { + canvas, + images: [], + setImage: (image) => renderer.images.push(image.src), + setView() {}, + getView: () => ({ yaw: 0, pitch: 0, fov: 80 }), + resize() {}, + clear() {}, + destroy() {}, + }; + renderers.push(renderer); + return renderer; + }, + ...options, + }); + return { viewer, renderers, loads }; +} + +/** Hand `parts` back to the viewer that presented `view`. */ +const attachAll = (view, parts) => { + for (const [name, element] of Object.entries(parts)) + view.actions.attach(name, element); +}; + +test('a mount overtaken by a second mount of the same viewer closes, and the second stays', async () => { + const { viewer } = trackedViewer(); + let latest = null; + const unsubscribe = viewer.subscribeView((view) => (latest = view)); + const first = viewer.mount({ id: 1 }); + const hostTwo = { id: 2 }; + const second = viewer.mount(hostTwo); + // The view draws on a later macrotask. + setTimeout(() => latest && attachAll(latest, elements()), 0); + await assert.rejects(first, /viewer was closed/); + await second; + assert.equal(latest?.host, hostTwo, 'the second mount is presented'); + viewer.unmount(); + unsubscribe(); +}); + +test('a mount whose view subscribes again in the same tick is drawn', async () => { + const { viewer } = trackedViewer(); + let latest = null; + const view = (next) => (latest = next); + let unsubscribe = viewer.subscribeView(view); + const mounting = viewer.mount({}); + // The view is replaced at once, and draws on a later macrotask. + unsubscribe(); + unsubscribe = viewer.subscribeView(view); + setTimeout(() => latest && attachAll(latest, elements()), 0); + await mounting; + assert.ok(latest, 'still presented'); + viewer.unmount(); + unsubscribe(); +}); + +test('a canvas handed back while a panorama’s open waits on its draw takes the panorama', async () => { + const { viewer, renderers, loads } = trackedViewer(); + const first = elements(); + const second = elements(); + let latest = null; + let hold = false; + const unsubscribe = viewer.subscribeView((view) => { + latest = view; + if (view && !hold) attachAll(view, first); + }); + await viewer.mount({}); + hold = true; + const opening = viewer.open('a'); + assert.ok(await until(() => latest?.kind === 'pano'), 'waiting on a draw'); + // The view draws it with a canvas of its own. + attachAll(latest, second); + await opening; + assert.equal(latest.kind, 'pano', 'not the front view'); + assert.deepEqual(loads, ['a-first'], 'no flat version loaded'); + assert.equal(renderers.at(-1).canvas, second.canvas); + assert.deepEqual(renderers.at(-1).images, ['a-first']); + viewer.unmount(); + unsubscribe(); +}); + +test('two views handing back canvases of their own do not take the panorama in turns', async () => { + let reopened = 0; + const { viewer, renderers } = trackedViewer({ + onReopen: (id) => { + reopened++; + if (reopened < 20) viewer.open(id).catch(() => {}); + }, + }); + const one = elements(); + const two = elements(); + const unsubscribes = [ + viewer.subscribeView((view) => view && attachAll(view, one)), + viewer.subscribeView((view) => view && attachAll(view, two)), + ]; + await viewer.mount({}); + await viewer.open('a'); + const built = renderers.length; + // Each presentation is drawn by both views. + for (const mode of ['fill', 'letterbox', 'fill']) { + viewer.setRenderMode(mode); + for (let i = 0; i < 5; i++) await tick(); + } + assert.equal(reopened, 0); + assert.equal(renderers.length, built, 'the panorama stays where it is'); + assert.deepEqual(renderers.at(-1).images, ['a-first']); + viewer.unmount(); + for (const unsubscribe of unsubscribes) unsubscribe(); +}); + +test('the panorama goes back to the one view left once a second view leaves', async () => { + const { viewer, renderers } = trackedViewer({ + onReopen: (id) => viewer.open(id).catch(() => {}), + }); + const one = elements(); + const two = elements(); + const unsubscribeOne = viewer.subscribeView( + (view) => view && attachAll(view, one), + ); + await viewer.mount({}); + await viewer.open('a'); + // A second view subscribes and draws its own canvas: the panorama moves. + const unsubscribeTwo = viewer.subscribeView( + (view) => view && attachAll(view, two), + ); + for (let i = 0; i < 5; i++) await tick(); + assert.equal(renderers.at(-1).canvas, two.canvas); + unsubscribeTwo(); + assert.ok( + await settles(viewer.open('b')), + 'the next open is not left waiting', + ); + for (let i = 0; i < 5; i++) await tick(); + assert.equal( + renderers.at(-1).canvas, + one.canvas, + 'the panorama is back on the view left', + ); + assert.equal(renderers.at(-1).images.at(-1), 'b-first'); + viewer.unmount(); + unsubscribeOne(); +}); + +test('a mount its view unmounts inside the first draw fails as closed', async () => { + const { viewer } = trackedViewer(); + const unsubscribe = viewer.subscribeView((view) => { + if (view) viewer.unmount(); + }); + await assert.rejects(viewer.mount({}), /Street-level viewer was closed/); + unsubscribe(); +}); diff --git a/src/layers/streetLevel/photoViewers.js b/src/layers/streetLevel/photoViewers.js index ecf4eab5a1..ed32dd5208 100644 --- a/src/layers/streetLevel/photoViewers.js +++ b/src/layers/streetLevel/photoViewers.js @@ -1,37 +1,93 @@ +/** The last key handed out by `nextViewKey()`. */ +let viewKeys = 0; + +/** + * A key no viewer or picker was ever given: photo viewers key their mounts + * and canvases with it, and a presentation without a mount key is stamped + * with one when first seen, so both rank on one scale. + */ +export function nextViewKey() { + return ++viewKeys; +} + +/** + * Each keyless viewer's current mount, `{actions, key}`: stamped once, by + * whichever picker sees it first, and kept until it presents null, so a + * picker made later ranks it the same. + */ +const keylessMounts = new WeakMap(); + /** * Receive the photo viewer to draw, out of several photo viewers mounting - * in one host (see photoViewer.js): the one mounted last, by its mount key, - * whatever order they present in. One view draws one viewer, so a viewer - * still mounting when a later one presents is superseded: it settles its - * mount as closed and stops presenting. Starts with the current one (null - * while none is mounted). + * in one host (see photoViewer.js): the one mounted last, whatever order + * they present in. One view draws one viewer, so a viewer still mounting + * when a later one presents is superseded: it settles its mount as closed + * and stops presenting. Starts with the current one (null while none is + * mounted). + * + * Two fields of a presentation are read here (see ViewerAdapter.subscribeView + * in registry.js): + * - `mountKey`, a number larger for each later mount (from `nextViewKey()`), + * orders the mounts. A presentation without one counts as mounted when + * any picker first saw it present: it is stamped with a `nextViewKey()` + * then, the same for every picker, however many are made later. + * - `actions.supersede()`, where present, is called on each presentation + * not drawn, whenever more than one presents. It runs on a microtask, + * after the presentation that won has reached every subscriber: a + * subscriber never sees the superseded one withdraw before it sees the + * one replacing it. * @param {Iterable<{subscribeView?: Function}>} viewers * @param {(view: ?object) => void} listener * @returns {() => void} Unsubscribe. */ export function subscribePhotoViewers(viewers, listener) { - // Each viewer's current presentation. + // Each viewer's current presentation and its rank, {view, key}. const shown = new Map(); let ready = false; + let closed = false; + let superseding = false; let last; + /** A mount's rank: its key, or the stamp of its first presentation. */ + const rank = (viewer, view) => { + if (Number.isFinite(view.mountKey)) return view.mountKey; + let mount = keylessMounts.get(viewer); + if (!mount || mount.actions !== view.actions) { + mount = { actions: view.actions, key: nextViewKey() }; + keylessMounts.set(viewer, mount); + } + return mount.key; + }; + // The others are not drawn: a mount still waiting on the view never + // would be. + const supersede = () => { + superseding = false; + if (closed || !last) return; + for (const { view } of [...shown.values()]) + if (view !== last) view.actions?.supersede?.(); + }; const publish = () => { let next = null; - for (const view of shown.values()) - if (!next || view.mountKey > next.mountKey) next = view; - if (!ready || next === last) return; - last = next; - listener(next); - // The others are not drawn: a mount still waiting on the view never - // would be. - if (next) - for (const view of [...shown.values()]) - if (view.mountKey < next.mountKey) view.actions.supersede(); + for (const entry of shown.values()) + if (!next || entry.key > next.key) next = entry; + next = next?.view ?? null; + if (!ready) return; + if (next !== last) { + last = next; + listener(next); + } + if (last && shown.size > 1 && !superseding) { + superseding = true; + queueMicrotask(supersede); + } }; const unsubscribes = []; for (const viewer of viewers) { const unsubscribe = viewer?.subscribeView?.((view) => { - if (view) shown.set(viewer, view); - else shown.delete(viewer); + if (closed) return; + if (!view) { + shown.delete(viewer); + keylessMounts.delete(viewer); + } else shown.set(viewer, { view, key: rank(viewer, view) }); publish(); }); if (typeof unsubscribe === 'function') unsubscribes.push(unsubscribe); @@ -40,6 +96,7 @@ export function subscribePhotoViewers(viewers, listener) { publish(); if (last === undefined) listener((last = null)); return () => { + closed = true; for (const unsubscribe of unsubscribes.splice(0)) unsubscribe(); }; } diff --git a/src/layers/streetLevel/photoViewers.test.mjs b/src/layers/streetLevel/photoViewers.test.mjs index a4525723bc..aa56b6b316 100644 --- a/src/layers/streetLevel/photoViewers.test.mjs +++ b/src/layers/streetLevel/photoViewers.test.mjs @@ -1,6 +1,7 @@ import assert from 'node:assert/strict'; import test from 'node:test'; -import { subscribePhotoViewers } from './photoViewers.js'; +import { createPhotoViewer } from './photoViewer.js'; +import { nextViewKey, subscribePhotoViewers } from './photoViewers.js'; /** * A photo viewer whose presentations the test sends; `superseded` counts. @@ -9,6 +10,7 @@ import { subscribePhotoViewers } from './photoViewers.js'; */ function fakeViewer() { const listeners = new Set(); + let current = null; const viewer = { superseded: 0, view(mountKey) { @@ -18,18 +20,19 @@ function fakeViewer() { }; }, present(view) { + current = view; for (const listener of [...listeners]) listener(view); }, subscribeView(listener) { listeners.add(listener); - listener(null); + listener(current); return () => listeners.delete(listener); }, }; return viewer; } -test('the later mount is drawn, whatever order the viewers present in', () => { +test('the later mount is drawn, whatever order the viewers present in', async () => { const a = fakeViewer(); const b = fakeViewer(); const shown = []; @@ -40,6 +43,8 @@ test('the later mount is drawn, whatever order the viewers present in', () => { const later = b.view(2); b.present(later); assert.equal(shown.at(-1), later); + // Once every subscriber has the later one. + await Promise.resolve(); assert.equal(a.superseded, 1, 'the earlier mount is told it is not drawn'); // The earlier viewer presents again: it does not take the view back. a.present({ ...first, kind: 'flat' }); @@ -53,3 +58,158 @@ test('the later mount is drawn, whatever order the viewers present in', () => { a.present(first); assert.equal(shown.length, 5, 'unsubscribed'); }); + +/** A viewer that, superseded, unmounts as photoViewer.js does: it presents null. */ +function unmountingViewer() { + const viewer = fakeViewer(); + const view = viewer.view; + viewer.view = (mountKey) => { + const presented = view(mountKey); + const supersede = presented.actions.supersede; + presented.actions.supersede = () => { + supersede(); + viewer.present(null); + }; + return presented; + }; + return viewer; +} + +test('every subscriber sees the earlier mount, then the later one, with no gap', async () => { + const a = unmountingViewer(); + const b = unmountingViewer(); + const first = []; + const second = []; + const unsubscribes = [ + subscribePhotoViewers([a, b], (view) => first.push(view)), + subscribePhotoViewers([a, b], (view) => second.push(view)), + ]; + const earlier = a.view(1); + a.present(earlier); + const later = b.view(2); + b.present(later); + await Promise.resolve(); + assert.equal(a.superseded, 1, 'superseded once, by both'); + assert.deepEqual(first, [null, earlier, later]); + assert.deepEqual(second, [null, earlier, later], 'never null between'); + for (const unsubscribe of unsubscribes) unsubscribe(); +}); + +test('a presentation without a mount key counts as mounted when it began presenting', async () => { + const a = fakeViewer(); + const b = fakeViewer(); + const c = fakeViewer(); + const shown = []; + const unsubscribe = subscribePhotoViewers([a, b, c], (view) => + shown.push(view), + ); + a.present(a.view(nextViewKey())); + const keyless = b.view(undefined); + b.present(keyless); + assert.equal(shown.at(-1), keyless, 'after the keyed one'); + // Of two without, the one that began presenting last. + const newer = c.view(undefined); + c.present(newer); + assert.equal(shown.at(-1), newer); + b.present({ ...keyless, kind: 'flat' }); + assert.equal(shown.at(-1), newer, 'presenting again is not a new mount'); + // A keyed mount made after them wins. + const latest = a.view(nextViewKey()); + a.present(latest); + assert.equal(shown.at(-1), latest); + await Promise.resolve(); + assert.ok(b.superseded > 0 && c.superseded > 0, 'the keyless ones are told'); + unsubscribe(); +}); + +test('a presentation that is not drawn is superseded even when the pick stays', async () => { + const a = fakeViewer(); + const b = fakeViewer(); + const shown = []; + const unsubscribe = subscribePhotoViewers([a, b], (view) => shown.push(view)); + const later = b.view(2); + b.present(later); + // An earlier mount presents once the later one is drawn. + a.present(a.view(1)); + assert.deepEqual(shown, [null, later]); + await Promise.resolve(); + assert.equal(a.superseded, 1); + unsubscribe(); +}); + +test('a photo viewer mounting while a keyless presentation shows is drawn, and the keyless one superseded', async () => { + let superseded = 0; + const keyless = { + subscribeView(listener) { + listener({ actions: { supersede: () => superseded++ } }); + return () => {}; + }, + }; + const viewer = createPhotoViewer({ + providerId: 'test', + name: 'Test', + sources: {}, + getPhoto: async () => null, + step: async () => null, + onStep() {}, + }); + const shown = []; + const element = { clientWidth: 400, clientHeight: 250 }; + const unsubscribe = subscribePhotoViewers([keyless, viewer], (view) => { + shown.push(view); + if (!view?.mountKey) return; + for (const name of ['root', 'picture', 'canvas', 'prev', 'next']) + view.actions.attach(name, element); + }); + const mounting = viewer.mount({}); + const outcome = await Promise.race([ + mounting.then(() => 'mounted'), + new Promise((resolve) => setTimeout(() => resolve('pending'), 50)), + ]); + assert.equal(outcome, 'mounted'); + assert.ok(Number.isFinite(shown.at(-1)?.mountKey), 'the mount is drawn'); + assert.ok(superseded >= 1, 'the keyless one is told'); + viewer.unmount(); + unsubscribe(); +}); + +test('a presentation without actions or supersede is drawn and passed over without throwing', async () => { + const a = fakeViewer(); + const b = fakeViewer(); + const shown = []; + const unsubscribe = subscribePhotoViewers([a, b], (view) => shown.push(view)); + a.present({ mountKey: 1 }); + const later = { mountKey: 2, actions: {} }; + assert.doesNotThrow(() => b.present(later)); + await Promise.resolve(); + assert.equal(shown.at(-1), later); + a.present({ mountKey: 3 }); + await Promise.resolve(); + assert.equal(shown.at(-1).mountKey, 3); + unsubscribe(); +}); + +test('a keyless viewer on screen keeps its place when the picker is made again', async () => { + const keyed = fakeViewer(); + const keyless = fakeViewer(); + keyed.present(keyed.view(nextViewKey())); + const shown = []; + let unsubscribe = subscribePhotoViewers([keyless, keyed], (view) => + shown.push(view), + ); + const mounted = keyless.view(undefined); + keyless.present(mounted); + assert.equal(shown.at(-1), mounted); + await Promise.resolve(); + unsubscribe(); + // A new picker, the keyless viewer first: it is still the later mount. + const again = []; + unsubscribe = subscribePhotoViewers([keyless, keyed], (view) => + again.push(view), + ); + assert.equal(again.at(-1), mounted); + await Promise.resolve(); + assert.equal(keyless.superseded, 0, 'never told it is not drawn'); + assert.ok(keyed.superseded > 0); + unsubscribe(); +}); diff --git a/src/layers/streetLevel/providers/kartaview/provider.test.mjs b/src/layers/streetLevel/providers/kartaview/provider.test.mjs index caf1cd3aef..bb8b167022 100644 --- a/src/layers/streetLevel/providers/kartaview/provider.test.mjs +++ b/src/layers/streetLevel/providers/kartaview/provider.test.mjs @@ -17,6 +17,7 @@ import { drawn, fakeHost, until, + resetPhotoView, } from '../../../../testSupport/kartaViewFakes.mjs'; import { bindStreetViewer, @@ -26,6 +27,9 @@ import { } from '../../../../testSupport/streetLevelFakes.mjs'; import { fakeDrawPort } from '../../../../testSupport/fakeDrawPort.mjs'; +// Each test draws its own viewers only. +test.beforeEach(resetPhotoView); + /** A photo record `metres` east of (42.3314, -83.0458), in sequence `seq` at `index`. */ function photoRecord(id, { metres = 0, seq = '14010', index = 0 } = {}) { const lon = -83.0458 + metres / 82_300; diff --git a/src/layers/streetLevel/providers/kartaview/viewer.test.mjs b/src/layers/streetLevel/providers/kartaview/viewer.test.mjs index 9c6218d52c..05dabd27a0 100644 --- a/src/layers/streetLevel/providers/kartaview/viewer.test.mjs +++ b/src/layers/streetLevel/providers/kartaview/viewer.test.mjs @@ -5,8 +5,12 @@ import { drawn, fakeHost, until, + resetPhotoView, } from '../../../../testSupport/kartaViewFakes.mjs'; +// Each test draws its own viewers only. +test.beforeEach(resetPhotoView); + const PHOTOS = { flat1: { id: 'flat1', diff --git a/src/layers/streetLevel/providers/panoramax/provider.test.mjs b/src/layers/streetLevel/providers/panoramax/provider.test.mjs index f26be6d023..99e3a92d77 100644 --- a/src/layers/streetLevel/providers/panoramax/provider.test.mjs +++ b/src/layers/streetLevel/providers/panoramax/provider.test.mjs @@ -18,6 +18,7 @@ import { drawn, fakeHost, until, + resetPhotoView, } from '../../../../testSupport/kartaViewFakes.mjs'; import { bindStreetViewer, @@ -31,6 +32,9 @@ import { stacItem, } from '../../../../testSupport/panoramaxFixtures.mjs'; +// Each test draws its own viewers only. +test.beforeEach(resetPhotoView); + const ORIGIN = { lon: 2.3495, lat: 48.8874 }; /** A point `metres` east of ORIGIN. */ const east = (metres) => ({ diff --git a/src/layers/streetLevel/providers/panoramax/viewer.test.mjs b/src/layers/streetLevel/providers/panoramax/viewer.test.mjs index 185e9eeb21..ddd97fcc20 100644 --- a/src/layers/streetLevel/providers/panoramax/viewer.test.mjs +++ b/src/layers/streetLevel/providers/panoramax/viewer.test.mjs @@ -2,9 +2,16 @@ import assert from 'node:assert/strict'; import test from 'node:test'; import { PANORAMAX_SOURCES, createPanoramaxViewer } from './viewer.js'; import { normalizeItem } from './policy.js'; -import { fakeHost, until } from '../../../../testSupport/kartaViewFakes.mjs'; +import { + fakeHost, + until, + resetPhotoView, +} from '../../../../testSupport/kartaViewFakes.mjs'; import { stacItem } from '../../../../testSupport/panoramaxFixtures.mjs'; +// Each test draws its own viewers only. +test.beforeEach(resetPhotoView); + const photo = (options) => normalizeItem(stacItem({ lon: 2.35, lat: 48.85, ...options })); diff --git a/src/layers/streetLevel/registry.js b/src/layers/streetLevel/registry.js index b74cfcdc99..b332b61355 100644 --- a/src/layers/streetLevel/registry.js +++ b/src/layers/streetLevel/registry.js @@ -65,7 +65,14 @@ export function filtersOf(provider) { * @property {(listener: (pose: StreetPose) => void) => () => void} onPose * @property {(listener: (view: ?object) => void) => () => void} [subscribeView] * An adapter that draws nothing itself presents its viewer here, for the - * layer's `subscribePhotoViewer()` (see photoViewer.js). + * layer's `subscribePhotoViewer()` (see photoViewer.js): its current + * presentation at once, then each new one, null while unmounted. One view + * draws one viewer (photoViewers.js picks it), reading two fields: + * `mountKey`, a number larger for each later mount (the later mount is + * drawn; a presentation without one counts as mounted when it began + * presenting), and `actions.supersede()`, called on a mount that is not + * drawn because a later one is (it should unmount, failing a mount still + * waiting to be drawn; an adapter without it is simply not drawn). * * @typedef {object} StreetPose * @property {string} providerId diff --git a/src/testSupport/kartaViewFakes.mjs b/src/testSupport/kartaViewFakes.mjs index 83ed5f38f5..5849e8f7d2 100644 --- a/src/testSupport/kartaViewFakes.mjs +++ b/src/testSupport/kartaViewFakes.mjs @@ -1,4 +1,5 @@ // DOM stand-ins for the KartaView viewer's tests (no browser in Node). +import { subscribePhotoViewers } from '../layers/streetLevel/photoViewers.js'; /** A DOM element with what the viewer touches: children, events, attributes. */ function fakeElement(tag) { @@ -71,7 +72,58 @@ export function fakeHost(viewer = null) { } /** - * Draw a photo viewer's presentations with fake elements, as + * The one view of the photo viewers given to `drawPhotoViewer`, as the + * application has one StreetLevelPhotoViewer: the viewers reach it through + * photoViewers.js's picker, as the layer's `subscribePhotoViewer()` does, + * so only the mount made last is drawn and the earlier ones are superseded. + */ +const shared = { + viewers: new Set(), + draw: null, + unsubscribe: null, + generation: 0, +}; + +/** Subscribe the view to the viewers it has now, then let the old picker go. */ +function resubscribe() { + const previous = shared.unsubscribe; + const generation = ++shared.generation; + // The new picker first: a viewer is never left without a view. + shared.unsubscribe = subscribePhotoViewers([...shared.viewers], (view) => { + if (generation === shared.generation) shared.draw(view); + }); + previous?.(); +} + +/** + * Start the shared view afresh, with no viewer: a test file calls it before + * each test, so a viewer left by an earlier test is not drawn with a later + * test's (nor superseded by it). A viewer it held is left without a view. + */ +export function resetPhotoView() { + shared.generation++; + shared.unsubscribe?.(); + shared.unsubscribe = null; + shared.viewers.clear(); + shared.draw = null; +} + +/** + * Draw a photo viewer with the shared view, alongside every other viewer + * given here since the last `resetPhotoView()` (see `shared`). + * @returns {() => void} Stop drawing it. + */ +export function drawPhotoViewer(viewer) { + shared.draw ??= photoView(); + shared.viewers.add(viewer); + resubscribe(); + return () => { + if (shared.viewers.delete(viewer)) resubscribe(); + }; +} + +/** + * A view drawing the presentations it is given with fake elements, as * StreetLevelPhotoViewer does through Vue: changes made in one tick are * drawn once, on a microtask, with their final value; the root (keyed by * the mount) holds the picture, the panorama canvas (keyed by its canvas @@ -79,9 +131,9 @@ export function fakeHost(viewer = null) { * is handed back on each draw. A value is written only when the drawn * presentation changes it, and the elements' events reach the viewer's * actions. - * @returns {() => void} Stop drawing. + * @returns {(view: ?object) => void} Draw this presentation. */ -export function drawPhotoViewer(viewer) { +function photoView() { let parts = null; let last = null; let pending = null; @@ -162,7 +214,7 @@ export function drawPhotoViewer(viewer) { for (const name of ['root', 'picture', 'canvas', 'prev', 'next']) view.actions.attach(name, parts[name]); }; - return viewer.subscribeView((view) => { + return (view) => { pending = view; if (queued) return; queued = true; @@ -170,7 +222,7 @@ export function drawPhotoViewer(viewer) { queued = false; draw(pending); }); - }); + }; } /** diff --git a/src/ui/kit/streetLevelPhotoControls.test.mjs b/src/ui/kit/streetLevelPhotoControls.test.mjs index be1d65a8b5..1c65279af4 100644 --- a/src/ui/kit/streetLevelPhotoControls.test.mjs +++ b/src/ui/kit/streetLevelPhotoControls.test.mjs @@ -74,10 +74,27 @@ test('the step buttons are not pressed toggles', () => { } }); +/** + * `loadImage`, which downloads through an Image of its own that is never on + * the page: the one place a `.src` is written. + */ +const LOADER = /^export function loadImage\([\s\S]*?^}$/m; +// An assignment, plain or compound (`=`, `+=`, `||=`, `??=`, `**=`…), not +// a comparison or an arrow. +const ASSIGN = String.raw`\s*(?:[-+*/%&|^]|\*\*|<<|>>>?|&&|\|\||\?\?)?=(?![=>])`; +const assigned = (target, flags = '') => + new RegExp(String.raw`${target}${ASSIGN}`, flags); +// A member or computed member: what a destructuring write must not target. +const MEMBER = /[\w$)\]]\s*(?:\.\s*[\w$]|\[)/; + test('the photo viewer is drawn by its view, and its layer needs no Vue', () => { const source = read(VIEWER); + const loader = source.match(LOADER)?.[0]; + assert.ok(loader, 'loadImage is found'); + const rest = source.replace(LOADER, ''); // No element made, inserted, moved, removed or written: the view does - // all of that. (An Image the loader downloads with is not on the page.) + // all of that. (The panorama renderer in panorama.js sizes its canvas's + // drawing buffer, as WebGL drawing does; nothing here does.) for (const write of [ /createElement/, /\b(?:inner|outer)HTML\b/, @@ -86,10 +103,59 @@ test('the photo viewer is drawn by its view, and its layer needs no Vue', () => /\.remove\(\)/, /\.(?:set|remove|toggle)Attribute(?:NS)?\(/, /\.(?:classList|className|dataset|style)\b/, - /\.(?:hidden|disabled|textContent|innerText|tabIndex|title|alt)\s*=[^=]/, + assigned( + String.raw`\.(?:hidden|disabled|textContent|innerText|tabIndex|title|alt)`, + ), + assigned(String.raw`\.(?:width|height|ariaLabel|id|value)`), + // Properties written in bulk or by reflection (an Error's own fields + // aside). + /\bObject\.assign\(\s*(?!new Error\()/, + /\bObject\.definePropert(?:y|ies)\(/, + /\bReflect\.(?:set|defineProperty)\(/, /from 'vue'|\.vue'/, ]) assert.doesNotMatch(source, write); + // No property written through brackets (`picture['src'] = …`, + // `el[name] ||= …`), outside array destructuring declarations. + assert.doesNotMatch( + source.replace(/\b(?:const|let|var)\s*\[/g, ''), + assigned(String.raw`[\w$)\]]\s*\[[^[\]]*\]`), + 'a bracket write', + ); + // No destructuring write to a property (`[el.src] = …`, + // `({ a: el.id } = …)`); declarations bind names only. + for (const pattern of [ + /(?])/g, + /(?])/g, + ]) + for (const [write, targets] of source.matchAll(pattern)) + assert.doesNotMatch(targets, MEMBER, write); + const SRC = assigned(String.raw`\.src`, 'g'); + assert.doesNotMatch(rest, SRC, 'a .src written on the page'); + // In loadImage, only on the off-page Image it creates: `image` is bound + // once, to that Image, and never rebound or shadowed. + assert.match(loader, /\bconst image = new Image\(\);/); + assert.equal( + loader.match(/\b(?:const|let|var|function|class)\s+image\b/g)?.length, + 1, + 'one binding of image', + ); + for (const rebinding of [ + assigned(String.raw`(?/, + /\((?:[^()]*[,{[\s(])?image\b[^()]*\)\s*=>/, + /\bfunction\b[^(]*\((?:[^)]*[,{[\s(])?image\b[^)]*\)/, + /\b(?:const|let|var)\s*[{[][^=]*\bimage\b/, + /\bcatch\s*\([^)]*\bimage\b/, + ]) + assert.doesNotMatch(loader, rebinding, 'image rebound or shadowed'); + const writes = loader.match(SRC)?.length ?? 0; + assert.equal( + loader.match(assigned(String.raw`(? new RegExp(String.raw`<${name}\b${ATTRS}\s${attribute}${ATTRS}>`); diff --git a/src/ui/stores/streetLevelPhoto.js b/src/ui/stores/streetLevelPhoto.js index dc0ebffacb..b9498452b3 100644 --- a/src/ui/stores/streetLevelPhoto.js +++ b/src/ui/stores/streetLevelPhoto.js @@ -10,9 +10,12 @@ export const useStreetLevelPhotoStore = defineStore( 'gev-street-level-photo', () => { /** - * `{host, providerId, label, alt, kind, src, fit, canvasKey, dragging, - * prevLabel, prevDisabled, nextLabel, nextDisabled, actions}`, or null - * while no photo viewer is mounted. + * `{host, mountKey, providerId, label, alt, kind, src, fit, canvasKey, + * dragging, prevLabel, prevDisabled, nextLabel, nextDisabled, actions}`, + * or null while no photo viewer is mounted. Of the viewers mounting in + * the host, only the one mounted last (the largest `mountKey`) is + * published; `actions.supersede()` tells the others they are not drawn + * (see `ViewerAdapter.subscribeView` in src/layers/streetLevel/registry.js). */ const photo = shallowRef(null);