@glissade/core 0.11.0 → 0.12.0-pre.1

package/dist/timeline.d.ts

@@ -0,0 +1,138 @@
+import { r as Track, t as Key } from "./track.js";
+
+//#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
+export { setDevWarning as _, FontFaceRef as a, Marker as c, TimelineValidationError as d, audioOffsetSamples as f, emitDevWarning as g, DevWarning as h, CompiledTimeline as i, Timeline as l, isDurationEditable as m, AudioClip as n, GainEnvelope as o, compileTimeline as p, ChildEntry as r, Json as s, AssetRef as t, TimelineInit as u };

package/dist/track.d.ts

@@ -0,0 +1,329 @@
+//#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/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';
+/** One mesh-gradient color point: `pos` in normalized [0,1]² fill space, `color`
+ * a CSS string. Both are ANIMATABLE (e.g. `track('node/fill.points.0.color', …)`
+ * drives aurora drift on one node). */
+interface MeshPoint {
+  pos: [number, number];
+  color: string;
+}
+/**
+ * How a `mesh` Paint blends its scattered color points: `smooth` (Shepard
+ * inverse-distance weighting in OKLab — sharper points), `gaussian` (a pinned-
+ * sigma gaussian melt — a softer, blurrier aurora), or `oklab` (an alias for
+ * `smooth`; the blend space is always OKLab). NO triangulator — one shared
+ * deterministic kernel both backends run (§3 Paint).
+ */
+type MeshInterpolation = 'smooth' | 'gaussian' | 'oklab';
+/** A native mesh-gradient fill: N color points blended across the [0,1]² fill
+ * rectangle as ONE animatable fill (replaces the "N blurred blobs" aurora). */
+interface MeshPaint {
+  kind: 'mesh';
+  points: MeshPoint[];
+  interpolation?: MeshInterpolation;
+  /** Optional baseline color (a zero-weight floor) so a sparse mesh doesn't smear
+   * one point across the whole rect; omit for a pure points-only blend. */
+  bg?: string;
+}
+/**
+ * A fill/stroke paint (§2.2 animatable document value): a solid color, a
+ * `linear`/`radial` gradient, or a `mesh` gradient. Geometry (`from`/`to`,
+ * `center`/`radius`, mesh `pos`) is in the shape's LOCAL space; omit gradient
+ * geometry 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;
+} | MeshPaint;
+/**
+ * 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/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
+export { easingDerivatives as $, getValueType as A, RetargetSpring as B, UnknownValueTypeError as C, Vec2 as D, ValueTypeInferenceError as E, registerValueType as F, springEasingDerivative as G, SpringEase as H, stringType as I, EaseSpec as J, springPresets as K, vec2ArcType as L, numberType as M, paintType as N, booleanType as O, pathType as P, cubicBezierDerivative as Q, vec2Equals as R, PathValue as S, ValueTypeId as T, spring as U, SpringConfig as V, springEasing as W, UnknownEasingError as X, EasingFn as Y, cubicBezier as Z, MeshInterpolation as _, key as a, Paint as b, sampleTrack as c, track as d, easings as et, validateTrack as f, HandoffKind as g, GradientInterpolation as h, TrackValidationError as i, inferValueType as j, colorType as k, springTo as l, ColorStop as m, KeyOpts as n, resolveEase as o, velocityAt as p, DEFAULT_EASE as q, Track as r, resolveEaseDerivative as s, Key as t, namedEasing as tt, stagger as u, MeshPaint as v, ValueType as w, PathContour as x, MeshPoint as y, vec2Type as z };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@glissade/core",
-  "version": "0.11.0",
+  "version": "0.12.0-pre.1",
   "description": "glissade core: signals, tracks, timeline document, evaluation, easing, springs, seeded RNG. Zero DOM/Node dependencies.",
   "license": "Apache-2.0",
   "engines": {
@@ -16,6 +16,14 @@
     "./studio-host": {
       "types": "./dist/studioHost.d.ts",
       "default": "./dist/studioHost.js"
+    },
+    "./clips": {
+      "types": "./dist/clips.d.ts",
+      "default": "./dist/clips.js"
+    },
+    "./font-ingest": {
+      "types": "./dist/font-ingest.d.ts",
+      "default": "./dist/font-ingest.js"
     }
   },
   "files": [
@@ -26,6 +34,9 @@
     "url": "git+https://github.com/tyevco/glissade.git",
     "directory": "packages/core"
   },
+  "optionalDependencies": {
+    "subset-font": "^2.5.0"
+  },
   "scripts": {
     "build": "tsdown",
     "typecheck": "tsc --noEmit"