@glissade/core 0.8.1 → 0.9.0-pre.1

package/dist/sidecar.d.ts

@@ -0,0 +1,510 @@
+//#region src/valueTypes.d.ts
+/**
+ * Value-type registry with pluggable per-type interpolation (DESIGN.md §2.2).
+ * `extrapolates` declares whether a type's lerp accepts easedT outside [0,1]
+ * (spring overshoot); non-extrapolating types clamp.
+ */
+type Vec2 = readonly [number, number];
+/** One bezier contour in Lottie's vertex form: anchor points + RELATIVE in/out tangents. */
+interface PathContour {
+  closed: boolean;
+  v: Vec2[];
+  in: Vec2[];
+  out: Vec2[];
+}
+/** The 'path' document value (§2.2): plain JSON, serializes with no new hooks. */
+type PathValue = PathContour[];
+/** Transition handoff policies (v2 addendum §A.4/§B.1); 'crossfade' reserved. */
+type HandoffKind = 'cut' | 'decay' | 'spring' | 'blend-from-frozen';
+interface ValueType<T> {
+  id: string;
+  lerp(a: T, b: T, t: number): T;
+  /** Accepts easedT outside [0,1] (spring overshoot)? Otherwise clamped. */
+  extrapolates: boolean;
+  equals(a: T, b: T): boolean;
+  /** Optional linear-space operators (offset decay + reserved additive blending, §B.6). */
+  add?(a: T, b: T): T;
+  sub?(a: T, b: T): T;
+  scale?(a: T, k: number): T;
+  /** Type-class handoff default (§B.1): spring for kinetic, cut for hold-only. */
+  defaultHandoff?: HandoffKind;
+  /** Document (de)serialization; default identity for JSON-native types (§2.2). */
+  serialize?(value: T): unknown;
+  deserialize?(raw: unknown): T;
+}
+type ValueTypeId = 'number' | 'vec2' | 'color' | 'string' | 'boolean' | (string & {});
+declare function registerValueType<T>(vt: ValueType<T>): void;
+declare class UnknownValueTypeError extends Error {
+  constructor(id: string);
+}
+declare function getValueType<T = unknown>(id: ValueTypeId): ValueType<T>;
+declare const numberType: ValueType<number>;
+declare const vec2Equals: (a: Vec2, b: Vec2) => boolean;
+declare const vec2Type: ValueType<Vec2>;
+/** vec2 swept along a circular arc: polar lerp of radius + shortest-path angle (§2.2). */
+declare const vec2ArcType: ValueType<Vec2>;
+declare const colorType: ValueType<string>;
+declare const stringType: ValueType<string>;
+declare const booleanType: ValueType<boolean>;
+/**
+ * Path morphing (§2.2): pairwise lerp of anchors and tangents — exactly how
+ * lottie-web morphs, so imported animations are pixel-faithful. Mismatched
+ * topology snaps (hold a, then b at t ≥ 1) with a one-time dev warning; the
+ * de Casteljau normalization fallback for arbitrary native morphs is tracked
+ * future work. Lerp-only: offsets are not well-defined under mismatched
+ * topology, so no add/sub/scale — handoffs blend from the frozen value.
+ */
+declare const pathType: ValueType<PathValue>;
+declare class ValueTypeInferenceError extends Error {
+  constructor(value: unknown);
+}
+/** Infer a registered type id from a sample value (builder + bake authoring surfaces). */
+declare function inferValueType(value: unknown): ValueTypeId;
+//#endregion
+//#region src/easing.d.ts
+/**
+ * Easing registry + cubic bézier (DESIGN.md §2.2). All functions map [0,1]→ℝ
+ * with f(0)=0 and f(1)=1; back/elastic intentionally leave [0,1].
+ */
+type EasingFn = (t: number) => number;
+type EaseSpec = string | {
+  kind: 'cubicBezier';
+  pts: [number, number, number, number];
+} | {
+  kind: 'spring';
+  stiffness: number;
+  damping: number;
+  mass: number;
+};
+declare const easings: Record<string, EasingFn>;
+/**
+ * Analytic derivatives d(u) of every named ease (§B.6) — closed-form, used
+ * for reading velocity off in-flight curves at interruption time. Property-
+ * tested against central differences at interior points.
+ */
+declare const easingDerivatives: Record<string, EasingFn>;
+/** Default property-tween ease (Motion Canvas precedent). */
+declare const DEFAULT_EASE = "easeInOutCubic";
+/**
+ * CSS-style cubic bézier where x is time and y is progress. Newton's method
+ * with a bisection fallback for the flat-derivative regions.
+ */
+declare function cubicBezier(p1x: number, p1y: number, p2x: number, p2y: number): EasingFn;
+/** Analytic dy/dx of a cubic bézier ease: y'(s)/x'(s) at the solved parameter (§B.6). */
+declare function cubicBezierDerivative(p1x: number, p1y: number, p2x: number, p2y: number): EasingFn;
+declare class UnknownEasingError extends Error {
+  constructor(name: string);
+}
+declare function namedEasing(name: string): EasingFn;
+//#endregion
+//#region src/spring.d.ts
+interface SpringConfig {
+  stiffness: number;
+  damping: number;
+  mass?: number;
+}
+interface SpringEase {
+  kind: 'spring';
+  stiffness: number;
+  damping: number;
+  mass: number;
+}
+/**
+ * Settle duration: the earliest time after which |x - 1| stays within
+ * settleTolerance. Closed-form via the decay envelope for the underdamped
+ * case; bisection on the monotone tail otherwise. Deterministic.
+ */
+declare function duration(cfg: SpringConfig, opts?: {
+  settleTolerance?: number;
+}): number;
+/**
+ * Spring progress at local time t, affinely rescaled so value(duration) = 1
+ * exactly — the raw form only approaches 1, and an unscaled curve would snap
+ * at the key (§2.7 "endpoint continuity"). May exceed 1 (overshoot).
+ */
+declare function value(cfg: SpringConfig, t: number, opts?: {
+  settleTolerance?: number;
+}): number;
+/**
+ * Velocity-matched retarget oscillator (v2 addendum §B.3): the same damped
+ * harmonic oscillator on an OFFSET in value units with nonzero initial
+ * velocity — y(0)=x0, y'(0)=v0, decaying to 0. No affine rescale (the target
+ * is exactly 0). Pure closed forms; seek-safe at any τ.
+ */
+interface RetargetSpring {
+  value(tau: number): number;
+  velocity(tau: number): number;
+  /** Earliest τ after which |value| stays within tol (default 0.005·|x0|+1e-6 floor). */
+  settleTime(tol?: number): number;
+}
+declare function retarget(cfg: SpringConfig, x0: number, v0: number): RetargetSpring;
+interface SpringFactory {
+  (cfg: SpringConfig): SpringEase;
+  duration: typeof duration;
+  value: typeof value;
+  retarget: typeof retarget;
+}
+declare const spring: SpringFactory;
+/**
+ * Named spring feels (react-spring conventions, mass 1) — a vocabulary instead
+ * of hand-tuned stiffness/damping. Use `spring(springPresets.wobbly)` or
+ * `springTo(t, a, b, springPresets.gentle)`.
+ */
+declare const springPresets: {
+  readonly default: {
+    readonly stiffness: 170;
+    readonly damping: 26;
+  };
+  readonly gentle: {
+    readonly stiffness: 120;
+    readonly damping: 14;
+  };
+  readonly wobbly: {
+    readonly stiffness: 180;
+    readonly damping: 12;
+  };
+  readonly stiff: {
+    readonly stiffness: 210;
+    readonly damping: 20;
+  };
+  readonly slow: {
+    readonly stiffness: 280;
+    readonly damping: 60;
+  };
+  readonly molasses: {
+    readonly stiffness: 280;
+    readonly damping: 120;
+  };
+};
+/**
+ * The spring as a normalized easing over a segment whose length must equal
+ * spring.duration(cfg) (validated at the document layer, §2.7).
+ */
+declare function springEasing(cfg: SpringConfig): EasingFn;
+/**
+ * Analytic d/dp of springEasing (§B.6): oscillator derivative × the affine
+ * rescale factor × duration (chain rule p → t = p·D). Flat past p=1,
+ * matching value()'s clamp (right-derivative convention).
+ */
+declare function springEasingDerivative(cfg: SpringConfig): EasingFn;
+//#endregion
+//#region src/track.d.ts
+interface Key<T = unknown> {
+  t: number;
+  value: T;
+  /** Shape of the segment ARRIVING at this key (from the previous key). */
+  ease?: EaseSpec;
+  interp?: 'default' | 'hold';
+  /** Stable key id (studio-assigned); optional in code-authored documents. */
+  id?: string;
+  /** Builder-resolved implicit from-value; re-resolved on merge (§2.6, §6.2). */
+  derived?: boolean;
+  /** Reserved (§4.7): a v2 synthesized-transition leading key reads the live value. v1 accepts but ignores it. */
+  from?: 'live';
+}
+interface Track<T = unknown> {
+  /** Canonical path: '<nodeId>/<prop.path>', e.g. 'circle/position.x'. */
+  target: string;
+  type: ValueTypeId;
+  /** Sorted by t; enforced by validateTrack(). */
+  keys: Key<T>[];
+  /** Studio may own this track's keys via sidecar (§6.2). */
+  editable?: boolean;
+  /** Reserved (§2.2/§B.6): v2 additive blending. v1 accepts but ignores it (coalesce stays last-wins). */
+  additive?: boolean;
+}
+declare class TrackValidationError extends Error {
+  constructor(target: string, message: string);
+}
+declare function validateTrack(track: Track): void;
+type KeyOpts<T> = Partial<Omit<Key<T>, 't' | 'value'>>;
+declare function key<T>(t: number, value: T, easeOrOpts?: EaseSpec | KeyOpts<T>): Key<T>;
+/**
+ * The settle-ON-the-beat helper: a spring key must sit at prev.t +
+ * spring.duration(cfg) (§2.7), so beat-anchored authoring otherwise means
+ * hand-computing the launch time. springTo returns the [launch, settle] key
+ * pair with the arithmetic done — spread it into a raw track():
+ *   track('x/width', 'number', [...springTo(beats.start('drop'), 0, 320, cfg)])
+ */
+declare function springTo<T>(endT: number, from: T, to: T, cfg: SpringConfig): [Key<T>, Key<T>];
+/**
+ * Cascade a set of tracks by shifting each one's key times — the classic
+ * stagger for animating a list of nodes with a delay between them. `delay` is
+ * the per-index gap in seconds, or a function of the index for non-linear
+ * cascades. Pure: returns new tracks, leaving the inputs untouched.
+ *
+ *   stagger(items.map((it, i) => track(`${it.id}/opacity`, 'number',
+ *     [key(0, 0), key(0.3, 1, 'easeOutCubic')])), 0.08)
+ */
+declare function stagger<T>(tracks: readonly Track<T>[], delay: number | ((index: number) => number)): Track<T>[];
+declare function track<T>(target: string, type: ValueTypeId, keys: Key<T>[], opts?: {
+  editable?: boolean;
+}): Track<T>;
+declare function resolveEase(spec: EaseSpec | undefined): EasingFn;
+/**
+ * Analytic d(u) for an ease spec (§B.6). Custom-registered eases without a
+ * derivative fall back to a symmetric difference with a one-time dev warning.
+ */
+declare function resolveEaseDerivative(spec: EaseSpec | undefined): EasingFn;
+/**
+ * Analytic track derivative at time t, in value-units per second of local
+ * track time (v2 addendum §B.3/§B.6 conventions, pinned):
+ * (a) at a key boundary, velocity is the RIGHT derivative;
+ * (b) hold segments and the clamped regions outside the keys have v = 0;
+ * (c) types without sub/scale operators return null (no kinetic velocity).
+ */
+declare function velocityAt<T>(tr: Track<T>, t: number): T | null;
+/** Pure sample of a track at time t (§2.4). */
+declare function sampleTrack<T>(tr: Track<T>, t: number): T;
+//#endregion
+//#region src/devWarning.d.ts
+/** The configurable dev-warning channel (no DOM lib in core; console may not exist). */
+type DevWarning = (message: string) => void;
+declare function setDevWarning(fn: DevWarning): void;
+/** Internal: emit through the configurable channel. */
+declare function emitDevWarning(message: string): void;
+//#endregion
+//#region src/timeline.d.ts
+type Json = null | boolean | number | string | Json[] | {
+  [k: string]: Json;
+};
+interface Marker {
+  t: number;
+  name: string;
+  data?: Json;
+}
+/**
+ * One concrete font face within a family — a (weight, style) variant at a URL.
+ * `weight`/`style` default to 400/'normal' (the CSS regular face). Lives on
+ * AssetRef.faces; a bare `{ kind: 'font', url }` is exactly the 400/normal face
+ * with no extra variants (so existing documents stay byte-identical, §3.6).
+ */
+interface FontFaceRef {
+  url: string;
+  weight?: number | undefined;
+  style?: 'normal' | 'italic' | undefined;
+}
+interface AssetRef {
+  kind: 'font' | 'image' | 'audio' | 'video' | 'timeline';
+  url: string;
+  /**
+   * Font only (§3.6): the explicit face set for this family. When present, the
+   * loaders register EVERY face (not the single `url`); the family-level `url`
+   * is the implicit 400/normal face. Omitted = the bare single-face form.
+   */
+  faces?: FontFaceRef[] | undefined;
+  /**
+   * Font only (§3.6): the explicit fallback family chain, in order. The
+   * registry resolves `[family, ...fallback]` for glyph coverage. Omitted = no
+   * declared fallback (system fallback still applies in the rasterizer).
+   */
+  fallback?: string[] | undefined;
+}
+/**
+ * A gain envelope: keys of linear gain multipliers on the clip's local time
+ * axis. A full Track satisfies it structurally, but its target/type carry no
+ * meaning here — `{ keys: [...] }` is all a clip needs.
+ */
+interface GainEnvelope {
+  keys: Key[];
+}
+/** Audio is timeline metadata, never a render product (§5.3). */
+interface AudioClip {
+  asset: AssetRef;
+  /** timeline seconds (frame-quantized at export via sample-position arithmetic) */
+  at: number;
+  /** seconds within the source asset */
+  trim?: {
+    start: number;
+    end: number;
+  };
+  gain?: GainEnvelope;
+  playbackRate?: number;
+}
+interface ChildEntry {
+  timeline: Timeline;
+  /** Offset on the parent time axis. */
+  at: number;
+  /**
+   * 'add': flattened at compile time into the parent's track space.
+   * 'sync': opaque sub-timeline with its own clock (parent t maps through
+   * at/timeScale); never coalesced against parent tracks.
+   */
+  mode: 'add' | 'sync';
+  /** sync-mode only: child plays at this rate. */
+  timeScale?: number;
+}
+interface Timeline {
+  version: 1;
+  duration?: number;
+  /**
+   * Studio opt-in (§6.2 rule 4): the timeline duration is code-owned and
+   * read-only in the editor UNLESS this flag is set (via `editableDuration()`
+   * on the builder, or directly). Mirrors `track.editable` for tracks.
+   */
+  editableDuration?: boolean;
+  fps?: number;
+  posterTime?: number;
+  tracks: Track[];
+  labels?: Record<string, number>;
+  markers?: Marker[];
+  children?: ChildEntry[];
+  audio?: AudioClip[];
+  assets?: Record<string, AssetRef>;
+}
+interface TimelineInit {
+  tracks?: Track[];
+  duration?: number;
+  /** Studio opt-in: expose the duration to editor editing (§6.2 rule 4). */
+  editableDuration?: boolean;
+  fps?: number;
+  posterTime?: number;
+  labels?: Record<string, number>;
+  markers?: Marker[];
+  children?: ChildEntry[];
+  audio?: AudioClip[];
+  assets?: Record<string, AssetRef>;
+}
+declare class TimelineValidationError extends Error {
+  constructor(message: string);
+}
+interface CompiledTimeline {
+  duration: number;
+  labels: Record<string, number>;
+  markers: Marker[];
+  /** One track per target (§2.2), keys rebased to the root time axis. */
+  tracks: Map<string, Track>;
+  /** Audio clips rebased to the root time axis (§5.3); sync timeScale scales playbackRate. */
+  audio: AudioClip[];
+}
+/**
+ * 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.
+ */
+declare function audioOffsetSamples(at: number, sampleRate?: number): number;
+/**
+ * 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.
+ */
+declare function isDurationEditable(doc: Timeline): boolean;
+declare function compileTimeline(doc: Timeline): CompiledTimeline;
+//#endregion
+//#region src/targetRef.d.ts
+/**
+ * Target references (DESIGN.md §2.6): the builder accepts either a canonical
+ * target string ('circle/opacity') or a property signal that carries its own
+ * path — attached by the scene package at node construction via TARGET_PATH.
+ */
+declare const TARGET_PATH: unique symbol;
+interface TargetCarrier {
+  [TARGET_PATH]?: string;
+}
+/**
+ * A target string, or any object carrying TARGET_PATH (property signals of
+ * id-bearing nodes). Typed as `object` because signals are callables and the
+ * symbol prop is attached dynamically; resolution is checked at build time.
+ */
+type TweenTarget = string | object;
+declare class UnresolvableTargetError extends Error {
+  constructor(message?: string);
+}
+/** The node-id portion of a canonical `nodeId/prop.path` target. */
+declare function targetNodeId(target: string): string;
+/**
+ * The single editable-host rule (§6.4 sub-decision, the 0.9 locked predicate):
+ * only a node with an EXPLICIT, non-structural id can host an editable or
+ * editor-created track. Structural fallback ids (`~Type.ordinal`, §6.5) are
+ * inspection-only and reorder-fragile, so they are never editable nor valid
+ * track targets. Lives here (the addressing module) so the builder guard, the
+ * scene, and the studio host all share ONE definition.
+ */
+declare function isEditableNodeId(id: string | undefined | null): id is string;
+declare function resolveTweenTarget(target: TweenTarget): string;
+//#endregion
+//#region src/sidecar.d.ts
+type OrphanReason = 'node-missing' | 'prop-missing' | 'type-changed';
+interface SidecarTrackEntry {
+  /** value type, so an editor-created track binds without a code baseline. */
+  type: ValueTypeId;
+  /** hash of the code baseline this track branched from; null = editor-created. */
+  baseHash: string | null;
+  keys: Key[];
+}
+interface SidecarOrphan {
+  type: ValueTypeId;
+  keys: Key[];
+  reason: OrphanReason;
+}
+interface SidecarTimelineEntry {
+  /** editor-owned tracks, keyed by canonical target. */
+  tracks: Record<string, SidecarTrackEntry>;
+  /** editor-created labels. */
+  labels?: Record<string, number>;
+  /** tracks parked off the merge because their target drifted (§6.2 rule 3). */
+  orphans?: Record<string, SidecarOrphan>;
+}
+interface SidecarDoc {
+  sidecarVersion: 2;
+  /** edits namespaced by timeline id; the linear timeline is 'main'. */
+  timelines: Record<string, SidecarTimelineEntry>;
+}
+/** The flat v1 shape, accepted on load and migrated forward. */
+interface SidecarDocV1 {
+  sidecarVersion: 1;
+  tracks: Track[];
+  labels?: Record<string, number>;
+}
+declare class SidecarVersionError extends Error {
+  constructor(version: unknown);
+}
+declare function emptySidecar(): SidecarDoc;
+/** Lift a v1 (or already-v2) document to the v2 shape. Throws on unknown versions. */
+declare function migrateSidecar(doc: SidecarDoc | SidecarDocV1 | null | undefined): SidecarDoc | null;
+/** Stable hash of a code track's keys — the baseline an editor branch records. */
+declare function hashKeys(keys: readonly Key[]): string;
+/** Assign stable monotonic `k<N>` ids to keys lacking one; existing ids preserved. */
+declare function assignKeyIds(keys: readonly Key[]): Key[];
+/**
+ * Set one editable track's keys in the sidecar (§6.2) — the studio write path.
+ * `codeBaselineKeys` is the code track this branches from (null = editor-created
+ * with no baseline). Keys get stable `k<N>` ids. Returns a new document.
+ */
+declare function setSidecarTrack(doc: SidecarDoc, timelineId: string, target: string, type: ValueTypeId, keys: Key[], codeBaselineKeys: readonly Key[] | null): SidecarDoc;
+/**
+ * Remove one editor-owned track from the sidecar (§6.2 rule 7 write-back): the
+ * "extract edits to code" affordance deletes the sidecar entry after copying its
+ * `key(...)` source to the clipboard. Source is never mutated — the user pastes
+ * the generated calls themselves. A missing entry is a no-op (returns the input
+ * unchanged); the document is never mutated in place.
+ */
+declare function deleteSidecarTrack(doc: SidecarDoc, timelineId: string, target: string): SidecarDoc;
+interface MergeResult {
+  timeline: Timeline;
+  /** targets whose code baseline changed beneath the editor's keys (§6.2 rule 2). */
+  drift: string[];
+  /** sidecar tracks parked off the merge (§6.2 rule 3). */
+  orphans: Record<string, SidecarOrphan>;
+}
+/**
+ * Merge with the full §6.2 report: the bindable Timeline, the list of targets
+ * whose code baseline drifted, and the orphaned tracks (type-changed, or whose
+ * code track vanished). Orphans are NEVER merged, so a drifted edit can't make
+ * the whole overlay fail to bind — the good edits survive. Inputs unmutated.
+ */
+declare function mergeSidecarDetailed(code: Timeline, sidecar: SidecarDoc | SidecarDocV1 | null | undefined): MergeResult;
+/** Merge the sidecar overlay onto the code baseline → a bindable Timeline (§6.2). */
+declare function mergeSidecar(code: Timeline, sidecar: SidecarDoc | SidecarDocV1 | null | undefined): Timeline;
+/**
+ * Editor-edit normalization (§2.7 invariant): a spring-eased key's t is
+ * intrinsic — prev.t + spring.duration(cfg) — so after any retime, sort and
+ * re-pin spring keys to their predecessors. Dragging a spring key itself
+ * therefore snaps back; retiming its predecessor carries it along. Returns a
+ * new array. Colliding keys are NUDGED apart (+1ms), never deleted — an editor
+ * must not silently destroy keyframe data on an exact-t collision.
+ */
+declare function normalizeEditedKeys(keys: Key[]): Key[];
+//#endregion
+export { validateTrack as $, GainEnvelope as A, pathType as At, emitDevWarning as B, resolveTweenTarget as C, ValueTypeInferenceError as Ct, ChildEntry as D, getValueType as Dt, AudioClip as E, colorType as Et, TimelineValidationError as F, vec2Type as Ft, TrackValidationError as G, Key as H, audioOffsetSamples as I, resolveEaseDerivative as J, key as K, compileTimeline as L, Marker as M, stringType as Mt, Timeline as N, vec2ArcType as Nt, CompiledTimeline as O, inferValueType as Ot, TimelineInit as P, vec2Equals as Pt, track as Q, isDurationEditable as R, isEditableNodeId as S, ValueTypeId as St, AssetRef as T, booleanType as Tt, KeyOpts as U, setDevWarning as V, Track as W, springTo as X, sampleTrack as Y, stagger as Z, setSidecarTrack as _, HandoffKind as _t, SidecarOrphan as a, springEasing as at, TweenTarget as b, UnknownValueTypeError as bt, SidecarVersionError as c, DEFAULT_EASE as ct, emptySidecar as d, UnknownEasingError as dt, velocityAt as et, hashKeys as f, cubicBezier as ft, normalizeEditedKeys as g, namedEasing as gt, migrateSidecar as h, easings as ht, SidecarDocV1 as i, spring as it, Json as j, registerValueType as jt, FontFaceRef as k, numberType as kt, assignKeyIds as l, EaseSpec as lt, mergeSidecarDetailed as m, easingDerivatives as mt, OrphanReason as n, SpringConfig as nt, SidecarTimelineEntry as o, springEasingDerivative as ot, mergeSidecar as p, cubicBezierDerivative as pt, resolveEase as q, SidecarDoc as r, SpringEase as rt, SidecarTrackEntry as s, springPresets as st, MergeResult as t, RetargetSpring as tt, deleteSidecarTrack as u, EasingFn as ut, TARGET_PATH as v, PathContour as vt, targetNodeId as w, Vec2 as wt, UnresolvableTargetError as x, ValueType as xt, TargetCarrier as y, PathValue as yt, DevWarning as z };