@glissade/core 0.13.0 → 0.14.0-pre.0

package/dist/i18n.d.ts

@@ -0,0 +1,65 @@
+import { l as Timeline } from "./timeline.js";
+
+//#region src/i18n.d.ts
+/** A locale's id manifest: the message ids it declares (narrate owns producing it). */
+interface LocaleManifest {
+  locale: string;
+  ids: readonly string[];
+}
+declare class ParityError extends Error {
+  constructor(message: string);
+}
+/**
+ * Assert every supplied locale declares the SAME id set — the cross-language
+ * analogue of `narration().require`. Throws a `ParityError` listing, per locale,
+ * every id that is MISSING (present in the union but not this locale) or EXTRA
+ * (present here but in no shared reference). A pure function of its inputs — no
+ * time, no filesystem. The reference set is the UNION of every locale's ids, so
+ * the report names each gap exactly once per affected locale.
+ *
+ * Ship-alone-able: the smallest blast radius of the four pieces. One manifest
+ * (or zero) is trivially in parity.
+ */
+declare function requireParity(...manifests: LocaleManifest[]): void;
+/** A flat message table: id → localized string (the `messages.<locale>.json` shape). */
+type MessageTable = Record<string, string>;
+interface LocalizeOptions {
+  /** the locale being resolved (carried for error context only; no behavior depends on it). */
+  locale: string;
+}
+declare class LocalizationError extends Error {
+  constructor(message: string);
+}
+/**
+ * Resolve a timeline document against a message `table`, returning a NEW doc
+ * (the input is never mutated). For every STRING track whose target node-id is a
+ * key in `table` — caption + narration-derived text tracks live in the doc as
+ * exactly these string tracks — every key's `value` is replaced with the table's
+ * localized string. Tracks whose node-id is absent from the table pass through
+ * untouched, byte-identical.
+ *
+ * Pure: no playhead, no time, no filesystem. The base-locale table (or an empty
+ * table) leaves the doc structurally identical to the input.
+ */
+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).
+ */
+declare function setMessageTable(table: MessageTable | undefined): void;
+/** The currently installed ambient message table (undefined when none is set). */
+declare function getMessageTable(): MessageTable | undefined;
+/**
+ * Resolve a free-standing message `id` against the ambient table — build-time
+ * sugar for static Text-node text (text that is NOT animated by a doc track,
+ * so `localize()` can't reach it): `new Text({ text: t('hero.title') })`.
+ *
+ * HARD-FAILS (throws) on an unknown id, mirroring `require()` — a stale or
+ * mistyped id is a build error, never a silent empty string. When NO ambient
+ * table is installed (the base / no-flag path), `t(id)` returns `id` verbatim,
+ * so an un-localized build renders its keys as authored and stays byte-identical.
+ */
+declare function t(id: string): string;
+//#endregion
+export { LocaleManifest, LocalizationError, LocalizeOptions, MessageTable, ParityError, getMessageTable, localize, requireParity, setMessageTable, t };

package/dist/i18n.js

@@ -0,0 +1,111 @@
+//#region src/i18n.ts
+var ParityError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "ParityError";
+	}
+};
+/**
+* Assert every supplied locale declares the SAME id set — the cross-language
+* analogue of `narration().require`. Throws a `ParityError` listing, per locale,
+* every id that is MISSING (present in the union but not this locale) or EXTRA
+* (present here but in no shared reference). A pure function of its inputs — no
+* time, no filesystem. The reference set is the UNION of every locale's ids, so
+* the report names each gap exactly once per affected locale.
+*
+* Ship-alone-able: the smallest blast radius of the four pieces. One manifest
+* (or zero) is trivially in parity.
+*/
+function requireParity(...manifests) {
+	if (manifests.length < 2) return;
+	const union = /* @__PURE__ */ new Set();
+	for (const m of manifests) for (const id of m.ids) union.add(id);
+	const problems = [];
+	for (const m of manifests) {
+		const have = new Set(m.ids);
+		const missing = [...union].filter((id) => !have.has(id)).sort();
+		const extra = [...have].filter((id) => manifests.every((other) => other === m || !other.ids.includes(id))).sort();
+		if (missing.length > 0 || extra.length > 0) {
+			const parts = [];
+			if (missing.length > 0) parts.push(`missing ${missing.map((id) => `'${id}'`).join(", ")}`);
+			if (extra.length > 0) parts.push(`extra ${extra.map((id) => `'${id}'`).join(", ")}`);
+			problems.push(`  ${m.locale}: ${parts.join("; ")}`);
+		}
+	}
+	if (problems.length > 0) throw new ParityError(`locale parity mismatch across ${manifests.length} locales:\n${problems.join("\n")}`);
+}
+var LocalizationError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "LocalizationError";
+	}
+};
+/** The node-id of a track target ('<nodeId>/<prop.path>' → '<nodeId>'). */
+function nodeIdOf(target) {
+	const slash = target.indexOf("/");
+	return slash >= 0 ? target.slice(0, slash) : target;
+}
+/**
+* Resolve a timeline document against a message `table`, returning a NEW doc
+* (the input is never mutated). For every STRING track whose target node-id is a
+* key in `table` — caption + narration-derived text tracks live in the doc as
+* exactly these string tracks — every key's `value` is replaced with the table's
+* localized string. Tracks whose node-id is absent from the table pass through
+* untouched, byte-identical.
+*
+* Pure: no playhead, no time, no filesystem. The base-locale table (or an empty
+* table) leaves the doc structurally identical to the input.
+*/
+function localize(doc, table, _opts) {
+	let changed = false;
+	const tracks = doc.tracks.map((tr) => {
+		if (tr.type !== "string") return tr;
+		const id = nodeIdOf(tr.target);
+		if (!(id in table)) return tr;
+		const localized = table[id];
+		changed = true;
+		return {
+			...tr,
+			keys: tr.keys.map((k) => k.value === localized ? k : {
+				...k,
+				value: localized
+			})
+		};
+	});
+	if (!changed) return { ...doc };
+	return {
+		...doc,
+		tracks
+	};
+}
+let ambientTable;
+/**
+* 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).
+*/
+function setMessageTable(table) {
+	ambientTable = table;
+}
+/** The currently installed ambient message table (undefined when none is set). */
+function getMessageTable() {
+	return ambientTable;
+}
+/**
+* Resolve a free-standing message `id` against the ambient table — build-time
+* sugar for static Text-node text (text that is NOT animated by a doc track,
+* so `localize()` can't reach it): `new Text({ text: t('hero.title') })`.
+*
+* HARD-FAILS (throws) on an unknown id, mirroring `require()` — a stale or
+* mistyped id is a build error, never a silent empty string. When NO ambient
+* table is installed (the base / no-flag path), `t(id)` returns `id` verbatim,
+* so an un-localized build renders its keys as authored and stays byte-identical.
+*/
+function t(id) {
+	if (ambientTable === void 0) return id;
+	const value = ambientTable[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, getMessageTable, localize, requireParity, setMessageTable, t };

package/dist/index.d.ts

@@ -102,13 +102,19 @@ declare function setScheduler(next?: Scheduler): Scheduler;
 declare function batch<T>(fn: () => T): T;
 //#endregion
 //#region src/vec2Signal.d.ts
+/** A scalar component signal carrying its bind-time type tag (§2.2). */
+type Vec2Component = BindableSignal<number> & {
+  readonly expects: ValueTypeId;
+};
 interface Vec2Signal extends ReadonlySignal<Vec2> {
-  readonly x: BindableSignal<number>;
-  readonly y: BindableSignal<number>;
+  readonly x: Vec2Component;
+  readonly y: Vec2Component;
   set(value: Vec2): void;
   /** Bind the compound level; component bindings on .x/.y override per component. */
   bindSource(fn: () => Vec2): void;
   unbindSource(): void;
+  /** Bind-time guard (§2.2): the compound accepts only a 'vec2' track. */
+  readonly expects: ValueTypeId;
 }
 declare function vec2Signal(initial: Vec2 | {
   x: number;
@@ -285,9 +291,30 @@ declare function createPlayhead(initial?: number): Playhead;
 declare class UnboundTargetError extends Error {
   constructor(target: string);
 }
+/**
+ * A track's value type doesn't match the shape of the property it targets — the
+ * silent-NaN class (§2.2): e.g. a scalar `number` track bound to a `vec2` prop
+ * makes the compound a number, its `.x`/`.y` index it to `undefined`, and the
+ * node's matrix goes NaN — the node and its subtree vanish. Caught at BIND time
+ * (the track's type is known then), the precedent being UnboundTargetError:
+ * mismatched binds are build errors, not silent no-ops.
+ */
+declare class BindTypeMismatchError extends Error {
+  readonly target: string;
+  readonly got: ValueTypeId;
+  /** The accepted type(s) — a single id, or the set a polymorphic prop (e.g. `fill`: color|paint) admits. */
+  readonly expected: ValueTypeId | readonly ValueTypeId[];
+  constructor(target: string, got: ValueTypeId, expected: ValueTypeId | readonly ValueTypeId[]);
+}
 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`).
+   */
+  readonly expects: ValueTypeId | readonly ValueTypeId[];
 }
 /** Analytic value/velocity access to one bound target (v2 addendum §B.6). */
 interface CurveSampler {
@@ -360,4 +387,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 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 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, 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

@@ -348,6 +348,8 @@ function vec2Signal(initial) {
 	const [ix, iy] = Array.isArray(initial) ? initial : [initial.x, initial.y];
 	const x = signal(ix);
 	const y = signal(iy);
+	x.expects = "number";
+	y.expects = "number";
 	const compound = signal(null, { equals: (a, b) => a === null || b === null ? a === b : a[0] === b[0] && a[1] === b[1] });
 	const baseX = signal(ix);
 	const baseY = signal(iy);
@@ -373,6 +375,7 @@ function vec2Signal(initial) {
 		compound.unbindSource();
 		compound.set(null);
 	};
+	sig["expects"] = "vec2";
 	Object.defineProperty(sig, "x", {
 		value: x,
 		enumerable: true
@@ -815,6 +818,30 @@ var UnboundTargetError = class extends Error {
 	}
 };
 /**
+* A track's value type doesn't match the shape of the property it targets — the
+* silent-NaN class (§2.2): e.g. a scalar `number` track bound to a `vec2` prop
+* makes the compound a number, its `.x`/`.y` index it to `undefined`, and the
+* node's matrix goes NaN — the node and its subtree vanish. Caught at BIND time
+* (the track's type is known then), the precedent being UnboundTargetError:
+* mismatched binds are build errors, not silent no-ops.
+*/
+var BindTypeMismatchError = class extends Error {
+	target;
+	got;
+	/** The accepted type(s) — a single id, or the set a polymorphic prop (e.g. `fill`: color|paint) admits. */
+	expected;
+	constructor(target, got, expected) {
+		const prop = target.slice(target.lastIndexOf("/") + 1);
+		const want = [expected].flat();
+		const hint = got === "number" && want.includes("vec2") ? `; target '${prop}.x'/'${prop}.y' or author a vec2 track` : "";
+		super(`track '${target}' is '${got}' but '${prop}' expects '${want.join("'|'")}' (would silently NaN evaluation)${hint}`);
+		this.target = target;
+		this.got = got;
+		this.name = "BindTypeMismatchError";
+		this.expected = expected;
+	}
+};
+/**
 * Bind a compiled timeline's tracks to property signals. `resolve` returns
 * the signal for a target path, or undefined — which is a compile-time-style
 * error (§2.2: unbound tracks are build errors, not silent no-ops).
@@ -825,6 +852,9 @@ function bindTimeline(compiled, resolve, playhead = createPlayhead()) {
 	for (const [target, tr] of compiled.tracks) {
 		const sig = resolve(target);
 		if (!sig) throw new UnboundTargetError(target);
+		const got = tr.type;
+		const expects = sig.expects;
+		if (!(Array.isArray(expects) ? expects.includes(got) : got === expects)) throw new BindTypeMismatchError(target, got, expects);
 		sig.bindSource(() => sampleTrack(tr, playhead()));
 		bound.push(sig);
 		samplers.set(target, {
@@ -974,4 +1004,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, 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, 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.13.0",
+  "version": "0.14.0-pre.0",
   "description": "glissade core: signals, tracks, timeline document, evaluation, easing, springs, seeded RNG. Zero DOM/Node dependencies.",
   "license": "Apache-2.0",
   "engines": {
@@ -21,6 +21,10 @@
       "types": "./dist/clips.d.ts",
       "default": "./dist/clips.js"
     },
+    "./i18n": {
+      "types": "./dist/i18n.d.ts",
+      "default": "./dist/i18n.js"
+    },
     "./font-ingest": {
       "types": "./dist/font-ingest.d.ts",
       "default": "./dist/font-ingest.js"