The VS Code of video editing, built for agents.
TypeScript
Enhance timeline functionality and state management
konstantin-paulus4c53ded4ca01
diff --git a/apps/web/src/engine/history.ts b/apps/web/src/engine/history.tsindex a3cd8791..72790c50 100644--- a/apps/web/src/engine/history.ts+++ b/apps/web/src/engine/history.ts@@ -39,7 +39,7 @@ import type { CapturedNode, DocumentEditor, EntityEdit } from './editor';* entering the history. `error` is the runtime speaking (see source-errors),* not the user.*/-const EXCLUDED_PROPS: ReadonlySet<string> = new Set(['selected', 'active', 'camera', 'expanded', 'clipHeight', 'error']);+const EXCLUDED_PROPS: ReadonlySet<string> = new Set(['selected', 'active', 'camera', 'expanded', 'clipHeight', 'timeline', 'error']);/*** How long after one step a same-shaped step still merges into it. Editsdiff --git a/apps/web/src/engine/timeline/controller.ts b/apps/web/src/engine/timeline/controller.tsindex c6e855e6..03c52391 100644--- a/apps/web/src/engine/timeline/controller.ts+++ b/apps/web/src/engine/timeline/controller.ts@@ -9,7 +9,10 @@* controller itself never paints.*/+import { getTimelineView } from '@diffusionstudio/runtime';+import { assert, clamp } from '@/utils';+import { getDocumentEditor } from '@/engine/editor';import { createPointer } from './pointer';import { TimelineSurface } from './surface';import { timelineSystem } from './timeline';@@ -59,6 +62,16 @@ export function createTimelineController(world: World) {if (scene !== null) action(scene);};+ /**+ * A gesture moved the view: report it so the file remembers where the+ * scene's timeline is looking (`<scene timeline>`), the way the camera+ * controller reports a pan. No `previous`, so it never enters the history.+ */+ const reportView = (scene: Entity): void => {+ const view = getTimelineView(world, scene);+ if (view) getDocumentEditor(world).reportEdit(scene, 'timeline', view);+ };+const applyResize = (): void => {const { canvas } = surface;const parent = canvas?.parentElement;@@ -152,6 +165,7 @@ export function createTimelineController(world: World) {}updateTimelineTransform(world, scene);+ reportView(scene);});};@@ -170,6 +184,7 @@ export function createTimelineController(world: World) {applyScroll();updateTimelineTransform(world, scene);+ reportView(scene);});};@@ -179,6 +194,7 @@ export function createTimelineController(world: World) {setScrollY(world, scene, getScrollY(world, scene) + deltaY);applyScroll();updateTimelineTransform(world, scene);+ reportView(scene);});};diff --git a/apps/web/src/engine/timeline/timeline.ts b/apps/web/src/engine/timeline/timeline.tsindex 51b87dfc..a87603e4 100644--- a/apps/web/src/engine/timeline/timeline.ts+++ b/apps/web/src/engine/timeline/timeline.ts@@ -14,7 +14,7 @@ import { RULER_HEIGHT } from './config';import { renderLayers, renderMarquee, renderPlayhead, renderRuler, renderSnapLine, renderWorkarea, updateMarquee } from './render';import { updateDragGestures } from './drag';import { TimelineSurface } from './surface';-import { ensureTimelineView, getTimelineScene } from './view';+import { getTimelineScene, updateTimelineTransform } from './view';import type { World } from 'koota';import type { TimelinePointer } from './pointer';@@ -33,7 +33,11 @@ export function timelineSystem(world: World): void {return;}- ensureTimelineView(world, scene);+ // Re-derived every pass rather than only on gestures: the view store can+ // move under the draw loop's feet — the reconciler restoring a+ // `<scene timeline>` from the file, or a scene shown again after the+ // canvas was resized while another was up.+ updateTimelineTransform(world, scene);try {ctx.setTransform(1, 0, 0, 1, 0, 0);diff --git a/apps/web/src/engine/timeline/view.ts b/apps/web/src/engine/timeline/view.tsindex 89cf6740..30ea4c49 100644--- a/apps/web/src/engine/timeline/view.ts+++ b/apps/web/src/engine/timeline/view.ts@@ -7,7 +7,9 @@* a frame is worth. The state lives on the scene being shown (the runtime's* `Timeline` trait) so every scene keeps its own place, and it is written* through the store rather than `entity.set`: a scroll is not an edit of the- * project, so nothing should observe it and nothing reaches the file.+ * project, so nothing should observe it. It does reach the file — as+ * `<scene timeline>`, which the controller reports itself the way the camera+ * controller reports a pan (see `./controller`).*/import { Computed, FrameRate, Timeline, getActiveEntity, store } from '@diffusionstudio/runtime';@@ -101,8 +103,8 @@ export function getViewport(world: World, scene: Entity, width: number): [left:/*** Re-derives the matrix the rows are drawn under: device pixels, scrolled,- * and below the ruler. Called whenever the scroll, the zoom or the canvas- * itself has moved.+ * and below the ruler. Called by every draw pass, and by the gestures that+ * move the view, so whatever wrote the store last is what is drawn.*/export function updateTimelineTransform(world: World, scene: Entity): void {ensureTimelineView(world, scene);diff --git a/packages/jsx/src/types.ts b/packages/jsx/src/types.tsindex 43f1fa60..a62187e2 100644--- a/packages/jsx/src/types.ts+++ b/packages/jsx/src/types.ts@@ -416,6 +416,13 @@ export type SourceProps = {*/export type CameraMatrix = [a: number, b: number, c: number, d: number, e: number, f: number];+/**+ * A scene's timeline viewport: `zoom` in pixels per second of timeline, `x`+ * the horizontal scroll in seconds, `y` the vertical scroll in pixels. See+ * `SceneProps["timeline"]`.+ */+export type TimelineView = [zoom: number, x: number, y: number];+/*** The infinite canvas every project renders into; only allowed as the root* element, and holding `<scene>` children.@@ -465,6 +472,16 @@ export type SceneProps = IdentityProps & PositionProps & Required<Pick<SizeProps* empty timeline, with no playhead and no scene to export.*/active?: boolean;+ /**+ * Where this scene's timeline is looking when the project is opened, as+ * `[zoom, x, y]`: zoomed to `zoom` pixels per second, scrolled `x` seconds+ * in, the rows scrolled down `y` pixels. Editor state carried by the source+ * the way `<stage>`'s `camera` is — nothing rendered or exported depends on+ * it, and the first scroll or zoom of the timeline overwrites it. Absent+ * means the default zoom, at the beginning, which is the right opening for+ * an authored project: there is no need to write one.+ */+ timeline?: TimelineView;/*** Decibels on the scene's own bus, which everything in it mixes into: the* master fader. 0 = unity, negative attenuates (-6 = half as loud),diff --git a/packages/reconciler/src/document.ts b/packages/reconciler/src/document.tsindex 8bdd4b3b..859353b1 100644--- a/packages/reconciler/src/document.ts+++ b/packages/reconciler/src/document.ts@@ -3,13 +3,13 @@* file, You can obtain one at http://mozilla.org/MPL/2.0/. */-import { Active, AdjustmentLayer, Animation, AnimationPhase, AnimationType, appendChild, AssetId, Audio, Background, bindAsset, BlendMode, BlendModeType, Blur, Caption, CaptionAlign, CAPTION_PRESET_FILLS, CAPTION_PRESET_STYLES, CaptionType, Chars, ClipHeight, ClipsContent, Computed, CornerRadius, createEntity, DEFAULT_BACKGROUND, Color, ColorStop, Delay, Effect, EffectType, Expanded, FontStyle, FramePromises, FrameRate, Generating, GenerationRequest, getActiveEntity, Loop, LoadRequest, Geometry, GeometryType, getEntityTree, getParentEntity, getParentNode, Hidden, Host, IsMask, isText, ItemIndex, KeepAspectRatio, Keyframe, KeyframeTrack, MixedCornerRadius, Muted, Name, Offset, Opacity, Paint, PaintType, parseColor, PendingSource, PendingSync, Playback, PlaybackRate, Position, removeChild, RenderSurface, resizeEntity, Scale, ScaleMode, ScaleModeType, secondsToFrames, getAsset, getEntityChildren, Group, Sequential, Shader, Size, Stage, Root, Rotation, Scene, Selected, Shadow, Source, SourceError, SourceFrameRate, SourceModifiers, hasModifier, setCameraMatrix, Stroke, StrokeCap, StrokeJoin, StrokeStyle, SyncRequest, TextAlign, TextBaseline, TextCase, TextRange, TextStyle, TranscriptionRequest, Transition, TransitionType, Trim, UniformScale, Volume, Workarea } from '@diffusionstudio/runtime';+import { Active, AdjustmentLayer, Animation, AnimationPhase, AnimationType, appendChild, AssetId, Audio, Background, bindAsset, BlendMode, BlendModeType, Blur, Caption, CaptionAlign, CAPTION_PRESET_FILLS, CAPTION_PRESET_STYLES, CaptionType, Chars, ClipHeight, ClipsContent, Computed, CornerRadius, createEntity, DEFAULT_BACKGROUND, Color, ColorStop, Delay, Effect, EffectType, Expanded, FontStyle, FramePromises, FrameRate, Generating, GenerationRequest, getActiveEntity, Loop, LoadRequest, Geometry, GeometryType, getEntityTree, getParentEntity, getParentNode, Hidden, Host, IsMask, isText, ItemIndex, KeepAspectRatio, Keyframe, KeyframeTrack, MixedCornerRadius, Muted, Name, Offset, Opacity, Paint, PaintType, parseColor, PendingSource, PendingSync, Playback, PlaybackRate, Position, removeChild, RenderSurface, resizeEntity, Scale, ScaleMode, ScaleModeType, secondsToFrames, getAsset, getEntityChildren, Group, Sequential, Shader, Size, Stage, Root, Rotation, Scene, Selected, Shadow, Source, SourceError, SourceFrameRate, SourceModifiers, hasModifier, setCameraMatrix, setTimelineView, Stroke, StrokeCap, StrokeJoin, StrokeStyle, SyncRequest, TextAlign, TextBaseline, TextCase, TextRange, TextStyle, TranscriptionRequest, Transition, TransitionType, Trim, UniformScale, Volume, Workarea } from '@diffusionstudio/runtime';import { LOOP_ATTR, parseTime, SOURCE_ATTR } from '@diffusionstudio/jsx';import { createSignal } from 'solid-js';import { SVGElements } from 'solid-js/web';import { IsExcluded } from 'koota';-import type { CameraMatrix, PropertyPath, SceneNode } from '@diffusionstudio/runtime';+import type { CameraMatrix, PropertyPath, SceneNode, TimelineView } from '@diffusionstudio/runtime';import type { AnimatableProperty, AssetRef } from '@diffusionstudio/jsx';import type { Entity, World } from 'koota';@@ -833,6 +833,15 @@ export class RuntimeDocument implements ProjectDocument<SceneNode> {}return;}+ case 'timeline': {+ if (!Array.isArray(value) || value.length !== 3) return;++ const numbers = value.map(toNumber);+ if (!numbers.includes(undefined)) {+ setTimelineView(this.world, entity, (numbers as TimelineView));+ }+ return;+ }case 'x':case 'y': {if (entity.has(Sequential)) return;diff --git a/packages/runtime/src/actions/index.ts b/packages/runtime/src/actions/index.tsindex 6e4f6ede..4f64904b 100644--- a/packages/runtime/src/actions/index.ts+++ b/packages/runtime/src/actions/index.ts@@ -13,6 +13,7 @@ export * from './entities';export * from './camera';export * from './hierarchy';export * from './cache';+export * from './timeline-view';export * from './timing';export * from './resize';export * from './keyframe';diff --git a/packages/runtime/src/actions/timeline-view.ts b/packages/runtime/src/actions/timeline-view.tsnew file mode 100644index 00000000..027ed6b5--- /dev/null+++ b/packages/runtime/src/actions/timeline-view.ts@@ -0,0 +1,33 @@+/* This Source Code Form is subject to the terms of the Mozilla Public+ * License, v. 2.0. If a copy of the MPL was not distributed with this+ * file, You can obtain one at http://mozilla.org/MPL/2.0/. */++// Timeline view write path. Written through the store rather than+// `entity.set`, the way the editor's own scroll handlers write it: where the+// timeline is looking is not an edit of the project, so nothing observes it.++import { FrameRate, Timeline } from '../traits';+import { store } from '../world/store';++import type { Entity, World } from 'koota';+import type { TimelineView } from '../queries/timeline-view';++/**+ * Restores a view `getTimelineView` reported: zoom in pixels per second,+ * horizontal scroll in seconds, vertical scroll in pixels. Unclamped, like+ * `setCameraMatrix`: the gestures that produce one have already been held to+ * the limits. A zoom of nothing (or less) would collapse the timeline onto+ * one column, so a view saying that is refused whole.+ */+export function setTimelineView(world: World, scene: Entity, [zoom, x, y]: TimelineView): void {+ if (!(zoom > 0) || !Number.isFinite(zoom) || !Number.isFinite(x) || !Number.isFinite(y)) return;++ const fps = world.get(FrameRate)?.value ?? 30;+ if (!scene.has(Timeline)) scene.add(Timeline);++ const view = store(world, Timeline);+ const eid = scene.id();+ view.resolution[eid] = zoom / fps;+ view.scrollX[eid] = x * fps;+ view.scrollY[eid] = y;+}diff --git a/packages/runtime/src/queries/index.ts b/packages/runtime/src/queries/index.tsindex 1891f407..c40a0c16 100644--- a/packages/runtime/src/queries/index.ts+++ b/packages/runtime/src/queries/index.ts@@ -2,5 +2,6 @@ export * from './predicates';export * from './camera';export * from './hierarchy';export * from './timeline-index';+export * from './timeline-view';export * from './hit-test';export * from './interaction';diff --git a/packages/runtime/src/queries/timeline-view.ts b/packages/runtime/src/queries/timeline-view.tsnew file mode 100644index 00000000..b480f607--- /dev/null+++ b/packages/runtime/src/queries/timeline-view.ts@@ -0,0 +1,33 @@+/* This Source Code Form is subject to the terms of the Mozilla Public+ * License, v. 2.0. If a copy of the MPL was not distributed with this+ * file, You can obtain one at http://mozilla.org/MPL/2.0/. */++// Timeline view read path. The Timeline trait on a scene is where its+// timeline canvas is looking; the editor's own reads go through its view+// helpers, and this is the round-trip form. Writes live in+// actions/timeline-view.ts.++import { FrameRate, Timeline } from '../traits';+import { store } from '../world/store';++import type { Entity, World } from 'koota';++/**+ * A scene's timeline viewport as `[zoom, x, y]`: `zoom` in pixels per second+ * of timeline, `x` the horizontal scroll in seconds, `y` the vertical scroll+ * in pixels. The form a project writes (`<scene timeline={…}>`): seconds+ * rather than the frames the trait holds, so the value survives a change of+ * frame rate.+ */+export type TimelineView = [zoom: number, x: number, y: number];++/** The scene's view in file form, or null while it has never been looked at. */+export function getTimelineView(world: World, scene: Entity): TimelineView | null {+ if (!scene.has(Timeline)) return null;++ const fps = world.get(FrameRate)?.value ?? 30;+ const view = store(world, Timeline);+ const eid = scene.id();++ return [(view.resolution[eid] ?? 1) * fps, (view.scrollX[eid] ?? 0) / fps, view.scrollY[eid] ?? 0];+}diff --git a/reference/jsx/scene.md b/reference/jsx/scene.mdindex abd9a2f1..c7b029f8 100644--- a/reference/jsx/scene.md+++ b/reference/jsx/scene.md@@ -21,12 +21,13 @@ A scene is the **clipped, playable frame** a composition is made in, and the onl| `active` | `boolean` | absent | Whether this is the scene the playhead, the timeline and `dapi capture` operate on. || `workarea` | `[in, out] \| null` | `null` | The stretch of the scene that plays and exports, in any [time format](./timing.md#time-formats). || `selected` | `boolean` | absent | Whether the editor has the scene selected. |+| `timeline` | `[zoom, x, y]` | absent | Where the scene's timeline is looking: `zoom` in pixels per second of timeline, horizontal scroll in seconds, vertical scroll in pixels. Absent means the default zoom, at the beginning. |A scene also takes paints as children, exactly as a `<rect>` does (see [paints.md](./paints.md)); `fill` is the shorthand for a solid one.## Editor state in the source-`active`, `selected`, `x` and `y` are editor concerns rather than part of the composition, but they live in the file for the same reason [`<stage>`](./stage.md)'s `camera` does: the source is the document, so a scene dragged or clicked on the canvas has nowhere else to be written back to. The editor writes the bare attribute and removes it again.+`active`, `selected`, `x`, `y` and `timeline` are editor concerns rather than part of the composition, but they live in the file for the same reason [`<stage>`](./stage.md)'s `camera` does: the source is the document, so a scene dragged or clicked on the canvas — or a timeline scrolled or zoomed — has nowhere else to be written back to. The editor writes them and removes them again; there is no need to author a `timeline`, and the first scroll or zoom overwrites one.Two rules the runtime holds for `active`: **at most one element is active**, and **only a root** — a direct child of `<stage>` — can be. A nested `active` is dropped, and when a file names more than one the last one rendered wins.