Merge pull request #1871 from bilawalsidhu/samehkhamis/street-level-photo-followups

Street Level photo viewer: settle every open and mount, one viewer drawn, a stated contract
This commit is contained in:
Sameh Khamis authored and GitHub committed 2026-11-19 16:50:15 -08:00
commit 9d5e10ddb1
14 files changed
+924 -79

No files matched your search

@@ -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).
+3 -2
View File
@@ -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
+160 -43
View File
@@ -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 <img> 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;
+361 -1
View File
@@ -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();
});
+75 -18
View File
@@ -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();
};
}
+163 -3
View File
@@ -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();
});
@@ -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;
@@ -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',
@@ -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) => ({
@@ -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 }));
+8 -1
View File
@@ -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
+57 -5
View File
@@ -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);
});
});
};
}
/**
+68 -2
View File
@@ -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 [
/(?<!\b(?:const|let|var)\s*)\[((?:[^[\]=;]|\[[^[\]=;]*\])*)\]\s*=(?![=>])/g,
/(?<!\b(?:const|let|var)\s*)\{((?:[^{}=;]|\{[^{}=;]*\})*)\}\s*\)?\s*=(?![=>])/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`(?<!\b(?:const|let|var)\s+)(?<![\w$.])image`),
/(?<![\w$.])image\s*=>/,
/\((?:[^()]*[,{[\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`(?<![\w$.)\]])image\.src`, 'g'))?.length ??
0,
writes,
'a .src written on something other than the Image',
);
const markup = template(VIEW);
const opening = (name, attribute) =>
new RegExp(String.raw`<${name}\b${ATTRS}\s${attribute}${ATTRS}>`);
+6 -3
View File
@@ -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);