The VS Code of video editing, built for agents.
TypeScript
Refactor timing traits to introduce Delay and Trim
konstantin-paulus589be2161dbd
diff --git a/apps/web/src/components/sidebar-right/inspector/time.tsx b/apps/web/src/components/sidebar-right/inspector/time.tsxindex 95119036..fe2c1bf1 100644--- a/apps/web/src/components/sidebar-right/inspector/time.tsx+++ b/apps/web/src/components/sidebar-right/inspector/time.tsx@@ -33,11 +33,11 @@ import { store } from "@/init";import { useTrait, useWorld } from "@diffusionstudio/koota-solid";import {Computed,- End,FrameRate,Geometry,PlaybackRate,SourceFrameRate,+ Trim,findGeometryAsset,findGeometryAssetSource,getSequenceFrameRate,@@ -115,13 +115,13 @@ export function TimeSettings(props: TimeSettingsProps) {const fps = () => frameRate()?.value ?? 30;const playbackRate = useTrait(entity, PlaybackRate);- const authoredEnd = useTrait(entity, End);+ const trim = useTrait(entity, Trim);const start = useDerived(() => entity().get(Computed)?.start ?? 0);const end = useDerived(() => entity().get(Computed)?.end ?? 0);const isContainer = createMemo(() => isGroupLike(entity()));- // A container authoring an End spans that rather than fitting its children.- const hasTrim = () => authoredEnd() !== undefined;+ // A container whose trim closes spans that rather than fitting its children.+ const hasTrim = () => (trim()?.end ?? null) !== null;const playbackRatePercent = createMemo(() => Math.round((playbackRate()?.value ?? 1) * 100));diff --git a/apps/web/src/engine/editor.ts b/apps/web/src/engine/editor.tsindex 577dddb2..d06c07cd 100644--- a/apps/web/src/engine/editor.ts+++ b/apps/web/src/engine/editor.ts@@ -10,7 +10,7 @@* where the commands live.*/-import { Active, Background, Chars, colorToHex, Computed, DEFAULT_BACKGROUND, End, FrameRate, framesToSeconds, getActiveEntity, getEntityChildren, getEntityTree, getIntrinsicPaint, getParentEntity, getTimelineOrigin, isText, Loop, PaintType, Selected, Sequential, setActive, Size, Source, Stage, Start } from '@diffusionstudio/runtime';+import { Active, Background, Chars, colorToHex, Computed, DEFAULT_BACKGROUND, FrameRate, framesToSeconds, getActiveEntity, getEntityChildren, getEntityTree, getIntrinsicPaint, getParentEntity, getTimelineOrigin, isText, Loop, PaintType, Selected, Sequential, setActive, Size, Source, Stage } from '@diffusionstudio/runtime';import { isAssetRef, isPropValue, serializeAssetRef, SOURCE_ATTR } from '@diffusionstudio/jsx';import { createRoot } from 'solid-js';@@ -719,7 +719,7 @@ export class DocumentEditor {* only the picture goes away: the box (a media element defaults to* 1920x1080 where a rect is 100x100) and the span (a clip lasts its* footage where a rect falls back to the default; the same pin the runtime- * makes when a geometry loses its paint, see `pinEndToCurrentBounds`).+ * makes when a geometry loses its paint, see `pinTrimToCurrentBounds`).* Goes to the file the way the fill picker swaps a fill's kind: the* insert of the rect, then the removal of the old element. The selection* and the timeline's active pointer move to the rect. Returns the rect,@@ -750,14 +750,13 @@ export class DocumentEditor {const fps = this.world.get(FrameRate)?.value ?? 30;if (props.start === undefined) {- // A start the source derived (a syncTo correlation) rather than+ // A start the runtime derived (a syncTo correlation) rather than// the element authored.- const start = node.get(Start)?.value ?? 0;+ const start = Math.round((node.get(Computed)?.start ?? 0) - getTimelineOrigin(node));if (start > 0) props.start = framesToSeconds(start, fps);}if (props.end === undefined) {- const end = node.get(End)?.value- ?? (node.get(Computed)?.end ?? 0) - getTimelineOrigin(node);+ const end = (node.get(Computed)?.end ?? 0) - getTimelineOrigin(node);if (end > 0) props.end = framesToSeconds(end, fps);}diff --git a/apps/web/src/engine/group.tsx b/apps/web/src/engine/group.tsxindex ce791717..1c9432ef 100644--- a/apps/web/src/engine/group.tsx+++ b/apps/web/src/engine/group.tsx@@ -6,7 +6,6 @@ import { Group as GroupElement, Sequence as SequenceElement } from '@diffusionstimport {AdjustmentLayer,Computed,- End,Flip,FrameRate,Geometry,@@ -15,7 +14,6 @@ import {Selected,Sequential,Skew,- Start,computeLocalMatrix,decompose2D,entityAnchor,@@ -36,6 +34,7 @@ import { getDocumentEditor } from './editor';import { editTransform } from './input/interactions';import { syncKeyframe } from './keyframes';import { resolveNewSequenceOverlaps } from './overlap';+import { authoredTime } from './timing';import type { TransformWrite } from './input/interactions';import type { Mat2D } from '@diffusionstudio/runtime';@@ -231,9 +230,9 @@ function dissolveContainers(world: World, containers: Entity[]): void {if (shift !== 0) {const fps = world.get(FrameRate)?.value ?? 30;- const start = (child.get(Start)?.value ?? 0) + shift;+ const start = (authoredTime(world, child, 'start') ?? 0) + shift;editor.editProperty(child, 'start', start === 0 ? false : framesToSeconds(start, fps));- const end = child.get(End)?.value;+ const end = authoredTime(world, child, 'end');if (end !== undefined) editor.editProperty(child, 'end', framesToSeconds(end + shift, fps));}}diff --git a/apps/web/src/engine/timeline/drag.ts b/apps/web/src/engine/timeline/drag.tsindex 036dcede..e9d2fe2d 100644--- a/apps/web/src/engine/timeline/drag.ts+++ b/apps/web/src/engine/timeline/drag.ts@@ -20,7 +20,6 @@ import {Group,KeyframeDragOrigin,Selected,- Start,TrimDragOrigin,findAssetDuration,store,@@ -29,7 +28,7 @@ import { Not, Or } from 'koota';import { clamp } from '@/utils';import { resolveSequentialOverlaps } from '../overlap';-import { moveEntityTo, trimIn, trimOut } from '../timing';+import { authoredTime, moveEntityTo, trimIn, trimOut } from '../timing';import { findSnapDelta, findSnapFrame } from './snapping';import { framesToPixels, pixelsToFrames } from './view';@@ -93,7 +92,7 @@ export function beginClipDrag(world: World, entity: Entity): void {entity.add(ClipDragOrigin);entity.set(ClipDragOrigin, {- authored: entity.get(Start)?.value ?? 0,+ authored: authoredTime(world, entity, 'start') ?? 0,start: computed.start[eid] ?? 0,end: computed.end[eid] ?? 0,});diff --git a/apps/web/src/engine/timing.ts b/apps/web/src/engine/timing.tsindex c42ef3ca..80d68789 100644--- a/apps/web/src/engine/timing.ts+++ b/apps/web/src/engine/timing.ts@@ -5,30 +5,52 @@/*** Where a node sits on the timeline, moved the way every editor change moves:* the document for the canvas, an edit for the file. The runtime has- * `trimEntityIn`/`trimEntityOut`, which write the traits themselves — that+ * `trimEntityIn`/`trimEntityOut`, which write Delay/Trim themselves — that* moves the clip on screen and nowhere else — so everything that trims a clip* (the inspector's fields, the timeline's handles, a split) goes through here* instead, and the file hears about it.+ *+ * The runtime no longer stores the file's time vocabulary: it reconciles+ * `start`/`end`/`sourceIn`/`sourceOut` down to Delay and Trim. What a node+ * authors is read back from the copy its host node keeps (`authoredTime`),+ * which is what these edits rewrite.*/import {Computed,- End,FrameRate,- SourceOut,- Start,+ Host,framesToSeconds,getSourceFrameAt,getTimelineOrigin,+ secondsToFrames,} from '@diffusionstudio/runtime';+import { parseTime } from '@diffusionstudio/jsx';import { getDocumentEditor } from './editor';+import type { Time } from '@diffusionstudio/jsx';import type { Entity, World } from 'koota';/** The time a node authors, in the vocabulary of the JSX rather than the traits'. */export type TimeProp = 'start' | 'end' | 'sourceIn' | 'sourceOut';+/**+ * The time prop as the node's host holds it, in frames of this project, or+ * undefined while the element doesn't author it. The authored copy rather+ * than the traits: Delay and Trim fold the four props together, and an edit+ * has to know what the file actually says to rewrite it.+ */+export function authoredTime(world: World, entity: Entity, name: TimeProp): number | undefined {+ const value = entity.get(Host)?.props[name];+ const seconds = typeof value === 'number' || typeof value === 'string'+ ? parseTime(value as Time | string)+ : undefined;+ if (seconds === undefined) return undefined;++ return secondsToFrames(seconds, world.get(FrameRate)?.value ?? 30);+}+/*** Writes a time prop from a frame count of this project; the file spells* times in seconds. `null` unsets it: the document drops the trait, and the@@ -59,15 +81,15 @@ export function editWorkarea(world: World, scene: Entity, range: [start: number,/*** Moves the node's in point to scene frame `frame`, keeping the rest of the* clip where it is: the runtime's `trimEntityIn`, as edits. The out point is- * only implied while the node authors no End, so it is pinned first, or the- * tail would follow the head; then Start moves and SourceIn rolls forward by+ * only implied while the node authors no end, so it is pinned first, or the+ * tail would follow the head; then start moves and sourceIn rolls forward by* as much as the head lost.*/export function trimIn(world: World, entity: Entity, frame: number): void {- if (!entity.has(End)) {+ if (authoredTime(world, entity, 'end') === undefined) {editTime(world, entity, 'end', (entity.get(Computed)?.end ?? 0) - getTimelineOrigin(entity));}- // Both read the origin, which the Start write moves.+ // Both read the origin, which the start write moves.const start = frame - getTimelineOrigin(entity);const source = getSourceFrameAt(entity, frame);editTime(world, entity, 'start', start);@@ -77,10 +99,10 @@ export function trimIn(world: World, entity: Entity, frame: number): void {/*** Moves the node's out point to scene frame `frame` (the runtime's* `trimEntityOut`, as edits). The source window follows only when the node- * authors one; otherwise End alone says where the clip runs out.+ * authors one; otherwise end alone says where the clip runs out.*/export function trimOut(world: World, entity: Entity, frame: number): void {- if (entity.has(SourceOut)) {+ if (authoredTime(world, entity, 'sourceOut') !== undefined) {editTime(world, entity, 'sourceOut', getSourceFrameAt(entity, frame));}editTime(world, entity, 'end', frame - getTimelineOrigin(entity));@@ -91,22 +113,22 @@ export function trimOut(world: World, entity: Entity, frame: number): void {* about it: the same stretch of its source plays, for the same length, only* later or earlier.*- * Start and End are both parent-relative — a node's length is `end - start` —+ * Start and end are both parent-relative — a node's length is `end - start` —* so a move is both of them by the same amount. Writing only the start would* leave the end where it was and stretch the clip, which is a trim.*- * A container that takes its bounds from its children authors no End, and so+ * A container that takes its bounds from its children authors no end, and so* only its start moves: its children are placed against its origin, and they* all travel with it.*/export function moveEntityTo(world: World, entity: Entity, frame: number): void {const start = frame - getTimelineOrigin(entity);- const delta = start - (entity.get(Start)?.value ?? 0);+ const delta = start - (authoredTime(world, entity, 'start') ?? 0);if (delta === 0) return;// Before the start, which moves the origin the end would then be read// against — both are worked out from what the node says now.- const end = entity.get(End)?.value;+ const end = authoredTime(world, entity, 'end');if (end !== undefined) editTime(world, entity, 'end', end + delta);editTime(world, entity, 'start', start);diff --git a/packages/reconciler/src/document.ts b/packages/reconciler/src/document.tsindex de2c327f..181efdd5 100644--- a/packages/reconciler/src/document.ts+++ b/packages/reconciler/src/document.ts@@ -3,7 +3,7 @@* 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, CaptionType, Chars, ClipHeight, ClipsContent, CornerRadius, createEntity, DEFAULT_BACKGROUND, Color, ColorStop, Effect, EffectType, End, Expanded, FontStyle, FrameRate, Generating, GenerationRequest, Loop, LoadRequest, Geometry, GeometryType, getEntityTree, getParentEntity, getParentNode, Hidden, Host, IsMask, isText, ItemIndex, Keyframe, KeyframeTrack, MixedCornerRadius, Muted, Name, Offset, Opacity, Paint, PaintType, parseColor, PendingSource, Playback, PlaybackRate, Position, removeChild, RenderSurface, resizeEntity, Scale, ScaleMode, ScaleModeType, secondsToFrames, getAsset, getEntityChildren, Group, Sequential, Shader, Size, Stage, Root, Rotation, Scene, Selected, Shadow, Source, SourceError, SourceIn, SourceOut, SourceFrameRate, SourceModifiers, hasModifier, setCameraMatrix, Start, Stroke, StrokeCap, StrokeJoin, StrokeStyle, TextAlign, TextBaseline, TextCase, TextRange, TextStyle, TranscriptionRequest, Transition, TransitionType, UniformScale, Volume, Workarea } from '@diffusionstudio/runtime';+import { Active, AdjustmentLayer, Animation, AnimationPhase, AnimationType, appendChild, AssetId, Audio, Background, bindAsset, BlendMode, BlendModeType, Blur, Caption, CaptionAlign, CaptionType, Chars, ClipHeight, ClipsContent, CornerRadius, createEntity, DEFAULT_BACKGROUND, Color, ColorStop, Delay, Effect, EffectType, Expanded, FontStyle, FrameRate, Generating, GenerationRequest, Loop, LoadRequest, Geometry, GeometryType, getEntityTree, getParentEntity, getParentNode, Hidden, Host, IsMask, isText, ItemIndex, Keyframe, KeyframeTrack, MixedCornerRadius, Muted, Name, Offset, Opacity, Paint, PaintType, parseColor, PendingSource, 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, 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 { SVGElements } from 'solid-js/web';import { IsExcluded } from 'koota';@@ -122,13 +122,6 @@ function detach(node: SceneNode): void {syncChars(parent);}-const TIME_TRAITS = {- start: Start,- end: End,- sourceIn: SourceIn,- sourceOut: SourceOut,-} as const;-const PAINT_TYPES: Record<string, PaintType> = {solidPaint: PaintType.SOLID,linearGradientPaint: PaintType.LINEAR_GRADIENT,@@ -919,11 +912,14 @@ export class RuntimeDocument implements ProjectDocument<SceneNode> {const rate = toNumber(value);if (rate === undefined || rate === 0) {entity.remove(PlaybackRate);- return;+ } else {+ entity.add(PlaybackRate);+ entity.set(PlaybackRate, { value: rate });}- entity.add(PlaybackRate);- entity.set(PlaybackRate, { value: rate });+ // The rate scales the authored window onto the runtime's traits,+ // so they are re-derived with it.+ this.syncTiming(node);return;}case 'transition': {@@ -1076,16 +1072,7 @@ export class RuntimeDocument implements ProjectDocument<SceneNode> {return;}- const trait = TIME_TRAITS[name];- const seconds = toSeconds(value);-- if (seconds === undefined) {- entity.remove(trait);- return;- }-- entity.add(trait);- entity.set(trait, { value: this.toFrames(seconds) });+ this.syncTiming(node);return;}case 'frameRate': {@@ -1384,6 +1371,58 @@ export class RuntimeDocument implements ProjectDocument<SceneNode> {return secondsToFrames(seconds, this.world.get(FrameRate)?.value ?? 30);}+ /**+ * Reconciles the authored time props (`start`/`end`/`sourceIn`/`sourceOut`,+ * the copy this node holds) into the runtime's own vocabulary, Delay and+ * Trim. Recomputed whole from the props on every one of them (and on+ * `playbackRate`, which scales the window), so the order Solid sets them in+ * does not matter.+ *+ * Delay places the node's local time 0 on its parent's timeline: the+ * authored start, pulled back by the stretch of source the trim skips+ * (`start - sourceIn/rate`), so the trimmed window opens at the start. The+ * trim is the source window; an authored end becomes source frames through+ * the rate, and whichever of it and sourceOut closes first wins. With no+ * out bound at all the trim stays open (`end: null`) and the runtime runs+ * the clip to its source's natural end.+ */+ private syncTiming(node: SceneNode): void {+ const { entity, props } = node;++ const rate = toNumber(props.playbackRate) || 1;+ const start = toSeconds(props.start);+ const end = toSeconds(props.end);+ const sourceIn = toSeconds(props.sourceIn);+ const sourceOut = toSeconds(props.sourceOut);++ const startFrames = start === undefined ? 0 : this.toFrames(start);+ const sourceInFrames = sourceIn === undefined ? 0 : this.toFrames(sourceIn);++ const delay = startFrames - sourceInFrames / rate;+ if (delay === 0) {+ entity.remove(Delay);+ } else {+ entity.add(Delay);+ entity.set(Delay, { value: delay });+ }++ let out: number | null = null;+ if (end !== undefined) {+ out = sourceInFrames + (this.toFrames(end) - startFrames) * rate;+ }+ if (sourceOut !== undefined) {+ const frames = this.toFrames(sourceOut);+ out = out === null ? frames : Math.min(out, frames);+ }++ if (sourceInFrames === 0 && out === null) {+ entity.remove(Trim);+ } else {+ entity.add(Trim);+ entity.set(Trim, { start: sourceInFrames, end: out });+ }+ }+/*** Writes a track's runtime property path from its authored `property`,* against the entity holding it (a `width` track under a stroke drives thediff --git a/packages/runtime/src/actions/timing.ts b/packages/runtime/src/actions/timing.tsindex 70381864..86fe184c 100644--- a/packages/runtime/src/actions/timing.ts+++ b/packages/runtime/src/actions/timing.ts@@ -4,80 +4,69 @@// Time-range recomputation after structural or asset changes (was part of// api/utils.ts). Computed is derived state (store writes, no events); the-// authored time traits fire change events, so edits go through entity.set.+// Delay/Trim time traits fire change events, so edits go through entity.set.import { store } from '../world/store';import { DEFAULT_DURATION_FRAMES } from '../constants';import {Geometry, Group, AdjustmentLayer, Paint, Caption, Cache, Computed,- Start, End, SourceIn, SourceOut, PlaybackRate, CaptionDecoderHandle,+ Delay, Trim, PlaybackRate, CaptionDecoderHandle,} from '../traits';import { isGroupLike } from '../queries/predicates';import { getParentNode } from '../queries/hierarchy';-import { findAssetDuration, getSourceFrameAt, getTimelineOrigin, isPaintEntity } from '../utils/time';+import { findAssetDuration, getSourceFrameAt, isPaintEntity } from '../utils/time';import type { Entity, World } from 'koota';import type { Ignorable, TimeTrait } from '../utils/time';/**- * The authored value, or undefined when the node doesn't carry it. `ignore`+ * The trait's value, or undefined when the node doesn't carry it. `ignore`* reads one trait as absent: koota fires onRemove before it clears the trait,* so a removal handler has to recompute against the value that is going away* (the same reason rebuildCaches takes an exclude).*/-function authored(entity: Entity, trait: TimeTrait, ignore?: Ignorable): number | undefined {+function stored(entity: Entity, trait: TimeTrait, ignore?: Ignorable): number | undefined {return trait === ignore ? undefined : entity.get(trait)?.value;}+/** The node's Trim, with the same `ignore` reading as `stored`. */+function storedTrim(entity: Entity, ignore?: Ignorable) {+ return Trim === ignore ? undefined : entity.get(Trim);+}+/**- * How long the node lasts on its parent's timeline, in frames, from whichever- * of the authored traits it carries.- *- * Each bound is optional and each one caps the duration, so when more than one- * is present the shortest wins rather than one silently overriding another: an- * End past the source runs out of frames, a SourceOut past the asset does too.- * Source-side spans divide by the rate to become timeline frames. With no bound- * at all the node runs for its whole source, or 16s when it has no source (a- * shape or a text has nothing to run out of, so its asset length is a default- * rather than a cap).+ * Where the node's source window closes, in source frames. Each bound is+ * optional and each one caps the window, so when more than one is present the+ * shortest wins rather than one silently overriding another: a trim past the+ * source runs out of frames. With no bound at all the node runs for its whole+ * source, or 16s when it has no source (a shape or a text has nothing to run+ * out of, so its asset length is a default rather than a cap).*/-function resolveDuration(+function resolveSourceOut(world: World,entity: Entity,- start: number,- sourceIn: number,+ trimStart: number,+ trimEnd: number | null,ignore?: Ignorable,): number {- const playbackRate = authored(entity, PlaybackRate, ignore) || 1;const assetDuration = findAssetDuration(world, entity, ignore);- let duration = Infinity;-- const end = authored(entity, End, ignore);- if (end !== undefined) duration = end - start;+ let out = trimEnd ?? Infinity;- const sourceOut = authored(entity, SourceOut, ignore);- if (sourceOut !== undefined) {- duration = Math.min(duration, (sourceOut - sourceIn) / playbackRate);- }-- if (assetDuration !== null) {- duration = Math.min(duration, (assetDuration - sourceIn) / playbackRate);- }+ if (assetDuration !== null) out = Math.min(out, assetDuration);- if (duration === Infinity) {- duration = (DEFAULT_DURATION_FRAMES - sourceIn) / playbackRate;- }+ if (out === Infinity) out = DEFAULT_DURATION_FRAMES;- return Math.max(0, duration);+ return Math.max(trimStart, out);}/**- * Resolve one node's authored time into its absolute bounds, origin, and rate.+ * Resolve one node's time traits into its absolute bounds, origin, and rate.*- * Authored values are parent-relative; Computed is absolute, so everything- * comparing two nodes works in one space. The rate places source frame 0, which- * is the origin every descendant is measured against.+ * Delay is parent-relative and Trim is in the node's own source frames;+ * Computed is absolute, so everything comparing two nodes works in one space.+ * The origin places source frame 0, which is what every descendant is+ * measured against.*/export function recomputeEntityTimeRange(world: World, entity: Entity, ignore?: Ignorable): void {const computed = store(world, Computed);@@ -86,20 +75,21 @@ export function recomputeEntityTimeRange(world: World, entity: Entity, ignore?:const parent = getParentNode(entity);const parentOrigin = parent !== null ? (computed.origin[parent.id()] ?? 0) : 0;- const authoredStart = authored(entity, Start, ignore) ?? 0;- const sourceIn = authored(entity, SourceIn, ignore) ?? 0;- const playbackRate = authored(entity, PlaybackRate, ignore) || 1;+ const delay = stored(entity, Delay, ignore) ?? 0;+ const playbackRate = stored(entity, PlaybackRate, ignore) || 1;+ const trim = storedTrim(entity, ignore);// Bounds land on frame boundaries, since everything comparing nodes works// in whole frames, while the origin keeps its fraction so audio scheduled// against it doesn't inherit a half-frame of slip.- const origin = parentOrigin + authoredStart - sourceIn / playbackRate;- const start = Math.round(parentOrigin + authoredStart);+ const origin = parentOrigin + delay;+ const trimStart = trim?.start ?? 0;+ const start = Math.round(origin + trimStart / playbackRate);computed.origin[eid] = origin;computed.playbackRate[eid] = playbackRate;- // A container with no End of its own spans whatever its children span.+ // A container with no trimmed end of its own spans whatever its children span.if (fitsChildren(entity, ignore)) {const children = entity.get(Cache)?.children ?? [];let fitStart = start;@@ -124,7 +114,8 @@ export function recomputeEntityTimeRange(world: World, entity: Entity, ignore?:return;}- const end = start + Math.round(resolveDuration(world, entity, authoredStart, sourceIn, ignore));+ const sourceOut = resolveSourceOut(world, entity, trimStart, trim?.end ?? null, ignore);+ const end = Math.max(start, Math.round(origin + sourceOut / playbackRate));computed.start[eid] = start;computed.end[eid] = end;@@ -149,7 +140,7 @@ export function propagateTimeRangeDown(world: World, entity: Entity, ignore?: Ig/*** Walk upward recomputing any ancestor whose bounds depend on its children- * (group-like without an explicit end). Call with the entity that changed.+ * (group-like without a trimmed end). Call with the entity that changed.*/export function bubbleTimeRangeUp(world: World, child: Entity): void {const entity = getParentNode(child);@@ -161,59 +152,49 @@ export function bubbleTimeRangeUp(world: World, child: Entity): void {bubbleTimeRangeUp(world, entity);}-/** Whether the node takes its bounds from its children rather than authoring them. */+/** Whether the node takes its bounds from its children rather than trimming them. */export function fitsChildren(entity: Entity, ignore?: Ignorable): boolean {- return isGroupLike(entity) && authored(entity, End, ignore) === undefined;+ if (!isGroupLike(entity)) return false;+ return (storedTrim(entity, ignore)?.end ?? null) === null;}/**- * Pin whatever the node currently spans as an authored End, so it keeps that+ * Pin whatever the node currently spans as a trimmed end, so it keeps that* span once the thing it was derived from is gone. Used when a paint is removed:* without this the geometry silently falls back to the 16s default after losing- * its asset source. A node that already authors an End is left alone.+ * its asset source. A node whose trim already closes is left alone.*/-export function pinEndToCurrentBounds(world: World, entity: Entity): void {- if (entity.has(End)) return;+export function pinTrimToCurrentBounds(world: World, entity: Entity): void {+ if ((entity.get(Trim)?.end ?? null) !== null) return;- const end = store(world, Computed).end[entity.id()] ?? 0;+ const computed = store(world, Computed);+ const eid = entity.id();+ const origin = computed.origin[eid] ?? 0;+ const playbackRate = computed.playbackRate[eid] || 1;+ const end = computed.end[eid] ?? 0;- entity.add(End({ value: end - getTimelineOrigin(entity) }));+ entity.add(Trim);+ entity.set(Trim, { end: (end - origin) * playbackRate });}/*** Move the node's in point to `frame` (scene time), keeping the rest of the- * clip where it is: the source rolls forward by as much as the head lost, so- * the frames left visible still line up with the timeline.+ * clip where it is: the origin stays put and the trim opens later, so the+ * frames left visible still line up with the timeline.*/export function trimEntityIn(world: World, entity: Entity, frame: number): void {- // The out point is only implied while the node has no authored End; pin it+ // The out point is only implied while the trim is open-ended; pin it// before moving the head, or the tail would follow along.- pinEndToCurrentBounds(world, entity);+ pinTrimToCurrentBounds(world, entity);- const start = frame - getTimelineOrigin(entity);- const source = getSourceFrameAt(entity, frame);-- entity.add(Start);- entity.set(Start, { value: start });- entity.add(SourceIn);- entity.set(SourceIn, { value: source });+ entity.add(Trim);+ entity.set(Trim, { start: getSourceFrameAt(entity, frame) });}-/**- * Move the node's out point to `frame` (scene time). The source window follows- * only if the node authors one: otherwise the End alone says where the clip- * runs out, and leaving SourceOut absent keeps it that way.- */+/** Move the node's out point to `frame` (scene time): the trim closes there. */export function trimEntityOut(_world: World, entity: Entity, frame: number): void {- const end = frame - getTimelineOrigin(entity);- const source = getSourceFrameAt(entity, frame);-- if (entity.has(SourceOut)) {- entity.set(SourceOut, { value: source });- }-- entity.add(End);- entity.set(End, { value: end });+ entity.add(Trim);+ entity.set(Trim, { end: getSourceFrameAt(entity, frame) });}/**@@ -243,9 +224,9 @@ export function reactToAssetChange(world: World, entity: Entity, ignore?: Ignora/*** Recompute the parent geometry against its new source and bubble the new- * bounds up. Nothing authored needs fixing up: the asset length is one of the- * caps resolveDuration takes, so a shorter source shortens the clip on its own- * and a longer one gives back whatever the authored bounds still allow.+ * bounds up. Nothing else needs fixing up: the asset length is one of the+ * caps resolveSourceOut takes, so a shorter source shortens the clip on its+ * own and a longer one gives back whatever the trim still allows.*/export function reactToPaintChange(world: World, paint: Entity) {// A geometry's own Paint is its intrinsic paint: the geometry is the clip.@@ -258,7 +239,7 @@ export function reactToPaintChange(world: World, paint: Entity) {/*** Recompute a geometry's bounds and bubble. Used when something other than its- * own authored time shifts its duration (e.g. the intrinsic media its own+ * own time traits shifts its duration (e.g. the intrinsic media its own* asset id names).*/export function reactToGeometryDurationChange(world: World, entity: Entity) {@@ -297,6 +278,6 @@ export function reactToChildDetached(world: World, child: Entity) {if (parent === null || !parent.has(Geometry)) return;// Pin the current duration before recomputing; otherwise the geometry// would silently fall back to the 16s default after losing its paint.- pinEndToCurrentBounds(world, parent);+ pinTrimToCurrentBounds(world, parent);}}diff --git a/packages/runtime/src/traits/timing.ts b/packages/runtime/src/traits/timing.tsindex 127c89a1..777df684 100644--- a/packages/runtime/src/traits/timing.ts+++ b/packages/runtime/src/traits/timing.ts@@ -6,21 +6,18 @@ import { trait } from 'koota';import { TransitionType } from '../constants';-// The authored time of a node, in the vocabulary the JSX uses. One trait per-// value, all frames, because a clip rarely says more than one of these things:-// they are separate answers to separate questions, and absence is the answer-// most nodes give. `resolveTimeRange` in actions/timing.ts fills the gaps.-//-// Start/End place the node on its parent's timeline. Absent Start is 0 (begin-// with the parent), absent End is the source's natural duration, or 16s for a-// node with no source. Scenes and groups without an End fit their children.-export const Start = trait({ value: 0 });-export const End = trait({ value: 0 });--// SourceIn/SourceOut pick the slice of the node's own source that plays there.-// Absent SourceIn is 0 (from the top), absent SourceOut is the natural end.-export const SourceIn = trait({ value: 0 });-export const SourceOut = trait({ value: 0 });+// Offset where the node's local time 0 (source frame 0) sits on its parent's+// timeline, in frames. May carry a fraction: audio is scheduled against it,+// and a trimmed clip's origin sits sourceIn/rate before its first visible+// frame. Absent is 0 (the node's time begins with its parent's).+export const Delay = trait({ value: 0 });++// The slice of the node's own source that plays, in source frames. A null+// `end` is no fixed out point: the clip runs to its source's natural end (or+// the 16s default for a node with no source). Absent entirely, `start` is 0+// and scenes/groups fit their children; `resolveSourceOut` in actions/+// timing.ts fills the gaps.+export const Trim = trait({ start: 0, end: null as number | null });// Frames per second a frames-directory source is played at, which is the only// thing that says how long it lasts: a folder of pictures has a count, not adiff --git a/packages/runtime/src/utils/time.ts b/packages/runtime/src/utils/time.tsindex 0d33116c..6fc54032 100644--- a/packages/runtime/src/utils/time.ts+++ b/packages/runtime/src/utils/time.ts@@ -4,8 +4,8 @@import { CONONICAL_TIME_BASE, PaintType } from '../constants';import {- Audio, AssetId, Cache, Computed, Geometry, Paint, SourceIn, Library, FrameRate,- Start, IsMask, SourceFrameRate,+ Audio, AssetId, Cache, Computed, Geometry, Paint, Trim, Library, FrameRate,+ Delay, IsMask, PlaybackRate, SourceFrameRate,} from '../traits';import { getParentNode } from '../queries/hierarchy';import { getSourceDuration } from '../actions/assets';@@ -60,9 +60,9 @@ export function formatTimecode(seconds: number, frameRate: number): string {}/**- * The scene frame that authored time 0 means for `entity`, its parent's+ * The scene frame that local time 0 means for `entity`, its parent's* origin. Converts between the absolute frames Computed works in and the- * parent-relative frames Start and End are authored in.+ * parent-relative frames Delay is expressed in.*/export function getTimelineOrigin(entity: Entity): number {const parent = getParentNode(entity);@@ -81,11 +81,11 @@ export function getSourceFrameAt(entity: Entity, frame: number): number {/*** The node's resolved source window, in source frames: where its in point is* and how far its timeline span actually reaches into the source. Derived from- * the resolved duration rather than read off SourceOut, so a window the node- * never gets to play (an End that runs out first) is not reported as playing.+ * the resolved duration rather than read off Trim's end, so a window the node+ * never gets to play (a source the trim outruns) is not reported as playing.*/export function getSourceWindow(entity: Entity): { in: number; out: number } {- const sourceIn = entity.get(SourceIn)?.value ?? 0;+ const sourceIn = entity.get(Trim)?.start ?? 0;const computed = entity.get(Computed);const duration = computed?.duration ?? 0;const playbackRate = computed?.playbackRate || 1;@@ -140,18 +140,18 @@ export function findGeometryAsset(world: World, entity: Entity): Asset | null {}/**- * One of the authored time traits: Start, End, SourceIn, SourceOut,- * PlaybackRate, SourceFrameRate. They all carry a single frame count (or rate).+ * A single-value time trait: Delay, PlaybackRate, SourceFrameRate. Each+ * carries one frame count (or rate).*/-export type TimeTrait = typeof Start;+export type TimeTrait = typeof Delay | typeof PlaybackRate | typeof SourceFrameRate;/**- * A trait a recompute may read as absent: one of the authored time traits, or- * the node's own AssetId (its intrinsic media, another source of a length).+ * A trait a recompute may read as absent: one of the time traits, or the+ * node's own AssetId (its intrinsic media, another source of a length).* koota fires onRemove before it clears the trait, so a removal handler has to* ask for the length the node will have once it is gone.*/-export type Ignorable = TimeTrait | typeof AssetId | typeof IsMask;+export type Ignorable = TimeTrait | typeof Trim | typeof AssetId | typeof IsMask;/*** Intrinsic duration (in project frames) of the media asset attached to andiff --git a/packages/runtime/src/world/observers.ts b/packages/runtime/src/world/observers.tsindex fc749a57..f3268c60 100644--- a/packages/runtime/src/world/observers.ts+++ b/packages/runtime/src/world/observers.ts@@ -6,7 +6,7 @@import { store } from './store';import {ChildOf, Culled, Sequential, Group, Scene, Audio, Paint, AssetId,- Start, End, SourceIn, SourceOut, PlaybackRate, SourceFrameRate, Keyframe, ItemIndex,+ Delay, Trim, PlaybackRate, SourceFrameRate, Keyframe, ItemIndex,Position, Offset, Rotation, Scale, UniformScale, Skew, Anchor, Flip,Opacity, Color, Blur, Volume, Effect, CornerRadius, MixedCornerRadius,ColorStop, StrokeStyle, Size, Computed, Active, Stage, IsMask,@@ -161,7 +161,7 @@ export function observeWorld(world: World): () => void {bubbleTimeRangeUp(world, entity);};- for (const trait of [Start, End, SourceIn, SourceOut, PlaybackRate]) {+ for (const trait of [Delay, Trim, PlaybackRate]) {subs.push(world.onAdd(trait, propagateAndBubble));subs.push(world.onChange(trait, propagateAndBubble));subs.push(world.onRemove(trait, (entity) => {diff --git a/packages/runtime/src/world/serialize.ts b/packages/runtime/src/world/serialize.tsindex 90ec17e5..fa6f4f95 100644--- a/packages/runtime/src/world/serialize.ts+++ b/packages/runtime/src/world/serialize.ts@@ -12,7 +12,7 @@ import {Opacity, BlendMode, Color, CornerRadius, MixedCornerRadius, Blur, ScaleMode, Effect,ColorStop, StrokeStyle, Shader,Chars, TextStyle,- Start, End, SourceIn, SourceOut, PlaybackRate, SourceFrameRate,+ Delay, Trim, PlaybackRate, SourceFrameRate,Playback, Sequential, Transition, ClipHeight, Expanded,Volume, Muted,KeyframeTrack, Keyframe, Animation, Stage,@@ -127,10 +127,11 @@ export interface EntityRecord {Playback?: {loop?: number;};- Start?: number;- End?: number;- SourceIn?: number;- SourceOut?: number;+ Delay?: number;+ Trim?: {+ start: number;+ end: number | null;+ };PlaybackRate?: number;SourceFrameRate?: number;Constraint?: {@@ -334,17 +335,12 @@ export function serializeEntity(entity: Entity): EntityRecord {loop: entity.get(Playback)!.loop ? 1 : 0,};}- if (entity.has(Start)) {- record.Start = entity.get(Start)!.value;- }- if (entity.has(End)) {- record.End = entity.get(End)!.value;- }- if (entity.has(SourceIn)) {- record.SourceIn = entity.get(SourceIn)!.value;+ if (entity.has(Delay)) {+ record.Delay = entity.get(Delay)!.value;}- if (entity.has(SourceOut)) {- record.SourceOut = entity.get(SourceOut)!.value;+ if (entity.has(Trim)) {+ const trim = entity.get(Trim)!;+ record.Trim = { start: trim.start, end: trim.end };}if (entity.has(SourceFrameRate)) {record.SourceFrameRate = entity.get(SourceFrameRate)!.value;@@ -584,17 +580,11 @@ export function deserializeEntity(entity: Entity, e: Partial<EntityRecord>): voientity.add(Playback);entity.set(Playback, { loop: !!e.Playback.loop });}- if (e.Start !== undefined) {- entity.add(Start({ value: e.Start }));- }- if (e.End !== undefined) {- entity.add(End({ value: e.End }));- }- if (e.SourceIn !== undefined) {- entity.add(SourceIn({ value: e.SourceIn }));+ if (e.Delay !== undefined) {+ entity.add(Delay({ value: e.Delay }));}- if (e.SourceOut !== undefined) {- entity.add(SourceOut({ value: e.SourceOut }));+ if (e.Trim !== undefined) {+ entity.add(Trim({ start: e.Trim.start, end: e.Trim.end }));}if (e.SourceFrameRate !== undefined) {entity.add(SourceFrameRate({ value: e.SourceFrameRate }));