@glissade/core 0.14.0 → 0.15.0-pre.0

package/dist/clips.d.ts

@@ -1,4 +1,4 @@
-import { J as EaseSpec, T as ValueTypeId, r as Track, t as Key } from "./track.js";
+import { T as ValueTypeId, Y as EaseSpec, r as Track, t as Key } from "./track.js";
 import { r as TweenTarget } from "./targetRef.js";
 
 //#region src/clip.d.ts

package/dist/i18n.d.ts

@@ -30,8 +30,13 @@ interface LocalizeOptions {
    * Message ids ALREADY consumed outside the doc — the free-standing `t()` ids
    * resolved at module-eval / createScene() time (`getConsumedMessageIds()`).
    * `localize` folds these into the "matched keys" set so the orphaned-key check
-   * (FIX 5) doesn't flag a legitimate `t()` key as unmatched. Omit when there is
-   * no ambient `t()` usage (then only node-id keys count as matched).
+   * (0.14 FIX 5) doesn't flag a legitimate `t()` key as unmatched. Omit when there
+   * is no ambient `t()` usage (then only node-id keys count as matched).
+   *
+   * 0.15 FIX 2: this set ALSO drives the key-collision guard — a table key that is
+   * BOTH a `t()` id (in here) AND a node-id with a string track is ambiguous (the
+   * two id-spaces would silently fight over the same key, with the node-track swap
+   * winning), so `localize` throws a `LocalizationError` rather than guess.
    */
   consumedIds?: ReadonlySet<string> | undefined;
 }
@@ -49,27 +54,66 @@ declare class LocalizationError extends Error {
  * Pure: no playhead, no time, no filesystem. The base-locale table (or an empty
  * table) leaves the doc structurally identical to the input.
  *
- * FIX 5 (0.14 canary): a table key matching NO consumed id (neither a string-track
+ * 0.14 FIX 5: a table key matching NO consumed id (neither a string-track
  * node-id NOR a `t()` id passed via `opts.consumedIds`) is a stale/typo'd key that
  * would silently never localize anything — so `localize` throws a `LocalizationError`
  * naming every orphaned key (the inverse of `t()`'s hard-fail). A fully-matched
  * table is silent.
+ *
+ * 0.15 FIX 1 (multi-cue collapse): broadcasting one table string across EVERY key
+ * of a string track freezes a single caption over a multi-cue track (>1 distinct
+ * keyed value). A multi-cue caption must be regenerated per-locale (locale-tagged
+ * narration), never collapsed — so a matched track with >1 distinct key value
+ * HARD-THROWS, naming the id. A single-value / single-key track localizes fine.
+ *
+ * 0.15 FIX 2 (key collision): a table key that is BOTH a node-id-with-a-string-
+ * track AND a `t()` id (`opts.consumedIds`) is ambiguous — the two id-spaces would
+ * silently fight over the same flat key. `localize` HARD-THROWS on any such key
+ * rather than let the node-track swap silently win. The flat `messages.<locale>.json`
+ * shape is UNCHANGED; this is a pure additive guard.
  */
 declare function localize(doc: Timeline, table: MessageTable, opts: LocalizeOptions): Timeline;
 /**
- * Install the ambient message table consulted by `t()`. Called ONCE before
- * scene construction (the render entry injects it from `--locale`). Pass
- * `undefined` to clear it (the base-locale / no-flag path leaves it unset).
- * Resets the consumed-id set (a fresh table = a fresh resolution pass).
+ * Install the ambient message table consulted by `t()` on the PROCESS-GLOBAL
+ * scope. Called ONCE before scene construction (the render entry injects it from
+ * `--locale`). Pass `undefined` to clear it (the base-locale / no-flag path leaves
+ * it unset). Resets the consumed-id set (a fresh table = a fresh resolution pass).
+ *
+ * 0.15 FIX 3: for CONCURRENT renders of different locales, prefer
+ * `runWithMessageTable` — this global setter races across interleaved flows.
  */
 declare function setMessageTable(table: MessageTable | undefined): void;
+/**
+ * Run `fn` with `table` installed as the ambient message table for the DURATION
+ * of `fn`'s async flow only — isolated from the process-global scope and from any
+ * other concurrent flow (0.15 FIX 3). `t()` inside `fn` (and anything it awaits)
+ * resolves against `table`; `t()` outside it is unaffected. Resolves to `fn`'s
+ * result. The render entry can scope the whole `loadSceneModule`→`localize` flow
+ * per locale with this so parallel embedders never cross-contaminate. The
+ * consumed-id set is collected per scope and is readable with
+ * `getConsumedMessageIds()` inside `fn`.
+ *
+ * Async because the AsyncLocalStorage class is loaded via a dynamic `node` import
+ * on first use (so this prepare/render-path module never statically pulls in
+ * `node:async_hooks`); the ALS context still spans `fn` and everything it awaits.
+ */
+declare function runWithMessageTable<T>(table: MessageTable | undefined, fn: () => T | Promise<T>): Promise<T>;
 /** The currently installed ambient message table (undefined when none is set). */
 declare function getMessageTable(): MessageTable | undefined;
+/**
+ * Run `fn` while PRESERVING the process-global ambient scope across it (0.15 FIX 3).
+ * `fn` may freely call `setMessageTable` / `loadSceneModule` (which clobbers the
+ * global table) — the table + consumed-id set are snapshotted before and restored
+ * after, so a no-locale helper (the audio-mix gather) can't leave a leaked or
+ * cleared table visible to a concurrent locale's flow. Awaits/returns `fn`'s result.
+ */
+declare function preservingMessageTable<T>(fn: () => Promise<T>): Promise<T>;
 /**
  * The set of ids `t()` has resolved against the ambient table since the last
- * `setMessageTable`. The render entry passes this to `localize` so a key consumed
- * by a free-standing `t()` (which `localize` can't see — it isn't a doc track)
- * isn't reported as an orphaned table key (FIX 5).
+ * `setMessageTable` (or, inside a `runWithMessageTable` flow, since that scope
+ * began). The render entry passes this to `localize` so a key consumed by a
+ * free-standing `t()` (which `localize` can't see — it isn't a doc track) isn't
+ * reported as an orphaned table key (0.14 FIX 5).
  */
 declare function getConsumedMessageIds(): ReadonlySet<string>;
 /**
@@ -84,4 +128,4 @@ declare function getConsumedMessageIds(): ReadonlySet<string>;
  */
 declare function t(id: string): string;
 //#endregion
-export { LocaleManifest, LocalizationError, LocalizeOptions, MessageTable, ParityError, getConsumedMessageIds, getMessageTable, localize, requireParity, setMessageTable, t };
+export { LocaleManifest, LocalizationError, LocalizeOptions, MessageTable, ParityError, getConsumedMessageIds, getMessageTable, localize, preservingMessageTable, requireParity, runWithMessageTable, setMessageTable, t };

package/dist/i18n.js

@@ -17,6 +17,14 @@ var ParityError = class extends Error {
 * (or zero) is trivially in parity.
 */
 function requireParity(...manifests) {
+	for (const m of manifests) if (new Set(m.ids).size !== m.ids.length) {
+		const seen = /* @__PURE__ */ new Set();
+		const dups = [];
+		for (const id of m.ids) if (seen.has(id)) dups.push(id);
+		else seen.add(id);
+		const uniqueDups = [...new Set(dups)].sort();
+		throw new ParityError(`locale '${m.locale}' declares duplicate id(s): ${uniqueDups.map((id) => `'${id}'`).join(", ")} — each message id must appear once per manifest.`);
+	}
 	if (manifests.length < 2) return;
 	const union = /* @__PURE__ */ new Set();
 	for (const m of manifests) for (const id of m.ids) union.add(id);
@@ -56,11 +64,23 @@ function nodeIdOf(target) {
 * Pure: no playhead, no time, no filesystem. The base-locale table (or an empty
 * table) leaves the doc structurally identical to the input.
 *
-* FIX 5 (0.14 canary): a table key matching NO consumed id (neither a string-track
+* 0.14 FIX 5: a table key matching NO consumed id (neither a string-track
 * node-id NOR a `t()` id passed via `opts.consumedIds`) is a stale/typo'd key that
 * would silently never localize anything — so `localize` throws a `LocalizationError`
 * naming every orphaned key (the inverse of `t()`'s hard-fail). A fully-matched
 * table is silent.
+*
+* 0.15 FIX 1 (multi-cue collapse): broadcasting one table string across EVERY key
+* of a string track freezes a single caption over a multi-cue track (>1 distinct
+* keyed value). A multi-cue caption must be regenerated per-locale (locale-tagged
+* narration), never collapsed — so a matched track with >1 distinct key value
+* HARD-THROWS, naming the id. A single-value / single-key track localizes fine.
+*
+* 0.15 FIX 2 (key collision): a table key that is BOTH a node-id-with-a-string-
+* track AND a `t()` id (`opts.consumedIds`) is ambiguous — the two id-spaces would
+* silently fight over the same flat key. `localize` HARD-THROWS on any such key
+* rather than let the node-track swap silently win. The flat `messages.<locale>.json`
+* shape is UNCHANGED; this is a pure additive guard.
 */
 function localize(doc, table, opts) {
 	let changed = false;
@@ -69,6 +89,9 @@ function localize(doc, table, opts) {
 		if (tr.type !== "string") return tr;
 		const id = nodeIdOf(tr.target);
 		if (!(id in table)) return tr;
+		if (opts.consumedIds?.has(id)) throw new LocalizationError(`message table for locale '${opts.locale}' has an AMBIGUOUS key '${id}' — it matches BOTH a string track on node '${id}' AND a free-standing t('${id}') id. The flat table can't serve both id-spaces from one key. Rename one of them so the key resolves a single target.`);
+		const distinctValues = new Set(tr.keys.map((k) => k.value));
+		if (distinctValues.size > 1) throw new LocalizationError(`message table for locale '${opts.locale}' targets node '${id}', whose string track has ${distinctValues.size} distinct keyed values (a multi-cue caption). Broadcasting one table string would freeze a single caption over the whole track. Regenerate this locale's narration (a locale-tagged '<base>.${opts.locale}.narration.timing.json') instead of localizing the multi-cue track via the message table.`);
 		consumed.add(id);
 		const localized = table[id];
 		changed = true;
@@ -88,30 +111,88 @@ function localize(doc, table, opts) {
 		tracks
 	};
 }
-let ambientTable;
-let consumedIds = /* @__PURE__ */ new Set();
+const globalScope = {
+	table: void 0,
+	consumedIds: /* @__PURE__ */ new Set()
+};
+let ambientStore;
+/** The scope `t()` should read: the ALS-scoped one if active, else the global one. */
+function activeScope() {
+	return ambientStore?.getStore() ?? globalScope;
+}
 /**
-* Install the ambient message table consulted by `t()`. Called ONCE before
-* scene construction (the render entry injects it from `--locale`). Pass
-* `undefined` to clear it (the base-locale / no-flag path leaves it unset).
-* Resets the consumed-id set (a fresh table = a fresh resolution pass).
+* Install the ambient message table consulted by `t()` on the PROCESS-GLOBAL
+* scope. Called ONCE before scene construction (the render entry injects it from
+* `--locale`). Pass `undefined` to clear it (the base-locale / no-flag path leaves
+* it unset). Resets the consumed-id set (a fresh table = a fresh resolution pass).
+*
+* 0.15 FIX 3: for CONCURRENT renders of different locales, prefer
+* `runWithMessageTable` — this global setter races across interleaved flows.
 */
 function setMessageTable(table) {
-	ambientTable = table;
-	consumedIds = /* @__PURE__ */ new Set();
+	globalScope.table = table;
+	globalScope.consumedIds = /* @__PURE__ */ new Set();
+}
+/**
+* Run `fn` with `table` installed as the ambient message table for the DURATION
+* of `fn`'s async flow only — isolated from the process-global scope and from any
+* other concurrent flow (0.15 FIX 3). `t()` inside `fn` (and anything it awaits)
+* resolves against `table`; `t()` outside it is unaffected. Resolves to `fn`'s
+* result. The render entry can scope the whole `loadSceneModule`→`localize` flow
+* per locale with this so parallel embedders never cross-contaminate. The
+* consumed-id set is collected per scope and is readable with
+* `getConsumedMessageIds()` inside `fn`.
+*
+* Async because the AsyncLocalStorage class is loaded via a dynamic `node` import
+* on first use (so this prepare/render-path module never statically pulls in
+* `node:async_hooks`); the ALS context still spans `fn` and everything it awaits.
+*/
+async function runWithMessageTable(table, fn) {
+	if (ambientStore === void 0) {
+		const { AsyncLocalStorage } = await import("node:async_hooks");
+		ambientStore ??= new AsyncLocalStorage();
+	}
+	return ambientStore.run({
+		table,
+		consumedIds: /* @__PURE__ */ new Set()
+	}, fn);
 }
 /** The currently installed ambient message table (undefined when none is set). */
 function getMessageTable() {
-	return ambientTable;
+	return activeScope().table;
+}
+/**
+* Run `fn` while PRESERVING the process-global ambient scope across it (0.15 FIX 3).
+* `fn` may freely call `setMessageTable` / `loadSceneModule` (which clobbers the
+* global table) — the table + consumed-id set are snapshotted before and restored
+* after, so a no-locale helper (the audio-mix gather) can't leave a leaked or
+* cleared table visible to a concurrent locale's flow. Awaits/returns `fn`'s result.
+*/
+function preservingMessageTable(fn) {
+	const savedTable = globalScope.table;
+	const savedConsumed = globalScope.consumedIds;
+	const restore = () => {
+		globalScope.table = savedTable;
+		globalScope.consumedIds = savedConsumed;
+	};
+	let promise;
+	try {
+		promise = fn();
+	} catch (err) {
+		restore();
+		throw err;
+	}
+	return promise.finally(restore);
 }
 /**
 * The set of ids `t()` has resolved against the ambient table since the last
-* `setMessageTable`. The render entry passes this to `localize` so a key consumed
-* by a free-standing `t()` (which `localize` can't see — it isn't a doc track)
-* isn't reported as an orphaned table key (FIX 5).
+* `setMessageTable` (or, inside a `runWithMessageTable` flow, since that scope
+* began). The render entry passes this to `localize` so a key consumed by a
+* free-standing `t()` (which `localize` can't see — it isn't a doc track) isn't
+* reported as an orphaned table key (0.14 FIX 5).
 */
 function getConsumedMessageIds() {
-	return consumedIds;
+	return activeScope().consumedIds;
 }
 /**
 * Resolve a free-standing message `id` against the ambient table — build-time
@@ -124,11 +205,13 @@ function getConsumedMessageIds() {
 * so an un-localized build renders its keys as authored and stays byte-identical.
 */
 function t(id) {
+	const scope = activeScope();
+	const ambientTable = scope.table;
 	if (ambientTable === void 0) return id;
 	const value = ambientTable[id];
-	if (value !== void 0) consumedIds.add(id);
+	if (value !== void 0) scope.consumedIds.add(id);
 	if (value === void 0) throw new LocalizationError(`t('${id}'): no message for id '${id}' in the active message table (have: ${Object.keys(ambientTable).map((k) => `'${k}'`).join(", ") || "<empty>"})`);
 	return value;
 }
 //#endregion
-export { LocalizationError, ParityError, getConsumedMessageIds, getMessageTable, localize, requireParity, setMessageTable, t };
+export { LocalizationError, ParityError, getConsumedMessageIds, getMessageTable, localize, preservingMessageTable, requireParity, runWithMessageTable, setMessageTable, t };

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { $ as easingDerivatives, A as getValueType, B as RetargetSpring, C as UnknownValueTypeError, D as Vec2, E as ValueTypeInferenceError, F as registerValueType, G as springEasingDerivative, H as SpringEase, I as stringType, J as EaseSpec, K as springPresets, L as vec2ArcType, M as numberType, N as paintType, O as booleanType, P as pathType, Q as cubicBezierDerivative, R as vec2Equals, S as PathValue, T as ValueTypeId, U as spring, V as SpringConfig, W as springEasing, X as UnknownEasingError, Y as EasingFn, Z as cubicBezier, _ as MeshInterpolation, a as key, b as Paint, c as sampleTrack, d as track, et as easings, 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, o as resolveEase, p as velocityAt, q as DEFAULT_EASE, r as Track, s as resolveEaseDerivative, t as Key, tt as namedEasing, u as stagger, v as MeshPaint, w as ValueType, x as PathContour, y as MeshPoint, z as vec2Type } from "./track.js";
+import { $ as cubicBezierDerivative, A as getValueType, B as vec2Type, C as UnknownValueTypeError, D as Vec2, E as ValueTypeInferenceError, F as registerValueType, G as springEasing, H as SpringConfig, I as reprOf, J as DEFAULT_EASE, K as springEasingDerivative, L as stringType, M as numberType, N as paintType, O as booleanType, P as pathType, Q as cubicBezier, R as vec2ArcType, S as PathValue, T as ValueTypeId, U as SpringEase, V as RetargetSpring, W as spring, X as EasingFn, Y as EaseSpec, Z as UnknownEasingError, _ as MeshInterpolation, a as key, b as Paint, c as sampleTrack, d as track, et as easingDerivatives, 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 namedEasing, o as resolveEase, p as velocityAt, q as springPresets, r as Track, s as resolveEaseDerivative, t as Key, tt as easings, u as stagger, v as MeshPaint, w as ValueType, x as PathContour, y as MeshPoint, z as vec2Equals } 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";
@@ -310,12 +310,14 @@ interface BindTarget {
   bindSource(fn: () => unknown): void;
   unbindSource(): void;
   /**
-   * The value type this target accepts; a track of any other type is a bind
-   * error. An ARRAY for a polymorphic prop that admits more than one type
-   * (e.g. a Shape `fill` accepts both `color` and `paint`, or a vec2 prop that
-   * accepts both `vec2` and `vec2-arc`). UNDEFINED means the target opted OUT
-   * of the guard (an untagged custom-node prop — back-compat with 0.13, which
-   * had no guard): any track binds without a type check.
+   * The value type this target accepts; a track whose REPRESENTATION (its
+   * `repr`, single-hop) differs is a bind error. So a `vec2-arc` track (repr
+   * 'vec2') binds to a plain `'vec2'` target, and a custom `cents` (repr
+   * 'number') binds to a `'number'` target — the extension door (0.15). An
+   * ARRAY is for GENUINE polymorphism — distinct reprs admitted at one prop
+   * (e.g. a Shape `fill` accepts both `color` and `paint`). UNDEFINED means the
+   * target opted OUT of the guard (an untagged custom-node prop — back-compat
+   * with 0.13, which had no guard): any track binds without a type check.
    */
   readonly expects: ValueTypeId | readonly ValueTypeId[] | undefined;
 }
@@ -390,4 +392,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, 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, mergeSidecar, mergeSidecarDetailed, migrateSidecar, namedEasing, normalizeEditedKeys, numberType, oklabToRgba, paintType, 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 };
+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, 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, 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 };

package/dist/index.js

@@ -1,4 +1,4 @@
-import { A as ColorParseError, B as springEasingDerivative, C as paintType, D as vec2ArcType, E as stringType, F as rgbaToOklab, G as cubicBezierDerivative, H as DEFAULT_EASE, I as emitDevWarning, J as namedEasing, K as easingDerivatives, L as setDevWarning, M as lerpColor, N as oklabToRgba, O as vec2Equals, P as parseColor, R as spring, S as numberType, T as registerValueType, U as UnknownEasingError, V as springPresets, W as cubicBezier, _ 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 formatColor, k as vec2Type, l as resolveEaseDerivative, m as validateTrack, n as UnresolvableTargetError, o as TrackValidationError, p as track, q as easings, r as isEditableNodeId, s as key, t as TARGET_PATH, u as sampleTrack, v as booleanType, w as pathType, x as inferValueType, y as colorType, z as springEasing } from "./targetRef.js";
+import { A as vec2Type, B as springEasing, C as paintType, D as stringType, E as reprOf, F as parseColor, G as cubicBezier, H as springPresets, I as rgbaToOklab, J as easings, K as cubicBezierDerivative, L as emitDevWarning, M as formatColor, N as lerpColor, O as vec2ArcType, P as oklabToRgba, R as setDevWarning, S as numberType, T as registerValueType, U as DEFAULT_EASE, V as springEasingDerivative, W as UnknownEasingError, Y as namedEasing, _ 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 ColorParseError, k as vec2Equals, l as resolveEaseDerivative, m as validateTrack, n as UnresolvableTargetError, o as TrackValidationError, p as track, q as easingDerivatives, r as isEditableNodeId, s as key, t as TARGET_PATH, u as sampleTrack, v as booleanType, w as pathType, x as inferValueType, y as colorType, z as spring } from "./targetRef.js";
 import { t as parseCmap } from "./cmap.js";
 import { a as hashKeys, c as migrateSidecar, d as TimelineValidationError, f as audioOffsetSamples, h as timeline$1, i as emptySidecar, l as normalizeEditedKeys, m as isDurationEditable, n as assignKeyIds, o as mergeSidecar, p as compileTimeline, r as deleteSidecarTrack, s as mergeSidecarDetailed, t as SidecarVersionError, u as setSidecarTrack } from "./sidecar.js";
 //#region src/ticker.ts
@@ -855,7 +855,8 @@ function bindTimeline(compiled, resolve, playhead = createPlayhead()) {
 		const got = tr.type;
 		const expects = sig.expects;
 		if (expects !== void 0) {
-			if (!(Array.isArray(expects) ? expects.includes(got) : got === expects)) throw new BindTypeMismatchError(target, got, expects);
+			const gotRepr = reprOf(got);
+			if (!(Array.isArray(expects) ? expects : [expects]).some((e) => reprOf(e) === gotRepr)) throw new BindTypeMismatchError(target, got, expects);
 		}
 		sig.bindSource(() => sampleTrack(tr, playhead()));
 		bound.push(sig);
@@ -1006,4 +1007,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, mergeSidecar, mergeSidecarDetailed, migrateSidecar, namedEasing, normalizeEditedKeys, numberType, oklabToRgba, paintType, 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 };
+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, 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 };

package/dist/sidecar.js

@@ -1,4 +1,4 @@
-import { I as emitDevWarning, R as spring, a as targetNodeId, m as validateTrack, o as TrackValidationError, r as isEditableNodeId } from "./targetRef.js";
+import { L as emitDevWarning, a as targetNodeId, m as validateTrack, o as TrackValidationError, r as isEditableNodeId, z as spring } from "./targetRef.js";
 //#region src/timeline.ts
 /**
 * The Timeline document (DESIGN.md §2.3) — the serializable animation source

package/dist/studioHost.d.ts

@@ -1,4 +1,4 @@
-import { J as EaseSpec, T as ValueTypeId, t as Key } from "./track.js";
+import { T as ValueTypeId, Y 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";

package/dist/targetRef.js

@@ -490,6 +490,16 @@ function getValueType(id) {
 	if (!vt) throw new UnknownValueTypeError(id);
 	return vt;
 }
+/**
+* Resolve a value-type id to its REPRESENTATION (the bind guard's compatibility
+* key, §2.2): a type's `repr` (the built-in it's representationally compatible
+* with), else the id itself. SINGLE-HOP — `repr` is never chained, so a custom
+* type's repr must be a base type. An UNREGISTERED id resolves to itself (the
+* guard's job is repr-compat, not existence — `getValueType` enforces that).
+*/
+function reprOf(id) {
+	return registry.get(id)?.repr ?? id;
+}
 const numberType = {
 	id: "number",
 	lerp: (a, b, t) => a + (b - a) * t,
@@ -514,6 +524,7 @@ const vec2Type = {
 /** vec2 swept along a circular arc: polar lerp of radius + shortest-path angle (§2.2). */
 const vec2ArcType = {
 	id: "vec2-arc",
+	repr: "vec2",
 	lerp: (a, b, t) => {
 		const ra = Math.hypot(a[0], a[1]);
 		const rb = Math.hypot(b[0], b[1]);
@@ -1019,4 +1030,4 @@ function resolveTweenTarget(target) {
 	return path;
 }
 //#endregion
-export { ColorParseError as A, springEasingDerivative as B, paintType as C, vec2ArcType as D, stringType as E, rgbaToOklab as F, cubicBezierDerivative as G, DEFAULT_EASE as H, emitDevWarning as I, namedEasing as J, easingDerivatives as K, setDevWarning as L, lerpColor as M, oklabToRgba as N, vec2Equals as O, parseColor as P, spring as R, numberType as S, registerValueType as T, UnknownEasingError as U, springPresets as V, cubicBezier as W, ValueTypeInferenceError as _, targetNodeId as a, getValueType as b, resolveEase as c, springTo as d, stagger as f, UnknownValueTypeError as g, velocityAt as h, resolveTweenTarget as i, formatColor as j, vec2Type as k, resolveEaseDerivative as l, validateTrack as m, UnresolvableTargetError as n, TrackValidationError as o, track as p, easings as q, isEditableNodeId as r, key as s, TARGET_PATH as t, sampleTrack as u, booleanType as v, pathType as w, inferValueType as x, colorType as y, springEasing as z };
+export { vec2Type as A, springEasing as B, paintType as C, stringType as D, reprOf as E, parseColor as F, cubicBezier as G, springPresets as H, rgbaToOklab as I, easings as J, cubicBezierDerivative as K, emitDevWarning as L, formatColor as M, lerpColor as N, vec2ArcType as O, oklabToRgba as P, setDevWarning as R, numberType as S, registerValueType as T, DEFAULT_EASE as U, springEasingDerivative as V, UnknownEasingError as W, namedEasing as Y, ValueTypeInferenceError as _, targetNodeId as a, getValueType as b, resolveEase as c, springTo as d, stagger as f, UnknownValueTypeError as g, velocityAt as h, resolveTweenTarget as i, ColorParseError as j, vec2Equals as k, resolveEaseDerivative as l, validateTrack as m, UnresolvableTargetError as n, TrackValidationError as o, track as p, easingDerivatives as q, isEditableNodeId as r, key as s, TARGET_PATH as t, sampleTrack as u, booleanType as v, pathType as w, inferValueType as x, colorType as y, spring as z };

package/dist/track.d.ts

@@ -145,6 +145,16 @@ type PathValue = PathContour[];
 type HandoffKind = 'cut' | 'decay' | 'spring' | 'blend-from-frozen';
 interface ValueType<T> {
   id: string;
+  /**
+   * The built-in value type this type is REPRESENTATIONALLY compatible with —
+   * the bind guard (binding.ts) matches a track to a target when their reprs
+   * agree, not just their ids. A custom type that is "a number under a different
+   * id" (e.g. a `cents` type) sets `repr: 'number'` so it binds to `number`
+   * props (and vice versa); `vec2-arc` sets `repr: 'vec2'`. SINGLE-HOP only:
+   * `repr` must name a base type that has no `repr` of its own (no chaining).
+   * Omitted ⇒ the type is its own repr.
+   */
+  repr?: ValueTypeId;
   lerp(a: T, b: T, t: number): T;
   /** Accepts easedT outside [0,1] (spring overshoot)? Otherwise clamped. */
   extrapolates: boolean;
@@ -165,6 +175,14 @@ declare class UnknownValueTypeError extends Error {
   constructor(id: string);
 }
 declare function getValueType<T = unknown>(id: ValueTypeId): ValueType<T>;
+/**
+ * Resolve a value-type id to its REPRESENTATION (the bind guard's compatibility
+ * key, §2.2): a type's `repr` (the built-in it's representationally compatible
+ * with), else the id itself. SINGLE-HOP — `repr` is never chained, so a custom
+ * type's repr must be a base type. An UNREGISTERED id resolves to itself (the
+ * guard's job is repr-compat, not existence — `getValueType` enforces that).
+ */
+declare function reprOf(id: ValueTypeId): ValueTypeId;
 declare const numberType: ValueType<number>;
 declare const vec2Equals: (a: Vec2, b: Vec2) => boolean;
 declare const vec2Type: ValueType<Vec2>;
@@ -326,4 +344,4 @@ 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 };
+export { cubicBezierDerivative as $, getValueType as A, vec2Type as B, UnknownValueTypeError as C, Vec2 as D, ValueTypeInferenceError as E, registerValueType as F, springEasing as G, SpringConfig as H, reprOf as I, DEFAULT_EASE as J, springEasingDerivative as K, stringType as L, numberType as M, paintType as N, booleanType as O, pathType as P, cubicBezier as Q, vec2ArcType as R, PathValue as S, ValueTypeId as T, SpringEase as U, RetargetSpring as V, spring as W, EasingFn as X, EaseSpec as Y, UnknownEasingError as Z, MeshInterpolation as _, key as a, Paint as b, sampleTrack as c, track as d, easingDerivatives 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, namedEasing as nt, resolveEase as o, velocityAt as p, springPresets as q, Track as r, resolveEaseDerivative as s, Key as t, easings as tt, stagger as u, MeshPaint as v, ValueType as w, PathContour as x, MeshPoint as y, vec2Equals as z };

package/package.json

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