Skip to content

The VS Code of video editing, built for agents.

TypeScript

Enhance runtime package with new dependencies and trait exports

konstantin-paulus3993a39abea6
diff --git a/package-lock.json b/package-lock.json
index 2a52f5c4..81cc57c1 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -11981,7 +11981,8 @@
"version": "0.1.0",
"license": "MPL-2.0",
"dependencies": {
- "koota": "^0.6.6"
+ "koota": "^0.6.6",
+ "mediabunny": "^1.32.2"
},
"devDependencies": {
"typescript": "~5.9.3"
diff --git a/packages/runtime/package.json b/packages/runtime/package.json
index d3c19fdc..8fb13a31 100644
--- a/packages/runtime/package.json
+++ b/packages/runtime/package.json
@@ -21,7 +21,8 @@
"video"
],
"dependencies": {
- "koota": "^0.6.6"
+ "koota": "^0.6.6",
+ "mediabunny": "^1.32.2"
},
"devDependencies": {
"typescript": "~5.9.3"
diff --git a/packages/runtime/src/capture/format.ts b/packages/runtime/src/capture/format.ts
new file mode 100644
index 00000000..41110876
--- /dev/null
+++ b/packages/runtime/src/capture/format.ts
@@ -0,0 +1,8 @@
+/* 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/. */
+
+// Container format for export. The rest of engine/encode/format.ts joins this
+// file when capture moves into the runtime.
+
+export type ContainerFormat = 'mp4' | 'webm' | 'ogg' | 'mov';
diff --git a/packages/runtime/src/capture/index.ts b/packages/runtime/src/capture/index.ts
index dd8d65fb..68f561e5 100644
--- a/packages/runtime/src/capture/index.ts
+++ b/packages/runtime/src/capture/index.ts
@@ -1 +1,2 @@
-// Capture and encoding: encoder, buffer, format, image-encoder (moves wholesale from engine/encode/).
+// Capture and encoding: encoder, buffer, image-encoder (move wholesale from engine/encode/).
+export * from './format';
diff --git a/packages/runtime/src/constants.ts b/packages/runtime/src/constants.ts
new file mode 100644
index 00000000..9091b4ea
--- /dev/null
+++ b/packages/runtime/src/constants.ts
@@ -0,0 +1,171 @@
+/* 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/. */
+
+export enum BlendMode {
+ SOURCE_OVER,
+ MULTIPLY,
+ SCREEN,
+ OVERLAY,
+ DARKEN,
+ LIGHTEN,
+ COLOR_DODGE,
+ COLOR_BURN,
+ HARD_LIGHT,
+ SOFT_LIGHT,
+ DIFFERENCE,
+ EXCLUSION,
+ HUE,
+ SATURATION,
+ COLOR,
+ LUMINOSITY,
+};
+
+export const COMPOSITE_OPERATIONS = Object.keys(BlendMode)
+ .filter(key => isNaN(Number(key)))
+ .map(key => key.toLowerCase().replace(/_/g, '-')) as GlobalCompositeOperation[];
+
+export enum StrokeJoin {
+ MITER,
+ ROUND,
+ BEVEL,
+}
+
+export enum StrokeCap {
+ BUTT,
+ ROUND,
+ SQUARE,
+}
+
+// Named ScaleModeType (not ScaleMode) so the enum and the ScaleMode trait can
+// coexist in one export surface, matching the Geometry/GeometryType pattern.
+export enum ScaleModeType {
+ COVER,
+ FILL,
+ FIT,
+ NONE,
+}
+
+export enum ConstraintType {
+ MIN,
+ MAX,
+ CENTER,
+ STRETCH,
+ SCALE,
+}
+
+export enum GeometryType {
+ RECT,
+ TEXT,
+}
+
+export enum PaintType {
+ SOLID,
+ IMAGE,
+ VIDEO,
+ LINEAR_GRADIENT,
+ RADIAL_GRADIENT,
+ SEQUENCE,
+ WAVEFORM,
+ HTML,
+ SURFACE,
+ SHADER,
+}
+
+export enum EffectType {
+ DROP_SHADOW,
+ LAYER_BLUR,
+ BRIGHTNESS,
+ CONTRAST,
+ GRAYSCALE,
+ HUE_ROTATION,
+ INVERT,
+ SATURATE,
+ SEPIA,
+}
+
+export enum MotionType {
+ ANIMATION,
+ KEYFRAME,
+}
+
+export enum AnimationType {
+ FADE,
+ GAIN,
+ GROW,
+ SHRINK,
+ BLUR,
+ SLIDE_LEFT,
+ SLIDE_RIGHT,
+ SLIDE_UP,
+ SLIDE_DOWN,
+ SPIN,
+ TWIST,
+ APPEAR_WORD,
+ APPEAR_CHAR,
+ SCRAMBLE,
+}
+
+export enum AnimationPhase {
+ IN,
+ OUT,
+}
+
+export enum TextAlign {
+ LEFT,
+ CENTER,
+ RIGHT,
+}
+
+export enum TextBaseline {
+ TOP,
+ MIDDLE,
+ BOTTOM,
+ ALPHABETIC,
+}
+
+export enum TextCase {
+ ORIGINAL,
+ UPPER,
+ LOWER,
+}
+
+export enum FontStyle {
+ NORMAL,
+ ITALIC,
+ OBLIQUE,
+}
+
+export enum TransitionType {
+ DISSOLVE,
+ SLIDE_FROM_RIGHT,
+ SLIDE_FROM_LEFT,
+ FADE_TO_BLACK,
+ FADE_TO_WHITE,
+}
+
+export enum CaptionType {
+ CLASSIC,
+ CASCADE,
+ SPOTLIGHT,
+ WHISPER,
+ PAPER,
+ GUINEA,
+ STARK,
+}
+
+export enum CaptionAlign {
+ TOP,
+ CENTER,
+ BOTTOM,
+}
+
+export enum ToolType {
+ MOVE,
+ HAND,
+ BLADE,
+ SCENE,
+ RECT,
+ TEXT,
+ TEXT_EDIT,
+}
diff --git a/packages/runtime/src/index.ts b/packages/runtime/src/index.ts
index 2d476e48..a2fcc25c 100644
--- a/packages/runtime/src/index.ts
+++ b/packages/runtime/src/index.ts
@@ -1 +1,4 @@
-// Root entry: re-exports traits, world, actions, queries, and systems.
+export * from './constants';
+export * from './traits';
+export * from './capture';
+export * from './utils';
diff --git a/packages/runtime/src/traits/audio.ts b/packages/runtime/src/traits/audio.ts
new file mode 100644
index 00000000..4b3f2736
--- /dev/null
+++ b/packages/runtime/src/traits/audio.ts
@@ -0,0 +1,21 @@
+/* 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/. */
+
+import { trait } from 'koota';
+
+// Audio volume in decibels (0 dB = unity, -Infinity = silence).
+export const Volume = trait({ value: 0 });
+
+// Presence means muted.
+export const Muted = trait();
+
+// Runtime-only solo tag (not serialized).
+export const Soloed = trait();
+
+// Runtime-only: maps timeline time to AudioContext time while playing.
+export const AudioPlayback = trait({
+ wasPlaying: false,
+ contextOffsetInSeconds: 0,
+ timelineOffsetInSeconds: 0,
+});
diff --git a/packages/runtime/src/traits/derived.ts b/packages/runtime/src/traits/derived.ts
new file mode 100644
index 00000000..e482dfe0
--- /dev/null
+++ b/packages/runtime/src/traits/derived.ts
@@ -0,0 +1,63 @@
+/* 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/. */
+
+import { trait, type Entity } from 'koota';
+
+// Fully resolved per-frame values (base state + constraints + animations +
+// keyframes). Written by the motion and transform systems, read by render and
+// UI code. Never serialized.
+export const Computed = trait({
+ positionX: 0,
+ positionY: 0,
+ offsetX: 0,
+ offsetY: 0,
+ // Local-space origin of the entity's bounding rect. Non-zero only for
+ // Group containers whose children's AABB extends past (0, 0).
+ originX: 0,
+ originY: 0,
+ rotation: 0,
+ scaleX: 1,
+ scaleY: 1,
+ skewX: 0,
+ skewY: 0,
+ opacity: 1,
+ color: 0,
+ blur: 0,
+ volume: 0,
+ value: 0,
+ strokeWidth: 0,
+ cornerRadius: 0,
+ cornerRadiusTopLeft: 0,
+ cornerRadiusTopRight: 0,
+ cornerRadiusBottomRight: 0,
+ cornerRadiusBottomLeft: 0,
+ stopOffset: 0,
+ stopColor: 0,
+ stopOpacity: 1,
+ width: 0,
+ height: 0,
+ chars: undefined as string | undefined,
+ localTimeInSeconds: 0, // playhead position in seconds
+ localTime: 0, // playhead position in frames (mirrors localTimeInSeconds)
+ duration: 0, // frames
+ start: 0,
+ end: 0,
+ delay: 0,
+ visibility: 1,
+});
+
+// Per-entity owned-sub-entity lists. Populated by observers from ChildOf
+// queries; consumed by render, motion, and UI code. Never serialized.
+export const Cache = trait({
+ children: () => [] as Entity[],
+ fills: () => [] as Entity[],
+ shadows: () => [] as Entity[],
+ strokes: () => [] as Entity[],
+ effects: () => [] as Entity[],
+ textRanges: () => [] as Entity[],
+ masks: () => [] as Entity[],
+ keyframeTracks: () => [] as Entity[],
+ keyframes: () => [] as Entity[],
+ animations: () => [] as Entity[],
+});
diff --git a/packages/runtime/src/traits/index.ts b/packages/runtime/src/traits/index.ts
index 562f52a7..5553c0a2 100644
--- a/packages/runtime/src/traits/index.ts
+++ b/packages/runtime/src/traits/index.ts
@@ -1 +1,12 @@
-// Re-exports all trait definitions.
+export * from './relations';
+export * from './node';
+export * from './transform';
+export * from './style';
+export * from './text';
+export * from './timing';
+export * from './audio';
+export * from './motion';
+export * from './derived';
+export * from './media';
+export * from './interaction';
+export * from './world';
diff --git a/packages/runtime/src/traits/interaction.ts b/packages/runtime/src/traits/interaction.ts
new file mode 100644
index 00000000..93285702
--- /dev/null
+++ b/packages/runtime/src/traits/interaction.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/. */
+
+import { trait } from 'koota';
+
+// Editor interaction state. Defined here so all trait definitions share one
+// home, but only ever added by the editor app; never serialized.
+
+export const Selected = trait();
+
+export const Interactive = trait();
+
+export const Hovering = trait();
+
+export const Dragging = trait();
+
+// Timeline canvas view state (scroll/zoom).
+export const Timeline = trait({
+ scrollX: 0,
+ scrollY: 0,
+ resolution: 1,
+ transform: () => new DOMMatrix(),
+});
+
+// Snapshot of a clip's timing at the moment a drag started.
+export const ClipDragOrigin = trait({ delay: 0, start: 0, end: 0 });
+
+export const KeyframeDragOrigin = trait({ time: 0 });
+
+// Snapshot of the clip's start/end frames at the moment a trim interaction
+// began. Tagged on the single clip being trimmed; removed on release.
+export const TrimDragOrigin = trait({ start: 0, end: 0 });
diff --git a/packages/runtime/src/traits/media.ts b/packages/runtime/src/traits/media.ts
index bfa00f7e..6ad6679d 100644
--- a/packages/runtime/src/traits/media.ts
+++ b/packages/runtime/src/traits/media.ts
@@ -1 +1,37 @@
-// Media traits: decoder handles, asset references, ExportSettings, Effect.
+/* 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/. */
+
+import { trait } from 'koota';
+
+// Renderer-runtime state on mounted entities (never serialized).
+export type MountData = {
+ props: Record<string, unknown>;
+ textBox?: DocumentFragment;
+};
+
+// Handle traits store live runtime instances (hosts, decoders, buses) and are
+// never serialized. They use AoS storage: entity.get(X) returns the instance
+// directly. Handle types are opaque until engine/decoders and services move
+// into src/media; tighten them to the concrete classes then.
+type Handle = object;
+
+export const HtmlHost = trait(() => null as Handle | null);
+
+export const SurfaceHost = trait(() => null as Handle | null);
+
+export const ShaderHost = trait(() => null as Handle | null);
+
+export const ImageDecoder = trait(() => null as Handle | null);
+
+export const VideoDecoder = trait(() => null as Handle | null);
+
+export const SequenceDecoder = trait(() => null as Handle | null);
+
+export const AudioDecoder = trait(() => null as Handle | null);
+
+export const CaptionDecoder = trait(() => null as Handle | null);
+
+export const AudioBus = trait(() => null as Handle | null);
+
+export const Data = trait(() => null as MountData | null);
diff --git a/packages/runtime/src/traits/motion.ts b/packages/runtime/src/traits/motion.ts
new file mode 100644
index 00000000..4916ce1a
--- /dev/null
+++ b/packages/runtime/src/traits/motion.ts
@@ -0,0 +1,29 @@
+/* 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/. */
+
+import { trait, type Entity } from 'koota';
+
+import { AnimationType, AnimationPhase } from '../constants';
+
+// KeyframeTrack entity: one per (target, property) pair. ChildOf its target
+// (geometry, paint, color stop, ...) and owns the Keyframe entities as
+// children. `target` is denormalised: ChildOf is authoritative, but the keyed
+// lookup is refreshed when tracks are aggregated so motion/render don't have
+// to walk up the relation on every frame.
+export const KeyframeTrack = trait({
+ property: '',
+ target: null as Entity | null,
+});
+
+// Keyframe entity: ChildOf its KeyframeTrack. Easing applies to the segment
+// from this keyframe to the next-in-time on the same track.
+export const Keyframe = trait({ time: 0, value: 0, easing: 'linear' });
+
+// Animation entity: one preset in/out animation, ChildOf its target.
+export const Animation = trait({
+ type: AnimationType.FADE as AnimationType,
+ duration: 0, // frames
+ delay: 0, // frames
+ phase: AnimationPhase.IN as AnimationPhase,
+});
diff --git a/packages/runtime/src/traits/node.ts b/packages/runtime/src/traits/node.ts
index 4f95e0f5..0bda4d00 100644
--- a/packages/runtime/src/traits/node.ts
+++ b/packages/runtime/src/traits/node.ts
@@ -1 +1,96 @@
-// Node traits: Geometry, Paint, Group, Scene, Audio, Caption, AdjustmentLayer, masks, effects.
+/* 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/. */
+
+import { trait } from 'koota';
+
+import { GeometryType, PaintType, CaptionType, CaptionAlign } from '../constants';
+
+import type { VideoCodec, AudioCodec } from 'mediabunny';
+import type { ContainerFormat } from '../capture/format';
+
+// Geometric primitive: RECT or TEXT (see GeometryType). Other node-like roles
+// (group, audio, scene, caption) are layered on top via tag traits.
+export const Geometry = trait({ value: GeometryType.RECT as GeometryType });
+
+// Paint applied to a geometry (or stroke). See PaintType.
+export const Paint = trait({ value: PaintType.SOLID as PaintType });
+
+// Tag marking a geometry as a group container. Groups have no Size of their
+// own: their Computed.width/height are derived from the local AABB of their
+// direct children (see the transform system). They carry transform state
+// (Position/Rotation/Scale/...) like any other entity.
+export const Group = trait();
+
+// Tag marking a geometry as a scene: a clipped, playable frame. Scenes have a
+// fixed Size like any frame; the tag layers playback + clipping on top.
+// Scenes are NOT Groups.
+export const Scene = trait();
+
+// Tag marking a geometry as an audio clip (no visual rendering).
+export const Audio = trait();
+
+export const AdjustmentLayer = trait();
+
+// Tag marking an entity as a mask. Masks are ChildOf their target;
+// Cache.masks on the target is derived from IsMask + ChildOf queries.
+export const IsMask = trait();
+
+// Tag for shadow sub-entities (distinguishes them from other Effect
+// sub-entities in ChildOf queries).
+export const Shadow = trait();
+
+// Tag for stroke sub-entities (distinguishes them from the StrokeStyle trait
+// on the parent in ChildOf queries).
+export const Stroke = trait();
+
+export const Hidden = trait();
+
+export const ClipsContent = trait();
+
+// Tag for entities whose content is still being generated.
+export const Generating = trait();
+
+// Runtime-only tombstone: entity is soft-deleted and kept around for undo.
+export const Deleted = trait();
+
+export const Name = trait({ value: '' });
+
+// Stable identity for entities.
+export const Key = trait({ value: '' });
+
+export const AssetId = trait({ value: '' });
+
+// Sibling order under a ChildOf parent.
+export const ItemIndex = trait({ value: 0 });
+
+// On a mount's root entity: the compiled module (a SCRIPT asset) that a world
+// re-executes to rebuild this mount's reactive graph and runtime hosts.
+export const MountScript = trait({ mountId: '', scriptAssetId: '' });
+
+// On every entity a mount materializes: its stable structural key (an index
+// path from the mount root), so a re-run in adopt mode can bind to the
+// existing entity instead of minting a new one.
+export const MountPath = trait({ mountId: '', path: '' });
+
+// Caption preset configuration; only on CAPTION node entities. The transcript
+// is either a standalone TRANSCRIPT asset or embedded in an AUDIO/VIDEO
+// asset, referenced via AssetId.
+export const Caption = trait({
+ type: CaptionType.CLASSIC as CaptionType,
+ colors: () => [] as number[],
+ verticalAlign: undefined as CaptionAlign | undefined, // unset = the preset's default
+});
+
+export const ExportSettings = trait({
+ templateId: null as string | null,
+ format: undefined as ContainerFormat | undefined,
+ videoEnabled: undefined as boolean | undefined,
+ videoCodec: undefined as VideoCodec | undefined,
+ videoBitrate: undefined as number | undefined,
+ videoFps: undefined as number | undefined,
+ videoResolution: undefined as number | undefined,
+ audioEnabled: undefined as boolean | undefined,
+ audioCodec: undefined as AudioCodec | undefined,
+ audioSampleRate: undefined as number | undefined,
+});
diff --git a/packages/runtime/src/traits/relations.ts b/packages/runtime/src/traits/relations.ts
index 0d48cc7e..86473c98 100644
--- a/packages/runtime/src/traits/relations.ts
+++ b/packages/runtime/src/traits/relations.ts
@@ -1 +1,16 @@
-// Entity relations via koota relation(): ChildOf and friends.
+/* 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/. */
+
+import { relation } from 'koota';
+
+/**
+ * Universal parent-child relation. Replaces all array-based ownership:
+ * fills, shadows, strokes, effects, text ranges, tracks, clips, animations.
+ *
+ * exclusive: an entity has at most one parent; re-parenting replaces the
+ * previous target. autoDestroy 'orphan': destroying a parent destroys its
+ * whole subtree. Children are distinguished by their type tags (Shadow,
+ * Stroke, IsMask, ...). Sibling order is encoded via ItemIndex on each child.
+ */
+export const ChildOf = relation({ exclusive: true, autoDestroy: 'orphan' });
diff --git a/packages/runtime/src/traits/style.ts b/packages/runtime/src/traits/style.ts
new file mode 100644
index 00000000..2a4d3dd0
--- /dev/null
+++ b/packages/runtime/src/traits/style.ts
@@ -0,0 +1,53 @@
+/* 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/. */
+
+import { trait } from 'koota';
+
+import { BlendMode, EffectType, ScaleModeType, StrokeJoin, StrokeCap } from '../constants';
+
+export const Appearance = trait({
+ opacity: 1,
+ blendMode: BlendMode.SOURCE_OVER as BlendMode,
+});
+
+export const Color = trait({ value: 0 });
+
+export const CornerRadius = trait({ value: 0 });
+
+// Per-corner radii (CSS order: TL, TR, BR, BL).
+export const MixedCornerRadius = trait({
+ topLeft: 0,
+ topRight: 0,
+ bottomRight: 0,
+ bottomLeft: 0,
+});
+
+export const Blur = trait({ value: 0 });
+
+// Scale mode for image fills and any other scaled asset display.
+export const ScaleMode = trait({ value: ScaleModeType.COVER as ScaleModeType });
+
+// Effect sub-entity: one per applied effect, ChildOf its target.
+export const Effect = trait({
+ type: EffectType.DROP_SHADOW as EffectType,
+ value: 0,
+});
+
+// Single gradient stop. Each stop is its own entity, ChildOf the gradient
+// fill. Stop count is fixed for the lifetime of the fill: to animate between
+// gradients with different stop counts use a separate fill and cross-fade.
+export const ColorStop = trait({ offset: 0, color: 0, opacity: 1 });
+
+export const StrokeStyle = trait({
+ width: 1,
+ join: StrokeJoin.MITER as StrokeJoin,
+ cap: StrokeCap.BUTT as StrokeCap,
+ miterLimit: 10,
+});
+
+// Shader paint source (document data; the compiled host lives in ShaderHost).
+export const Shader = trait({
+ code: '',
+ uniforms: () => null as Record<string, number | number[] | string> | null,
+});
diff --git a/packages/runtime/src/traits/text.ts b/packages/runtime/src/traits/text.ts
new file mode 100644
index 00000000..d8400819
--- /dev/null
+++ b/packages/runtime/src/traits/text.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/. */
+
+import { trait } from 'koota';
+
+import { FontStyle, TextAlign, TextBaseline, TextCase } from '../constants';
+
+import type { Token } from '../utils/text';
+
+// Text characters: only on the parent text node, not shared with ranges.
+export const Chars = trait({ value: '' });
+
+// Text style properties, shared between a text node and its TextRange
+// sub-entities. On a text node this is the default style; on a range
+// sub-entity it overrides.
+export const TextStyle = trait({
+ leading: 1.2,
+ fontSize: 16,
+ fontFamily: '',
+ fontWeight: '400',
+ fontStyle: FontStyle.NORMAL as FontStyle,
+ textAlign: TextAlign.LEFT as TextAlign,
+ textBaseline: TextBaseline.TOP as TextBaseline,
+ textCase: TextCase.ORIGINAL as TextCase,
+ letterSpacing: 0, // extra spacing between characters (px)
+});
+
+// Character range a TextStyle override applies to; end null = to the end.
+export const TextRange = trait({ start: 0, end: null as number | null });
+
+// Runtime-only: cached text layout, one Token[] per line. Never serialized.
+export const TextCache = trait({ tokens: () => [] as Token[][] });
diff --git a/packages/runtime/src/traits/timing.ts b/packages/runtime/src/traits/timing.ts
index 22fd6c02..7ac0e448 100644
--- a/packages/runtime/src/traits/timing.ts
+++ b/packages/runtime/src/traits/timing.ts
@@ -1 +1,46 @@
-// Timing traits: clip in/out points, offsets, and keyframes.
+/* 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/. */
+
+import { trait } from 'koota';
+
+import { TransitionType } from '../constants';
+
+// Offset where the node starts inside its parent's timeline (frames).
+export const Delay = trait({ value: 0 });
+
+// Speed multiplier for the node's local time (1 = normal).
+export const PlaybackRate = trait({ value: 1 });
+
+// Explicit duration window in the clip's own local time. When present, the
+// node has fixed bounds (workarea on scenes, trimmed source on media clips).
+// When absent: scenes auto-fit to their children, other nodes have no
+// inherent duration (the runtime adds Trim immediately on creation).
+export const Trim = trait({ start: 0, end: 0 });
+
+// Explicit playback/export window on a scene.
+export const Workarea = trait({ start: 0, end: 0 });
+
+// Playback state of an entity.
+export const Playback = trait({
+ playing: false,
+ loop: false,
+ speed: 1, // playback speed multiplier (negative = reverse)
+});
+
+// Tag marking a container whose direct children cannot overlap in time.
+// Drag/trim of any direct child clamps at the neighbour's edge.
+export const Sequential = trait();
+
+// Transition between adjacent clips in a track. Stored on clip entities:
+// describes the transition INTO this clip from the previous one.
+export const Transition = trait({
+ type: TransitionType.DISSOLVE as TransitionType,
+ duration: 0, // frames
+});
+
+// Per-clip user-customized timeline row height (persisted).
+export const ClipHeight = trait({ value: 0 });
+
+// Tag: this clip's keyframe rows are expanded below the clip body (persisted).
+export const Expanded = trait();
diff --git a/packages/runtime/src/traits/transform.ts b/packages/runtime/src/traits/transform.ts
index 0b902601..d1e1c62a 100644
--- a/packages/runtime/src/traits/transform.ts
+++ b/packages/runtime/src/traits/transform.ts
@@ -1 +1,54 @@
-// Transform traits: Position, Rotation, Scale, Anchor, Skew, Flip, Size, and computed matrices.
+/* 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/. */
+
+import { trait } from 'koota';
+
+import { ConstraintType } from '../constants';
+
+export const Position = trait({ x: 0, y: 0 });
+
+export const Offset = trait({ x: 0, y: 0 });
+
+export const Rotation = trait({ value: 0 });
+
+export const Scale = trait({ x: 1, y: 1 });
+
+export const UniformScale = trait({ value: 1 });
+
+export const Anchor = trait({ x: 0, y: 0 });
+
+export const Skew = trait({ x: 0, y: 0 });
+
+export const Size = trait({ width: 0, height: 0 });
+
+export const Flip = trait({ x: 1 as -1 | 1, y: 1 as -1 | 1 });
+
+// Constraint anchoring relative to the parent frame (see ConstraintType).
+export const Constraint = trait({
+ horizontal: ConstraintType.MIN as ConstraintType,
+ vertical: ConstraintType.MIN as ConstraintType,
+});
+
+// Aspect ratio lock: captures the dimensions at the moment the trait is set.
+export const KeepAspectRatio = trait({ width: 0, height: 0 });
+
+// Derived state below: written by the transform system, never serialized.
+
+// Local 2D affine matrix from Offset, Rotation, Scale, Anchor, Skew and Size.
+export const LocalTransform = trait({ a: 1, b: 0, c: 0, d: 1, e: 0, f: 0 });
+
+export const WorldTransform = trait({ a: 1, b: 0, c: 0, d: 1, e: 0, f: 0 });
+
+export const WorldBounds = trait({ minX: 0, minY: 0, maxX: 0, maxY: 0 });
+
+// Tag: entity is outside the viewport this frame.
+export const Culled = trait();
+
+// Parent/child dimensions snapshotted for constraint resolution.
+export const ConstraintCache = trait({
+ parentWidth: 0,
+ parentHeight: 0,
+ childWidth: 0,
+ childHeight: 0,
+});
diff --git a/packages/runtime/src/utils/index.ts b/packages/runtime/src/utils/index.ts
index 857d3f77..e86991a6 100644
--- a/packages/runtime/src/utils/index.ts
+++ b/packages/runtime/src/utils/index.ts
@@ -1 +1,2 @@
-// Pure helpers only: time, text, sort, transition, captions. DOM-touching utils (cursor, interaction) stay in apps/web.
+// Pure helpers only: time, sort, transition, captions follow. DOM-touching utils (cursor, interaction) stay in apps/web.
+export * from './text';
diff --git a/packages/runtime/src/utils/text.ts b/packages/runtime/src/utils/text.ts
new file mode 100644
index 00000000..b53cd454
--- /dev/null
+++ b/packages/runtime/src/utils/text.ts
@@ -0,0 +1,95 @@
+/* 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/. */
+
+// Text layout data model. The layout, measurement, and canvas render helpers
+// join this file when engine/utils/text.ts moves into the runtime.
+
+export type TokenOptions = {
+ /**
+ * Defines the characters to render
+ */
+ chars: string;
+ /**
+ * Defines the X offset of the token to the left of the line
+ */
+ offset: number;
+ /**
+ * Defines the metrics of the token
+ */
+ metrics: TextMetrics;
+ /**
+ * Defines the style of the token
+ */
+ ranges: number[];
+}
+
+export type Line = {
+ offsetX: number;
+ offsetY: number;
+ baseline: number;
+ height: number;
+};
+
+export class Token {
+ public offset: number;
+ public metrics: TextMetrics;
+ public ranges: number[];
+ public chars: string;
+ public width: number;
+ public height: number;
+ public line = { offsetX: 0, offsetY: 0, baseline: 0, height: 0 };
+
+ constructor(options: TokenOptions) {
+ this.offset = options.offset;
+ this.metrics = options.metrics;
+ this.ranges = options.ranges;
+ this.width = options.metrics.width;
+ this.height = options.metrics.fontBoundingBoxAscent + options.metrics.fontBoundingBoxDescent;
+ this.chars = options.chars;
+ }
+
+ public get x(): number {
+ return (this.offset + this.line.offsetX) | 0;
+ }
+
+ public get y(): number {
+ return (this.line.offsetY + this.line.baseline) | 0;
+ }
+
+ public get left(): number {
+ return (
+ this.offset +
+ this.line.offsetX -
+ this.metrics.actualBoundingBoxLeft
+ ) | 0;
+ }
+
+ public get right(): number {
+ return (
+ this.offset +
+ this.line.offsetX +
+ this.metrics.actualBoundingBoxRight
+ ) | 0;
+ }
+
+ public get top(): number {
+ return (
+ this.line.offsetY +
+ this.line.baseline -
+ this.metrics.actualBoundingBoxAscent
+ ) | 0
+ }
+
+ public get bottom(): number {
+ return (
+ this.line.offsetY +
+ this.line.baseline +
+ this.metrics.actualBoundingBoxDescent
+ ) | 0
+ }
+
+ public setLine(line: Line) {
+ this.line = { ...line };
+ }
+}
diff --git a/packages/runtime/tsconfig.json b/packages/runtime/tsconfig.json
index 5bf184ea..d3ad84ef 100644
--- a/packages/runtime/tsconfig.json
+++ b/packages/runtime/tsconfig.json
@@ -2,6 +2,7 @@
"extends": "../../tsconfig.base.json",
"compilerOptions": {
"tsBuildInfoFile": "./node_modules/.tmp/tsconfig.tsbuildinfo",
+ "erasableSyntaxOnly": false,
"lib": ["es2024", "dom"]
},
"include": ["src"]