@glissade/scene 0.23.0 → 0.24.0-pre.1

package/dist/describe.d.ts

@@ -51,6 +51,13 @@ interface DescribedNode {
   props: {
     [prop: string]: DescribedProp;
   };
+  /**
+   * Runnable, drift-guarded code snippets for this node — present ONLY when
+   * `describe({ examples: true })` is called AND `@glissade/scene/examples` has
+   * been imported (it registers the corpus). Each string is an executable example
+   * the doctest harness runs, so it can't go stale (§0.24 onboarding).
+   */
+  examples?: readonly string[];
   /**
    * What this node's `position` points at WITHOUT an explicit `anchor` (its
    * legacy origin): 'center' for shapes, 'baseline-left' for Text, etc. Override
@@ -68,6 +75,8 @@ interface DescribedNode {
 interface DescribedBuilderMethod {
   name: string;
   signature: string;
+  /** Runnable example snippets — see {@link DescribedNode.examples}. */
+  examples?: readonly string[];
 }
 /**
  * One helper/factory in the manifest — the broader builder API beyond the node
@@ -87,6 +96,8 @@ interface DescribedHelper {
   import: string;
   /** A minimal signature/usage string showing the call shape. */
   usage: string;
+  /** Runnable example snippets — see {@link DescribedNode.examples}. */
+  examples?: readonly string[];
 }
 /** The full machine-readable manifest `describe()` returns. */
 interface ApiManifest {
@@ -117,6 +128,23 @@ interface ApiManifest {
  * targets, enumerate the ValueType + easing registries, and curate the builder /
  * subpath surface. JSON-serializable; safe to call any number of times.
  */
-declare function describe(): ApiManifest;
+interface DescribeOptions {
+  /**
+   * Attach runnable example snippets (per node / builder method / helper) from
+   * the registered corpus (§0.24 onboarding). The corpus is registered by
+   * importing `@glissade/scene/examples`, kept OFF the base index so it costs
+   * nothing when unused. With no corpus registered, `examples: true` is a no-op
+   * (the manifest is byte-identical to `describe()`).
+   */
+  examples?: boolean;
+}
+/**
+ * Register the runnable-example corpus — called by `@glissade/scene/examples` on
+ * import. A registration hook (not a static import) so `describe()` stays lean.
+ */
+declare function registerExamples(corpus: {
+  readonly [key: string]: readonly string[];
+}): void;
+declare function describe(opts?: DescribeOptions): ApiManifest;
 //#endregion
-export { ApiManifest, DescribedBuilderMethod, DescribedHelper, DescribedNode, DescribedProp, describe };
+export { ApiManifest, DescribeOptions, DescribedBuilderMethod, DescribedHelper, DescribedNode, DescribedProp, describe, registerExamples };

package/dist/describe.js

@@ -22,7 +22,7 @@ import { easings, listValueTypes } from "@glissade/core";
 * never pulled onto the base embed path — a scene that never calls `describe()`
 * pays zero bytes for it.
 */
-const RAW_VERSION = "0.23.0";
+const RAW_VERSION = "0.24.0-pre.1";
 const PACKAGE_VERSION = RAW_VERSION.includes("GLISSADE_".concat("VERSION")) ? "0.0.0-dev" : RAW_VERSION;
 /** Arity of a value type's numeric repr: vec2/vec2-arc → 2, number → 1; others (color/paint/path/string/boolean) carry no scalar arity. */
 function arityOf(type) {
@@ -390,31 +390,60 @@ const SUBPATHS = {
 	"@glissade/scene/path": "SVG geometry: pathFromSvg / parseSvgPathData — parse an SVG `d` string into a PathValue for Path.data."
 };
 /**
-* Build the machine-readable API manifest from the live registries (§4.4). Pure
-* introspection: instantiate each built-in node once to read its registered track
-* targets, enumerate the ValueType + easing registries, and curate the builder /
-* subpath surface. JSON-serializable; safe to call any number of times.
+* The registered runnable-example corpus, keyed by describe-key (node type name /
+* builder method name / helper name). Populated by `@glissade/scene/examples` at
+* import time via {@link registerExamples} — describe NEVER statically imports the
+* corpus, so the base index and the IIFE never pay for it (the value-type-registry
+* pattern). Empty until that subpath is loaded.
 */
-function describe() {
+let exampleCorpus = {};
+/**
+* Register the runnable-example corpus — called by `@glissade/scene/examples` on
+* import. A registration hook (not a static import) so `describe()` stays lean.
+*/
+function registerExamples(corpus) {
+	exampleCorpus = corpus;
+}
+function describe(opts = {}) {
+	const withEx = opts.examples === true && Object.keys(exampleCorpus).length > 0;
+	const ex = (key) => {
+		const e = withEx ? exampleCorpus[key] : void 0;
+		return e && e.length > 0 ? { examples: e } : void 0;
+	};
 	const nodes = {};
-	for (const [name, factory] of Object.entries(NODE_FACTORIES)) nodes[name] = describeNode(factory(), name);
+	for (const [name, factory] of Object.entries(NODE_FACTORIES)) nodes[name] = {
+		...describeNode(factory(), name),
+		...ex(name)
+	};
 	const layout = describeLayoutNode();
 	for (const name of [
 		"Layout",
 		"Stack",
 		"Row",
 		"Column"
-	]) nodes[name] = layout;
+	]) {
+		const e = ex(name);
+		nodes[name] = e ? {
+			...layout,
+			...e
+		} : layout;
+	}
 	return {
 		version: PACKAGE_VERSION,
 		nodes,
 		valueTypes: listValueTypes(),
 		easings: Object.keys(easings),
-		builder: { methods: BUILDER_METHODS },
-		helpers: HELPERS,
+		builder: { methods: withEx ? BUILDER_METHODS.map((m) => ({
+			...m,
+			...ex(m.name)
+		})) : BUILDER_METHODS },
+		helpers: withEx ? HELPERS.map((h) => ({
+			...h,
+			...ex(h.name)
+		})) : HELPERS,
 		createScene: "createScene({ size: { w, h }, children: Node[] }): Scene  —  media assets are declared on the Timeline document: timeline({ assets: { <id>: { kind: 'image'|'video', url } } }); an Image/Video node's `assetId` names an entry here.",
 		subpaths: SUBPATHS
 	};
 }
 //#endregion
-export { describe };
+export { describe, registerExamples };

package/dist/diagnostics.js

@@ -1,4 +1,4 @@
-import { H as createDisplayListBuilder, K as collapseReplacer, r as Group } from "./nodes.js";
+import { U as createDisplayListBuilder, q as collapseReplacer, r as Group } from "./nodes.js";
 import { a as evaluate } from "./scene.js";
 //#region src/displayDiff.ts
 /** A flat, stable JSON value for one command with its resource ids INLINED to content. */

package/dist/examples.d.ts

@@ -0,0 +1,38 @@
+//#region src/examples.d.ts
+/**
+ * `@glissade/scene/examples` — the runnable example corpus (§0.24 onboarding,
+ * card `8jQ9rNqStGDL`). The single highest agent-onboarding cost is STALE
+ * examples: prose that drifts from the runtime, which a cold agent can't
+ * glance-test. The fix is to make canonical examples EXECUTABLE and surfaced from
+ * the same place the doctest harness runs them, so they can't go stale.
+ *
+ * Each {@link ApiExample} carries a copy-pasteable `code` string (what
+ * `describe({ examples: true })` surfaces) AND an executable `run` thunk against
+ * the REAL API (what `examples.test.ts` asserts never throws). The two sit
+ * adjacent and are kept in lockstep; the `run` guard is what fails CI the moment
+ * an example's API drifts (a renamed export, a changed shape).
+ *
+ * Tree-shaking: this module is OFF the base scene index (its own subpath entry),
+ * so a scene that never imports it pays zero bytes. Importing it REGISTERS the
+ * corpus with `describe()` via {@link registerExamples} (the value-type-registry
+ * pattern) — describe never imports examples, so the base embed + IIFE stay lean.
+ */
+/** One runnable example, attached to its describe-key (node type / builder method
+ *  / helper name). `code` is surfaced; `run` is the executed drift guard. */
+interface ApiExample {
+  /** The describe-key this attaches to: a node type ('Rect'), builder method
+   *  ('to'), or helper name ('splitText'). */
+  key: string;
+  /** The copy-pasteable snippet `describe({ examples: true })` surfaces. */
+  code: string;
+  /** Executes the SAME call against the real API — the doctest harness asserts it
+   *  never throws, so the surfaced `code` can't reference a drifted API. */
+  run: () => void;
+}
+declare const EXAMPLES: readonly ApiExample[];
+/** Group the corpus by describe-key → the surfaced code snippets. */
+declare function examplesByKey(): {
+  readonly [key: string]: readonly string[];
+};
+//#endregion
+export { ApiExample, EXAMPLES, examplesByKey };

package/dist/examples.js

@@ -0,0 +1,217 @@
+import { a as Path, i as ImageNode, o as Rect, r as Group, s as Text, t as Circle } from "./nodes.js";
+import { registerExamples } from "./describe.js";
+import { a as evaluate, i as createScene } from "./scene.js";
+import { Grid } from "./grid.js";
+import { Stack } from "./layoutCtors.js";
+import { splitText } from "./type.js";
+import { r as motionPath } from "./motionPath.js";
+import { pathFromSvg } from "./path.js";
+import { key, timeline, track } from "@glissade/core";
+//#region src/examples.ts
+/**
+* `@glissade/scene/examples` — the runnable example corpus (§0.24 onboarding,
+* card `8jQ9rNqStGDL`). The single highest agent-onboarding cost is STALE
+* examples: prose that drifts from the runtime, which a cold agent can't
+* glance-test. The fix is to make canonical examples EXECUTABLE and surfaced from
+* the same place the doctest harness runs them, so they can't go stale.
+*
+* Each {@link ApiExample} carries a copy-pasteable `code` string (what
+* `describe({ examples: true })` surfaces) AND an executable `run` thunk against
+* the REAL API (what `examples.test.ts` asserts never throws). The two sit
+* adjacent and are kept in lockstep; the `run` guard is what fails CI the moment
+* an example's API drifts (a renamed export, a changed shape).
+*
+* Tree-shaking: this module is OFF the base scene index (its own subpath entry),
+* so a scene that never imports it pays zero bytes. Importing it REGISTERS the
+* corpus with `describe()` via {@link registerExamples} (the value-type-registry
+* pattern) — describe never imports examples, so the base embed + IIFE stay lean.
+*/
+/** A throwaway scene+evaluate so a node example proves it renders end-to-end, not
+*  just constructs (the estimating measurer suffices — no backend needed). */
+function renders(...children) {
+	evaluate(createScene({
+		size: {
+			w: 320,
+			h: 200
+		},
+		children
+	}), timeline(() => {}), 0);
+}
+const EXAMPLES = [
+	{
+		key: "Rect",
+		code: "import { Rect } from '@glissade/scene';\nnew Rect({ position: [160, 100], width: 200, height: 100, fill: '#3b82f6', cornerRadius: 12 });",
+		run: () => renders(new Rect({
+			position: [160, 100],
+			width: 200,
+			height: 100,
+			fill: "#3b82f6",
+			cornerRadius: 12
+		}))
+	},
+	{
+		key: "Circle",
+		code: "import { Circle } from '@glissade/scene';\nnew Circle({ position: [160, 100], radius: 48, fill: '#ef4444' });",
+		run: () => renders(new Circle({
+			position: [160, 100],
+			radius: 48,
+			fill: "#ef4444"
+		}))
+	},
+	{
+		key: "Text",
+		code: "import { Text } from '@glissade/scene';\n// position anchors at the baseline-left by default; set `anchor` to share a corner with a shape\nnew Text({ position: [40, 60], text: 'Hello', fontSize: 32, fill: '#111827' });",
+		run: () => renders(new Text({
+			position: [40, 60],
+			text: "Hello",
+			fontSize: 32,
+			fill: "#111827"
+		}))
+	},
+	{
+		key: "Path",
+		code: "import { Path } from '@glissade/scene';\nimport { pathFromSvg } from '@glissade/scene/path';\n// Path.data wants a PathValue — parse an SVG `d` string with pathFromSvg (NOT a raw string)\nnew Path({ data: pathFromSvg('M0 0 L100 0 L50 80 Z'), fill: '#10b981' });",
+		run: () => renders(new Path({
+			data: pathFromSvg("M0 0 L100 0 L50 80 Z"),
+			fill: "#10b981"
+		}))
+	},
+	{
+		key: "Group",
+		code: "import { Group, Rect, Text } from '@glissade/scene';\n// a Group nests its children as one unit (and renders as a wrapper <div> on the DOM tier)\nnew Group({ id: 'card', children: [\n  new Rect({ anchor: 'top-left', position: [0, 0], width: 240, height: 96, fill: '#0f172a', cornerRadius: 16 }),\n  new Text({ anchor: 'top-left', position: [16, 16], text: 'Title', fontSize: 24, fill: '#f8fafc' }),\n] });",
+		run: () => renders(new Group({
+			id: "card",
+			children: [new Rect({
+				anchor: "top-left",
+				position: [0, 0],
+				width: 240,
+				height: 96,
+				fill: "#0f172a",
+				cornerRadius: 16
+			}), new Text({
+				anchor: "top-left",
+				position: [16, 16],
+				text: "Title",
+				fontSize: 24,
+				fill: "#f8fafc"
+			})]
+		}))
+	},
+	{
+		key: "Image",
+		code: "import { Image } from '@glissade/scene';\n// `assetId` names a media entry declared on the Timeline: timeline({ assets: { hero: { kind: 'image', url } } })\nnew Image({ assetId: 'hero', position: [160, 100], width: 200, height: 120 });",
+		run: () => renders(new ImageNode({
+			assetId: "hero",
+			position: [160, 100],
+			width: 200,
+			height: 120
+		}))
+	},
+	{
+		key: "to",
+		code: "import { timeline } from '@glissade/core';\n// `from` anchors the start; the per-target cursor advances by `duration`\ntimeline((tl) => tl.to('card/position', [200, 100], { duration: 1, from: [0, 0] }));",
+		run: () => void timeline((tl) => tl.to("card/position", [200, 100], {
+			duration: 1,
+			from: [0, 0]
+		}))
+	},
+	{
+		key: "fromTo",
+		code: "import { timeline } from '@glissade/core';\ntimeline((tl) => tl.fromTo('card/opacity', 0, 1, { duration: 0.5 }));",
+		run: () => void timeline((tl) => tl.fromTo("card/opacity", 0, 1, { duration: .5 }))
+	},
+	{
+		key: "stagger",
+		code: "import { timeline } from '@glissade/core';\n// one tween per target, cascaded by `each`; `anchor` picks where the cascade ranks from\ntimeline((tl) => tl.stagger(['a/opacity', 'b/opacity', 'c/opacity'], { to: 1, from: 0, duration: 0.4 }, { each: 0.1 }));",
+		run: () => void timeline((tl) => tl.stagger([
+			"a/opacity",
+			"b/opacity",
+			"c/opacity"
+		], {
+			to: 1,
+			from: 0,
+			duration: .4
+		}, { each: .1 }))
+	},
+	{
+		key: "set",
+		code: "import { timeline } from '@glissade/core';\n// a hold key — the value snaps at the resolved position\ntimeline((tl) => tl.set('card/fill', '#ef4444', { at: 0.5 }));",
+		run: () => void timeline((tl) => tl.set("card/fill", "#ef4444", { at: .5 }))
+	},
+	{
+		key: "tracks",
+		code: "import { timeline, track, key } from '@glissade/core';\n// attach raw keyframe tracks (the value type is the 2nd arg)\ntimeline((tl) => tl.tracks([track('card/x', 'number', [key(0, 0), key(1, 100)])]));",
+		run: () => void timeline((tl) => tl.tracks([track("card/x", "number", [key(0, 0), key(1, 100)])]))
+	},
+	{
+		key: "splitText",
+		code: "import { splitText } from '@glissade/scene/type';\n// the source needs an `id` — parts bind tracks against `<id>/<i>`. sp.targets('opacity') gives the reveal-recipe targets\nconst sp = splitText({ id: 'title', text: 'Hello', fontSize: 40 }, { by: 'grapheme' });",
+		run: () => void splitText({
+			id: "title",
+			text: "Hello",
+			fontSize: 40
+		}, { by: "grapheme" })
+	},
+	{
+		key: "measureWrappedText",
+		code: "import { createScene } from '@glissade/scene';\n// size a bubble/card to wrapped text WITHOUT a Text node (the FontSpec field is `size`, not `fontSize`)\nconst scene = createScene({ size: { w: 400, h: 200 }, children: [] });\nconst { width, lines, height } = scene.measureWrappedText('a long string that wraps across the box', { family: 'sans-serif', size: 24 }, 280);",
+		run: () => {
+			createScene({
+				size: {
+					w: 400,
+					h: 200
+				},
+				children: []
+			}).measureWrappedText("a long string that wraps across the box", {
+				family: "sans-serif",
+				size: 24
+			}, 280);
+		}
+	},
+	{
+		key: "Grid",
+		code: "import { Grid } from '@glissade/scene/grid';\n// build-time fan-out into a column grid (no Yoga) — children move to cell centers.\n// fr columns (`columns: 3`) need a `width` to resolve against; `cellHeight` is the row pitch\nGrid({ columns: 3, width: 360, gap: 16, cellHeight: 80, children: [new Rect({ width: 80, height: 60 }), new Rect({ width: 80, height: 60 })] });",
+		run: () => void Grid({
+			columns: 3,
+			width: 360,
+			gap: 16,
+			cellHeight: 80,
+			children: [new Rect({
+				width: 80,
+				height: 60
+			}), new Rect({
+				width: 80,
+				height: 60
+			})]
+		})
+	},
+	{
+		key: "Stack",
+		code: "import { Stack } from '@glissade/scene/layout';\nimport { loadYogaLayoutEngine } from '@glissade/scene/layout';\n// flexbox via Yoga — load the engine ONCE before evaluating any layout scene:\n// await loadYogaLayoutEngine();\nStack({ direction: 'row', gap: 16, children: [new Rect({ width: 80, height: 80 }), new Rect({ width: 80, height: 80 })] });",
+		run: () => void Stack({
+			direction: "row",
+			gap: 16,
+			children: [new Rect({
+				width: 80,
+				height: 80
+			}), new Rect({
+				width: 80,
+				height: 80
+			})]
+		})
+	},
+	{
+		key: "motionPath",
+		code: "import { motionPath } from '@glissade/scene/motion';\nimport { pathFromSvg } from '@glissade/scene/path';\nconst mp = motionPath(pathFromSvg('M0 0 C50 0 50 100 100 100'));\nconst pointHalfway = mp.atProgress(0.5); // { x, y }",
+		run: () => void motionPath(pathFromSvg("M0 0 C50 0 50 100 100 100")).atProgress(.5)
+	}
+];
+/** Group the corpus by describe-key → the surfaced code snippets. */
+function examplesByKey() {
+	const byKey = {};
+	for (const ex of EXAMPLES) (byKey[ex.key] ??= []).push(ex.code);
+	return byKey;
+}
+registerExamples(examplesByKey());
+//#endregion
+export { EXAMPLES, examplesByKey };

package/dist/identity.js

@@ -1,4 +1,4 @@
-import { H as createDisplayListBuilder } from "./nodes.js";
+import { U as createDisplayListBuilder } from "./nodes.js";
 import { r as bindScene } from "./scene.js";
 import { evaluateAt } from "@glissade/core";
 //#region src/identity.ts

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import { C as Mat2x3, D as matEquals, E as invert, O as multiply, S as IDENTITY, T as fromTRS, _ as StrokeStyle, a as FilterSpec, b as glow, c as MeshInterpolation, d as Paint, f as PathSeg, g as ShaderRef, h as ResourceId, i as DrawCommand, l as MeshPaint, m as Resource, n as DisplayList, o as FilterValidationError, p as Rect$1, r as DisplayListBuilder, s as FontSpec, t as BlendMode, u as MeshPoint, v as createDisplayListBuilder, w as applyToPoint, x as validateFilters, y as filtersToCanvasFilter } from "./displayList.js";
 import { t as collapseReplacer } from "./collapseReplacer.js";
-import { $ as quantize, A as resolveSketch, B as NodeConstructionError, C as Polyline, D as arcLength, E as SketchValidationError, F as AnchorSpec, G as TextMeasurer, H as PropInit, I as BindablePropTarget, J as __resetEstimateWarnings, K as TextMetricsLite, L as EvalContext, M as sketchStrokes, N as validateHachure, O as flatten, P as validateSketch, Q as measureWrappedText, R as HitArea, S as HachureSpec, T as SketchStyle, U as resolveAnchor, V as NodeProps, W as MEASURE_QUANTUM_PX, X as estimatingMeasurer, Y as breakLines, Z as isEstimatingMeasurer, _ as WordBox, a as ImageNode, b as revealSchedule, c as Path, d as RevealMark, et as segmentGraphemes, f as ShapeProps, g as VideoProps, h as Video, i as Group, j as roughen, k as hachureLines, l as PathProps, m as TextProps, n as Custom, nt as setDefaultMeasurer, o as ImageProps, p as Text, q as WrappedTextMetrics, r as GraphemeBox, s as LineBox, t as Circle, tt as segmentWords, u as Rect, v as coercePathData, w as ResolvedSketch, x as roundedRectSegs, y as pathFromSegs, z as Node } from "./nodes.js";
+import { $ as measureWrappedText, A as resolveSketch, B as NodeConstructionError, C as Polyline, D as arcLength, E as SketchValidationError, F as AnchorSpec, G as TextMeasurer, H as PropInit, I as BindablePropTarget, J as __resetEstimateWarnings, K as TextMetricsLite, L as EvalContext, M as sketchStrokes, N as validateHachure, O as flatten, P as validateSketch, Q as isEstimatingMeasurer, R as HitArea, S as HachureSpec, T as SketchStyle, U as resolveAnchor, V as NodeProps, W as MEASURE_QUANTUM_PX, X as breakLines, Y as assertFiniteFontSize, Z as estimatingMeasurer, _ as WordBox, a as ImageNode, b as revealSchedule, c as Path, d as RevealMark, et as quantize, f as ShapeProps, g as VideoProps, h as Video, i as Group, j as roughen, k as hachureLines, l as PathProps, m as TextProps, n as Custom, nt as segmentWords, o as ImageProps, p as Text, q as WrappedTextMetrics, r as GraphemeBox, rt as setDefaultMeasurer, s as LineBox, t as Circle, tt as segmentGraphemes, u as Rect, v as coercePathData, w as ResolvedSketch, x as roundedRectSegs, y as pathFromSegs, z as Node } from "./nodes.js";
 import { a as SceneModule, c as evaluate, i as SceneInit, n as ReservedNodeIdError, o as bindScene, r as Scene, s as createScene, t as DuplicateNodeIdError } from "./scene.js";
 import { a as LayoutEngineMissingError, c as requireLayoutEngine, i as LayoutEngine, l as setLayoutEngine, n as LayoutChildSpec, r as LayoutContainerSpec, s as getLayoutEngine, t as LayoutBox } from "./layoutEngine.js";
 import { BindableSignal, CoverageReport, EaseSpec, FontMode, FontUsage, MeshPaint as MeshPaint$1, Rng, Timeline, Track } from "@glissade/core";
@@ -619,4 +619,4 @@ declare function meshRasterSize(bw: number, bh: number): {
   h: number;
 };
 //#endregion
-export { ALL_FILTER_KINDS, type AnchorSpec, type BackendCaps, type BindablePropTarget, type BlendMode, type CanvasLike, Circle, ColdAssetError, type Ctx2DLike, Custom, DeterminismViolationError, type DisplayList, type DisplayListBuilder, type DrawCommand, type DrawOnEachOptions, type DrawOnOptions, DuplicateNodeIdError, type EachBox, type EachContext, type EachDistribute, EachError, type EachLayout, type EachMotion, type EachOpts, type EachResult, type EditMark, type EvalContext, type FilterKind, type FilterSpec, FilterValidationError, type FontByteLoader, type FontSpec, type GraphemeBox, Group, type GuardMode, type HachureSpec, Highlight, type HighlightProps, type HitArea, IDENTITY, ImageNode as Image, ImageNode, type ImageDataLike, type ImageHandle, type ImageProps, type LayoutBox, type LayoutChildSpec, type LayoutContainerSpec, type LayoutEngine, LayoutEngineMissingError, type LineBox, MEASURE_QUANTUM_PX, MESH_DOWNSCALE, MESH_SHEPARD_POWER, MESH_SIGMA, type Mat2x3, type MeshInterpolation, type MeshPaint, type MeshPoint, NODE_TAXONOMY, Node, NodeConstructionError, type NodeProps, type NodeTypeName, type Paint, Path, type PathLike, type PathProps, type PathSeg, type Place, type Polyline, type PropInit, Raster2D, type Raster2DHost, Rect, type Rect$1 as RectShape, type RenderBackend, ReservedNodeIdError, type ResolvedSketch, type Resource, type ResourceId, type RevealMark, type Scene, type SceneInit, type SceneModule, type ShaderCaps, ShaderEffect, type ShaderEffectProps, type ShaderRef, type ShapeProps, type SketchStyle, SketchValidationError, type StepMark, type StrokeStyle, Text, TextCursor, type TextCursorProps, type TextMeasurer, type TextMetricsLite, type TextProps, type TypeEdit, type TypewriterResult, type ValidateSceneFontsOptions, Video, type VideoFrameSource, type VideoProps, type WordBox, type WrappedTextMetrics, __resetEstimateWarnings, applyToPoint, arcLength, bindScene, breakLines, coercePathData, collapseReplacer, collectLocalizedTextUsages, collectTextUsages, createDisplayListBuilder, createScene, drawOn, drawOnEach, each, estimatingMeasurer, evaluate, filtersToCanvasFilter, flatten, fontString, fromTRS, getLayoutEngine, glow, hachureLines, highlight, invert, isEstimatingMeasurer, matEquals, measureWrappedText, meshRasterSize, multiply, pathFromSegs, quantize, rasterizeMesh, requireLayoutEngine, resolveAnchor, resolveSketch, revealSchedule, roughen, roundedRectSegs, segmentGraphemes, segmentWords, setDefaultMeasurer, setLayoutEngine, sketchStrokes, textCursor, typewriter, validateFilters, validateHachure, validateSceneFonts, validateSketch, withDeterminismGuards };
+export { ALL_FILTER_KINDS, type AnchorSpec, type BackendCaps, type BindablePropTarget, type BlendMode, type CanvasLike, Circle, ColdAssetError, type Ctx2DLike, Custom, DeterminismViolationError, type DisplayList, type DisplayListBuilder, type DrawCommand, type DrawOnEachOptions, type DrawOnOptions, DuplicateNodeIdError, type EachBox, type EachContext, type EachDistribute, EachError, type EachLayout, type EachMotion, type EachOpts, type EachResult, type EditMark, type EvalContext, type FilterKind, type FilterSpec, FilterValidationError, type FontByteLoader, type FontSpec, type GraphemeBox, Group, type GuardMode, type HachureSpec, Highlight, type HighlightProps, type HitArea, IDENTITY, ImageNode as Image, ImageNode, type ImageDataLike, type ImageHandle, type ImageProps, type LayoutBox, type LayoutChildSpec, type LayoutContainerSpec, type LayoutEngine, LayoutEngineMissingError, type LineBox, MEASURE_QUANTUM_PX, MESH_DOWNSCALE, MESH_SHEPARD_POWER, MESH_SIGMA, type Mat2x3, type MeshInterpolation, type MeshPaint, type MeshPoint, NODE_TAXONOMY, Node, NodeConstructionError, type NodeProps, type NodeTypeName, type Paint, Path, type PathLike, type PathProps, type PathSeg, type Place, type Polyline, type PropInit, Raster2D, type Raster2DHost, Rect, type Rect$1 as RectShape, type RenderBackend, ReservedNodeIdError, type ResolvedSketch, type Resource, type ResourceId, type RevealMark, type Scene, type SceneInit, type SceneModule, type ShaderCaps, ShaderEffect, type ShaderEffectProps, type ShaderRef, type ShapeProps, type SketchStyle, SketchValidationError, type StepMark, type StrokeStyle, Text, TextCursor, type TextCursorProps, type TextMeasurer, type TextMetricsLite, type TextProps, type TypeEdit, type TypewriterResult, type ValidateSceneFontsOptions, Video, type VideoFrameSource, type VideoProps, type WordBox, type WrappedTextMetrics, __resetEstimateWarnings, applyToPoint, arcLength, assertFiniteFontSize, bindScene, breakLines, coercePathData, collapseReplacer, collectLocalizedTextUsages, collectTextUsages, createDisplayListBuilder, createScene, drawOn, drawOnEach, each, estimatingMeasurer, evaluate, filtersToCanvasFilter, flatten, fontString, fromTRS, getLayoutEngine, glow, hachureLines, highlight, invert, isEstimatingMeasurer, matEquals, measureWrappedText, meshRasterSize, multiply, pathFromSegs, quantize, rasterizeMesh, requireLayoutEngine, resolveAnchor, resolveSketch, revealSchedule, roughen, roundedRectSegs, segmentGraphemes, segmentWords, setDefaultMeasurer, setLayoutEngine, sketchStrokes, textCursor, typewriter, validateFilters, validateHachure, validateSceneFonts, validateSketch, withDeterminismGuards };

package/dist/index.js

@@ -1,4 +1,4 @@
-import { B as validateSketch, D as segmentGraphemes, E as quantize, F as hashStr, G as validateFilters, H as createDisplayListBuilder, I as resolveSketch, J as applyToPoint, K as collapseReplacer, L as roughen, M as arcLength, N as flatten, O as segmentWords, P as hachureLines, Q as multiply, R as sketchStrokes, S as estimatingMeasurer, T as measureWrappedText, U as filtersToCanvasFilter, V as FilterValidationError, W as glow, X as invert, Y as fromTRS, Z as matEquals, a as Path, b as __resetEstimateWarnings, c as Video, d as revealSchedule, f as roundedRectSegs, h as resolveAnchor, i as ImageNode, j as SketchValidationError, k as setDefaultMeasurer, l as coercePathData, m as NodeConstructionError, n as Custom, o as Rect, p as Node, q as IDENTITY, r as Group, s as Text, t as Circle, u as pathFromSegs, w as isEstimatingMeasurer, x as breakLines, y as MEASURE_QUANTUM_PX, z as validateHachure } from "./nodes.js";
+import { $ as multiply, A as setDefaultMeasurer, B as validateHachure, C as estimatingMeasurer, D as quantize, E as measureWrappedText, F as hachureLines, G as glow, H as FilterValidationError, I as hashStr, J as IDENTITY, K as validateFilters, L as resolveSketch, M as SketchValidationError, N as arcLength, O as segmentGraphemes, P as flatten, Q as matEquals, R as roughen, S as breakLines, T as isEstimatingMeasurer, U as createDisplayListBuilder, V as validateSketch, W as filtersToCanvasFilter, X as fromTRS, Y as applyToPoint, Z as invert, a as Path, b as __resetEstimateWarnings, c as Video, d as revealSchedule, f as roundedRectSegs, h as resolveAnchor, i as ImageNode, k as segmentWords, l as coercePathData, m as NodeConstructionError, n as Custom, o as Rect, p as Node, q as collapseReplacer, r as Group, s as Text, t as Circle, u as pathFromSegs, x as assertFiniteFontSize, y as MEASURE_QUANTUM_PX, z as sketchStrokes } from "./nodes.js";
 import { a as evaluate, i as createScene, n as ReservedNodeIdError, r as bindScene, t as DuplicateNodeIdError } from "./scene.js";
 import { i as setLayoutEngine, n as getLayoutEngine, r as requireLayoutEngine, t as LayoutEngineMissingError } from "./layoutEngine.js";
 import { buildFontRegistry, emitDevWarning, key, lerpColor, oklabToRgba, parseCmap, parseColor, random, rgbaToOklab, signal, stagger, track, validateFonts } from "@glissade/core";
@@ -1356,4 +1356,4 @@ var Raster2D = class {
 	}
 };
 //#endregion
-export { ALL_FILTER_KINDS, Circle, ColdAssetError, Custom, DeterminismViolationError, DuplicateNodeIdError, EachError, FilterValidationError, Group, Highlight, IDENTITY, ImageNode as Image, ImageNode, LayoutEngineMissingError, MEASURE_QUANTUM_PX, MESH_DOWNSCALE, MESH_SHEPARD_POWER, MESH_SIGMA, NODE_TAXONOMY, Node, NodeConstructionError, Path, Raster2D, Rect, ReservedNodeIdError, ShaderEffect, SketchValidationError, Text, TextCursor, Video, __resetEstimateWarnings, applyToPoint, arcLength, bindScene, breakLines, coercePathData, collapseReplacer, collectLocalizedTextUsages, collectTextUsages, createDisplayListBuilder, createScene, drawOn, drawOnEach, each, estimatingMeasurer, evaluate, filtersToCanvasFilter, flatten, fontString, fromTRS, getLayoutEngine, glow, hachureLines, highlight, invert, isEstimatingMeasurer, matEquals, measureWrappedText, meshRasterSize, multiply, pathFromSegs, quantize, rasterizeMesh, requireLayoutEngine, resolveAnchor, resolveSketch, revealSchedule, roughen, roundedRectSegs, segmentGraphemes, segmentWords, setDefaultMeasurer, setLayoutEngine, sketchStrokes, textCursor, typewriter, validateFilters, validateHachure, validateSceneFonts, validateSketch, withDeterminismGuards };
+export { ALL_FILTER_KINDS, Circle, ColdAssetError, Custom, DeterminismViolationError, DuplicateNodeIdError, EachError, FilterValidationError, Group, Highlight, IDENTITY, ImageNode as Image, ImageNode, LayoutEngineMissingError, MEASURE_QUANTUM_PX, MESH_DOWNSCALE, MESH_SHEPARD_POWER, MESH_SIGMA, NODE_TAXONOMY, Node, NodeConstructionError, Path, Raster2D, Rect, ReservedNodeIdError, ShaderEffect, SketchValidationError, Text, TextCursor, Video, __resetEstimateWarnings, applyToPoint, arcLength, assertFiniteFontSize, bindScene, breakLines, coercePathData, collapseReplacer, collectLocalizedTextUsages, collectTextUsages, createDisplayListBuilder, createScene, drawOn, drawOnEach, each, estimatingMeasurer, evaluate, filtersToCanvasFilter, flatten, fontString, fromTRS, getLayoutEngine, glow, hachureLines, highlight, invert, isEstimatingMeasurer, matEquals, measureWrappedText, meshRasterSize, multiply, pathFromSegs, quantize, rasterizeMesh, requireLayoutEngine, resolveAnchor, resolveSketch, revealSchedule, roughen, roundedRectSegs, segmentGraphemes, segmentWords, setDefaultMeasurer, setLayoutEngine, sketchStrokes, textCursor, typewriter, validateFilters, validateHachure, validateSceneFonts, validateSketch, withDeterminismGuards };

package/dist/layoutCtors.js

@@ -1,4 +1,4 @@
-import { C as fallbackMeasurer, r as Group } from "./nodes.js";
+import { r as Group, w as fallbackMeasurer } from "./nodes.js";
 import { r as requireLayoutEngine } from "./layoutEngine.js";
 import { computed, signal } from "@glissade/core";
 //#region src/layoutCtors.ts

package/dist/motion.js

@@ -1,171 +1,2 @@
-import { a as Path, p as Node } from "./nodes.js";
-import { signal } from "@glissade/core";
-//#region src/motionPath.ts
-/**
-* Motion along a path: sample a point (and tangent) at an arc-length position on
-* a PathValue, and drive a node along it over time. The Path node draws/morphs
-* geometry; this is the companion that makes another node — a cursor, a dot, an
-* arrow — *travel* that geometry.
-*
-* Sampling is arc-length parameterized (constant speed), so progress 0→1 moves
-* evenly instead of bunching at the control points. Pure and deterministic: the
-* table is built once from a static PathValue and `atProgress` is a pure
-* function of progress, so evaluate() stays pure and goldens are byte-stable.
-*/
-const clamp01 = (v) => v < 0 ? 0 : v > 1 ? 1 : v;
-function cubicPoint(p0, p1, p2, p3, t) {
-	const mt = 1 - t;
-	const a = mt * mt * mt;
-	const b = 3 * mt * mt * t;
-	const c = 3 * mt * t * t;
-	const d = t * t * t;
-	return [a * p0[0] + b * p1[0] + c * p2[0] + d * p3[0], a * p0[1] + b * p1[1] + c * p2[1] + d * p3[1]];
-}
-/** PathValue contours → cubic segments, same v/in/out math as Path.pathSegs. */
-function toCubics(path) {
-	const out = [];
-	for (const ct of path) {
-		const n = ct.v.length;
-		for (let i = 0; i < n - 1; i++) out.push([
-			ct.v[i],
-			[ct.v[i][0] + ct.out[i][0], ct.v[i][1] + ct.out[i][1]],
-			[ct.v[i + 1][0] + ct.in[i + 1][0], ct.v[i + 1][1] + ct.in[i + 1][1]],
-			ct.v[i + 1]
-		]);
-		if (ct.closed && n > 1) out.push([
-			ct.v[n - 1],
-			[ct.v[n - 1][0] + ct.out[n - 1][0], ct.v[n - 1][1] + ct.out[n - 1][1]],
-			[ct.v[0][0] + ct.in[0][0], ct.v[0][1] + ct.in[0][1]],
-			ct.v[0]
-		]);
-	}
-	return out;
-}
-/**
-* Build a reusable arc-length sampler. Densely samples each cubic into a
-* cumulative-length polyline (samplesPerSegment, default 32) so `at`/`tangent`
-* are simple span lerps — smooth enough for motion, no per-call bezier solve.
-*/
-function motionPath(path, opts = {}) {
-	const steps = Math.max(1, Math.floor(opts.samplesPerSegment ?? 32));
-	const cubics = toCubics(path);
-	const pts = [];
-	const cum = [];
-	if (cubics.length > 0) {
-		let prev = cubicPoint(...cubics[0], 0);
-		pts.push(prev);
-		cum.push(0);
-		let acc = 0;
-		for (const cub of cubics) for (let k = 1; k <= steps; k++) {
-			const p = cubicPoint(...cub, k / steps);
-			acc += Math.hypot(p[0] - prev[0], p[1] - prev[1]);
-			pts.push(p);
-			cum.push(acc);
-			prev = p;
-		}
-	} else {
-		const first = path[0]?.v[0];
-		pts.push(first ? [first[0], first[1]] : [0, 0]);
-		cum.push(0);
-	}
-	const total = cum[cum.length - 1];
-	const locate = (s) => {
-		if (total <= 0 || s <= 0) return {
-			i: 0,
-			f: 0
-		};
-		if (s >= total) return {
-			i: pts.length - 2,
-			f: 1
-		};
-		let i = 0;
-		while (i < cum.length - 1 && cum[i + 1] < s) i++;
-		const span = cum[i + 1] - cum[i];
-		return {
-			i,
-			f: span > 0 ? (s - cum[i]) / span : 0
-		};
-	};
-	const at = (s) => {
-		if (pts.length === 1) return [pts[0][0], pts[0][1]];
-		const { i, f } = locate(s);
-		const a = pts[i];
-		const b = pts[i + 1];
-		return [a[0] + (b[0] - a[0]) * f, a[1] + (b[1] - a[1]) * f];
-	};
-	const tangentAt = (s) => {
-		if (pts.length === 1) return [1, 0];
-		const { i } = locate(s);
-		const a = pts[i];
-		const b = pts[i + 1];
-		const dx = b[0] - a[0];
-		const dy = b[1] - a[1];
-		const len = Math.hypot(dx, dy);
-		return len > 0 ? [dx / len, dy / len] : [1, 0];
-	};
-	return {
-		length: total,
-		at,
-		tangentAt,
-		atProgress: (u) => at(clamp01(u) * total),
-		tangentAtProgress: (u) => tangentAt(clamp01(u) * total)
-	};
-}
-/** Total arc length of a path. */
-function pathLength(path) {
-	return motionPath(path).length;
-}
-/** Point at arc-length s along a path (clamped to [0, length]). */
-function pointAtLength(path, s) {
-	return motionPath(path).at(s);
-}
-/**
-* A companion node that drives `target` along `path` as `progress` animates.
-* Owns the target's `position` (and `rotation` when `orient`) via pull-based
-* binding, so there's no eval-order side effect. Add it to the scene (its
-* `progress` is the animatable target); it draws nothing itself.
-*/
-var FollowPath = class extends Node {
-	target;
-	progress;
-	constructor(props) {
-		super(props);
-		this.target = props.target;
-		this.progress = signal(1);
-		if (typeof props.progress === "function") this.progress.bindSource(props.progress);
-		else if (props.progress !== void 0) this.progress.set(props.progress);
-		this.registerTarget("progress", this.progress, "number");
-		const sOpts = props.samplesPerSegment !== void 0 ? { samplesPerSegment: props.samplesPerSegment } : {};
-		const getPath = props.path instanceof Path ? () => props.path.data() : () => props.path;
-		let cachedPath = getPath();
-		let cachedSampler = motionPath(cachedPath, sOpts);
-		const sampler = () => {
-			const pv = getPath();
-			if (pv !== cachedPath) {
-				cachedPath = pv;
-				cachedSampler = motionPath(pv, sOpts);
-			}
-			return cachedSampler;
-		};
-		props.target.position.bindSource(() => sampler().atProgress(this.progress()));
-		if (props.orient) {
-			const offset = props.orientOffset ?? 0;
-			props.target.rotation.bindSource(() => {
-				const t = sampler().tangentAtProgress(this.progress());
-				return Math.atan2(t[1], t[0]) * 180 / Math.PI + offset;
-			});
-		}
-	}
-	draw() {}
-};
-/** `children: [route, cursor, followPath(cursor, route, { orient: true })]` — cursor traces the route.
-* Pass the Path *node* to follow it as it morphs; pass a PathValue for a fixed route. */
-function followPath(target, path, props = {}) {
-	return new FollowPath({
-		...props,
-		target,
-		path
-	});
-}
-//#endregion
+import { a as pointAtLength, i as pathLength, n as followPath, r as motionPath, t as FollowPath } from "./motionPath.js";
 export { FollowPath, followPath, motionPath, pathLength, pointAtLength };

package/dist/motionPath.js

@@ -0,0 +1,171 @@
+import { a as Path, p as Node } from "./nodes.js";
+import { signal } from "@glissade/core";
+//#region src/motionPath.ts
+/**
+* Motion along a path: sample a point (and tangent) at an arc-length position on
+* a PathValue, and drive a node along it over time. The Path node draws/morphs
+* geometry; this is the companion that makes another node — a cursor, a dot, an
+* arrow — *travel* that geometry.
+*
+* Sampling is arc-length parameterized (constant speed), so progress 0→1 moves
+* evenly instead of bunching at the control points. Pure and deterministic: the
+* table is built once from a static PathValue and `atProgress` is a pure
+* function of progress, so evaluate() stays pure and goldens are byte-stable.
+*/
+const clamp01 = (v) => v < 0 ? 0 : v > 1 ? 1 : v;
+function cubicPoint(p0, p1, p2, p3, t) {
+	const mt = 1 - t;
+	const a = mt * mt * mt;
+	const b = 3 * mt * mt * t;
+	const c = 3 * mt * t * t;
+	const d = t * t * t;
+	return [a * p0[0] + b * p1[0] + c * p2[0] + d * p3[0], a * p0[1] + b * p1[1] + c * p2[1] + d * p3[1]];
+}
+/** PathValue contours → cubic segments, same v/in/out math as Path.pathSegs. */
+function toCubics(path) {
+	const out = [];
+	for (const ct of path) {
+		const n = ct.v.length;
+		for (let i = 0; i < n - 1; i++) out.push([
+			ct.v[i],
+			[ct.v[i][0] + ct.out[i][0], ct.v[i][1] + ct.out[i][1]],
+			[ct.v[i + 1][0] + ct.in[i + 1][0], ct.v[i + 1][1] + ct.in[i + 1][1]],
+			ct.v[i + 1]
+		]);
+		if (ct.closed && n > 1) out.push([
+			ct.v[n - 1],
+			[ct.v[n - 1][0] + ct.out[n - 1][0], ct.v[n - 1][1] + ct.out[n - 1][1]],
+			[ct.v[0][0] + ct.in[0][0], ct.v[0][1] + ct.in[0][1]],
+			ct.v[0]
+		]);
+	}
+	return out;
+}
+/**
+* Build a reusable arc-length sampler. Densely samples each cubic into a
+* cumulative-length polyline (samplesPerSegment, default 32) so `at`/`tangent`
+* are simple span lerps — smooth enough for motion, no per-call bezier solve.
+*/
+function motionPath(path, opts = {}) {
+	const steps = Math.max(1, Math.floor(opts.samplesPerSegment ?? 32));
+	const cubics = toCubics(path);
+	const pts = [];
+	const cum = [];
+	if (cubics.length > 0) {
+		let prev = cubicPoint(...cubics[0], 0);
+		pts.push(prev);
+		cum.push(0);
+		let acc = 0;
+		for (const cub of cubics) for (let k = 1; k <= steps; k++) {
+			const p = cubicPoint(...cub, k / steps);
+			acc += Math.hypot(p[0] - prev[0], p[1] - prev[1]);
+			pts.push(p);
+			cum.push(acc);
+			prev = p;
+		}
+	} else {
+		const first = path[0]?.v[0];
+		pts.push(first ? [first[0], first[1]] : [0, 0]);
+		cum.push(0);
+	}
+	const total = cum[cum.length - 1];
+	const locate = (s) => {
+		if (total <= 0 || s <= 0) return {
+			i: 0,
+			f: 0
+		};
+		if (s >= total) return {
+			i: pts.length - 2,
+			f: 1
+		};
+		let i = 0;
+		while (i < cum.length - 1 && cum[i + 1] < s) i++;
+		const span = cum[i + 1] - cum[i];
+		return {
+			i,
+			f: span > 0 ? (s - cum[i]) / span : 0
+		};
+	};
+	const at = (s) => {
+		if (pts.length === 1) return [pts[0][0], pts[0][1]];
+		const { i, f } = locate(s);
+		const a = pts[i];
+		const b = pts[i + 1];
+		return [a[0] + (b[0] - a[0]) * f, a[1] + (b[1] - a[1]) * f];
+	};
+	const tangentAt = (s) => {
+		if (pts.length === 1) return [1, 0];
+		const { i } = locate(s);
+		const a = pts[i];
+		const b = pts[i + 1];
+		const dx = b[0] - a[0];
+		const dy = b[1] - a[1];
+		const len = Math.hypot(dx, dy);
+		return len > 0 ? [dx / len, dy / len] : [1, 0];
+	};
+	return {
+		length: total,
+		at,
+		tangentAt,
+		atProgress: (u) => at(clamp01(u) * total),
+		tangentAtProgress: (u) => tangentAt(clamp01(u) * total)
+	};
+}
+/** Total arc length of a path. */
+function pathLength(path) {
+	return motionPath(path).length;
+}
+/** Point at arc-length s along a path (clamped to [0, length]). */
+function pointAtLength(path, s) {
+	return motionPath(path).at(s);
+}
+/**
+* A companion node that drives `target` along `path` as `progress` animates.
+* Owns the target's `position` (and `rotation` when `orient`) via pull-based
+* binding, so there's no eval-order side effect. Add it to the scene (its
+* `progress` is the animatable target); it draws nothing itself.
+*/
+var FollowPath = class extends Node {
+	target;
+	progress;
+	constructor(props) {
+		super(props);
+		this.target = props.target;
+		this.progress = signal(1);
+		if (typeof props.progress === "function") this.progress.bindSource(props.progress);
+		else if (props.progress !== void 0) this.progress.set(props.progress);
+		this.registerTarget("progress", this.progress, "number");
+		const sOpts = props.samplesPerSegment !== void 0 ? { samplesPerSegment: props.samplesPerSegment } : {};
+		const getPath = props.path instanceof Path ? () => props.path.data() : () => props.path;
+		let cachedPath = getPath();
+		let cachedSampler = motionPath(cachedPath, sOpts);
+		const sampler = () => {
+			const pv = getPath();
+			if (pv !== cachedPath) {
+				cachedPath = pv;
+				cachedSampler = motionPath(pv, sOpts);
+			}
+			return cachedSampler;
+		};
+		props.target.position.bindSource(() => sampler().atProgress(this.progress()));
+		if (props.orient) {
+			const offset = props.orientOffset ?? 0;
+			props.target.rotation.bindSource(() => {
+				const t = sampler().tangentAtProgress(this.progress());
+				return Math.atan2(t[1], t[0]) * 180 / Math.PI + offset;
+			});
+		}
+	}
+	draw() {}
+};
+/** `children: [route, cursor, followPath(cursor, route, { orient: true })]` — cursor traces the route.
+* Pass the Path *node* to follow it as it morphs; pass a PathValue for a fixed route. */
+function followPath(target, path, props = {}) {
+	return new FollowPath({
+		...props,
+		target,
+		path
+	});
+}
+//#endregion
+export { pointAtLength as a, pathLength as i, followPath as n, motionPath as r, FollowPath as t };

package/dist/nodes.d.ts

@@ -21,6 +21,17 @@ interface TextMeasurer {
 declare const MEASURE_QUANTUM_PX = 0.5;
 /** §3.6 measurement quantum — round to the MEASURE_QUANTUM_PX grid. */
 declare function quantize(v: number): number;
+/**
+ * FAIL LOUD on a non-measurable FontSpec (§0.24 fail-loud sweep). A `size` that
+ * isn't a finite positive number silently yields NaN/0 metrics in the estimating
+ * measurers (and a wrong-font fallback in the real backends) → zero-height layout
+ * boxes, broken wrapping/reveal, all with NO error — the silent-wrong-result class
+ * an agent can't glance-test. The common cause is the field name: the FontSpec
+ * field is `size`, NOT `fontSize` (that is the Text node prop). The single guard
+ * every measurement entry point (breakLines, measureWrappedText, the backend
+ * `measureText`s) routes through, so the contract is enforced uniformly.
+ */
+declare function assertFiniteFontSize(font: FontSpec, where: string): void;
 /**
  * Process-wide fallback measurer for FACTORY-TIME measurement — component
  * factories run before any scene exists, so Text pulls (measuredSize,
@@ -879,4 +890,4 @@ interface RevealMark {
  */
 declare function revealSchedule(text: Text, reveal: Track<number>, measurer?: TextMeasurer): RevealMark[];
 //#endregion
-export { quantize as $, resolveSketch as A, NodeConstructionError as B, Polyline as C, arcLength as D, SketchValidationError as E, AnchorSpec as F, TextMeasurer as G, PropInit as H, BindablePropTarget as I, __resetEstimateWarnings as J, TextMetricsLite as K, EvalContext as L, sketchStrokes as M, validateHachure as N, flatten as O, validateSketch as P, measureWrappedText as Q, HitArea as R, HachureSpec as S, SketchStyle as T, resolveAnchor as U, NodeProps as V, MEASURE_QUANTUM_PX as W, estimatingMeasurer as X, breakLines as Y, isEstimatingMeasurer as Z, WordBox as _, ImageNode as a, revealSchedule as b, Path as c, RevealMark as d, segmentGraphemes as et, ShapeProps as f, VideoProps as g, Video as h, Group as i, roughen as j, hachureLines as k, PathProps as l, TextProps as m, Custom as n, setDefaultMeasurer as nt, ImageProps as o, Text as p, WrappedTextMetrics as q, GraphemeBox as r, LineBox as s, Circle as t, segmentWords as tt, Rect as u, coercePathData as v, ResolvedSketch as w, roundedRectSegs as x, pathFromSegs as y, Node as z };
+export { measureWrappedText as $, resolveSketch as A, NodeConstructionError as B, Polyline as C, arcLength as D, SketchValidationError as E, AnchorSpec as F, TextMeasurer as G, PropInit as H, BindablePropTarget as I, __resetEstimateWarnings as J, TextMetricsLite as K, EvalContext as L, sketchStrokes as M, validateHachure as N, flatten as O, validateSketch as P, isEstimatingMeasurer as Q, HitArea as R, HachureSpec as S, SketchStyle as T, resolveAnchor as U, NodeProps as V, MEASURE_QUANTUM_PX as W, breakLines as X, assertFiniteFontSize as Y, estimatingMeasurer as Z, WordBox as _, ImageNode as a, revealSchedule as b, Path as c, RevealMark as d, quantize as et, ShapeProps as f, VideoProps as g, Video as h, Group as i, roughen as j, hachureLines as k, PathProps as l, TextProps as m, Custom as n, segmentWords as nt, ImageProps as o, Text as p, WrappedTextMetrics as q, GraphemeBox as r, setDefaultMeasurer as rt, LineBox as s, Circle as t, segmentGraphemes as tt, Rect as u, coercePathData as v, ResolvedSketch as w, roundedRectSegs as x, pathFromSegs as y, Node as z };

package/dist/nodes.js

@@ -560,6 +560,19 @@ function quantize(v) {
 	return Math.round(v / MEASURE_QUANTUM_PX) * MEASURE_QUANTUM_PX;
 }
 /**
+* FAIL LOUD on a non-measurable FontSpec (§0.24 fail-loud sweep). A `size` that
+* isn't a finite positive number silently yields NaN/0 metrics in the estimating
+* measurers (and a wrong-font fallback in the real backends) → zero-height layout
+* boxes, broken wrapping/reveal, all with NO error — the silent-wrong-result class
+* an agent can't glance-test. The common cause is the field name: the FontSpec
+* field is `size`, NOT `fontSize` (that is the Text node prop). The single guard
+* every measurement entry point (breakLines, measureWrappedText, the backend
+* `measureText`s) routes through, so the contract is enforced uniformly.
+*/
+function assertFiniteFontSize(font, where) {
+	if (typeof font.size !== "number" || !Number.isFinite(font.size) || font.size <= 0) throw new Error(`${where}: font.size must be a positive number (got ${JSON.stringify(font.size)}). The FontSpec field is \`size\`, not \`fontSize\` (that is the Text node prop) — pass \`{ family, size }\`.`);
+}
+/**
 * Estimating fallback measurer — used only when no backend has been injected
 * (e.g. evaluating for IR-level tests). Deterministic but not metrically
 * faithful; mount(), the CLI, and exporters always inject the real one.
@@ -651,6 +664,7 @@ function segmentGraphemes(text) {
 * intra-word breaking in v1).
 */
 function breakLines(text, font, maxWidth, measurer) {
+	assertFiniteFontSize(font, "breakLines");
 	const paragraphs = text.split("\n");
 	if (maxWidth === void 0 || maxWidth <= 0) return paragraphs;
 	const lines = [];
@@ -678,7 +692,7 @@ function breakLines(text, font, maxWidth, measurer) {
 * `FontSpec`, so it's a parameter here).
 */
 function measureWrappedText(text, font, width, lineHeight, measurer) {
-	if (typeof font.size !== "number" || !Number.isFinite(font.size) || font.size <= 0) throw new Error(`measureWrappedText: font.size must be a positive number (got ${JSON.stringify(font.size)}). The FontSpec field is \`size\`, not \`fontSize\` (that is the Text node prop) — pass \`{ family, size }\`.`);
+	assertFiniteFontSize(font, "measureWrappedText");
 	const lines = breakLines(text, font, width > 0 ? width : void 0, measurer);
 	let widest = 0;
 	let ascent = 0;
@@ -2288,4 +2302,4 @@ function revealSchedule(text, reveal, measurer) {
 	return marks;
 }
 //#endregion
-export { warnIfEstimating as A, validateSketch as B, fallbackMeasurer as C, segmentGraphemes as D, quantize as E, hashStr as F, validateFilters as G, createDisplayListBuilder as H, resolveSketch as I, applyToPoint as J, collapseReplacer as K, roughen as L, arcLength as M, flatten as N, segmentWords as O, hachureLines as P, multiply as Q, sketchStrokes as R, estimatingMeasurer as S, measureWrappedText as T, filtersToCanvasFilter as U, FilterValidationError as V, glow as W, invert as X, fromTRS as Y, matEquals as Z, NODE_CONSTRUCTION_PROP_NAMES as _, Path as a, __resetEstimateWarnings as b, Video as c, revealSchedule as d, roundedRectSegs as f, BASE_CONSTRUCTION_PROP_NAMES as g, resolveAnchor as h, ImageNode as i, SketchValidationError as j, setDefaultMeasurer as k, coercePathData as l, NodeConstructionError as m, Custom as n, Rect as o, Node as p, IDENTITY as q, Group as r, Text as s, Circle as t, pathFromSegs as u, isConstructionProp as v, isEstimatingMeasurer as w, breakLines as x, MEASURE_QUANTUM_PX as y, validateHachure as z };
+export { multiply as $, setDefaultMeasurer as A, validateHachure as B, estimatingMeasurer as C, quantize as D, measureWrappedText as E, hachureLines as F, glow as G, FilterValidationError as H, hashStr as I, IDENTITY as J, validateFilters as K, resolveSketch as L, SketchValidationError as M, arcLength as N, segmentGraphemes as O, flatten as P, matEquals as Q, roughen as R, breakLines as S, isEstimatingMeasurer as T, createDisplayListBuilder as U, validateSketch as V, filtersToCanvasFilter as W, fromTRS as X, applyToPoint as Y, invert as Z, NODE_CONSTRUCTION_PROP_NAMES as _, Path as a, __resetEstimateWarnings as b, Video as c, revealSchedule as d, roundedRectSegs as f, BASE_CONSTRUCTION_PROP_NAMES as g, resolveAnchor as h, ImageNode as i, warnIfEstimating as j, segmentWords as k, coercePathData as l, NodeConstructionError as m, Custom as n, Rect as o, Node as p, collapseReplacer as q, Group as r, Text as s, Circle as t, pathFromSegs as u, isConstructionProp as v, fallbackMeasurer as w, assertFiniteFontSize as x, MEASURE_QUANTUM_PX as y, sketchStrokes as z };

package/dist/scene.js

@@ -1,4 +1,4 @@
-import { C as fallbackMeasurer, H as createDisplayListBuilder, T as measureWrappedText, r as Group, v as isConstructionProp } from "./nodes.js";
+import { E as measureWrappedText, U as createDisplayListBuilder, r as Group, v as isConstructionProp, w as fallbackMeasurer } from "./nodes.js";
 import { bindTimeline, compileTimeline, createPlayhead, evaluateAt, signal } from "@glissade/core";
 //#region src/scene.ts
 /**

package/dist/tokens.js

@@ -1,4 +1,4 @@
-import { Z as matEquals, f as roundedRectSegs, p as Node, q as IDENTITY } from "./nodes.js";
+import { J as IDENTITY, Q as matEquals, f as roundedRectSegs, p as Node } from "./nodes.js";
 import { signal, vec2Signal } from "@glissade/core";
 //#region src/tokenHighlight.ts
 /**

package/dist/type.js

@@ -1,4 +1,4 @@
-import { A as warnIfEstimating, C as fallbackMeasurer, E as quantize, r as Group, s as Text } from "./nodes.js";
+import { D as quantize, j as warnIfEstimating, r as Group, s as Text, w as fallbackMeasurer } from "./nodes.js";
 //#region src/type.ts
 /**
 * `@glissade/scene/type` — `splitText()`: build-time split-text sub-targets

package/package.json

@@ -1,13 +1,15 @@
 {
   "name": "@glissade/scene",
-  "version": "0.23.0",
+  "version": "0.24.0-pre.1",
   "description": "glissade scene graph: nodes, transforms, DisplayList emission. Renderer-agnostic; zero DOM/Node dependencies.",
   "license": "Apache-2.0",
   "engines": {
     "node": ">=20.19"
   },
   "type": "module",
-  "sideEffects": false,
+  "sideEffects": [
+    "./dist/examples.js"
+  ],
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -52,6 +54,10 @@
     "./identity": {
       "types": "./dist/identity.d.ts",
       "default": "./dist/identity.js"
+    },
+    "./examples": {
+      "types": "./dist/examples.d.ts",
+      "default": "./dist/examples.js"
     }
   },
   "files": [
@@ -59,7 +65,7 @@
   ],
   "dependencies": {
     "yoga-layout": "^3.2.1",
-    "@glissade/core": "0.23.0"
+    "@glissade/core": "0.24.0-pre.1"
   },
   "repository": {
     "type": "git",