@glissade/scene 0.8.1 → 0.9.0-pre.1

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import { $ as quantize, A as ResolvedSketch, B as validateSketch, C as VideoProps, Ct as applyToPoint, D as roundedRectSegs, Dt as multiply, E as revealSchedule, Et as matEquals, F as hachureLines, G as Node, H as BindablePropTarget, I as resolveSketch, J as resolveAnchor, K as NodeProps, L as roughen, M as SketchValidationError, N as arcLength, O as HachureSpec, P as flatten, Q as estimatingMeasurer, R as sketchStrokes, S as Video, St as Mat2x3, T as pathFromSegs, Tt as invert, U as EvalContext, V as AnchorSpec, W as HitArea, X as TextMetricsLite, Y as TextMeasurer, Z as breakLines, _ as Rect, _t as createDisplayListBuilder, a as LayoutEngineMissingError, at as DisplayListBuilder, b as Text, bt as validateFilters, c as requireLayoutEngine, ct as FilterValidationError, d as Group, dt as PathSeg, et as segmentGraphemes, f as ImageNode, ft as Rect$1, g as PathProps, gt as StrokeStyle, h as Path, ht as ShaderRef, i as LayoutEngine, it as DisplayList, j as SketchStyle, k as Polyline, l as setLayoutEngine, lt as FontSpec, m as LineBox, mt as ResourceId, n as LayoutChildSpec, nt as setDefaultMeasurer, ot as DrawCommand, p as ImageProps, pt as Resource, q as PropInit, r as LayoutContainerSpec, rt as BlendMode, s as getLayoutEngine, st as FilterSpec, t as LayoutBox, tt as segmentWords, u as Circle, ut as Paint, v as RevealMark, vt as filtersToCanvasFilter, w as WordBox, wt as fromTRS, x as TextProps, xt as IDENTITY, y as ShapeProps, yt as glow, z as validateHachure } from "./layoutEngine.js";
-import { BindableSignal, BoundTimeline, CompiledTimeline, EaseSpec, PathValue, Playhead, Timeline, Track, Vec2 } from "@glissade/core";
+import { BindableSignal, BoundTimeline, CompiledTimeline, CoverageReport, EaseSpec, FontMode, FontUsage, PathValue, Playhead, Timeline, Track, Vec2 } from "@glissade/core";
 
 //#region src/highlight.d.ts
 
@@ -183,6 +183,9 @@ interface Scene {
 declare class DuplicateNodeIdError extends Error {
   constructor(id: string);
 }
+declare class ReservedNodeIdError extends Error {
+  constructor(id: string);
+}
 interface SceneInit {
   size: {
     w: number;
@@ -396,6 +399,29 @@ declare class TokenHighlight extends Node {
  */
 declare function tokenHighlight(text: Text, props: Omit<TokenHighlightProps, 'text'>): TokenHighlight;
 //#endregion
+//#region src/fontUsage.d.ts
+/** Walk `scene` for Text nodes; one usage per node carrying its full text. */
+declare function collectTextUsages(scene: Scene): FontUsage[];
+/**
+ * Caller-supplied I/O: fetch the raw bytes for a font face URL (the export
+ * paths read a file / fetch a URL; this keeps core pure). Returning undefined
+ * means "could not load" — that family contributes no coverage, surfacing as
+ * missing glyphs (strict) / a dev warning, never a hang.
+ */
+type FontByteLoader = (url: string) => Promise<ArrayBuffer | undefined>;
+interface ValidateSceneFontsOptions {
+  mode?: FontMode;
+  /** OS-installed families to treat as registered (case-insensitive). */
+  osFamilies?: ReadonlySet<string> | undefined;
+}
+/**
+ * Run §3.6 font validation for a scene + its timeline document. Builds the
+ * registry from `doc.assets`, loads each registered face's cmap via `loadBytes`
+ * (once per family — the first face's URL is enough for coverage), and runs the
+ * pure `validateFonts`. Strict mode throws FontValidationError; dev warns.
+ */
+declare function validateSceneFonts(scene: Scene, doc: Timeline, loadBytes: FontByteLoader, options?: ValidateSceneFontsOptions): Promise<CoverageReport>;
+//#endregion
 //#region src/shaderEffect.d.ts
 interface ShaderEffectProps extends NodeProps {
   children?: Node[];
@@ -503,4 +529,4 @@ declare class Raster2D<TCanvas extends CanvasLike, TPath extends PathLike, TDraw
   render(target: TCanvas, list: DisplayList): void;
 }
 //#endregion
-export { ALL_FILTER_KINDS, type AnchorSpec, type BackendCaps, type BindablePropTarget, type BlendMode, type CacheColdResult, type CanvasLike, Circle, ColdAssetError, type Ctx2DLike, DeterminismViolationError, type DisplayList, type DisplayListBuilder, type DrawCommand, type DrawOnEachOptions, type DrawOnOptions, DuplicateNodeIdError, type EditMark, type EvalContext, type FilterKind, type FilterSpec, FilterValidationError, FollowPath, type FollowPathProps, type FontSpec, Group, type GuardMode, type HachureSpec, Highlight, type HighlightProps, type HitArea, IDENTITY, type ImageHandle, ImageNode, type ImageProps, type LayoutBox, type LayoutChildSpec, type LayoutContainerSpec, type LayoutEngine, LayoutEngineMissingError, type LineBox, type Mat2x3, Node, type NodeProps, type Paint, Path, type PathLike, type PathProps, type PathSampler, type PathSeg, type Polyline, type PropInit, Raster2D, type Raster2DHost, Rect, type Rect$1 as RectShape, type RenderBackend, 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, TokenHighlight, type TokenHighlightProps, TokenMatchError, type TokenRange, type TypeEdit, type TypewriterResult, Video, type VideoFrameSource, type VideoProps, type WordBox, applyToPoint, arcLength, auditCacheCold, bindScene, breakLines, createDisplayListBuilder, createScene, drawOn, drawOnEach, estimatingMeasurer, evaluate, filtersToCanvasFilter, flatten, followPath, fontString, fromTRS, getLayoutEngine, glow, hachureLines, highlight, invert, matEquals, matchTokenRun, motionPath, multiply, pathFromSegs, pathLength, pointAtLength, quantize, requireLayoutEngine, resolveAnchor, resolveSketch, revealSchedule, roughen, roundedRectSegs, segmentGraphemes, segmentWords, setDefaultMeasurer, setLayoutEngine, sketchStrokes, textCursor, tokenHighlight, typewriter, validateFilters, validateHachure, validateSketch, withDeterminismGuards };
+export { ALL_FILTER_KINDS, type AnchorSpec, type BackendCaps, type BindablePropTarget, type BlendMode, type CacheColdResult, type CanvasLike, Circle, ColdAssetError, type Ctx2DLike, DeterminismViolationError, type DisplayList, type DisplayListBuilder, type DrawCommand, type DrawOnEachOptions, type DrawOnOptions, DuplicateNodeIdError, type EditMark, type EvalContext, type FilterKind, type FilterSpec, FilterValidationError, FollowPath, type FollowPathProps, type FontByteLoader, type FontSpec, Group, type GuardMode, type HachureSpec, Highlight, type HighlightProps, type HitArea, IDENTITY, type ImageHandle, ImageNode, type ImageProps, type LayoutBox, type LayoutChildSpec, type LayoutContainerSpec, type LayoutEngine, LayoutEngineMissingError, type LineBox, type Mat2x3, Node, type NodeProps, type Paint, Path, type PathLike, type PathProps, type PathSampler, type PathSeg, 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, TokenHighlight, type TokenHighlightProps, TokenMatchError, type TokenRange, type TypeEdit, type TypewriterResult, type ValidateSceneFontsOptions, Video, type VideoFrameSource, type VideoProps, type WordBox, applyToPoint, arcLength, auditCacheCold, bindScene, breakLines, collectTextUsages, createDisplayListBuilder, createScene, drawOn, drawOnEach, estimatingMeasurer, evaluate, filtersToCanvasFilter, flatten, followPath, fontString, fromTRS, getLayoutEngine, glow, hachureLines, highlight, invert, matEquals, matchTokenRun, motionPath, multiply, pathFromSegs, pathLength, pointAtLength, quantize, requireLayoutEngine, resolveAnchor, resolveSketch, revealSchedule, roughen, roundedRectSegs, segmentGraphemes, segmentWords, setDefaultMeasurer, setLayoutEngine, sketchStrokes, textCursor, tokenHighlight, typewriter, validateFilters, validateHachure, validateSceneFonts, validateSketch, withDeterminismGuards };

package/dist/index.js

@@ -1,5 +1,5 @@
 import { A as segmentGraphemes, B as fromTRS, C as validateSketch, D as estimatingMeasurer, E as breakLines, F as filtersToCanvasFilter, H as matEquals, I as glow, L as validateFilters, M as setDefaultMeasurer, N as FilterValidationError, O as fallbackMeasurer, P as createDisplayListBuilder, R as IDENTITY, S as validateHachure, T as resolveAnchor, U as multiply, V as invert, _ as flatten, a as Circle, b as roughen, c as Path, d as Video, f as pathFromSegs, g as arcLength, h as SketchValidationError, i as setLayoutEngine, j as segmentWords, k as quantize, l as Rect, m as roundedRectSegs, n as getLayoutEngine, o as Group, p as revealSchedule, r as requireLayoutEngine, s as ImageNode, t as LayoutEngineMissingError, u as Text, v as hachureLines, w as Node, x as sketchStrokes, y as resolveSketch, z as applyToPoint } from "./layoutEngine.js";
-import { bindTimeline, compileTimeline, createPlayhead, emitDevWarning, evaluateAt, key, signal, stagger, track, vec2Signal } from "@glissade/core";
+import { bindTimeline, buildFontRegistry, compileTimeline, createPlayhead, emitDevWarning, evaluateAt, key, parseCmap, signal, stagger, track, validateFonts, vec2Signal } from "@glissade/core";
 //#region src/highlight.ts
 /**
 * Marker-style text highlight: per-line rounded rects behind a Text node's
@@ -349,9 +349,16 @@ var DuplicateNodeIdError = class extends Error {
 		this.name = "DuplicateNodeIdError";
 	}
 };
+var ReservedNodeIdError = class extends Error {
+	constructor(id) {
+		super(`node id '${id}' uses the reserved '~' prefix — that namespace is for structural fallback ids (§6.5), which are inspection-only and never track targets; choose another id`);
+		this.name = "ReservedNodeIdError";
+	}
+};
 function indexNodes(root, into, measurerSource) {
 	root.measurerSource = measurerSource;
 	if (root.id !== void 0) {
+		if (root.id.startsWith("~")) throw new ReservedNodeIdError(root.id);
 		if (into.has(root.id)) throw new DuplicateNodeIdError(root.id);
 		into.set(root.id, root);
 	}
@@ -849,6 +856,55 @@ function initVec(sig, v) {
 	return sig;
 }
 //#endregion
+//#region src/fontUsage.ts
+/**
+* Scene → font-validation bridge (DESIGN.md §3.6). Core owns the AssetRef,
+* FontRegistry, cmap reader, and the pure validation; this module owns the
+* node-walk (which only `scene` can do) and the I/O seam that loads a font
+* face's bytes so core stays DOM/Node-free.
+*
+* `collectTextUsages` walks every Text node and reads the FULL `.text()` (not
+* the reveal-masked prefix) — coverage is a property of the authored content,
+* independent of the playhead, so it stays out of the pure evaluate() path.
+*/
+/** Walk `scene` for Text nodes; one usage per node carrying its full text. */
+function collectTextUsages(scene) {
+	const out = [];
+	const visit = (node) => {
+		if (node instanceof Text) {
+			const text = node.text();
+			if (text) out.push({
+				family: node.fontFamily,
+				text
+			});
+		}
+		if (node instanceof Group) for (const child of node.children) visit(child);
+	};
+	visit(scene.root);
+	return out;
+}
+/**
+* Run §3.6 font validation for a scene + its timeline document. Builds the
+* registry from `doc.assets`, loads each registered face's cmap via `loadBytes`
+* (once per family — the first face's URL is enough for coverage), and runs the
+* pure `validateFonts`. Strict mode throws FontValidationError; dev warns.
+*/
+async function validateSceneFonts(scene, doc, loadBytes, options = {}) {
+	const mode = options.mode ?? "dev";
+	const registry = buildFontRegistry(doc.assets);
+	const usages = collectTextUsages(scene);
+	const wanted = /* @__PURE__ */ new Set();
+	for (const u of usages) if (registry.has(u.family)) for (const f of registry.fallbackChain(u.family)) wanted.add(f);
+	const cmaps = /* @__PURE__ */ new Map();
+	for (const family of wanted) {
+		const face = registry.resolveFace(family);
+		if (!face) continue;
+		const bytes = await loadBytes(face.url);
+		if (bytes) cmaps.set(family, parseCmap(bytes));
+	}
+	return validateFonts(usages, registry, cmaps, mode, { ...options.osFamilies !== void 0 ? { osFamilies: options.osFamilies } : {} });
+}
+//#endregion
 //#region src/assets.ts
 var ColdAssetError = class extends Error {
 	assetId;
@@ -1254,4 +1310,4 @@ var Raster2D = class {
 	}
 };
 //#endregion
-export { ALL_FILTER_KINDS, Circle, ColdAssetError, DeterminismViolationError, DuplicateNodeIdError, FilterValidationError, FollowPath, Group, Highlight, IDENTITY, ImageNode, LayoutEngineMissingError, Node, Path, Raster2D, Rect, ShaderEffect, SketchValidationError, Text, TextCursor, TokenHighlight, TokenMatchError, Video, applyToPoint, arcLength, auditCacheCold, bindScene, breakLines, createDisplayListBuilder, createScene, drawOn, drawOnEach, estimatingMeasurer, evaluate, filtersToCanvasFilter, flatten, followPath, fontString, fromTRS, getLayoutEngine, glow, hachureLines, highlight, invert, matEquals, matchTokenRun, motionPath, multiply, pathFromSegs, pathLength, pointAtLength, quantize, requireLayoutEngine, resolveAnchor, resolveSketch, revealSchedule, roughen, roundedRectSegs, segmentGraphemes, segmentWords, setDefaultMeasurer, setLayoutEngine, sketchStrokes, textCursor, tokenHighlight, typewriter, validateFilters, validateHachure, validateSketch, withDeterminismGuards };
+export { ALL_FILTER_KINDS, Circle, ColdAssetError, DeterminismViolationError, DuplicateNodeIdError, FilterValidationError, FollowPath, Group, Highlight, IDENTITY, ImageNode, LayoutEngineMissingError, Node, Path, Raster2D, Rect, ReservedNodeIdError, ShaderEffect, SketchValidationError, Text, TextCursor, TokenHighlight, TokenMatchError, Video, applyToPoint, arcLength, auditCacheCold, bindScene, breakLines, collectTextUsages, createDisplayListBuilder, createScene, drawOn, drawOnEach, estimatingMeasurer, evaluate, filtersToCanvasFilter, flatten, followPath, fontString, fromTRS, getLayoutEngine, glow, hachureLines, highlight, invert, matEquals, matchTokenRun, motionPath, multiply, pathFromSegs, pathLength, pointAtLength, quantize, requireLayoutEngine, resolveAnchor, resolveSketch, revealSchedule, roughen, roundedRectSegs, segmentGraphemes, segmentWords, setDefaultMeasurer, setLayoutEngine, sketchStrokes, textCursor, tokenHighlight, typewriter, validateFilters, validateHachure, validateSceneFonts, validateSketch, withDeterminismGuards };

package/dist/layoutEngine.d.ts

@@ -622,6 +622,8 @@ interface TextProps extends NodeProps {
   fontFamily?: string;
   fontSize?: PropInit<number>;
   fontWeight?: number;
+  /** Font style; default 'normal'. Threaded into FontSpec.style (§3.6). */
+  fontStyle?: 'normal' | 'italic';
   /** Horizontal alignment about the node position; default 'left'. */
   align?: 'left' | 'center' | 'right';
   /** Wrap width in px; unset = no wrapping (explicit \n still breaks). */
@@ -642,6 +644,7 @@ declare class Text extends Node {
   readonly fontSize: BindableSignal<number>;
   readonly fontFamily: string;
   readonly fontWeight: number;
+  readonly fontStyle: 'normal' | 'italic';
   readonly align: 'left' | 'center' | 'right';
   readonly width: BindableSignal<number>;
   readonly lineHeight: number;

package/dist/layoutEngine.js

@@ -1363,6 +1363,7 @@ var Text = class extends Node {
 	fontSize;
 	fontFamily;
 	fontWeight;
+	fontStyle;
 	align;
 	width;
 	lineHeight;
@@ -1374,6 +1375,7 @@ var Text = class extends Node {
 		this.fontSize = initProp(signal(16), props.fontSize);
 		this.fontFamily = props.fontFamily ?? "sans-serif";
 		this.fontWeight = props.fontWeight ?? 400;
+		this.fontStyle = props.fontStyle ?? "normal";
 		this.align = props.align ?? "left";
 		this.width = initProp(signal(0), props.width);
 		this.lineHeight = props.lineHeight ?? 1.25;
@@ -1393,7 +1395,8 @@ var Text = class extends Node {
 		const font = {
 			family: this.fontFamily,
 			size: this.fontSize(),
-			weight: this.fontWeight
+			weight: this.fontWeight,
+			...this.fontStyle === "italic" ? { style: "italic" } : {}
 		};
 		const maxWidth = this.width();
 		const lines = breakLines(text, font, maxWidth > 0 ? maxWidth : void 0, measurer);
@@ -1410,7 +1413,8 @@ var Text = class extends Node {
 		const font = {
 			family: this.fontFamily,
 			size: this.fontSize(),
-			weight: this.fontWeight
+			weight: this.fontWeight,
+			...this.fontStyle === "italic" ? { style: "italic" } : {}
 		};
 		const firstLine = breakLines(this.text(), font, this.width() > 0 ? this.width() : void 0, m)[0] ?? "";
 		const ascent = m.measureText(firstLine, font).ascent;
@@ -1441,7 +1445,8 @@ var Text = class extends Node {
 		const font = {
 			family: this.fontFamily,
 			size: this.fontSize(),
-			weight: this.fontWeight
+			weight: this.fontWeight,
+			...this.fontStyle === "italic" ? { style: "italic" } : {}
 		};
 		const maxWidth = this.width();
 		const lines = breakLines(text, font, maxWidth > 0 ? maxWidth : void 0, m);
@@ -1478,7 +1483,8 @@ var Text = class extends Node {
 		const font = {
 			family: this.fontFamily,
 			size: this.fontSize(),
-			weight: this.fontWeight
+			weight: this.fontWeight,
+			...this.fontStyle === "italic" ? { style: "italic" } : {}
 		};
 		const maxWidth = this.width();
 		const lines = breakLines(text, font, maxWidth > 0 ? maxWidth : void 0, m);
@@ -1531,7 +1537,8 @@ var Text = class extends Node {
 		const font = {
 			family: this.fontFamily,
 			size: this.fontSize(),
-			weight: this.fontWeight
+			weight: this.fontWeight,
+			...this.fontStyle === "italic" ? { style: "italic" } : {}
 		};
 		const maxWidth = this.width();
 		const lines = breakLines(text, font, maxWidth > 0 ? maxWidth : void 0, m);
@@ -1550,7 +1557,8 @@ var Text = class extends Node {
 		const font = {
 			family: this.fontFamily,
 			size: this.fontSize(),
-			weight: this.fontWeight
+			weight: this.fontWeight,
+			...this.fontStyle === "italic" ? { style: "italic" } : {}
 		};
 		const maxWidth = this.width();
 		const lines = breakLines(this.text(), font, maxWidth > 0 ? maxWidth : void 0, m);
@@ -1598,7 +1606,8 @@ var Text = class extends Node {
 		const font = {
 			family: this.fontFamily,
 			size: this.fontSize(),
-			weight: this.fontWeight
+			weight: this.fontWeight,
+			...this.fontStyle === "italic" ? { style: "italic" } : {}
 		};
 		const maxWidth = this.width();
 		const lines = breakLines(text, font, maxWidth > 0 ? maxWidth : void 0, ctx.measurer);
@@ -1673,7 +1682,8 @@ function revealSchedule(text, reveal, measurer) {
 	const font = {
 		family: text.fontFamily,
 		size: text.fontSize(),
-		weight: text.fontWeight
+		weight: text.fontWeight,
+		...text.fontStyle === "italic" ? { style: "italic" } : {}
 	};
 	const maxWidth = text.width();
 	const lines = breakLines(src, font, maxWidth > 0 ? maxWidth : void 0, m);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@glissade/scene",
-  "version": "0.8.1",
+  "version": "0.9.0-pre.1",
   "description": "glissade scene graph: nodes, transforms, DisplayList emission. Renderer-agnostic; zero DOM/Node dependencies.",
   "license": "Apache-2.0",
   "type": "module",
@@ -20,7 +20,7 @@
   ],
   "dependencies": {
     "yoga-layout": "^3.2.1",
-    "@glissade/core": "0.8.1"
+    "@glissade/core": "0.9.0-pre.1"
   },
   "repository": {
     "type": "git",