@scenerok/sdk 0.8.0 → 0.10.0

package/dist/ir-builder.js

@@ -1,18 +1,99 @@
 /**
- * Shared IR builder — appends SDK nodes onto an IRTimeline.
- * Used by @scenerok/sdk Timeline and (later) optionally by the VidScript compiler.
+ * IR lowering for SDK nodes — the TypeScript twin of the VidScript compiler's
+ * placement rules (`placeVidValue` in the platform's `src/parser/compiler-v2.ts`),
+ * so an SDK scene and the VidScript that says the same thing emit the same IR.
+ *
+ * A timeline records placements and lowers them in `toIR()`. Lowering late lets
+ * a nested timeline take its parent's canvas and share its id counter.
  */
 import { defaultIRTimeline, } from './ir.js';
 import { toSeconds } from './duration.js';
+import { frameRateOf, isFractionalTimeBase, snapToFrame, timecodeToSeconds } from './frame-rate.js';
 import { defaultGridSpec, placementFromGridArea, resolveGridAreas, } from './grid.js';
+import { DEFAULT_STILL_LENGTH, playedLength } from './media.js';
+import { animationsToMotionTracks } from './motion-tracks.js';
 import { isSchedulable } from './types.js';
-let idCounter = 0;
-export function resetIrBuilderIds(seed = 0) {
-    idCounter = seed;
+const FALLBACK_CANVAS = { width: 1080, height: 1920, fps: 30 };
+/**
+ * The canvas `timeline()` uses when it gives no size: the host's (a VidScript
+ * import sets `globalThis.__scenerokCanvas` to the importing script's output),
+ * else 1080×1920 at 30 fps.
+ */
+export function hostCanvas() {
+    const host = globalThis.__scenerokCanvas;
+    return {
+        width: positive(host?.width) ?? FALLBACK_CANVAS.width,
+        height: positive(host?.height) ?? FALLBACK_CANVAS.height,
+        fps: positive(host?.fps) ?? FALLBACK_CANVAS.fps,
+    };
+}
+function positive(value) {
+    return typeof value === 'number' && Number.isFinite(value) && value > 0 ? value : undefined;
+}
+/** @deprecated Ids are numbered per `toIR()` call now; kept for compatibility. */
+export function resetIrBuilderIds(_seed = 0) {
+    // Each lowering starts its own counter, so output is deterministic without a reset.
+}
+export function createIrBuilder(options = {}, canvas = hostCanvas(), ids = { next: 0 }) {
+    const ir = defaultIRTimeline();
+    ir.width = options.width ?? canvas.width;
+    ir.height = options.height ?? canvas.height;
+    ir.fps = options.fps ?? canvas.fps;
+    if (options.background != null)
+        ir.background = options.background;
+    const timeBase = frameRateOf(ir.fps);
+    if (isFractionalTimeBase(timeBase))
+        ir.timeBase = timeBase;
+    const out = options.output ?? {};
+    ir.output = {
+        ...ir.output,
+        path: out.path ?? ir.output.path,
+        format: out.format ?? ir.output.format,
+        codec: out.codec ?? ir.output.codec,
+        bitrate: out.bitrate ?? ir.output.bitrate,
+        resolution: out.resolution ?? `${ir.width}x${ir.height}`,
+        fps: out.fps ?? ir.fps,
+    };
+    if (out.startTimecode !== undefined) {
+        // Validates the fields against the output rate; throws with the reason.
+        timecodeToSeconds(out.startTimecode, ir.output.fps, 'startTimecode');
+        ir.output.startTimecode = out.startTimecode;
+    }
+    if (out.burnIn !== undefined) {
+        if (out.burnIn !== 'timecode')
+            throw new TypeError(`output burnIn must be 'timecode', got '${String(out.burnIn)}'`);
+        ir.output.burnIn = 'timecode';
+    }
+    return { ir, visualCursor: 0, audioCursor: 0, gridAreas: null, timeBase, ids };
+}
+function nextId(state, prefix) {
+    state.ids.next += 1;
+    return `${prefix}-${state.ids.next}`;
+}
+/** Declare or replace the timeline grid used by `area:` placement. */
+export function setGrid(state, spec) {
+    const areas = resolveGridAreas(spec);
+    state.gridAreas = areas;
+    return areas;
 }
-function nextId(prefix) {
-    idCounter += 1;
-    return `${prefix}-${idCounter}`;
+function gridRect(state, areaName) {
+    const areas = state.gridAreas
+        ?? resolveGridAreas(defaultGridSpec(state.ir.width, state.ir.height));
+    const rect = areas.get(areaName);
+    if (!rect) {
+        throw new Error(`Unknown grid area '${areaName}' (available: ${[...areas.keys()].join(', ')})`);
+    }
+    return rect;
+}
+/** The pixel rect of a grid area (videos, images, and solids place by their top-left). */
+function gridPixelRect(state, areaName) {
+    const rect = gridRect(state, areaName);
+    return {
+        x: (rect.x / 100) * state.ir.width,
+        y: (rect.y / 100) * state.ir.height,
+        width: (rect.width / 100) * state.ir.width,
+        height: (rect.height / 100) * state.ir.height,
+    };
 }
 function definedEntries(partial) {
     const out = {};
@@ -22,52 +103,32 @@ function definedEntries(partial) {
     }
     return out;
 }
-function defaultTextStyle(partial = {}) {
-    return {
-        font: 'Inter',
-        size: 48,
-        color: '#FFFFFF',
-        stroke: 'transparent',
-        strokeWidth: 0,
-        position: 'center',
-        bold: false,
-        italic: false,
-        x: '50%',
-        y: '50%',
-        rotation: 0,
-        opacity: 1,
-        align: 'center',
-        lineHeight: 1.2,
-        letterSpacing: 0,
-        shadowColor: 'transparent',
-        shadowBlur: 0,
-        shadowOffsetX: 0,
-        shadowOffsetY: 0,
-        ...definedEntries(partial),
-    };
+function bumpDuration(state, end) {
+    if (end > state.ir.duration)
+        state.ir.duration = end;
 }
+// ─── Animation ───
 function isExitFade(descriptor) {
-    return (descriptor.type === 'fade'
-        && descriptor.from?.opacity === 1
-        && descriptor.to?.opacity === 0);
+    return descriptor.type === 'fade' && descriptor.from?.opacity === 1 && descriptor.to?.opacity === 0;
 }
-function resolveAnimationWindow(descriptor, blockStart, blockEnd) {
+function animationWindow(descriptor, blockStart, blockEnd) {
     const span = Math.max(0, blockEnd - blockStart);
     const duration = descriptor.duration > 0 ? Math.min(descriptor.duration, span) : span;
-    const alignEnd = descriptor.align === 'end' || isExitFade(descriptor);
-    if (alignEnd) {
+    if (descriptor.align === 'end' || isExitFade(descriptor)) {
         return { start: blockEnd - duration, end: blockEnd };
     }
     return { start: blockStart, end: Math.min(blockEnd, blockStart + duration) };
 }
-function lowerAnimations(descriptors, blockStart, blockEnd) {
-    const animations = [];
-    const motion = [];
-    for (const descriptor of descriptors) {
-        const window = resolveAnimationWindow(descriptor, blockStart, blockEnd);
-        const id = nextId('anim');
-        animations.push({
-            id,
+function normalizeAnims(animate) {
+    if (!animate)
+        return [];
+    return Array.isArray(animate) ? animate : [animate];
+}
+function lowerAnimations(state, descriptors, blockStart, blockEnd) {
+    const animations = descriptors.map((descriptor) => {
+        const window = animationWindow(descriptor, blockStart, blockEnd);
+        return {
+            id: nextId(state, 'anim'),
             type: descriptor.type,
             plugin: descriptor.plugin,
             from: { ...descriptor.from },
@@ -76,128 +137,442 @@ function lowerAnimations(descriptors, blockStart, blockEnd) {
             end: window.end,
             easing: descriptor.easing,
             loop: descriptor.loop,
-        });
-        // Lower common opacity / transform props into motion tracks (preview/render parity).
-        for (const key of Object.keys({ ...descriptor.from, ...descriptor.to })) {
-            const fromVal = descriptor.from[key];
-            const toVal = descriptor.to[key];
-            if (fromVal === undefined && toVal === undefined)
-                continue;
-            motion.push({
-                id: nextId('motion'),
-                target: key,
-                sourceAnimationId: id,
-                plugin: descriptor.plugin,
-                keyframes: [
-                    { time: window.start, value: (fromVal ?? toVal) },
-                    { time: window.end, value: (toVal ?? fromVal) },
-                ],
-            });
+        };
+    });
+    return { animations, motion: animationsToMotionTracks(animations) };
+}
+function attachAnimations(state, target, descriptors, start, end) {
+    if (descriptors.length === 0)
+        return;
+    const { animations, motion } = lowerAnimations(state, descriptors, start, end);
+    target.animations = [...(target.animations ?? []), ...animations];
+    target.motion = [...(target.motion ?? []), ...motion];
+}
+// ─── Placement properties (VidScript `applyVideoParams`) ───
+const BLEND_MODES = ['normal', 'multiply', 'screen', 'overlay', 'difference', 'add', 'subtract', 'darken', 'lighten'];
+const BLEND_ALIASES = {
+    'source-over': 'normal',
+    src: 'normal',
+    'linear-dodge': 'add',
+    lineardodge: 'add',
+    'linear-burn': 'subtract',
+    'color-dodge': 'screen',
+    'color-burn': 'multiply',
+    'soft-light': 'overlay',
+    'hard-light': 'overlay',
+};
+export function normalizeBlendMode(raw) {
+    const key = String(raw).trim().toLowerCase().replace(/[\s_]/g, '-');
+    const mode = BLEND_MODES.includes(key) ? key : BLEND_ALIASES[key];
+    if (!mode)
+        throw new RangeError(`Unsupported blend mode '${raw}'. Use one of: ${BLEND_MODES.join(', ')}.`);
+    return mode;
+}
+function resolveMotionBlur(option) {
+    if (option === false)
+        return null;
+    const spec = option === true ? {} : option;
+    const shutter = spec.shutter ?? 180;
+    const samples = spec.samples ?? 8;
+    if (!(shutter > 0 && shutter <= 360))
+        throw new RangeError(`motionBlur shutter must be above 0 and at most 360, got ${shutter}`);
+    if (!Number.isInteger(samples) || samples < 2 || samples > 64) {
+        throw new RangeError(`motionBlur samples must be a whole number from 2 to 64, got ${samples}`);
+    }
+    return { shutter, samples };
+}
+function validateCorners(corners) {
+    if (!Array.isArray(corners) || corners.length !== 4
+        || corners.some((p) => !Array.isArray(p) || p.length < 2 || !p.every((n) => Number.isFinite(n)))) {
+        throw new TypeError('corners must be four [x, y] points in output pixels, TL → TR → BR → BL.');
+    }
+    return corners.map((p) => [p[0], p[1]]);
+}
+/** Geometry, opacity, motion, and shape of a placed picture, written onto a clip. */
+function applyPlacement(state, clip, opts) {
+    attachAnimations(state, clip, normalizeAnims(opts.animate), clip.start, clip.end);
+    if (opts.area !== undefined) {
+        const rect = gridPixelRect(state, opts.area);
+        clip.x = rect.x;
+        clip.y = rect.y;
+        clip.width = rect.width;
+        clip.height = rect.height;
+    }
+    if (opts.width !== undefined)
+        clip.width = opts.width;
+    if (opts.height !== undefined)
+        clip.height = opts.height;
+    if (opts.x !== undefined)
+        clip.x = opts.x;
+    if (opts.y !== undefined)
+        clip.y = opts.y;
+    if (opts.opacity !== undefined)
+        clip.opacity = opts.opacity;
+    if (typeof opts.rotation === 'number' && !(clip.motion ?? []).some((t) => t.target === 'transform.rotation.z')) {
+        attachAnimations(state, clip, [{
+                __sdk: true, kind: 'animation', type: 'rotation',
+                from: { rotation: opts.rotation }, to: { rotation: opts.rotation }, duration: 0,
+            }], clip.start, clip.end);
+    }
+    if (opts.radius !== undefined) {
+        if (!Number.isFinite(opts.radius) || opts.radius < 0)
+            throw new RangeError(`Invalid radius '${opts.radius}'.`);
+        if (opts.radius > 0)
+            clip.radius = opts.radius;
+    }
+    if (opts.corners !== undefined)
+        clip.corners = validateCorners(opts.corners);
+    if (opts.inputColorspace !== undefined || opts.outputColorspace !== undefined) {
+        clip.colorspace = definedEntries({ input: opts.inputColorspace, output: opts.outputColorspace });
+    }
+    if (opts.motionBlur !== undefined) {
+        const blur = resolveMotionBlur(opts.motionBlur);
+        if (blur)
+            clip.motionBlur = blur;
+    }
+}
+/** What a blended item draws over: anything visible in its window. */
+function findBelow(state, start, end, exceptId) {
+    const { ir } = state;
+    const overlaps = (item) => item.start < end && item.end > start;
+    const below = [...ir.clips].reverse().find((c) => c.id !== exceptId && overlaps(c))
+        ?? [...(ir.groups ?? [])].reverse().find((g) => g.id !== exceptId && overlaps(g))
+        ?? [...ir.layers].reverse().find((l) => l.type === 'text' && overlaps(l))
+        ?? [...ir.surfaces].reverse().find(overlaps);
+    if (!below) {
+        throw new Error(`blend needs something below it to blend with in ${start}s..${end}s; place it first`);
+    }
+    return below;
+}
+function markIr(ir) {
+    return {
+        clips: ir.clips.length,
+        layers: ir.layers.length,
+        surfaces: ir.surfaces.length,
+        groups: ir.groups?.length ?? 0,
+        effects: ir.effects.length,
+        audio: ir.audio.length,
+        markers: ir.markers?.length ?? 0,
+    };
+}
+function takePictureItems(ir, marks) {
+    const items = {
+        clips: ir.clips.splice(marks.clips),
+        layers: ir.layers.splice(marks.layers),
+        surfaces: ir.surfaces.splice(marks.surfaces),
+        groups: (ir.groups ?? []).splice(marks.groups),
+        effects: ir.effects.splice(marks.effects),
+    };
+    if (ir.groups && ir.groups.length === 0)
+        delete ir.groups;
+    return items;
+}
+function shiftTimed(item, delta) {
+    return {
+        ...item,
+        start: item.start + delta,
+        end: item.end + delta,
+        ...(item.animations ? { animations: item.animations.map((a) => ({ ...a, start: a.start + delta, end: a.end + delta })) } : {}),
+        ...(item.motion
+            ? { motion: item.motion.map((t) => ({ ...t, keyframes: t.keyframes.map((k) => ({ ...k, time: k.time + delta })) })) }
+            : {}),
+    };
+}
+function shiftPicture(items, delta) {
+    if (delta === 0)
+        return items;
+    return {
+        clips: items.clips.map((c) => shiftTimed(c, delta)),
+        layers: items.layers.map((l) => (l.type === 'text' ? shiftTimed(l, delta) : { ...l, start: l.start + delta, end: l.end + delta })),
+        surfaces: items.surfaces.map((s) => shiftTimed(s, delta)),
+        // A group's children are in its own time; only the group moves.
+        groups: items.groups.map((g) => shiftTimed(g, delta)),
+        effects: items.effects.map((e) => shiftTimed(e, delta)),
+    };
+}
+function checkGroupChildren(items) {
+    if (items.surfaces.some((s) => s.type === 'transition')) {
+        throw new Error('A transition cannot be inside a group (it draws outside the compositor); keep it on the top-level timeline');
+    }
+}
+/**
+ * Move what a placement just emitted into one `IRGroup` — VidScript's
+ * `wrapAddedItemsInGroup`. Children land in group-local time; audio and
+ * markers stay on the timeline.
+ */
+function wrapInGroup(state, marks, start, end, placement) {
+    const { ir } = state;
+    const items = shiftPicture(takePictureItems(ir, marks), -start);
+    checkGroupChildren(items);
+    const { blend, ...props } = placement.props;
+    const width = placement.size?.width ?? ir.width;
+    const height = placement.size?.height ?? ir.height;
+    // Placement properties are a clip's: a scratch clip takes them, the group reads them back.
+    const scratch = {
+        id: nextId(state, 'group'), source: '', start, end, trimStart: 0, trimEnd: 0, speed: 1, loop: 1,
+        opacity: 1, width, height, x: 0, y: 0,
+    };
+    applyPlacement(state, scratch, props);
+    const grades = [
+        ...items.effects,
+        ...placement.effects.map((effect) => ({ ...effect, id: nextId(state, 'fx'), start: 0, end: end - start })),
+    ];
+    const group = {
+        id: scratch.id,
+        start,
+        end,
+        clips: items.clips,
+        layers: items.layers,
+        surfaces: items.surfaces,
+        ...(items.groups.length > 0 ? { groups: items.groups } : {}),
+        ...(grades.length > 0 ? { effects: grades } : {}),
+        width,
+        height,
+        x: scratch.x,
+        y: scratch.y,
+        opacity: scratch.opacity,
+    };
+    if (scratch.width !== width)
+        group.displayWidth = scratch.width;
+    if (scratch.height !== height)
+        group.displayHeight = scratch.height;
+    if (scratch.radius !== undefined)
+        group.radius = scratch.radius;
+    if (scratch.corners)
+        group.corners = scratch.corners;
+    if (scratch.animations)
+        group.animations = scratch.animations;
+    if (scratch.motion)
+        group.motion = scratch.motion;
+    if (scratch.motionBlur)
+        group.motionBlur = scratch.motionBlur;
+    if (placement.crop) {
+        const c = placement.crop;
+        if (c.x + c.width > width || c.y + c.height > height) {
+            throw new RangeError(`crop ${c.width}x${c.height} at (${c.x}, ${c.y}) is outside the ${width}x${height} picture`);
+        }
+        group.crop = c;
+    }
+    if (blend !== undefined) {
+        const mode = normalizeBlendMode(blend);
+        if (mode !== 'normal') {
+            findBelow(state, start, end);
+            group.blend = mode;
         }
     }
-    return { animations, motion };
+    (ir.groups ??= []).push(group);
+    return group;
 }
-export function createIrBuilder(options = {}) {
-    const ir = defaultIRTimeline();
-    if (options.width != null)
-        ir.width = options.width;
-    if (options.height != null)
-        ir.height = options.height;
-    if (options.fps != null)
-        ir.fps = options.fps;
-    if (options.background != null)
-        ir.background = options.background;
-    const out = options.output ?? {};
-    ir.output = {
-        ...ir.output,
-        path: out.path ?? ir.output.path,
-        format: out.format ?? ir.output.format,
-        codec: out.codec ?? ir.output.codec,
-        bitrate: out.bitrate ?? ir.output.bitrate,
-        resolution: out.resolution
-            ?? `${ir.width}x${ir.height}`,
-        fps: out.fps ?? ir.fps,
+/** The matte of a mask: the value placed over the host's window, as a group in local time. */
+function buildMatte(state, matte, start, end) {
+    const { ir } = state;
+    const marks = markIr(ir);
+    scheduleAt(state, start, end, matte, { snap: false, advance: false });
+    ir.audio.splice(marks.audio);
+    ir.markers?.splice(marks.markers);
+    const items = shiftPicture(takePictureItems(ir, marks), -start);
+    checkGroupChildren(items);
+    return {
+        id: nextId(state, 'matte'),
+        start: 0,
+        end: end - start,
+        clips: items.clips,
+        layers: items.layers,
+        surfaces: items.surfaces,
+        ...(items.groups.length > 0 ? { groups: items.groups } : {}),
+        ...(items.effects.length > 0 ? { effects: items.effects } : {}),
+        width: ir.width,
+        height: ir.height,
+        x: 0,
+        y: 0,
+        opacity: 1,
     };
-    return { ir, visualCursor: 0, audioCursor: 0, gridAreas: null };
 }
-/** Declare or replace the timeline grid used by `area:` text placement. */
-export function setGrid(state, spec) {
-    const areas = resolveGridAreas(spec);
-    state.gridAreas = areas;
-    return areas;
+function attachMask(state, group, mask) {
+    group.mask = { group: buildMatte(state, mask.matte, group.start, group.end), mode: mask.mode };
 }
-function resolveTextAreaPlacement(state, areaName) {
-    const areas = state.gridAreas
-        ?? resolveGridAreas(defaultGridSpec(state.ir.width, state.ir.height));
-    const rect = areas.get(areaName);
-    if (!rect) {
-        throw new Error(`Unknown grid area '${areaName}' (available: ${[...areas.keys()].join(', ')})`);
+/** Run `place`; with a blend other than `normal`, what it emitted becomes a blended group. */
+function placeBlended(state, blend, start, end, place) {
+    if (blend === undefined || normalizeBlendMode(blend) === 'normal') {
+        place();
+        return;
     }
-    return placementFromGridArea(rect);
+    const marks = markIr(state.ir);
+    place();
+    wrapInGroup(state, marks, start, end, { props: { blend }, effects: [] });
 }
-function bumpDuration(state, end) {
-    if (end > state.ir.duration)
-        state.ir.duration = end;
+// ─── Kinds ───
+/** EBU R128 targets VidScript applies to generated sound and `loudness: "ebu-r128"`. */
+const EBU_R128 = {
+    loudnessNormalization: 'ebu-r128',
+    targetLufs: -16,
+    truePeakDb: -1.5,
+    loudnessRangeLufs: 11,
+};
+/**
+ * How long a value with a known length occupies a window: its own length when
+ * shorter (a clip ends when it stops playing), else the window.
+ */
+function fitToWindow(known, start, end) {
+    const span = Math.max(0, end - start);
+    if (known > 0 && (span <= 0 || known < span))
+        return known;
+    return span;
 }
-function scheduleVideo(state, start, end, clip) {
-    const { animations, motion } = lowerAnimations(clip.animations, start, end);
-    const irClip = {
-        id: nextId('clip'),
-        source: clip.source,
+function scheduleMedia(state, start, end, node) {
+    const opts = node.options;
+    if (opts.enabled === false)
+        return end;
+    const edits = node.edits ?? {};
+    if (edits.mask) {
+        // The matte multiplies the picture as one unit, so the clip draws in a
+        // group; only `blend` belongs to the group, which sees the picture below.
+        const { blend, ...clipOpts } = opts;
+        const marks = markIr(state.ir);
+        const clipEnd = scheduleMedia(state, start, end, {
+            ...node, options: clipOpts, edits: { ...edits, mask: undefined },
+        });
+        const group = wrapInGroup(state, marks, start, clipEnd, { props: blend === undefined ? {} : { blend }, effects: [] });
+        attachMask(state, group, edits.mask);
+        return clipEnd;
+    }
+    const mediaDuration = node.kind === 'video' ? node.mediaDuration : undefined;
+    const played = node.kind === 'video' ? playedLength(edits, mediaDuration) : 0;
+    const clipEnd = start + fitToWindow(played, start, end);
+    const sequence = node.kind === 'video' ? node.sequence : undefined;
+    const rate = node.kind === 'video' && !sequence ? node.options.rate : undefined;
+    const clip = {
+        id: nextId(state, 'clip'),
+        source: node.source,
+        ...(sequence ? { sequence } : {}),
+        ...(rate !== undefined ? { sourceRate: rate } : {}),
         start,
-        end,
-        trimStart: clip.options.trimStart != null ? toSeconds(clip.options.trimStart) : 0,
-        trimEnd: clip.options.trimEnd != null ? toSeconds(clip.options.trimEnd) : 0,
-        speed: clip.options.speed ?? 1,
-        loop: clip.options.loop ?? 0,
-        opacity: clip.options.opacity ?? 1,
-        width: clip.options.width ?? state.ir.width,
-        height: clip.options.height ?? state.ir.height,
-        x: clip.options.x ?? 0,
-        y: clip.options.y ?? 0,
-        animations: animations.length ? animations : undefined,
-        motion: motion.length ? motion : undefined,
+        end: clipEnd,
+        trimStart: edits.trimStart ?? 0,
+        trimEnd: edits.trimEnd ?? 0,
+        speed: edits.speed ?? 1,
+        loop: edits.loop ?? 1,
+        opacity: edits.opacity ?? 1,
+        width: edits.width ?? state.ir.width,
+        height: edits.height ?? state.ir.height,
+        x: 0,
+        y: 0,
+        ...(edits.crop ? { crop: edits.crop } : {}),
+    };
+    applyPlacement(state, clip, opts);
+    if (edits.effects && edits.effects.length > 0)
+        clip.effects = edits.effects.map((e) => ({ ...e }));
+    let compositeMode;
+    if (opts.blend !== undefined) {
+        const mode = normalizeBlendMode(opts.blend);
+        if (mode !== 'normal')
+            compositeMode = mode;
+    }
+    const below = compositeMode ? findBelow(state, clip.start, clip.end, clip.id) : null;
+    state.ir.clips.push(clip);
+    if (compositeMode && below) {
+        // `blend:` on a clip lowers to a composite layer over what is below it.
+        state.ir.layers.push({
+            type: 'composite',
+            id: nextId(state, 'composite'),
+            targetClipId: below.id,
+            otherClipId: clip.id,
+            start: clip.start,
+            end: clip.end,
+            x: 0,
+            y: 0,
+            opacity: clip.opacity,
+            mode: compositeMode,
+        });
+    }
+    if (node.kind === 'video' && opts.nativeAudio)
+        addClipSound(state, clip, opts.volume);
+    return clipEnd;
+}
+/**
+ * A generated clip's own sound, cut the way the clip is (VidScript `addClipSound`):
+ * from its in-point, one pass of its source range. Audio cannot retime, so a
+ * sped-up clip's sound is left out and a looped clip's plays once.
+ */
+function addClipSound(state, clip, volume) {
+    if (clip.speed !== 1)
+        return;
+    const placed = Math.max(0, clip.end - clip.start);
+    const loop = Math.max(1, Math.floor(clip.loop || 1));
+    const onePass = clip.trimEnd > clip.trimStart ? clip.trimEnd - clip.trimStart : placed / loop;
+    const duration = Math.min(placed, onePass);
+    if (duration <= 0)
+        return;
+    state.ir.audio.push({
+        id: nextId(state, 'audio'),
+        source: clip.source,
+        start: clip.start,
+        duration,
+        volume: volume ?? 1,
+        fadeIn: 0,
+        fadeOut: 0,
+        ...(clip.trimStart > 0 ? { sourceOffset: clip.trimStart } : {}),
+        ...EBU_R128,
+    });
+}
+function defaultTextStyle(partial = {}) {
+    return {
+        font: 'Inter',
+        size: 48,
+        color: '#FFFFFF',
+        stroke: 'transparent',
+        strokeWidth: 0,
+        position: 'center',
+        bold: false,
+        italic: false,
+        x: '50%',
+        y: '50%',
+        rotation: 0,
+        opacity: 1,
+        align: 'center',
+        lineHeight: 1.2,
+        letterSpacing: 0,
+        shadowColor: 'transparent',
+        shadowBlur: 0,
+        shadowOffsetX: 0,
+        shadowOffsetY: 0,
+        ...definedEntries(partial),
     };
-    state.ir.clips.push(irClip);
-    state.visualCursor = Math.max(state.visualCursor, end);
-    bumpDuration(state, end);
 }
 function scheduleText(state, start, end, layer) {
     const opts = layer.options;
-    const { animations, motion } = lowerAnimations(layer.animations, start, end);
-    // Resolve `area:` like VidScript: center in the cell and cap maxWidth/maxHeight.
-    // Explicit x/y/maxWidth/maxHeight win over the area.
-    let areaX;
-    let areaY;
-    let areaMaxWidth;
-    let areaMaxHeight;
-    if (opts.area) {
-        const placement = resolveTextAreaPlacement(state, opts.area);
-        areaX = placement.x;
-        areaY = placement.y;
-        areaMaxWidth = placement.maxWidth;
-        areaMaxHeight = placement.maxHeight;
+    if (opts.enabled === false)
+        return;
+    if (opts.stagger !== undefined && opts.stagger !== 'word' && opts.stagger !== 'char') {
+        throw new RangeError(`Unsupported stagger '${String(opts.stagger)}'. Use "word" or "char".`);
     }
+    // `area:` centres in the cell and caps maxWidth/maxHeight, as VidScript does.
+    let area;
+    if (opts.area)
+        area = placementFromGridArea(gridRect(state, opts.area));
     const style = defaultTextStyle({
         font: opts.font,
         size: opts.size,
+        minSize: opts.minSize,
         color: opts.color,
         stroke: opts.stroke,
         strokeWidth: opts.strokeWidth,
         bold: opts.bold,
         italic: opts.italic,
-        x: opts.x ?? areaX ?? '50%',
-        y: opts.y ?? areaY ?? '50%',
+        x: opts.x ?? area?.x ?? '50%',
+        y: opts.y ?? area?.y ?? '50%',
         rotation: opts.rotation,
         opacity: opts.opacity,
         align: opts.align,
         lineHeight: opts.lineHeight,
         letterSpacing: opts.letterSpacing,
         position: opts.position ?? 'center',
+        stagger: opts.stagger,
         fit: opts.fit,
         overflow: opts.overflow,
-        maxWidth: opts.maxWidth ?? areaMaxWidth,
-        maxHeight: opts.maxHeight ?? areaMaxHeight,
+        safeArea: opts.safeArea,
+        maxWidth: opts.maxWidth ?? area?.maxWidth,
+        maxHeight: opts.maxHeight ?? area?.maxHeight,
         maxLines: opts.maxLines,
         anchor: opts.anchor,
         shadowColor: opts.shadowColor,
@@ -205,65 +580,109 @@ function scheduleText(state, start, end, layer) {
         shadowOffsetX: opts.shadowOffsetX,
         shadowOffsetY: opts.shadowOffsetY,
     });
-    const textLayer = {
-        type: 'text',
-        id: nextId('text'),
-        content: layer.content,
-        start,
-        end,
-        style,
-        animations: animations.length ? animations : undefined,
-        motion: motion.length ? motion : undefined,
-    };
-    state.ir.layers.push(textLayer);
-    state.visualCursor = Math.max(state.visualCursor, end);
-    bumpDuration(state, end);
+    placeBlended(state, opts.blend, start, end, () => {
+        const textLayer = {
+            type: 'text',
+            id: nextId(state, 'text'),
+            content: layer.content,
+            start,
+            end,
+            style,
+        };
+        attachAnimations(state, textLayer, layer.animations, start, end);
+        state.ir.layers.push(textLayer);
+    });
+}
+function scheduleSolid(state, start, end, node) {
+    const opts = node.options;
+    if (opts.enabled === false)
+        return;
+    const rect = opts.area !== undefined ? gridPixelRect(state, opts.area) : null;
+    if (opts.radius !== undefined && (!Number.isFinite(opts.radius) || opts.radius < 0)) {
+        throw new RangeError(`Invalid radius '${opts.radius}'.`);
+    }
+    placeBlended(state, opts.blend, start, end, () => {
+        const surface = {
+            id: nextId(state, 'surface'),
+            type: 'solid',
+            start,
+            end,
+            data: {
+                color: node.color,
+                width: opts.width ?? rect?.width ?? state.ir.width,
+                height: opts.height ?? rect?.height ?? state.ir.height,
+                x: opts.x ?? rect?.x ?? 0,
+                y: opts.y ?? rect?.y ?? 0,
+                opacity: opts.opacity ?? 1,
+                ...(opts.radius ? { radius: opts.radius } : {}),
+                ...(opts.corners ? { corners: validateCorners(opts.corners) } : {}),
+            },
+        };
+        attachAnimations(state, surface, normalizeAnims(opts.animate), start, end);
+        state.ir.surfaces.push(surface);
+    });
 }
 function scheduleAudio(state, start, end, track) {
-    const duration = Math.max(0, end - start);
+    const opts = track.options;
+    const duration = fitToWindow(track.mediaDuration ?? 0, start, end);
+    const sourceOffset = opts.trimStart !== undefined ? toSeconds(opts.trimStart) : 0;
+    const duck = typeof opts.duckUnder === 'string' ? opts.duckUnder.trim() : opts.duckUnder?.source;
+    const ebu = opts.loudness === 'ebu-r128' || opts.loudnessNormalization === 'ebu-r128';
     const audio = {
-        id: nextId('audio'),
+        id: nextId(state, 'audio'),
         source: track.source,
         start,
         duration,
-        volume: track.options.volume ?? 1,
-        fadeIn: track.options.fadeIn != null ? toSeconds(track.options.fadeIn) : 0,
-        fadeOut: track.options.fadeOut != null ? toSeconds(track.options.fadeOut) : 0,
-        loudnessNormalization: track.options.loudnessNormalization,
-        targetLufs: track.options.targetLufs,
+        volume: opts.volume ?? 1,
+        fadeIn: opts.fadeIn != null ? toSeconds(opts.fadeIn) : 0,
+        fadeOut: opts.fadeOut != null ? toSeconds(opts.fadeOut) : 0,
+        ...(sourceOffset > 0 ? { sourceOffset } : {}),
+        ...(opts.pan !== undefined ? { pan: opts.pan } : {}),
+        ...(duck ? { duckUnder: duck } : {}),
+        ...(ebu ? { ...EBU_R128, ...(opts.targetLufs !== undefined ? { targetLufs: opts.targetLufs } : {}) } : {}),
     };
+    attachAnimations(state, audio, normalizeAnims(opts.animate), start, end > start ? end : start + duration);
     state.ir.audio.push(audio);
-    state.audioCursor = Math.max(state.audioCursor, end);
-    bumpDuration(state, end);
+    return start + duration;
+}
+function scheduleMarker(state, start, end, node) {
+    (state.ir.markers ??= []).push({
+        id: nextId(state, 'marker'),
+        name: node.name,
+        time: start,
+        duration: Math.max(0, end - start),
+        ...(node.metadata ? { metadata: { ...node.metadata } } : {}),
+    });
 }
 function scheduleFilter(state, start, end, effect) {
+    if (effect.name.trim().toLowerCase() === 'lut') {
+        throw new TypeError('filter("lut") reads a .cube file at compile time; use VidScript: filter "lut", file: "look.cube"');
+    }
     const builtin = {
         type: 'builtin',
-        id: nextId('fx'),
+        id: nextId(state, 'fx'),
         name: effect.name,
         start,
         end,
         params: { ...effect.params },
     };
     state.ir.effects.push(builtin);
-    bumpDuration(state, end);
 }
 function scheduleShader(state, start, end, effect) {
     const shaderFx = {
         type: 'shader',
-        id: nextId('shader'),
+        id: nextId(state, 'shader'),
         shaderSource: effect.shaderSource,
         start,
         end,
         params: { ...effect.params },
     };
     state.ir.effects.push(shaderFx);
-    bumpDuration(state, end);
 }
 function scheduleTransition(state, start, end, effect) {
     const opts = effect.options;
     const surface = {
-        id: nextId('surface'),
+        id: nextId(state, 'surface'),
         type: 'transition',
         start,
         end,
@@ -281,6 +700,8 @@ function scheduleTransition(state, start, end, effect) {
             x: opts.x,
             y: opts.y,
             opacity: opts.opacity ?? 1,
+            ...(opts.inOffset !== undefined ? { inOffset: toSeconds(opts.inOffset) } : {}),
+            ...(opts.outOffset !== undefined ? { outOffset: toSeconds(opts.outOffset) } : {}),
         },
         metadata: {
             package: '@scenerok/transitions',
@@ -288,8 +709,6 @@ function scheduleTransition(state, start, end, effect) {
         },
     };
     state.ir.surfaces.push(surface);
-    state.visualCursor = Math.max(state.visualCursor, end);
-    bumpDuration(state, end);
 }
 /**
  * Post-pass: resolve fromId/toId for transition surfaces from neighboring clips.
@@ -301,143 +720,182 @@ export function bindTransitions(ir, warnings = []) {
             continue;
         const Ts = surface.start;
         const Te = surface.end;
-        const atFrom = ir.clips.filter((c) => c.start <= Ts && c.end >= Ts);
-        let fromId;
-        if (atFrom.length === 0) {
-            fromId = null;
-        }
-        else if (atFrom.length === 1) {
-            fromId = atFrom[0].id;
-        }
-        else {
-            fromId = null;
-            warnings.push(`transition at ${Ts}s: multiple clips active at the start seam; transitions are only defined at a clean cut — use Overlay/Composite for layered clips`);
-        }
-        const atTo = ir.clips.filter((c) => c.start <= Te && c.end >= Te);
-        let toId;
-        if (atTo.length === 0) {
-            toId = null;
-        }
-        else if (atTo.length === 1) {
-            toId = atTo[0].id;
-        }
-        else {
-            toId = null;
-            warnings.push(`transition at ${Te}s: multiple clips active at the end seam; transitions are only defined at a clean cut — use Overlay/Composite for layered clips`);
-        }
+        const side = (t, edge) => {
+            const active = ir.clips.filter((c) => c.start <= t && c.end >= t);
+            if (active.length === 1)
+                return active[0].id;
+            if (active.length > 1) {
+                warnings.push(`transition at ${t}s: multiple clips active at the ${edge} seam; transitions are only defined at a clean cut — use blend for layered clips`);
+            }
+            return null;
+        };
+        const fromId = side(Ts, 'start');
+        const toId = side(Te, 'end');
         const data = surface.data;
-        if (fromId && toId && fromId === toId) {
+        if (fromId && toId && fromId === toId)
             data.self = true;
-        }
         const userMode = typeof data.mode === 'string' ? data.mode : '';
-        if (!userMode) {
+        if (!userMode)
             data.mode = fromId && toId ? 'roll' : 'freeze';
-        }
         data.fromId = fromId;
         data.toId = toId;
         data.progressStart = Ts;
         data.progressEnd = Te;
     }
 }
-function scheduleNestedTimeline(state, start, end, nested) {
-    const nestedIr = nested.toIR();
-    const offset = start;
-    const span = Math.max(0, end - start);
-    const scale = nestedIr.duration > 0 ? span / nestedIr.duration : 1;
-    const remap = (t) => offset + t * scale;
-    for (const clip of nestedIr.clips) {
-        state.ir.clips.push({
-            ...clip,
-            id: nextId('clip'),
-            start: remap(clip.start),
-            end: remap(clip.end),
-        });
-    }
-    for (const layer of nestedIr.layers) {
-        state.ir.layers.push({
-            ...layer,
-            id: nextId(layer.type === 'text' ? 'text' : 'layer'),
-            start: remap(layer.start),
-            end: remap(layer.end),
-        });
-    }
-    for (const effect of nestedIr.effects) {
-        state.ir.effects.push({
-            ...effect,
-            id: nextId('fx'),
-            start: remap(effect.start),
-            end: remap(effect.end),
-        });
+const RECORD = Symbol.for('scenerok.timeline.record');
+export function timelineRecordOf(value) {
+    const record = value[RECORD];
+    if (!record)
+        throw new TypeError('Not a SceneRok timeline');
+    return record;
+}
+export { RECORD as TIMELINE_RECORD };
+/** Lower a recorded timeline into a fresh builder on `canvas`. Transitions are not bound. */
+export function lowerTimeline(record, canvas, ids = { next: 0 }) {
+    const state = createIrBuilder(record.options, canvas, ids);
+    if (record.grid)
+        setGrid(state, record.grid);
+    for (const entry of record.entries) {
+        scheduleAt(state, entry.start, entry.end, entry.value);
     }
-    for (const audio of nestedIr.audio) {
-        state.ir.audio.push({
-            ...audio,
-            id: nextId('audio'),
-            start: remap(audio.start),
-            duration: audio.duration * scale,
-        });
+    return state;
+}
+function isTimelineView(value) {
+    return 'placement' in value && 'timeline' in value;
+}
+function scheduleNestedTimeline(state, start, end, value) {
+    const view = isTimelineView(value) ? value : null;
+    const nested = view ? view.timeline : value;
+    const placement = view?.placement ?? {};
+    if (placement.enabled === false)
+        return end;
+    const record = timelineRecordOf(nested);
+    // A nested timeline without its own size or rate lays out on its parent's canvas.
+    const child = lowerTimeline(record, { width: state.ir.width, height: state.ir.height, fps: state.ir.fps }, state.ids);
+    const childIr = child.ir;
+    const extentEnd = start + childIr.duration;
+    const effects = view?.effects ?? [];
+    const crop = view?.cropRect;
+    const mask = view?.maskSpec;
+    const sized = childIr.width !== state.ir.width || childIr.height !== state.ir.height;
+    // Properties, a grade (its own or applied), a crop, a mask, or its own canvas
+    // size: the timeline draws as one group. Otherwise it joins flat — same pixels.
+    const grouped = Object.keys(placement).length > 0 || effects.length > 0 || crop !== undefined
+        || mask !== undefined || childIr.effects.length > 0 || sized;
+    const marks = markIr(state.ir);
+    const shift = (x) => shiftTimed(x, start);
+    state.ir.clips.push(...childIr.clips.map(shift));
+    state.ir.layers.push(...childIr.layers.map((l) => (l.type === 'text' ? shift(l) : { ...l, start: l.start + start, end: l.end + start })));
+    state.ir.surfaces.push(...childIr.surfaces.map(shift));
+    if (childIr.groups?.length)
+        (state.ir.groups ??= []).push(...childIr.groups.map(shift));
+    state.ir.effects.push(...childIr.effects.map(shift));
+    state.ir.audio.push(...childIr.audio.map((a) => ({
+        ...a,
+        start: a.start + start,
+        ...(a.animations ? { animations: a.animations.map((x) => ({ ...x, start: x.start + start, end: x.end + start })) } : {}),
+        ...(a.motion ? { motion: a.motion.map((t) => ({ ...t, keyframes: t.keyframes.map((k) => ({ ...k, time: k.time + start })) })) } : {}),
+    })));
+    if (childIr.markers?.length) {
+        (state.ir.markers ??= []).push(...childIr.markers.map((m) => ({ ...m, time: m.time + start })));
     }
-    for (const surface of nestedIr.surfaces) {
-        state.ir.surfaces.push({
-            ...surface,
-            id: nextId('surface'),
-            start: remap(surface.start),
-            end: remap(surface.end),
+    let placedEnd = extentEnd;
+    if (grouped) {
+        // The group lives for the placement's window; a longer body is cut off at it.
+        placedEnd = end > start ? Math.min(extentEnd, end) : extentEnd;
+        const group = wrapInGroup(state, marks, start, placedEnd, {
+            props: placement,
+            effects,
+            crop,
+            size: { width: childIr.width, height: childIr.height },
         });
+        if (mask)
+            attachMask(state, group, mask);
     }
-    const use = {
-        name: nested.options.name ?? 'nested',
-        sourceOffset: 0,
-        start,
-        end,
-    };
-    state.ir.timelineUses = [...(state.ir.timelineUses ?? []), use];
-    state.visualCursor = Math.max(state.visualCursor, end);
-    bumpDuration(state, end);
+    state.ir.timelineUses = [...(state.ir.timelineUses ?? []), {
+            name: nested.options.name ?? 'nested',
+            sourceOffset: 0,
+            start,
+            end: placedEnd,
+        }];
+    return placedEnd;
 }
-export function scheduleAt(state, start, end, value) {
-    if (end < start) {
-        throw new RangeError(`Invalid range: end (${end}) < start (${start})`);
+/** Lower one placement into `state.ir`. Returns where it ended. */
+export function scheduleAt(state, rawStart, rawEnd, value, options = {}) {
+    if (rawEnd < rawStart) {
+        throw new RangeError(`Invalid range: end (${rawEnd}) < start (${rawStart})`);
     }
+    // Block boundaries are frame boundaries of the output, as in VidScript.
+    const snap = options.snap !== false;
+    const start = snap ? snapToFrame(rawStart, state.timeBase) : rawStart;
+    const end = snap ? Math.max(start, snapToFrame(rawEnd, state.timeBase)) : rawEnd;
+    let placedEnd = end;
+    let channel = 'visual';
     switch (value.kind) {
         case 'video':
-            scheduleVideo(state, start, end, value);
+        case 'image':
+            placedEnd = scheduleMedia(state, start, end, value);
             break;
         case 'text':
             scheduleText(state, start, end, value);
             break;
+        case 'solid':
+            scheduleSolid(state, start, end, value);
+            break;
         case 'audio':
-            scheduleAudio(state, start, end, value);
+            placedEnd = scheduleAudio(state, start, end, value);
+            channel = 'audio';
+            break;
+        case 'gap':
+            break;
+        case 'marker':
+            scheduleMarker(state, start, end, value);
+            channel = 'none';
             break;
         case 'filter':
             scheduleFilter(state, start, end, value);
+            channel = 'none';
             break;
         case 'shader':
             scheduleShader(state, start, end, value);
+            channel = 'none';
             break;
         case 'transition':
             scheduleTransition(state, start, end, value);
             break;
         case 'timeline':
-            scheduleNestedTimeline(state, start, end, value);
+            placedEnd = scheduleNestedTimeline(state, start, end, value);
             break;
         default:
             throw new TypeError(`Unsupported schedulable kind: ${value.kind}`);
     }
+    if (options.advance !== false) {
+        if (channel === 'visual')
+            state.visualCursor = Math.max(state.visualCursor, placedEnd);
+        if (channel === 'audio')
+            state.audioCursor = Math.max(state.audioCursor, placedEnd);
+    }
+    bumpDuration(state, Math.max(end, placedEnd));
+    return placedEnd;
 }
-export function inferAutoDuration(value, explicit) {
+/** The span `push` gives a value with no explicit duration. */
+export function inferAutoDuration(value, explicit, fps) {
     if (explicit !== undefined)
-        return toSeconds(explicit);
+        return toSeconds(explicit, fps);
     switch (value.kind) {
         case 'video':
         case 'audio':
-            return value.duration;
         case 'timeline':
-            return value.duration;
         case 'transition':
             return value.duration;
+        case 'image':
         case 'text':
-            return 3;
+        case 'solid':
+            return DEFAULT_STILL_LENGTH;
+        case 'marker':
+        case 'gap':
+            return 0;
         case 'filter':
         case 'shader':
             return 1;
@@ -447,6 +905,6 @@ export function inferAutoDuration(value, explicit) {
 }
 export function assertSchedulable(value) {
     if (!isSchedulable(value)) {
-        throw new TypeError('Timeline assignment RHS must be a SDK media node (video/text/audio/filter/shader/transition/timeline)');
+        throw new TypeError('Timeline assignment RHS must be an SDK node (video/image/text/audio/solid/gap/marker/filter/shader/transition/timeline)');
     }
 }