From 20f6ceb74c08fde802af8fe5e5d5b5dc1ea6a21b Mon Sep 17 00:00:00 2001 From: Sameh Khamis Date: Mon, 16 Nov 2026 13:40:17 -0800 Subject: [PATCH] Scene document: accept the Stories fields only from version 7 stories, storyThumb and storyTags arrived with version 7, so they are gated by version like anchors and dataPacks. --- docs/CURRENT-STATE.md | 2 +- docs/SCENE-DOCUMENT.md | 9 ++++----- src/director/document.js | 4 +--- src/scenes/director.test.mjs | 29 ++++++++++++++++++++++++----- 4 files changed, 30 insertions(+), 14 deletions(-) diff --git a/docs/CURRENT-STATE.md b/docs/CURRENT-STATE.md index b14a451da..aa140e9c2 100644 --- a/docs/CURRENT-STATE.md +++ b/docs/CURRENT-STATE.md @@ -1639,7 +1639,7 @@ rules own presentation overrides and Nepal map fallback without changing saved shots or content. Scene-document validation and legacy migration now have separate owners. Invalid imports preserve the current project; unreadable saved projects are protected from fallback writes. Version 7 adds Scenes' optional Stories -metadata and reads prior project files, including version 6 drafts, with +metadata (accepted only in version 7 documents) and reads prior project files with zero pitch, low camera heights, scope and detection edits preserved. See [the document contract](SCENE-DOCUMENT.md); see [Director](DIRECTOR.md) for camera, pack, action and sharing support. diff --git a/docs/SCENE-DOCUMENT.md b/docs/SCENE-DOCUMENT.md index dd4ff9b18..061560319 100644 --- a/docs/SCENE-DOCUMENT.md +++ b/docs/SCENE-DOCUMENT.md @@ -1,8 +1,7 @@ # Scene document format Authoring exports a UTF-8 JSON project. Version 7 records Stories metadata. -Versions 1 through 6 and unversioned legacy files migrate on import, including -version 6 projects written by early Stories builds. Existing shots keep their +Versions 1 through 6 and unversioned legacy files migrate on import. Existing shots keep their camera behavior. Unknown versions or unsupported fields are rejected with a field path before the current project, selection or saved bytes change. @@ -34,9 +33,9 @@ Each scene requires a `shots` array; optional fields are `id`, `title`, `releaseLayerIds`, `appliedShotPacks` and version-4 `anchors`. A pack marker has `id`, optional numeric `version` and `shotBindings` (original shot title to saved shot ID). These markers retain the editor's existing pack-update and rename behavior. -Scenes may include `stories` (true when saved to Stories), `storyThumb` -(a JPEG or PNG data URL of at most 300,000 characters) and `storyTags` (up to -five supported topic keys). +From version 7, scenes may include `stories` (true when saved to Stories), +`storyThumb` (a JPEG or PNG data URL of at most 300,000 characters) and +`storyTags` (up to five supported topic keys). Shots accept `id`, `title`, `durationSec`, `holdSec`, `camera`, `visual`, `layers`, `sourcePackId`, `sourcePackVersion` and version-4 `move`. Scene IDs are unique within the project; diff --git a/src/director/document.js b/src/director/document.js index b871dd08b..1adda48e6 100644 --- a/src/director/document.js +++ b/src/director/document.js @@ -95,11 +95,9 @@ export function validateSceneDocument(project) { 'releaseLayerIds', 'appliedShotPacks', 'shots', - 'stories', - 'storyThumb', - 'storyTags', ...(version >= 4 ? ['anchors'] : []), ...(version >= 5 ? ['dataPacks'] : []), + ...(version >= 7 ? ['stories', 'storyThumb', 'storyTags'] : []), ]); uniqueId(scene, path, sceneIds); optional(scene, 'title', path, (v, p) => string(v, p, 4096)); diff --git a/src/scenes/director.test.mjs b/src/scenes/director.test.mjs index 5dd7400f3..e940a749d 100644 --- a/src/scenes/director.test.mjs +++ b/src/scenes/director.test.mjs @@ -20,7 +20,10 @@ import test from 'node:test'; import { LayerLifecycle } from '../data/lifecycle.js'; import { SceneDirector } from './director.js'; -import { stringifySceneDocument } from '../director/document.js'; +import { + stringifySceneDocument, + validateSceneDocument, +} from '../director/document.js'; import { SCENE_TRACKING_PARAM_KEYS } from './scenePolicy.js'; import { SCENE_APPEND_RECIPES, @@ -2383,7 +2386,7 @@ test('projects saved before the Stories flag still load, and a malformed flag is const { director, restore } = makeDirector(); try { assert.equal(Object.hasOwn(director._project.scenes[0], 'stories'), false); - const project = structuredClone(PROJECT_FIXTURE); + const project = { ...structuredClone(PROJECT_FIXTURE), version: 7 }; project.scenes[0].stories = 'yes'; const before = director._project; await director.importProjectFile({ @@ -2690,8 +2693,7 @@ test('story thumbnail and tags survive a reload and an export/import round trip' try { first.director.setSceneStoryThumb('scene-1', THUMB); first.director.setSceneStoryTags('scene-1', ['Storms']); - // Draft builds wrote the same optional Stories fields in version 6. - saved = JSON.stringify({ ...savedProject(), version: 6 }); + saved = JSON.stringify(savedProject()); } finally { first.restore(); } @@ -2721,6 +2723,23 @@ test('story thumbnail and tags survive a reload and an export/import round trip' } }); +test('Stories fields are refused before document version 7, like other new fields', () => { + for (const [field, value] of [ + ['stories', true], + ['storyThumb', THUMB], + ['storyTags', ['Storms']], + ]) { + const project = { ...structuredClone(PROJECT_FIXTURE), version: 6 }; + project.scenes[0][field] = value; + assert.throws( + () => validateSceneDocument(project), + new RegExp(`scenes\\[0\\]\\.${field}`), + field, + ); + validateSceneDocument({ ...project, version: 7 }); + } +}); + test('imports with a malformed thumbnail or tags are refused', async () => { const { director, restore } = makeDirector(); try { @@ -2744,7 +2763,7 @@ test('imports with a malformed thumbnail or tags are refused', async () => { ['storyTags', ['Volcanoes'], /storyTags/], ['storyTags', STORY_TAGS.slice(0, 6), /storyTags/], ]) { - const project = structuredClone(PROJECT_FIXTURE); + const project = { ...structuredClone(PROJECT_FIXTURE), version: 7 }; project.scenes[0][field] = value; await director.importProjectFile({ name: 'bad.json',