@glissade/core 0.19.0 → 0.20.0-pre.3

package/dist/index.d.ts

@@ -1,7 +1,6 @@
 import { $ as cubicBezier, A as getValueType, B as vec2Equals, C as UnknownValueTypeError, D as Vec2, E as ValueTypeInferenceError, F as pathType, G as spring, H as RetargetSpring, I as registerValueType, J as springPresets, K as springEasing, L as reprOf, M as listValueTypes, N as numberType, O as booleanType, P as paintType, Q as UnknownEasingError, R as stringType, S as PathValue, T as ValueTypeId, U as SpringConfig, V as vec2Type, W as SpringEase, X as EaseSpec, Y as DEFAULT_EASE, Z as EasingFn, _ as MeshInterpolation, a as key, b as Paint, c as sampleTrack, d as track, et as cubicBezierDerivative, f as validateTrack, g as HandoffKind, h as GradientInterpolation, i as TrackValidationError, j as inferValueType, k as colorType, l as springTo, m as ColorStop, n as KeyOpts, nt as easings, o as resolveEase, p as velocityAt, q as springEasingDerivative, r as Track, rt as namedEasing, s as resolveEaseDerivative, t as Key, tt as easingDerivatives, u as stagger, v as MeshPaint, w as ValueType, x as PathContour, y as MeshPoint, z as vec2ArcType } from "./track.js";
 import { a as isEditableNodeId, i as UnresolvableTargetError, n as TargetCarrier, o as resolveTweenTarget, r as TweenTarget, s as targetNodeId, t as TARGET_PATH } from "./targetRef.js";
 import { _ as setDevWarning, a as FontFaceRef, c as Marker, d as TimelineValidationError, f as audioOffsetSamples, g as emitDevWarning, h as DevWarning, i as CompiledTimeline, l as Timeline, m as isDurationEditable, n as AudioClip, o as GainEnvelope, p as compileTimeline, r as ChildEntry, s as Json, t as AssetRef, u as TimelineInit } from "./timeline.js";
-import { _ as setSidecarTrack, a as SidecarOrphan, c as SidecarVersionError, d as emptySidecar, f as hashKeys, g as normalizeEditedKeys, h as migrateSidecar, i as SidecarDocV1, l as assignKeyIds, m as mergeSidecarDetailed, n as OrphanReason, o as SidecarTimelineEntry, p as mergeSidecar, r as SidecarDoc, s as SidecarTrackEntry, t as MergeResult, u as deleteSidecarTrack } from "./sidecar.js";
 
 //#region src/signal.d.ts
 
@@ -374,7 +373,13 @@ declare function timeline(build: (tl: TimelineBuilder) => void, init?: Omit<Time
 type Playhead = BindableSignal<number>;
 declare function createPlayhead(initial?: number): Playhead;
 declare class UnboundTargetError extends Error {
-  constructor(target: string);
+  /**
+   * `message` overrides the default generic text — the seam a layer with more
+   * context (e.g. `scene`, which knows the node's construction-prop schema) uses
+   * to throw a friendlier, more specific reason while keeping the same error
+   * type (so existing `instanceof UnboundTargetError` catches still fire).
+   */
+  constructor(target: string, message?: string);
 }
 /**
  * A track's value type doesn't match the shape of the property it targets — the
@@ -421,12 +426,25 @@ interface BoundTimeline {
   /** Detach every track binding, freezing signals at their last values. */
   unbind(): void;
 }
+/**
+ * Optional knobs for {@link bindTimeline}.
+ */
+interface BindOptions {
+  /**
+   * Asked for a friendlier message when a target fails to resolve. `core` knows
+   * nothing about node types or construction props; a caller with that context
+   * (e.g. `scene`) can return a more-specific reason string — used verbatim as
+   * the {@link UnboundTargetError} message — or `undefined` to fall through to
+   * the generic "no property signal resolves to it".
+   */
+  unboundMessage?: (target: string) => string | undefined;
+}
 /**
  * Bind a compiled timeline's tracks to property signals. `resolve` returns
  * the signal for a target path, or undefined — which is a compile-time-style
  * error (§2.2: unbound tracks are build errors, not silent no-ops).
  */
-declare function bindTimeline(compiled: CompiledTimeline, resolve: (target: string) => BindTarget | undefined, playhead?: Playhead): BoundTimeline;
+declare function bindTimeline(compiled: CompiledTimeline, resolve: (target: string) => BindTarget | undefined, playhead?: Playhead, options?: BindOptions): BoundTimeline;
 /**
  * The evaluation entry discipline (§2.5): the playhead write is the sanctioned
  * entry mutation, then the read phase begins and `read` must be pure.
@@ -477,4 +495,4 @@ interface CheckpointedSim {
 }
 declare function bakeCheckpointed<W, S = W>(cfg: CheckpointedBakeConfig<W, S>): CheckpointedSim;
 //#endregion
-export { type AssetRef, type AudioClip, type BakeConfig, BakeError, type BindTarget, BindTypeMismatchError, type BindableSignal, type BoundTimeline, type CheckpointedBakeConfig, type CheckpointedSim, type ChildEntry, CircularDependencyError, ColorParseError, type ColorStop, type CompiledTimeline, type CoverageReport, type CurveSampler, DEFAULT_EASE, type DevWarning, type EaseSpec, type EasingFn, type Equals, type FontFaceRef, type FontMode, type FontRegistry, type FontUsage, FontValidationError, type GainEnvelope, type GradientInterpolation, type HandoffKind, type Json, type Key, type KeyOpts, type Marker, type MergeResult, type MeshInterpolation, type MeshPaint, type MeshPoint, type MissingGlyphs, type OkLab, type OrphanReason, type Paint, type PathContour, type PathValue, type Playhead, type Position, PositionError, type ReadonlySignal, type ResolvedFace, type RetargetSpring, type Rgba, type Rng, type Scheduler, type SidecarDoc, type SidecarDocV1, type SidecarOrphan, type SidecarTimelineEntry, type SidecarTrackEntry, SidecarVersionError, type Signal, type SignalOptions, type SpringConfig, type SpringEase, type StaggerOpts, type StaggerSpec, TARGET_PATH, type TargetCarrier, type Timeline, type TimelineBuilder, type TimelineInit, TimelineValidationError, type Track, TrackValidationError, type TweenOpts, type TweenTarget, UnboundTargetError, UnknownEasingError, UnknownValueTypeError, UnresolvableTargetError, type ValidateFontsOptions, type ValueType, type ValueTypeId, ValueTypeInferenceError, type Vec2, type Vec2Component, type Vec2Signal, WriteDuringEvaluationError, assignKeyIds, audioOffsetSamples, bake, bakeCheckpointed, batch, beginReadPhase, bindTimeline, booleanType, buildFontRegistry, buildTimeline, colorType, compileTimeline, computed, createPlayhead, cubicBezier, cubicBezierDerivative, deleteSidecarTrack, easingDerivatives, easings, emitDevWarning, emptySidecar, endReadPhase, evaluateAt, formatColor, getTimelineCallbacks, getValueType, hashKeys, inReadPhase, inferValueType, isDurationEditable, isEditableNodeId, isExemptFamily, key, lerpColor, listValueTypes, mergeSidecar, mergeSidecarDetailed, migrateSidecar, namedEasing, normalizeEditedKeys, numberType, oklabToRgba, paintType, parseCmap, parseColor, pathType, random, registerValueType, reprOf, resolveEase, resolveEaseDerivative, resolveTweenTarget, rgbaToOklab, sampleTrack, setDevWarning, setScheduler, setSidecarTrack, signal, spring, springEasing, springEasingDerivative, springPresets, springTo, stagger, stringType, synchronousScheduler, targetNodeId, timeline, track, untracked, validateFonts, validateTrack, vec2ArcType, vec2Equals, vec2Signal, vec2Type, velocityAt };
+export { type AssetRef, type AudioClip, type BakeConfig, BakeError, type BindOptions, type BindTarget, BindTypeMismatchError, type BindableSignal, type BoundTimeline, type CheckpointedBakeConfig, type CheckpointedSim, type ChildEntry, CircularDependencyError, ColorParseError, type ColorStop, type CompiledTimeline, type CoverageReport, type CurveSampler, DEFAULT_EASE, type DevWarning, type EaseSpec, type EasingFn, type Equals, type FontFaceRef, type FontMode, type FontRegistry, type FontUsage, FontValidationError, type GainEnvelope, type GradientInterpolation, type HandoffKind, type Json, type Key, type KeyOpts, type Marker, type MeshInterpolation, type MeshPaint, type MeshPoint, type MissingGlyphs, type OkLab, type Paint, type PathContour, type PathValue, type Playhead, type Position, PositionError, type ReadonlySignal, type ResolvedFace, type RetargetSpring, type Rgba, type Rng, type Scheduler, type Signal, type SignalOptions, type SpringConfig, type SpringEase, type StaggerOpts, type StaggerSpec, TARGET_PATH, type TargetCarrier, type Timeline, type TimelineBuilder, type TimelineInit, TimelineValidationError, type Track, TrackValidationError, type TweenOpts, type TweenTarget, UnboundTargetError, UnknownEasingError, UnknownValueTypeError, UnresolvableTargetError, type ValidateFontsOptions, type ValueType, type ValueTypeId, ValueTypeInferenceError, type Vec2, type Vec2Component, type Vec2Signal, WriteDuringEvaluationError, audioOffsetSamples, bake, bakeCheckpointed, batch, beginReadPhase, bindTimeline, booleanType, buildFontRegistry, buildTimeline, colorType, compileTimeline, computed, createPlayhead, cubicBezier, cubicBezierDerivative, easingDerivatives, easings, emitDevWarning, endReadPhase, evaluateAt, formatColor, getTimelineCallbacks, getValueType, inReadPhase, inferValueType, isDurationEditable, isEditableNodeId, isExemptFamily, key, lerpColor, listValueTypes, namedEasing, numberType, oklabToRgba, paintType, parseCmap, parseColor, pathType, random, registerValueType, reprOf, resolveEase, resolveEaseDerivative, resolveTweenTarget, rgbaToOklab, sampleTrack, setDevWarning, setScheduler, signal, spring, springEasing, springEasingDerivative, springPresets, springTo, stagger, stringType, synchronousScheduler, targetNodeId, timeline, track, untracked, validateFonts, validateTrack, vec2ArcType, vec2Equals, vec2Signal, vec2Type, velocityAt };

package/dist/index.js

@@ -1,6 +1,6 @@
 import { A as vec2Equals, B as spring, C as numberType, D as reprOf, E as registerValueType, F as oklabToRgba, G as UnknownEasingError, H as springEasingDerivative, I as parseColor, J as easingDerivatives, K as cubicBezier, L as rgbaToOklab, M as ColorParseError, N as formatColor, O as stringType, P as lerpColor, R as emitDevWarning, S as listValueTypes, T as pathType, U as springPresets, V as springEasing, W as DEFAULT_EASE, X as namedEasing, Y as easings, _ as ValueTypeInferenceError, a as targetNodeId, b as getValueType, c as resolveEase, d as springTo, f as stagger, g as UnknownValueTypeError, h as velocityAt, i as resolveTweenTarget, j as vec2Type, k as vec2ArcType, l as resolveEaseDerivative, m as validateTrack, n as UnresolvableTargetError, o as TrackValidationError, p as track, q as cubicBezierDerivative, r as isEditableNodeId, s as key, t as TARGET_PATH, u as sampleTrack, v as booleanType, w as paintType, x as inferValueType, y as colorType, z as setDevWarning } from "./targetRef.js";
 import { t as parseCmap } from "./cmap.js";
-import { _ as timeline$1, a as hashKeys, c as migrateSidecar, d as TimelineValidationError, f as audioOffsetSamples, g as namespaceCallName, h as isDurationEditable, i as emptySidecar, l as normalizeEditedKeys, m as compileTimeline, n as assignKeyIds, o as mergeSidecar, p as callMarkerPrefix, r as deleteSidecarTrack, s as mergeSidecarDetailed, t as SidecarVersionError, u as setSidecarTrack } from "./sidecar.js";
+import { a as isDurationEditable, i as compileTimeline, n as audioOffsetSamples, o as namespaceCallName, r as callMarkerPrefix, s as timeline$1, t as TimelineValidationError } from "./timeline.js";
 //#region src/ticker.ts
 /** The default scheduler: flush synchronously, preserving pre-ticker timing. */
 const synchronousScheduler = (flush) => flush();
@@ -914,8 +914,14 @@ function createPlayhead(initial = 0) {
 	return signal(initial);
 }
 var UnboundTargetError = class extends Error {
-	constructor(target) {
-		super(`timeline targets '${target}' but no property signal resolves to it`);
+	/**
+	* `message` overrides the default generic text — the seam a layer with more
+	* context (e.g. `scene`, which knows the node's construction-prop schema) uses
+	* to throw a friendlier, more specific reason while keeping the same error
+	* type (so existing `instanceof UnboundTargetError` catches still fire).
+	*/
+	constructor(target, message) {
+		super(message ?? `timeline targets '${target}' but no property signal resolves to it`);
 		this.name = "UnboundTargetError";
 	}
 };
@@ -948,12 +954,12 @@ var BindTypeMismatchError = class extends Error {
 * the signal for a target path, or undefined — which is a compile-time-style
 * error (§2.2: unbound tracks are build errors, not silent no-ops).
 */
-function bindTimeline(compiled, resolve, playhead = createPlayhead()) {
+function bindTimeline(compiled, resolve, playhead = createPlayhead(), options = {}) {
 	const bound = [];
 	const samplers = /* @__PURE__ */ new Map();
 	for (const [target, tr] of compiled.tracks) {
 		const sig = resolve(target);
-		if (!sig) throw new UnboundTargetError(target);
+		if (!sig) throw new UnboundTargetError(target, options.unboundMessage?.(target));
 		const got = tr.type;
 		const expects = sig.expects;
 		if (expects !== void 0) {
@@ -1109,4 +1115,4 @@ function bakeCheckpointed(cfg) {
 	};
 }
 //#endregion
-export { BakeError, BindTypeMismatchError, CircularDependencyError, ColorParseError, DEFAULT_EASE, FontValidationError, PositionError, SidecarVersionError, TARGET_PATH, TimelineValidationError, TrackValidationError, UnboundTargetError, UnknownEasingError, UnknownValueTypeError, UnresolvableTargetError, ValueTypeInferenceError, WriteDuringEvaluationError, assignKeyIds, audioOffsetSamples, bake, bakeCheckpointed, batch, beginReadPhase, bindTimeline, booleanType, buildFontRegistry, buildTimeline, colorType, compileTimeline, computed, createPlayhead, cubicBezier, cubicBezierDerivative, deleteSidecarTrack, easingDerivatives, easings, emitDevWarning, emptySidecar, endReadPhase, evaluateAt, formatColor, getTimelineCallbacks, getValueType, hashKeys, inReadPhase, inferValueType, isDurationEditable, isEditableNodeId, isExemptFamily, key, lerpColor, listValueTypes, mergeSidecar, mergeSidecarDetailed, migrateSidecar, namedEasing, normalizeEditedKeys, numberType, oklabToRgba, paintType, parseCmap, parseColor, pathType, random, registerValueType, reprOf, resolveEase, resolveEaseDerivative, resolveTweenTarget, rgbaToOklab, sampleTrack, setDevWarning, setScheduler, setSidecarTrack, signal, spring, springEasing, springEasingDerivative, springPresets, springTo, stagger, stringType, synchronousScheduler, targetNodeId, timeline, track, untracked, validateFonts, validateTrack, vec2ArcType, vec2Equals, vec2Signal, vec2Type, velocityAt };
+export { BakeError, BindTypeMismatchError, CircularDependencyError, ColorParseError, DEFAULT_EASE, FontValidationError, PositionError, TARGET_PATH, TimelineValidationError, TrackValidationError, UnboundTargetError, UnknownEasingError, UnknownValueTypeError, UnresolvableTargetError, ValueTypeInferenceError, WriteDuringEvaluationError, audioOffsetSamples, bake, bakeCheckpointed, batch, beginReadPhase, bindTimeline, booleanType, buildFontRegistry, buildTimeline, colorType, compileTimeline, computed, createPlayhead, cubicBezier, cubicBezierDerivative, easingDerivatives, easings, emitDevWarning, endReadPhase, evaluateAt, formatColor, getTimelineCallbacks, getValueType, inReadPhase, inferValueType, isDurationEditable, isEditableNodeId, isExemptFamily, key, lerpColor, listValueTypes, namedEasing, numberType, oklabToRgba, paintType, parseCmap, parseColor, pathType, random, registerValueType, reprOf, resolveEase, resolveEaseDerivative, resolveTweenTarget, rgbaToOklab, sampleTrack, setDevWarning, setScheduler, signal, spring, springEasing, springEasingDerivative, springPresets, springTo, stagger, stringType, synchronousScheduler, targetNodeId, timeline, track, untracked, validateFonts, validateTrack, vec2ArcType, vec2Equals, vec2Signal, vec2Type, velocityAt };

package/dist/sidecar.d.ts

@@ -85,4 +85,4 @@ declare function mergeSidecar(code: Timeline, sidecar: SidecarDoc | SidecarDocV1
  */
 declare function normalizeEditedKeys(keys: Key[]): Key[];
 //#endregion
-export { setSidecarTrack as _, SidecarOrphan as a, SidecarVersionError as c, emptySidecar as d, hashKeys as f, normalizeEditedKeys as g, migrateSidecar as h, SidecarDocV1 as i, assignKeyIds as l, mergeSidecarDetailed as m, OrphanReason as n, SidecarTimelineEntry as o, mergeSidecar as p, SidecarDoc as r, SidecarTrackEntry as s, MergeResult as t, deleteSidecarTrack as u };
+export { MergeResult, OrphanReason, SidecarDoc, SidecarDocV1, SidecarOrphan, SidecarTimelineEntry, SidecarTrackEntry, SidecarVersionError, assignKeyIds, deleteSidecarTrack, emptySidecar, hashKeys, mergeSidecar, mergeSidecarDetailed, migrateSidecar, normalizeEditedKeys, setSidecarTrack };

package/dist/sidecar.js

@@ -1,190 +1,4 @@
-import { B as spring, R as emitDevWarning, a as targetNodeId, m as validateTrack, o as TrackValidationError, r as isEditableNodeId } from "./targetRef.js";
-//#region src/timeline.ts
-/**
-* The Timeline document (DESIGN.md §2.3) — the serializable animation source
-* of truth — and its compiler: child flattening (add/sync), same-target
-* coalescing (last-insertion-wins, §2.2), duration computation, validation.
-*/
-function timeline(init) {
-	const doc = {
-		version: 1,
-		tracks: init.tracks ?? []
-	};
-	if (init.duration !== void 0) doc.duration = init.duration;
-	if (init.editableDuration !== void 0) doc.editableDuration = init.editableDuration;
-	if (init.fps !== void 0) doc.fps = init.fps;
-	if (init.posterTime !== void 0) doc.posterTime = init.posterTime;
-	if (init.labels !== void 0) doc.labels = init.labels;
-	if (init.markers !== void 0) doc.markers = init.markers;
-	if (init.children !== void 0) doc.children = init.children;
-	if (init.audio !== void 0) doc.audio = init.audio;
-	if (init.assets !== void 0) doc.assets = init.assets;
-	return doc;
-}
-var TimelineValidationError = class extends Error {
-	constructor(message) {
-		super(message);
-		this.name = "TimelineValidationError";
-	}
-};
-/** Spring key rule (§2.7): a spring-eased key's t must equal prev.t + spring.duration(cfg). */
-function validateSpringKeys(tr) {
-	for (let i = 1; i < tr.keys.length; i++) {
-		const k = tr.keys[i];
-		if (k.ease && typeof k.ease === "object" && k.ease.kind === "spring") {
-			const expected = tr.keys[i - 1].t + spring.duration(k.ease);
-			if (Math.abs(k.t - expected) > 1e-6) throw new TimelineValidationError(`track '${tr.target}': spring-eased key at t=${k.t} must sit at prev.t + spring.duration (${expected.toFixed(6)}); the builder computes this automatically`);
-		}
-	}
-}
-/**
-* Sample-indexed clip offset — the single A/V-sync source of truth (§5.3),
-* `round(at * sampleRate)`. Both the CLI (FFmpeg) and the browser
-* (OfflineAudioContext) mixers derive their delay from this, so A/V offsets
-* agree across paths by construction rather than one rounding to milliseconds
-* and the other to raw float seconds. Default rate is the canonical mix grid.
-*/
-function audioOffsetSamples(at, sampleRate = 48e3) {
-	return Math.round(at * sampleRate);
-}
-function rebaseKeys(keys, at, timeScale) {
-	return keys.map((k) => ({
-		...k,
-		t: at + k.t / timeScale
-	}));
-}
-/**
-* `.call()` markers carry an auto-assigned `call:N` name whose counter resets
-* per document, so two sibling sub-timelines that each define a `.call()` would
-* collide on `call:0` when rebased into one parent (one callback dropped, the
-* other double-firing). We namespace a child's `call:*` markers by the child's
-* position PATH in the parent (`c<index>/…`), and the builder's `add()` applies
-* the EXACT same prefix when forwarding the child's name→fn map — so the rebased
-* marker name and the registered callback key agree by construction. Only
-* `call:*` names are rewritten; author-named cues keep their names. Both surfaces
-* call these so the convention lives in one place.
-*/
-function callMarkerPrefix(childIndex) {
-	return `c${childIndex}/`;
-}
-const CALL = /(^|\/)call:\d+$/;
-function namespaceCallName(name, prefix) {
-	return prefix !== "" && CALL.test(name) ? prefix + name : name;
-}
-function flatten(doc, at, timeScale, unit, out, counter) {
-	for (const tr of doc.tracks) {
-		validateTrack(tr);
-		validateSpringKeys(tr);
-		out.push({
-			track: {
-				...tr,
-				keys: rebaseKeys(tr.keys, at, timeScale)
-			},
-			unit
-		});
-	}
-	for (const child of doc.children ?? []) {
-		const scale = child.mode === "sync" ? child.timeScale ?? 1 : 1;
-		if (child.mode === "add" && child.timeScale !== void 0) throw new TimelineValidationError("timeScale is only valid on mode:'sync' children (§2.3)");
-		if (scale <= 0) throw new TimelineValidationError("sync timeScale must be > 0");
-		const childUnit = child.mode === "sync" ? ++counter.n : unit;
-		flatten(child.timeline, at + child.at / timeScale, timeScale * scale, childUnit, out, counter);
-	}
-}
-/**
-* Coalesce same-target tracks: later insertion wins where key ranges overlap
-* (§2.2/§2.6 decided rule), with a dev warning. Earlier keys inside the later
-* track's [first.t, last.t] span are dropped.
-*/
-function coalesce(entries) {
-	const byTarget = /* @__PURE__ */ new Map();
-	for (const { track: tr, unit } of entries) {
-		const existing = byTarget.get(tr.target);
-		if (!existing) {
-			byTarget.set(tr.target, {
-				track: {
-					...tr,
-					keys: [...tr.keys]
-				},
-				unit
-			});
-			continue;
-		}
-		if (existing.unit !== unit) throw new TimelineValidationError(`target '${tr.target}' is animated by a sync (opaque) child and another timeline unit; sync children must own disjoint targets (no last-writer-wins across the sync boundary, §2.3)`);
-		if (existing.track.type !== tr.type) throw new TimelineValidationError(`target '${tr.target}' has conflicting value types '${existing.track.type}' and '${tr.type}'`);
-		const start = tr.keys[0].t;
-		const end = tr.keys[tr.keys.length - 1].t;
-		const existingStart = existing.track.keys[0].t;
-		const existingEnd = existing.track.keys[existing.track.keys.length - 1].t;
-		const kept = existing.track.keys.filter((k) => k.t < start || k.t > end);
-		if (existingStart <= end && start <= existingEnd) emitDevWarning(`overlapping tracks for '${tr.target}' in [${start}, ${end}]: later insertion wins (${existing.track.keys.length - kept.length} earlier key(s) dropped)`);
-		existing.track.keys = [...kept, ...tr.keys].sort((a, b) => a.t - b.t);
-	}
-	const result = /* @__PURE__ */ new Map();
-	for (const [target, { track }] of byTarget) result.set(target, track);
-	return result;
-}
-/**
-* Studio reader (§6.2 rule 4): is this timeline's duration opted into editor
-* editing? Code-owned and read-only by default; `editableDuration()` flips it.
-*/
-function isDurationEditable(doc) {
-	return doc.editableDuration === true;
-}
-function childExtent(child) {
-	const scale = child.mode === "sync" ? child.timeScale ?? 1 : 1;
-	return child.at + computeDuration(child.timeline) / scale;
-}
-function computeDuration(doc) {
-	if (doc.duration !== void 0) return doc.duration;
-	let max = 0;
-	for (const tr of doc.tracks) {
-		const last = tr.keys[tr.keys.length - 1];
-		if (last) max = Math.max(max, last.t);
-	}
-	for (const m of doc.markers ?? []) max = Math.max(max, m.t);
-	for (const child of doc.children ?? []) max = Math.max(max, childExtent(child));
-	return max;
-}
-function compileTimeline(doc) {
-	if (doc.version !== 1) throw new TimelineValidationError(`unsupported timeline document version ${String(doc.version)}`);
-	const flat = [];
-	flatten(doc, 0, 1, 0, flat, { n: 0 });
-	const tracks = coalesce(flat);
-	const labels = { ...doc.labels };
-	const markers = [...doc.markers ?? []];
-	const audio = [...doc.audio ?? []];
-	const visitChildren = (children, at, scale, prefix) => {
-		(children ?? []).forEach((child, index) => {
-			const base = at + child.at / scale;
-			const childScale = scale * (child.mode === "sync" ? child.timeScale ?? 1 : 1);
-			const childPrefix = prefix + callMarkerPrefix(index);
-			for (const [name, t] of Object.entries(child.timeline.labels ?? {})) if (!(name in labels)) labels[name] = base + t / childScale;
-			for (const m of child.timeline.markers ?? []) markers.push({
-				...m,
-				name: namespaceCallName(m.name, childPrefix),
-				t: base + m.t / childScale
-			});
-			for (const clip of child.timeline.audio ?? []) audio.push({
-				...clip,
-				at: base + clip.at / childScale,
-				...childScale !== 1 ? { playbackRate: (clip.playbackRate ?? 1) * childScale } : {}
-			});
-			visitChildren(child.timeline.children, base, childScale, childPrefix);
-		});
-	};
-	visitChildren(doc.children, 0, 1, "");
-	markers.sort((a, b) => a.t - b.t);
-	audio.sort((a, b) => a.at - b.at);
-	return {
-		duration: computeDuration(doc),
-		labels,
-		markers,
-		tracks,
-		audio
-	};
-}
-//#endregion
+import { B as spring, R as emitDevWarning, a as targetNodeId, o as TrackValidationError, r as isEditableNodeId } from "./targetRef.js";
 //#region src/sidecar.ts
 /**
 * The editor sidecar (DESIGN.md §6.2): code declares scene structure and
@@ -411,4 +225,4 @@ function normalizeEditedKeys(keys) {
 	return out;
 }
 //#endregion
-export { timeline as _, hashKeys as a, migrateSidecar as c, TimelineValidationError as d, audioOffsetSamples as f, namespaceCallName as g, isDurationEditable as h, emptySidecar as i, normalizeEditedKeys as l, compileTimeline as m, assignKeyIds as n, mergeSidecar as o, callMarkerPrefix as p, deleteSidecarTrack as r, mergeSidecarDetailed as s, SidecarVersionError as t, setSidecarTrack as u };
+export { SidecarVersionError, assignKeyIds, deleteSidecarTrack, emptySidecar, hashKeys, mergeSidecar, mergeSidecarDetailed, migrateSidecar, normalizeEditedKeys, setSidecarTrack };

package/dist/studioHost.d.ts

@@ -1,7 +1,7 @@
 import { T as ValueTypeId, X as EaseSpec, t as Key } from "./track.js";
 import { a as isEditableNodeId, s as targetNodeId } from "./targetRef.js";
 import { l as Timeline } from "./timeline.js";
-import { a as SidecarOrphan, r as SidecarDoc } from "./sidecar.js";
+import { SidecarDoc, SidecarOrphan } from "./sidecar.js";
 
 //#region src/timelinePatch.d.ts
 

package/dist/studioHost.js

@@ -1,5 +1,5 @@
 import { a as targetNodeId, r as isEditableNodeId } from "./targetRef.js";
-import { a as hashKeys, l as normalizeEditedKeys, n as assignKeyIds } from "./sidecar.js";
+import { assignKeyIds, hashKeys, normalizeEditedKeys } from "./sidecar.js";
 //#region src/timelinePatch.ts
 /** Unambiguous composite map key (no control-char separators). */
 function refKey(timelineId, name) {

package/dist/timeline.js

@@ -0,0 +1,188 @@
+import { B as spring, R as emitDevWarning, m as validateTrack } from "./targetRef.js";
+//#region src/timeline.ts
+/**
+* The Timeline document (DESIGN.md §2.3) — the serializable animation source
+* of truth — and its compiler: child flattening (add/sync), same-target
+* coalescing (last-insertion-wins, §2.2), duration computation, validation.
+*/
+function timeline(init) {
+	const doc = {
+		version: 1,
+		tracks: init.tracks ?? []
+	};
+	if (init.duration !== void 0) doc.duration = init.duration;
+	if (init.editableDuration !== void 0) doc.editableDuration = init.editableDuration;
+	if (init.fps !== void 0) doc.fps = init.fps;
+	if (init.posterTime !== void 0) doc.posterTime = init.posterTime;
+	if (init.labels !== void 0) doc.labels = init.labels;
+	if (init.markers !== void 0) doc.markers = init.markers;
+	if (init.children !== void 0) doc.children = init.children;
+	if (init.audio !== void 0) doc.audio = init.audio;
+	if (init.assets !== void 0) doc.assets = init.assets;
+	return doc;
+}
+var TimelineValidationError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "TimelineValidationError";
+	}
+};
+/** Spring key rule (§2.7): a spring-eased key's t must equal prev.t + spring.duration(cfg). */
+function validateSpringKeys(tr) {
+	for (let i = 1; i < tr.keys.length; i++) {
+		const k = tr.keys[i];
+		if (k.ease && typeof k.ease === "object" && k.ease.kind === "spring") {
+			const expected = tr.keys[i - 1].t + spring.duration(k.ease);
+			if (Math.abs(k.t - expected) > 1e-6) throw new TimelineValidationError(`track '${tr.target}': spring-eased key at t=${k.t} must sit at prev.t + spring.duration (${expected.toFixed(6)}); the builder computes this automatically`);
+		}
+	}
+}
+/**
+* Sample-indexed clip offset — the single A/V-sync source of truth (§5.3),
+* `round(at * sampleRate)`. Both the CLI (FFmpeg) and the browser
+* (OfflineAudioContext) mixers derive their delay from this, so A/V offsets
+* agree across paths by construction rather than one rounding to milliseconds
+* and the other to raw float seconds. Default rate is the canonical mix grid.
+*/
+function audioOffsetSamples(at, sampleRate = 48e3) {
+	return Math.round(at * sampleRate);
+}
+function rebaseKeys(keys, at, timeScale) {
+	return keys.map((k) => ({
+		...k,
+		t: at + k.t / timeScale
+	}));
+}
+/**
+* `.call()` markers carry an auto-assigned `call:N` name whose counter resets
+* per document, so two sibling sub-timelines that each define a `.call()` would
+* collide on `call:0` when rebased into one parent (one callback dropped, the
+* other double-firing). We namespace a child's `call:*` markers by the child's
+* position PATH in the parent (`c<index>/…`), and the builder's `add()` applies
+* the EXACT same prefix when forwarding the child's name→fn map — so the rebased
+* marker name and the registered callback key agree by construction. Only
+* `call:*` names are rewritten; author-named cues keep their names. Both surfaces
+* call these so the convention lives in one place.
+*/
+function callMarkerPrefix(childIndex) {
+	return `c${childIndex}/`;
+}
+const CALL = /(^|\/)call:\d+$/;
+function namespaceCallName(name, prefix) {
+	return prefix !== "" && CALL.test(name) ? prefix + name : name;
+}
+function flatten(doc, at, timeScale, unit, out, counter) {
+	for (const tr of doc.tracks) {
+		validateTrack(tr);
+		validateSpringKeys(tr);
+		out.push({
+			track: {
+				...tr,
+				keys: rebaseKeys(tr.keys, at, timeScale)
+			},
+			unit
+		});
+	}
+	for (const child of doc.children ?? []) {
+		const scale = child.mode === "sync" ? child.timeScale ?? 1 : 1;
+		if (child.mode === "add" && child.timeScale !== void 0) throw new TimelineValidationError("timeScale is only valid on mode:'sync' children (§2.3)");
+		if (scale <= 0) throw new TimelineValidationError("sync timeScale must be > 0");
+		const childUnit = child.mode === "sync" ? ++counter.n : unit;
+		flatten(child.timeline, at + child.at / timeScale, timeScale * scale, childUnit, out, counter);
+	}
+}
+/**
+* Coalesce same-target tracks: later insertion wins where key ranges overlap
+* (§2.2/§2.6 decided rule), with a dev warning. Earlier keys inside the later
+* track's [first.t, last.t] span are dropped.
+*/
+function coalesce(entries) {
+	const byTarget = /* @__PURE__ */ new Map();
+	for (const { track: tr, unit } of entries) {
+		const existing = byTarget.get(tr.target);
+		if (!existing) {
+			byTarget.set(tr.target, {
+				track: {
+					...tr,
+					keys: [...tr.keys]
+				},
+				unit
+			});
+			continue;
+		}
+		if (existing.unit !== unit) throw new TimelineValidationError(`target '${tr.target}' is animated by a sync (opaque) child and another timeline unit; sync children must own disjoint targets (no last-writer-wins across the sync boundary, §2.3)`);
+		if (existing.track.type !== tr.type) throw new TimelineValidationError(`target '${tr.target}' has conflicting value types '${existing.track.type}' and '${tr.type}'`);
+		const start = tr.keys[0].t;
+		const end = tr.keys[tr.keys.length - 1].t;
+		const existingStart = existing.track.keys[0].t;
+		const existingEnd = existing.track.keys[existing.track.keys.length - 1].t;
+		const kept = existing.track.keys.filter((k) => k.t < start || k.t > end);
+		if (existingStart <= end && start <= existingEnd) emitDevWarning(`overlapping tracks for '${tr.target}' in [${start}, ${end}]: later insertion wins (${existing.track.keys.length - kept.length} earlier key(s) dropped)`);
+		existing.track.keys = [...kept, ...tr.keys].sort((a, b) => a.t - b.t);
+	}
+	const result = /* @__PURE__ */ new Map();
+	for (const [target, { track }] of byTarget) result.set(target, track);
+	return result;
+}
+/**
+* Studio reader (§6.2 rule 4): is this timeline's duration opted into editor
+* editing? Code-owned and read-only by default; `editableDuration()` flips it.
+*/
+function isDurationEditable(doc) {
+	return doc.editableDuration === true;
+}
+function childExtent(child) {
+	const scale = child.mode === "sync" ? child.timeScale ?? 1 : 1;
+	return child.at + computeDuration(child.timeline) / scale;
+}
+function computeDuration(doc) {
+	if (doc.duration !== void 0) return doc.duration;
+	let max = 0;
+	for (const tr of doc.tracks) {
+		const last = tr.keys[tr.keys.length - 1];
+		if (last) max = Math.max(max, last.t);
+	}
+	for (const m of doc.markers ?? []) max = Math.max(max, m.t);
+	for (const child of doc.children ?? []) max = Math.max(max, childExtent(child));
+	return max;
+}
+function compileTimeline(doc) {
+	if (doc.version !== 1) throw new TimelineValidationError(`unsupported timeline document version ${String(doc.version)}`);
+	const flat = [];
+	flatten(doc, 0, 1, 0, flat, { n: 0 });
+	const tracks = coalesce(flat);
+	const labels = { ...doc.labels };
+	const markers = [...doc.markers ?? []];
+	const audio = [...doc.audio ?? []];
+	const visitChildren = (children, at, scale, prefix) => {
+		(children ?? []).forEach((child, index) => {
+			const base = at + child.at / scale;
+			const childScale = scale * (child.mode === "sync" ? child.timeScale ?? 1 : 1);
+			const childPrefix = prefix + callMarkerPrefix(index);
+			for (const [name, t] of Object.entries(child.timeline.labels ?? {})) if (!(name in labels)) labels[name] = base + t / childScale;
+			for (const m of child.timeline.markers ?? []) markers.push({
+				...m,
+				name: namespaceCallName(m.name, childPrefix),
+				t: base + m.t / childScale
+			});
+			for (const clip of child.timeline.audio ?? []) audio.push({
+				...clip,
+				at: base + clip.at / childScale,
+				...childScale !== 1 ? { playbackRate: (clip.playbackRate ?? 1) * childScale } : {}
+			});
+			visitChildren(child.timeline.children, base, childScale, childPrefix);
+		});
+	};
+	visitChildren(doc.children, 0, 1, "");
+	markers.sort((a, b) => a.t - b.t);
+	audio.sort((a, b) => a.at - b.at);
+	return {
+		duration: computeDuration(doc),
+		labels,
+		markers,
+		tracks,
+		audio
+	};
+}
+//#endregion
+export { isDurationEditable as a, compileTimeline as i, audioOffsetSamples as n, namespaceCallName as o, callMarkerPrefix as r, timeline as s, TimelineValidationError as t };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@glissade/core",
-  "version": "0.19.0",
+  "version": "0.20.0-pre.3",
   "description": "glissade core: signals, tracks, timeline document, evaluation, easing, springs, seeded RNG. Zero DOM/Node dependencies.",
   "license": "Apache-2.0",
   "engines": {
@@ -21,6 +21,10 @@
       "types": "./dist/clips.d.ts",
       "default": "./dist/clips.js"
     },
+    "./sidecar": {
+      "types": "./dist/sidecar.d.ts",
+      "default": "./dist/sidecar.js"
+    },
     "./i18n": {
       "types": "./dist/i18n.d.ts",
       "default": "./dist/i18n.js"