Street Level photo viewer: settle opens, a gapless picker, a stated contract

Follow-ups to the photo viewer's move to a Vue view (#1868):

- A panorama's open waits for a draw of the canvas counted from before it
  is shown, so a view that draws at once inside its listener no longer
  leaves the open pending; and when the last view unsubscribes, an open
  waiting on a draw goes on instead of hanging.
- photoViewers.js supersedes the mounts not drawn on a microtask, after
  the winning presentation has reached every subscriber: a second
  subscriber sees the earlier mount, then the later one, never null
  between.
- A presentation without a mountKey counts as the latest mount (among
  several without, the one that began presenting last), and one without
  actions or supersede is passed over without throwing. Both fields are
  documented on ViewerAdapter.subscribeView in registry.js and in the
  store's comment.
- The guard test also refuses .width, .height, .ariaLabel, .id and .value
  writes in photoViewer.js, and .src writes outside loadImage, where only
  the off-page Image it creates may take one.
- The test fakes draw every viewer through one shared view behind
  photoViewers.js's picker, as the application does, so provider and
  layer tests see supersede.

Nothing changes in the running app.

Co-authored-by: Manjunath Paparaju <[email protected]>
This commit is contained in:
Sameh KhamisandManjunath Paparaju committed 2026-11-19 15:48:50 -08:00
1 parent 12dc0de20d
commit 33ac0545ef
9 files changed
+337 -49

No files matched your search

+40 -21
View File
@@ -228,13 +228,15 @@ 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; an open waiting
* on a draw when the last view leaves goes on without it.
*
* Photos are normalized by the provider: `{id, sequenceId, lon, lat,
* heading, isPano, capturedAt}` plus whatever its `sources` read.
@@ -284,6 +286,8 @@ 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;
let renderer = null;
/** WebGL failed once: 360° photos show their front view instead. */
let rendererFailed = false;
@@ -396,22 +400,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() {
@@ -667,7 +677,10 @@ export function createPhotoViewer({
if (presented?.actions !== actions || !element) return;
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),
@@ -865,9 +878,11 @@ 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;
show('pano');
await nextDraw(signal);
await drawnAfter(draws, signal);
if (seq !== openSeq || !renderer) {
image.close?.();
if (seq !== openSeq) return false;
@@ -1029,7 +1044,11 @@ export function createPhotoViewer({
subscribeView(listener) {
viewListeners.add(listener);
listener(presented);
return () => viewListeners.delete(listener);
return () => {
// The last view went: an open waiting on its draw goes on without.
if (viewListeners.delete(listener) && !viewListeners.size)
wake(canvasWaiters);
};
},
};
return adapter;
@@ -636,3 +636,94 @@ 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('an open waiting on the view’s draw goes on when the view unsubscribes', async () => {
const { viewer } = panoramaViewer();
const parts = elements();
const kinds = [];
// Draws the mount, then nothing more.
const unsubscribe = viewer.subscribeView((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');
viewer.unmount();
});
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();
});
+49 -15
View File
@@ -1,37 +1,70 @@
/**
* 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, orders the mounts. A
* presentation without one counts as the latest mount; among several
* without, the one that began presenting last is.
* - `actions.supersede()`, where present, is called on each presentation
* not drawn once the pick changes. 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 when it began presenting.
const shown = new Map();
let arrivals = 0;
let ready = false;
let closed = false;
let superseding = false;
let last;
/** Whether `a` was mounted after `b`. */
const later = (a, b) => {
const key = ({ view }) =>
Number.isFinite(view.mountKey) ? view.mountKey : Infinity;
const ka = key(a);
const kb = key(b);
return ka !== kb ? ka > kb : a.arrival > b.arrival;
};
// 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;
for (const entry of shown.values())
if (!next || later(entry, next)) next = entry;
next = next?.view ?? null;
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();
if (next && 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;
const entry = shown.get(viewer);
if (!view) shown.delete(viewer);
else if (entry && entry.view.mountKey === view.mountKey)
entry.view = view;
else shown.set(viewer, { view, arrival: ++arrivals });
publish();
});
if (typeof unsubscribe === 'function') unsubscribes.push(unsubscribe);
@@ -40,6 +73,7 @@ export function subscribePhotoViewers(viewers, listener) {
publish();
if (last === undefined) listener((last = null));
return () => {
closed = true;
for (const unsubscribe of unsubscribes.splice(0)) unsubscribe();
};
}
+79 -1
View File
@@ -29,7 +29,7 @@ function fakeViewer() {
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 +40,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 +55,79 @@ 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 the latest mount', () => {
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(5));
const keyless = { actions: {} };
b.present(keyless);
assert.equal(shown.at(-1), keyless, 'after the keyed one');
// A keyed mount presenting later does not take it back.
a.present(a.view(6));
assert.equal(shown.at(-1), keyless);
// Of two without, the one that began presenting last.
const newer = { actions: {} };
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');
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();
});
+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 the latest), 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