Skip to content

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.ts
index 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. Edits
diff --git a/apps/web/src/engine/timeline/controller.ts b/apps/web/src/engine/timeline/controller.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
new file mode 100644
index 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.md
index 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.