@glissade/core 0.9.1 → 0.10.0-pre.0

package/dist/index.d.ts

@@ -9,6 +9,13 @@ import { $ as validateTrack, A as GainEnvelope, At as pathType, B as emitDevWarn
  * transitive dependents CHECK. A CHECK node re-validates dependency versions on
  * read and only recomputes if one actually changed; a recompute that produces an
  * equal value keeps its version, so dirtiness stops propagating at that node.
+ *
+ * Subscriber NOTIFICATION (only) is routed through the ticker (`./ticker.ts`,
+ * DESIGN.md §6.1): a write enqueues affected subscribers and the active
+ * scheduler decides when to flush. The default scheduler is synchronous and
+ * flushes at the end of the outermost write, reproducing the pre-ticker timing
+ * byte-for-byte. The read path (get/peek/updateIfNecessary) is untouched and
+ * stays fully synchronous.
  */
 type Equals<T> = (a: T, b: T) => boolean;
 declare class WriteDuringEvaluationError extends Error {
@@ -45,6 +52,52 @@ declare function computed<T>(fn: () => T, options?: SignalOptions<T>): ReadonlyS
 /** Run `fn` without registering dependencies on the active consumer. */
 declare function untracked<T>(fn: () => T): T;
 //#endregion
+//#region src/ticker.d.ts
+/**
+ * Per-tick subscriber-notification coalescer (DESIGN.md §6.1).
+ *
+ * Signals stay pull-based and synchronous on the READ path: peek/get/evaluate
+ * return the new value immediately after set() — the DIRTY/CHECK staleness
+ * cascade is untouched (§2.1). This module times only *subscriber notification*:
+ * a write enqueues each affected subscriber, and a scheduler decides when the
+ * queue is flushed.
+ *
+ * The default scheduler is **synchronous**: it flushes at the end of the
+ * outermost write (or batch), so a single set() outside any batch notifies its
+ * subscribers inline — byte-for-byte the timing the framework had before this
+ * module existed. `batch(fn)` coalesces every write inside `fn` into one flush;
+ * `setScheduler` lets a consumer defer the flush to a microtask / rAF so that a
+ * scrub frame dirtying N signals produces one observer pass (Theatre's
+ * `dataverse` Ticker pattern).
+ *
+ * Determinism: nothing here is reachable from evaluate(). No Date.now /
+ * performance.now / Math.random / setTimeout lives on this path; the default
+ * scheduler is pure and synchronous, and a write *during* a flush is drained by
+ * a bounded loop rather than recursion.
+ */
+/**
+ * A scheduler receives the coalesced `flush` and decides when to run it. It must
+ * call `flush` exactly once per request (calling it synchronously reproduces the
+ * default, eager behavior). A microtask/rAF scheduler defers the call.
+ */
+type Scheduler = (flush: () => void) => void;
+/** The default scheduler: flush synchronously, preserving pre-ticker timing. */
+declare const synchronousScheduler: Scheduler;
+/**
+ * Install a notification scheduler. Pass the synchronous default back (or call
+ * with no argument) to restore eager flushing. Returns the previous scheduler.
+ */
+declare function setScheduler(next?: Scheduler): Scheduler;
+/** The synchronous default scheduler, exported so callers can restore it. */
+
+/**
+ * Coalesce every signal write inside `fn` into a single subscriber-notification
+ * pass. Reads inside `fn` stay synchronous and see each write immediately; only
+ * the *notification* is deferred to the end. Nested batches flush once, at the
+ * outermost exit. Returns whatever `fn` returns.
+ */
+declare function batch<T>(fn: () => T): T;
+//#endregion
 //#region src/vec2Signal.d.ts
 interface Vec2Signal extends ReadonlySignal<Vec2> {
   readonly x: BindableSignal<number>;
@@ -124,7 +177,7 @@ declare function buildFontRegistry(assets?: Record<string, AssetRef> | undefined
  *   - format 12 (segmented coverage — astral planes, e.g. emoji)
  * Malformed or unsupported input yields an empty set; it never throws or hangs.
  */
-declare function parseCmap(bytes: ArrayBuffer): Set<number>;
+declare function parseCmap(bytes: ArrayBuffer | ArrayBufferView): Set<number>;
 //#endregion
 //#region src/fontValidation.d.ts
 type FontMode = 'strict' | 'dev';
@@ -304,4 +357,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, type BindableSignal, type BoundTimeline, type CheckpointedBakeConfig, type CheckpointedSim, type ChildEntry, CircularDependencyError, ColorParseError, 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 HandoffKind, type Json, type Key, type KeyOpts, type Marker, type MergeResult, type MissingGlyphs, type OkLab, type OrphanReason, type PathContour, type PathValue, type Playhead, type Position, PositionError, type ReadonlySignal, type ResolvedFace, type RetargetSpring, type Rgba, type Rng, type SidecarDoc, type SidecarDocV1, type SidecarOrphan, type SidecarTimelineEntry, type SidecarTrackEntry, SidecarVersionError, type Signal, type SignalOptions, type SpringConfig, type SpringEase, 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 Vec2Signal, WriteDuringEvaluationError, assignKeyIds, audioOffsetSamples, bake, bakeCheckpointed, 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, mergeSidecar, mergeSidecarDetailed, migrateSidecar, namedEasing, normalizeEditedKeys, numberType, oklabToRgba, parseCmap, parseColor, pathType, random, registerValueType, resolveEase, resolveEaseDerivative, resolveTweenTarget, rgbaToOklab, sampleTrack, setDevWarning, setSidecarTrack, signal, spring, springEasing, springEasingDerivative, springPresets, springTo, stagger, stringType, targetNodeId, timeline, track, untracked, validateFonts, validateTrack, vec2ArcType, vec2Equals, vec2Signal, vec2Type, velocityAt };
+export { type AssetRef, type AudioClip, type BakeConfig, BakeError, type BindTarget, type BindableSignal, type BoundTimeline, type CheckpointedBakeConfig, type CheckpointedSim, type ChildEntry, CircularDependencyError, ColorParseError, 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 HandoffKind, type Json, type Key, type KeyOpts, type Marker, type MergeResult, type MissingGlyphs, type OkLab, type OrphanReason, 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, 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 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, mergeSidecar, mergeSidecarDetailed, migrateSidecar, namedEasing, normalizeEditedKeys, numberType, oklabToRgba, parseCmap, parseColor, pathType, random, registerValueType, 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 };

package/dist/index.js

@@ -1,5 +1,125 @@
 import { $ as vec2Equals, A as velocityAt, B as easings, C as resolveEase, D as stagger, E as springTo, F as DEFAULT_EASE, G as colorType, H as UnknownValueTypeError, I as UnknownEasingError, J as numberType, K as getValueType, L as cubicBezier, M as springEasing, N as springEasingDerivative, O as track, P as springPresets, Q as vec2ArcType, R as cubicBezierDerivative, S as key, T as sampleTrack, U as ValueTypeInferenceError, V as namedEasing, W as booleanType, X as registerValueType, Y as pathType, Z as stringType, _ as audioOffsetSamples, a as hashKeys, at as lerpColor, b as timeline$1, c as migrateSidecar, ct as rgbaToOklab, d as TARGET_PATH, et as vec2Type, f as UnresolvableTargetError, g as TimelineValidationError, h as targetNodeId, i as emptySidecar, it as formatColor, j as spring, k as validateTrack, l as normalizeEditedKeys, m as resolveTweenTarget, n as assignKeyIds, nt as setDevWarning, o as mergeSidecar, ot as oklabToRgba, p as isEditableNodeId, q as inferValueType, r as deleteSidecarTrack, rt as ColorParseError, s as mergeSidecarDetailed, st as parseColor, t as SidecarVersionError, tt as emitDevWarning, u as setSidecarTrack, v as compileTimeline, w as resolveEaseDerivative, x as TrackValidationError, y as isDurationEditable, z as easingDerivatives } from "./sidecar.js";
+//#region src/ticker.ts
+/** The default scheduler: flush synchronously, preserving pre-ticker timing. */
+const synchronousScheduler = (flush) => flush();
+let scheduler = synchronousScheduler;
+/** Pending subscriber callbacks for the current tick (deduped, insertion-ordered). */
+const pending = /* @__PURE__ */ new Set();
+/**
+* Depth of active `batch()` calls *plus* in-flight top-level writes; >0
+* suppresses flushing so a write's whole staleness cascade completes before any
+* subscriber runs, and `batch()` coalesces across writes.
+*/
+let batchDepth = 0;
+/** True while a flush is in progress, so writes mid-flush enqueue, not re-flush. */
+let flushing = false;
+/** True once a flush has been requested from the scheduler but not yet run. */
+let flushScheduled = false;
+/** Guard against an unbounded write-during-flush cascade. */
+const MAX_FLUSH_PASSES = 1e3;
+/**
+* Install a notification scheduler. Pass the synchronous default back (or call
+* with no argument) to restore eager flushing. Returns the previous scheduler.
+*/
+function setScheduler(next) {
+	const prev = scheduler;
+	scheduler = next ?? synchronousScheduler;
+	if (flushScheduled && !flushing) {
+		flushScheduled = false;
+		if (pending.size > 0) requestFlush();
+	}
+	return prev;
+}
+/**
+* Enqueue a subscriber notification. Called by the signal layer in place of
+* invoking the callback directly. Honors the active batch and scheduler.
+*/
+function enqueueNotification(cb) {
+	pending.add(cb);
+	requestFlush();
+}
+function requestFlush() {
+	if (batchDepth > 0 || flushing || flushScheduled) return;
+	flushScheduled = true;
+	scheduler(runFlush);
+}
+function runFlush() {
+	flushScheduled = false;
+	if (flushing) return;
+	drain();
+}
+/**
+* Drain the pending queue. A subscriber may write synchronously (e.g.
+* useSyncExternalStore re-reads and a derived store updates), enqueuing more
+* callbacks; the bounded loop catches those in subsequent passes within the
+* same flush so each tick settles in one synchronous burst.
+*/
+function drain() {
+	if (flushing) return;
+	flushing = true;
+	try {
+		let passes = 0;
+		while (pending.size > 0) {
+			if (++passes > MAX_FLUSH_PASSES) {
+				pending.clear();
+				throw new Error("signal notification flush did not settle within 1000 passes: a subscriber is writing to a signal it observes (DESIGN.md §6.1).");
+			}
+			const batchCbs = [...pending];
+			pending.clear();
+			for (const cb of batchCbs) cb();
+		}
+	} finally {
+		flushing = false;
+	}
+}
+/**
+* Bracket a single top-level write (the signal layer calls this around each
+* set/forceSet/bindSource cascade). While open, enqueued notifications are
+* held; on the outermost close — when no `batch()` and no other write is in
+* flight — the queue is flushed exactly as before this module existed.
+*
+* Nesting these (a write whose flush triggers another write) or wrapping them in
+* `batch()` defers the flush to the outermost boundary, the coalescing the
+* ticker exists to provide.
+*/
+function beginNotify() {
+	batchDepth++;
+}
+function endNotify() {
+	batchDepth--;
+	if (batchDepth === 0 && pending.size > 0) requestFlush();
+}
+/**
+* Coalesce every signal write inside `fn` into a single subscriber-notification
+* pass. Reads inside `fn` stay synchronous and see each write immediately; only
+* the *notification* is deferred to the end. Nested batches flush once, at the
+* outermost exit. Returns whatever `fn` returns.
+*/
+function batch(fn) {
+	beginNotify();
+	try {
+		return fn();
+	} finally {
+		endNotify();
+	}
+}
+//#endregion
 //#region src/signal.ts
+/**
+* Pull-based reactive signals: lazy, cached, dependency-tracked (DESIGN.md §2.1).
+*
+* Staleness uses the two-flag scheme: a write marks direct dependents DIRTY and
+* transitive dependents CHECK. A CHECK node re-validates dependency versions on
+* read and only recomputes if one actually changed; a recompute that produces an
+* equal value keeps its version, so dirtiness stops propagating at that node.
+*
+* Subscriber NOTIFICATION (only) is routed through the ticker (`./ticker.ts`,
+* DESIGN.md §6.1): a write enqueues affected subscribers and the active
+* scheduler decides when to flush. The default scheduler is synchronous and
+* flushes at the end of the outermost write, reproducing the pre-ticker timing
+* byte-for-byte. The read path (get/peek/updateIfNecessary) is untouched and
+* stays fully synchronous.
+*/
 let activeConsumer = null;
 let readPhaseDepth = 0;
 var WriteDuringEvaluationError = class extends Error {
@@ -54,8 +174,13 @@ var SignalNode = class {
 	}
 	set(next) {
 		if (readPhaseDepth > 0) throw new WriteDuringEvaluationError();
-		if (this.fn) this.detachFn();
-		this.writeValue(next);
+		beginNotify();
+		try {
+			if (this.fn) this.detachFn();
+			this.writeValue(next);
+		} finally {
+			endNotify();
+		}
 	}
 	/**
 	* Sanctioned entry write (the playhead at evaluate() entry, DESIGN.md §2.5).
@@ -63,15 +188,25 @@ var SignalNode = class {
 	* signal surface.
 	*/
 	forceSet(next) {
-		if (this.fn) this.detachFn();
-		this.writeValue(next);
+		beginNotify();
+		try {
+			if (this.fn) this.detachFn();
+			this.writeValue(next);
+		} finally {
+			endNotify();
+		}
 	}
 	/** Rewire this signal's source to a computation (timeline binding, §2.4). */
 	bindSource(fn) {
 		if (readPhaseDepth > 0) throw new WriteDuringEvaluationError();
-		this.fn = fn;
-		this.state = 2;
-		this.invalidateDependents(2);
+		beginNotify();
+		try {
+			this.fn = fn;
+			this.state = 2;
+			this.invalidateDependents(2);
+		} finally {
+			endNotify();
+		}
 	}
 	/** Remove a bound source, freezing the signal at its last value. */
 	unbindSource() {
@@ -109,7 +244,7 @@ var SignalNode = class {
 	}
 	invalidateDependents(level) {
 		for (const d of [...this.dependents]) d.markStale(level);
-		if (this.subscribers.size > 0) for (const cb of [...this.subscribers]) cb();
+		if (this.subscribers.size > 0) for (const cb of [...this.subscribers]) enqueueNotification(cb);
 	}
 	markStale(level) {
 		if (this.state >= level) return;
@@ -380,7 +515,7 @@ function parseFormat12(dv, base, into) {
 function parseCmap(bytes) {
 	const out = /* @__PURE__ */ new Set();
 	try {
-		const dv = new DataView(bytes);
+		const dv = ArrayBuffer.isView(bytes) ? new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength) : new DataView(bytes);
 		if (dv.byteLength < 12) return out;
 		let sfntOff = 0;
 		if (u32(dv, 0) === 1953784678) sfntOff = u32(dv, 12);
@@ -942,4 +1077,4 @@ function bakeCheckpointed(cfg) {
 	};
 }
 //#endregion
-export { BakeError, CircularDependencyError, ColorParseError, DEFAULT_EASE, FontValidationError, PositionError, SidecarVersionError, TARGET_PATH, TimelineValidationError, TrackValidationError, UnboundTargetError, UnknownEasingError, UnknownValueTypeError, UnresolvableTargetError, ValueTypeInferenceError, WriteDuringEvaluationError, assignKeyIds, audioOffsetSamples, bake, bakeCheckpointed, 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, mergeSidecar, mergeSidecarDetailed, migrateSidecar, namedEasing, normalizeEditedKeys, numberType, oklabToRgba, parseCmap, parseColor, pathType, random, registerValueType, resolveEase, resolveEaseDerivative, resolveTweenTarget, rgbaToOklab, sampleTrack, setDevWarning, setSidecarTrack, signal, spring, springEasing, springEasingDerivative, springPresets, springTo, stagger, stringType, targetNodeId, timeline, track, untracked, validateFonts, validateTrack, vec2ArcType, vec2Equals, vec2Signal, vec2Type, velocityAt };
+export { BakeError, 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, mergeSidecar, mergeSidecarDetailed, migrateSidecar, namedEasing, normalizeEditedKeys, numberType, oklabToRgba, parseCmap, parseColor, pathType, random, registerValueType, 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 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@glissade/core",
-  "version": "0.9.1",
+  "version": "0.10.0-pre.0",
   "description": "glissade core: signals, tracks, timeline document, evaluation, easing, springs, seeded RNG. Zero DOM/Node dependencies.",
   "license": "Apache-2.0",
   "type": "module",