Scenes: a run resumed inside a hold plays its layers on from that moment

After placing the layers at the seek's moment, the hold settles them
without the seek, so the reveal continues from where the seek put it and
a clip the moment falls in starts again from its beginning (a clip
cannot be joined partway); one the moment is past stays finished.
This commit is contained in:
Sameh Khamis committed 2026-11-16 13:54:40 -08:00
1 parent 87b6a4d0c8
commit b2c7144cce
6 files changed
+127 -28

No files matched your search

+3 -2
View File
@@ -729,8 +729,9 @@ cancels in-flight Authoring work before it captures the view it will
restore. Dragging the timeline previews the time, and releasing
it seeks the globe once. Play after a pause, a seek or a paused link goes on
from that exact moment (`SceneDirector.startScene` with `fromProgress`), even
inside a shot or its final quarter-second: the camera, the hold and the scene
clock carry on from there. A scene that has actually ended replays from the
inside a shot or its final quarter-second: the camera, the hold, the scene
clock and the layers' reveals carry on from there (a clip that moment falls in
starts again from its beginning, and the hold waits for it). A scene that has actually ended replays from the
beginning.
Opening Stories claims the camera through the shared navigation policy, so
+4 -2
View File
@@ -39,8 +39,10 @@ point of the scene's clock: the queue begins with the shot that point falls in,
carrying that point's seek state as `resume`. Inside the shot's flight the camera
goes on from there along the rest of the path a seek samples, over the rest of the
flight; inside its hold, the layers take that moment's state as a seek gives them
(a clip playing at that moment is not started again) and only the rest of the
hold is waited out. The scene clock carries on from the same point. `SceneDirector` still owns editor state, saved-project import/export,
and then play on from it: a reveal goes on from where the seek put it, and a
clip the moment falls in starts again from its beginning (a clip cannot be
joined partway), while one the moment is past stays finished. Only the rest of
the hold is waited out. The scene clock carries on from the same point. `SceneDirector` still owns editor state, saved-project import/export,
camera ownership and asynchronous load/seek arbitration. Pure seek calculations
live in `src/director/timeline.js`; `src/director/clock.js` owns the run/load/shot
tickers, hold deadlines, snapshots and clock subscriptions. Stop settles pending
+55 -19
View File
@@ -1088,6 +1088,8 @@ export function createBhoteKoshiEventLayer({
let _sceneRevealAnimationFrame = null;
let _sceneRevealHoldActive = false;
let _sceneRevealProgress = 1;
// How far a timeline seek's settled-camera reveal had come (0..1, linear).
let _sceneSeekRevealLinear = 1;
let _cinematicKeyframes = [];
let _cinematicActive = false;
let _cinematicReplayArmed = false;
@@ -1411,6 +1413,16 @@ export function createBhoteKoshiEventLayer({
: null;
}
/** Whether a seek's moment in the hold comes after the shot's clip. */
function sceneSeekPassedMedia(seek) {
if (_sceneControls.evidenceMediaAutoplay !== true) return false;
const mediaDurationSec = Math.max(
SCENE_MEDIA_MIN_PLAYBACK_SECONDS,
Number(_sceneControls.mediaPlaybackHoldSec) || 0,
);
return Math.max(0, Number(seek?.holdElapsedSec) || 0) >= mediaDurationSec;
}
function sceneTimelineMediaVisible() {
const seek = sceneTimelineSeek();
if (!seek || _sceneControls.evidenceMediaAutoplay !== true) return true;
@@ -1821,6 +1833,7 @@ export function createBhoteKoshiEventLayer({
function applySceneTimelineSeek() {
const seek = sceneTimelineSeek();
if (!seek) return false;
_sceneSeekRevealLinear = 1;
stopScenePathReveal();
stopSceneEvidenceReveal();
stopSceneMediaPlayback();
@@ -1905,6 +1918,7 @@ export function createBhoteKoshiEventLayer({
: mediaDurationSec + exitDurationSec,
);
const linear = clampUnit((holdElapsedSec - pathStartSec) / pathDurationSec);
_sceneSeekRevealLinear = linear;
_sceneRevealProgress = smoothstep(0, 1, linear);
_scenePathRevealProgress =
startProgress + (targetProgress - startProgress) * _sceneRevealProgress;
@@ -2025,7 +2039,11 @@ export function createBhoteKoshiEventLayer({
_scenePathAnimationFrame = requestAnimationFrame(step);
}
function startSceneEvidenceReveal() {
/**
* Start the settled-camera reveal, from `fromLinear` of its way when a run
* goes on from a timeline seek that had already brought it that far.
*/
function startSceneEvidenceReveal(fromLinear = 0) {
stopSceneEvidenceReveal();
const sequenceAnimates = sceneEvidenceSequenceAnimates();
if (
@@ -2069,7 +2087,25 @@ export function createBhoteKoshiEventLayer({
);
if (sequenceWindow) updateProgress(sequenceWindow.startProgress);
let lastTickAt = performance.now();
let activeElapsedMs = 0;
let activeElapsedMs = clampUnit(fromLinear) * durationMs;
const applyReveal = (linear) => {
_sceneRevealProgress = smoothstep(0, 1, linear);
if (sequenceWindow) {
updateProgress(
sequenceWindow.startProgress +
(sequenceWindow.targetProgress - sequenceWindow.startProgress) *
_sceneRevealProgress,
);
} else if (!scenePathMovesDuringCamera()) {
const floodProgress = sourceWindow
? sourceWindow.start +
(sourceWindow.target - sourceWindow.start) * _sceneRevealProgress
: targetFloodProgress * _sceneRevealProgress;
updateFloodTrace(floodProgress);
updateSurgeFront(floodProgress);
}
};
if (activeElapsedMs > 0) applyReveal(activeElapsedMs / durationMs);
renderHost.hold(SCENE_REVEAL_RENDER_HOLD);
_sceneRevealHoldActive = true;
const step = (now) => {
@@ -2086,21 +2122,7 @@ export function createBhoteKoshiEventLayer({
activeElapsedMs += tickAt - lastTickAt;
lastTickAt = tickAt;
const linear = clampUnit(activeElapsedMs / durationMs);
_sceneRevealProgress = smoothstep(0, 1, linear);
if (sequenceWindow) {
updateProgress(
sequenceWindow.startProgress +
(sequenceWindow.targetProgress - sequenceWindow.startProgress) *
_sceneRevealProgress,
);
} else if (!scenePathMovesDuringCamera()) {
const floodProgress = sourceWindow
? sourceWindow.start +
(sourceWindow.target - sourceWindow.start) * _sceneRevealProgress
: targetFloodProgress * _sceneRevealProgress;
updateFloodTrace(floodProgress);
updateSurgeFront(floodProgress);
}
applyReveal(linear);
renderHost.request('bhote-koshi-scene-beat-reveal');
if (linear < 1) {
_sceneRevealAnimationFrame = requestAnimationFrame(step);
@@ -3786,6 +3808,7 @@ export function createBhoteKoshiEventLayer({
_sceneControls.cameraTravel?.completed === true;
const previousTravelCancelled =
_sceneControls.cameraTravel?.cancelled === true;
const previousSeek = sceneTimelineSeek();
if (params.presentation === BHOTE_KOSHI_SCENE_PRESENTATION) {
_presentation = BHOTE_KOSHI_SCENE_PRESENTATION;
_sceneSurface =
@@ -3840,6 +3863,19 @@ export function createBhoteKoshiEventLayer({
stopSceneMediaPlayback();
_sceneMediaPlaybackCompletedBeatId = null;
}
// A run going on from a seek inside the settled hold plays on from that
// moment: the reveal continues from where the seek put it, and the clip
// starts again unless the seek was already past it.
const resumesSeek =
previousSeek != null &&
!sceneTimelineSeek() &&
!beatChanged &&
cameraIsSettled &&
cameraWasSettled &&
previouslyDeferred &&
nowDeferred;
if (resumesSeek && sceneSeekPassedMedia(previousSeek))
_sceneMediaPlaybackCompletedBeatId = _sceneBeatId;
if (!nowDeferred) {
stopSceneEvidenceReveal();
_sceneRevealProgress = 1;
@@ -3906,9 +3942,9 @@ export function createBhoteKoshiEventLayer({
!timelineSeekActive &&
cameraIsSettled &&
(nowDeferred || sceneEvidenceSequenceAnimates()) &&
(beatChanged || !previouslyDeferred || !cameraWasSettled)
(beatChanged || !previouslyDeferred || !cameraWasSettled || resumesSeek)
) {
startSceneEvidenceReveal();
startSceneEvidenceReveal(resumesSeek ? _sceneSeekRevealLinear : 0);
}
if (!sceneDirected && params.cinematic === true)
startCinematic({ play: params.autoPlay !== false });
+52
View File
@@ -415,6 +415,58 @@ test('trimmed scene media holds through provider startup, playback and fade, the
}
});
test('scene media plays again when a run goes on from a seek inside its hold, unless the seek was past the clip', async () => {
const previous = { document: globalThis.document, window: globalThis.window,
requestAnimationFrame: globalThis.requestAnimationFrame,
cancelAnimationFrame: globalThis.cancelAnimationFrame };
installEventDom();
globalThis.window = { setTimeout: () => 1, clearTimeout() {} };
// The reveal's frames are not driven here; only that it starts.
let frames = 0;
globalThis.requestAnimationFrame = () => ++frames;
globalThis.cancelAnimationFrame = () => {};
const event = JSON.parse(await readFile(eventUrl, 'utf8'));
let plays = 0;
const layer = createBhoteKoshiEventLayer({
eventLoader: async () => event,
imagerySpecFactory: async (url) => ({ url }),
terrainSampler: async (_viewer, observations) => observations.map(() => ({ height: 800 })),
mediaLoader: async () => { throw Object.assign(new Error('No bundled clip'), { name: 'AbortError' }); },
overlayHost: { setEntries() {}, setVisible() {}, clearSource() {} },
renderHost: { request() {}, hold() {}, release() {} },
embeddedMediaFactory: () => ({ warm: () => true, show: () => true, play() { plays++; }, pause() {},
getPlaybackState: () => ({ phase: 'playing' }), hide() {}, destroy() {} }),
});
const controls = { evidenceMediaAutoplay: true, mediaPlaybackHoldSec: 4, cameraSettled: true,
deferEvidenceUntilCameraSettled: true };
const params = (sceneControls) => ({ presentation: 'scene-beat', sceneSurface: 'evidence-beat',
beatId: 'mailung-bazzar', sceneContext: { sceneId: 'scene', shotId: 'shot', holdSec: 7.65 }, sceneControls });
const seek = (holdElapsedSec) => ({ ...controls,
timelineSeek: { cameraProgress: 1, holdElapsedSec, holdDurationSec: 7.65, flightDurationSec: 2 } });
try {
const viewer = eventViewer();
await layer.init(viewer);
layer.setSceneMediaPlayback({ sceneId: 'scene', shotId: 'shot', token: { cancelled: false } });
// A seek 1 s into the hold shows that moment and plays nothing.
layer.setParams(params(seek(1)), { origin: 'scene' });
await layer.enable(viewer, { origin: 'scene' });
assert.equal(plays, 0);
assert.equal(layer.getSceneShotMediaHold('mailung-bazzar'), null);
// The run goes on from there: the clip starts again and holds the shot.
const framesBefore = frames;
layer.setParams(params(controls), { origin: 'scene' });
assert.ok(frames > framesBefore, 'the reveal runs again');
assert.ok(plays > 0, 'the clip plays');
assert.equal(layer.getSceneShotMediaHold('mailung-bazzar').pending, true);
// A seek after the clip goes on without it.
layer.setParams(params(seek(6)), { origin: 'scene' });
const before = plays;
layer.setParams(params(controls), { origin: 'scene' });
assert.equal(plays, before, 'the clip already played');
assert.equal(layer.getSceneShotMediaHold('mailung-bazzar').pending, false);
} finally { await layer.destroy(); Object.assign(globalThis, previous); }
});
test('Pinokio source-card fallback selects authored Director dwell, not an impossible player hold', async () => {
const previous = { document: globalThis.document, window: globalThis.window };
installEventDom();
+7 -1
View File
@@ -2152,7 +2152,7 @@ test('a run resumed inside a flight goes on from that point of the path and cloc
} finally { await director.destroy(); restoreFrames(); restore(); }
});
test('a run resumed inside a hold keeps the seek’s layer state and waits only the rest of it', async () => {
test('a run resumed inside a hold plays its layers on from the seek’s state and waits only the rest of it', async () => {
const project = structuredClone(PROJECT_FIXTURE);
project.scenes[0].shots[0].holdSec = 0.6;
const { director, viewer, restore } = makeDirector({ project });
@@ -2196,6 +2196,12 @@ test('a run resumed inside a hold keeps the seek’s layer state and waits only
assert.equal(seekStates.length, 1, 'shot A’s layers are given the moment');
assert.equal(seekStates[0].shot.id, 'shot-a');
assert.ok(Math.abs(seekStates[0].options.sceneSeek.holdElapsedSec - 0.4) < 1e-9);
// Then they play on from that moment: shot A settles without the seek.
const after = layerCalls.slice(layerCalls.indexOf(seekStates[0]) + 1);
const played = after.find(({ shot }) => shot.id === 'shot-a');
assert.ok(played, 'shot A’s layers go back to running playback');
assert.equal(played.options.cameraSettled, true);
assert.equal(played.options.sceneSeek, undefined);
} finally { await director.destroy(); restore(); }
});
+6 -4
View File
@@ -5,7 +5,8 @@ import { displaySceneTitle, displayShotTitle } from './recipes.js';
/**
* A run resumed partway into its first shot carries the seek state of that
* moment (`resume`). Inside the shot's hold, its layers take that moment's
* state as a seek gives it, and only the rest of the hold is waited out; inside
* state as a seek gives it and then play on from it, and only the rest of the
* hold is waited out; inside
* its flight, the camera goes on from where it is along the rest of the path.
*/
const inHold = (resume) => resume?.holdElapsedSec > 0;
@@ -101,9 +102,10 @@ export function createScenePlaybackAdapter(
director._publishShotTravel(scene, shot, travel);
return flight;
},
settle({ scene, shot, token, resume }) {
// Resumed inside the hold, the layers already hold that moment's state.
if (inHold(resume)) return;
settle({ scene, shot, token }) {
// Resumed inside the hold too: the layers placed at that moment go back
// to running playback from it. Their reveals go on, and scene media
// starts its clip again, since a clip cannot be joined partway.
director._settleShotLayerStates(scene, shot, token, travel);
},
hold({ scene, shot, token, resume }) {