From b2c7144cce16a1bd9351443ab18ea7510003bbc8 Mon Sep 17 00:00:00 2001 From: Sameh Khamis Date: Mon, 16 Nov 2026 13:54:40 -0800 Subject: [PATCH] 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. --- docs/CURRENT-STATE.md | 5 ++- docs/DIRECTOR.md | 6 ++- src/data/bhoteKoshiEvent.js | 74 +++++++++++++++++++++++-------- src/data/bhoteKoshiEvent.test.mjs | 52 ++++++++++++++++++++++ src/scenes/director.test.mjs | 8 +++- src/scenes/playbackAdapter.js | 10 +++-- 6 files changed, 127 insertions(+), 28 deletions(-) diff --git a/docs/CURRENT-STATE.md b/docs/CURRENT-STATE.md index 35ed46791..12f0ba3d8 100644 --- a/docs/CURRENT-STATE.md +++ b/docs/CURRENT-STATE.md @@ -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 diff --git a/docs/DIRECTOR.md b/docs/DIRECTOR.md index cb9abf7da..01ada0127 100644 --- a/docs/DIRECTOR.md +++ b/docs/DIRECTOR.md @@ -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 diff --git a/src/data/bhoteKoshiEvent.js b/src/data/bhoteKoshiEvent.js index e0fa8ee04..bbd6abe1d 100644 --- a/src/data/bhoteKoshiEvent.js +++ b/src/data/bhoteKoshiEvent.js @@ -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 }); diff --git a/src/data/bhoteKoshiEvent.test.mjs b/src/data/bhoteKoshiEvent.test.mjs index 509147e15..a33984d0f 100644 --- a/src/data/bhoteKoshiEvent.test.mjs +++ b/src/data/bhoteKoshiEvent.test.mjs @@ -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(); diff --git a/src/scenes/director.test.mjs b/src/scenes/director.test.mjs index 8faee864d..b75858a4a 100644 --- a/src/scenes/director.test.mjs +++ b/src/scenes/director.test.mjs @@ -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(); } }); diff --git a/src/scenes/playbackAdapter.js b/src/scenes/playbackAdapter.js index a53052ff8..e22937f0f 100644 --- a/src/scenes/playbackAdapter.js +++ b/src/scenes/playbackAdapter.js @@ -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 }) {