@glissade/core 0.11.0 → 0.12.0-pre.0

package/dist/sidecar.d.ts

@@ -1,473 +1,8 @@
-//#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>;
-/** A gradient color stop: `offset` 0..1 along the gradient, `color` a CSS string. */
-interface ColorStop {
-  offset: number;
-  color: string;
-}
-/**
- * How a gradient blends BETWEEN its stops: `linear` (the canvas-native ramp,
- * the default — byte-identical to no mode), `smooth` (a smoothstep S-curve, no
- * Mach-banding at stops), or `gaussian` (a soft gaussian shoulder — melts like
- * a wide blur with 2-3 stops). `smooth`/`gaussian` densify + oklab-interpolate
- * the stops at raster, so a soft-light fill reads as smooth as a blur, no filter.
- */
-type GradientInterpolation = 'linear' | 'smooth' | 'gaussian';
-/**
- * A fill/stroke paint (§2.2 animatable document value): a solid color, or a
- * `linear`/`radial` gradient. Geometry (`from`/`to`, `center`/`radius`) is in
- * the shape's LOCAL space; omit it to default to the filled path's bounds.
- * Plain JSON — serializes with no hooks; animatable via `paintType`.
- */
-type Paint = {
-  kind: 'color';
-  color: string;
-} | {
-  kind: 'linear';
-  stops: ColorStop[];
-  from?: [number, number];
-  to?: [number, number];
-  interpolation?: GradientInterpolation;
-} | {
-  kind: 'radial';
-  stops: ColorStop[];
-  center?: [number, number];
-  radius?: number;
-  interpolation?: GradientInterpolation;
-};
-/**
- * Gradient paint morphing (§2.2): a solid color lifts to a uniform gradient to
- * meet the other side, then matched-kind/matched-stop-count gradients lerp their
- * stops (offset + oklab color) and geometry pairwise; a mismatched kind or stop
- * count snaps (hold a, then b at t ≥ 1) with a one-time dev warning. Lerp-only —
- * no offsets under mismatch — so handoffs blend from the frozen value.
- */
-declare const paintType: ValueType<Paint>;
-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
+import { T as ValueTypeId, r as Track, t as Key } from "./track.js";
+import { l as Timeline } from "./timeline.js";
+
 //#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. */
@@ -550,4 +85,4 @@ declare function mergeSidecar(code: Timeline, sidecar: SidecarDoc | SidecarDocV1
  */
 declare function normalizeEditedKeys(keys: Key[]): Key[];
 //#endregion
-export { validateTrack as $, GainEnvelope as A, getValueType as At, emitDevWarning as B, resolveTweenTarget as C, UnknownValueTypeError as Ct, ChildEntry as D, Vec2 as Dt, AudioClip as E, ValueTypeInferenceError as Et, TimelineValidationError as F, registerValueType as Ft, TrackValidationError as G, Key as H, audioOffsetSamples as I, stringType as It, resolveEaseDerivative as J, key as K, compileTimeline as L, vec2ArcType as Lt, Marker as M, numberType as Mt, Timeline as N, paintType as Nt, CompiledTimeline as O, booleanType as Ot, TimelineInit as P, pathType as Pt, track as Q, isDurationEditable as R, vec2Equals as Rt, isEditableNodeId as S, PathValue as St, AssetRef as T, ValueTypeId as Tt, KeyOpts as U, setDevWarning as V, Track as W, springTo as X, sampleTrack as Y, stagger as Z, setSidecarTrack as _, ColorStop as _t, SidecarOrphan as a, springEasing as at, TweenTarget as b, Paint 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, inferValueType as jt, FontFaceRef as k, colorType 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, GradientInterpolation as vt, targetNodeId as w, ValueType as wt, UnresolvableTargetError as x, PathContour as xt, TargetCarrier as y, HandoffKind as yt, DevWarning as z, vec2Type as zt };
+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 };