@glissade/scene 0.9.1-pre.0 → 0.10.0-pre.0

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-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 { $ as estimatingMeasurer, A as ResolvedSketch, B as validateSketch, C as VideoProps, Ct as Mat2x3, D as roundedRectSegs, Dt as matEquals, E as revealSchedule, Et as invert, 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, Ot as multiply, P as flatten, Q as breakLines, R as sketchStrokes, S as Video, St as IDENTITY, T as pathFromSegs, Tt as fromTRS, U as EvalContext, V as AnchorSpec, W as HitArea, X as TextMeasurer, Y as MEASURE_QUANTUM_PX, Z as TextMetricsLite, _ as Rect, _t as StrokeStyle, a as LayoutEngineMissingError, at as DisplayList, b as Text, bt as glow, c as requireLayoutEngine, ct as FilterSpec, d as Group, dt as Paint, et as quantize, f as ImageNode, ft as PathSeg, g as PathProps, gt as ShaderRef, h as Path, ht as ResourceId, i as LayoutEngine, it as BlendMode, j as SketchStyle, k as Polyline, l as setLayoutEngine, lt as FilterValidationError, m as LineBox, mt as Resource, n as LayoutChildSpec, nt as segmentWords, ot as DisplayListBuilder, p as ImageProps, pt as Rect$1, q as PropInit, r as LayoutContainerSpec, rt as setDefaultMeasurer, s as getLayoutEngine, st as DrawCommand, t as LayoutBox, tt as segmentGraphemes, u as Circle, ut as FontSpec, v as RevealMark, vt as createDisplayListBuilder, w as WordBox, wt as applyToPoint, x as TextProps, xt as validateFilters, y as ShapeProps, yt as filtersToCanvasFilter, z as validateHachure } from "./layoutEngine.js";
 import { BindableSignal, BoundTimeline, CompiledTimeline, CoverageReport, EaseSpec, FontMode, FontUsage, PathValue, Playhead, Timeline, Track, Vec2 } from "@glissade/core";
 
 //#region src/highlight.d.ts
@@ -512,8 +512,22 @@ declare class Raster2D<TCanvas extends CanvasLike, TPath extends PathLike, TDraw
   private readonly images;
   private readonly videos;
   private warnedShaders;
+  /**
+   * §3.5 bitmap LRU: device-transform-qualified cacheKey → rasterized layer.
+   * A Map preserves insertion order, so the oldest key is `keys().next()` —
+   * touch-on-hit by delete+set keeps it a true LRU. Disabled (stays empty) when
+   * `cacheEnabled` is false, so cache-cold === cache-warm is testable directly.
+   */
+  private readonly rasterCache;
+  private readonly cacheEnabled;
   constructor(host: Raster2DHost<TCanvas, TPath, TDrawable>, /** caps.shaders (§3.7): what happens when a shader can't run here. */
-  shaderCaps?: ShaderCaps);
+  shaderCaps?: ShaderCaps,
+  /**
+   * §3.5: opt-OUT switch for the bitmap LRU. Defaults on, but the env var
+   * RASTER_CACHE=0 force-disables it (the equality test renders both ways).
+   * A disabled cache is byte-identical — it just always takes the miss path.
+   */
+  cacheEnabled?: boolean);
   /** Register a decoded still (kind 'image' assets). */
   setImageAsset(assetId: string, image: TDrawable): void;
   /** Register a warmed-on-demand video source (kind 'video' assets, §3.8). */
@@ -525,8 +539,23 @@ declare class Raster2D<TCanvas extends CanvasLike, TPath extends PathLike, TDraw
   private buildPath;
   private acquire;
   private release;
+  /**
+   * §3.5 LRU insert with touch-on-hit + eviction-to-pool. Storing under a key
+   * that already holds a (different) canvas releases the old one first.
+   */
+  private cacheStore;
+  private cacheTouch;
+  /**
+   * §3.4/§3.5 composite of a finished group layer onto its parent — the EXACT
+   * same save/resetTransform/clip/globalAlpha/filter/blend/drawImage sequence
+   * for both the freshly-rasterized miss path and a cache-blit hit, so a HIT is
+   * byte-identical to a MISS. `bounds`/`unbounded` come from the layer (miss) or
+   * the cache entry (hit); the composite params (opacity/blend/filters) always
+   * come from the LIVE pushGroup command, never the cache.
+   */
+  private composite;
   /** The command walk — order and operations identical to the pre-extraction twins. */
   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 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 };
+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, MEASURE_QUANTUM_PX, 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,4 +1,4 @@
-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 { A as quantize, B as applyToPoint, C as validateSketch, D as breakLines, E as MEASURE_QUANTUM_PX, F as createDisplayListBuilder, H as invert, I as filtersToCanvasFilter, L as glow, M as segmentWords, N as setDefaultMeasurer, O as estimatingMeasurer, P as FilterValidationError, R as validateFilters, S as validateHachure, T as resolveAnchor, U as matEquals, V as fromTRS, W as multiply, _ 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 segmentGraphemes, k as fallbackMeasurer, 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 IDENTITY } from "./layoutEngine.js";
 import { bindTimeline, buildFontRegistry, compileTimeline, createPlayhead, emitDevWarning, evaluateAt, key, parseCmap, signal, stagger, track, validateFonts, vec2Signal } from "@glissade/core";
 //#region src/highlight.ts
 /**
@@ -970,6 +970,21 @@ var ShaderEffect = class extends Group {
 function fontString(font) {
 	return `${font.style === "italic" ? "italic " : ""}${font.weight !== void 0 && font.weight !== 400 ? `${font.weight} ` : ""}${font.size}px ${font.family}`;
 }
+/** Hardcoded LRU cap (§3.5). Evicted canvases return to the raster pool. */
+const RASTER_CACHE_CAP = 16;
+/**
+* Round a device-transform component into the cache key. The layer bakes the
+* parent CTM into its pixels, so two frames that share a cacheKey but differ in
+* device transform are NOT interchangeable — they must key separately. Rounding
+* to 1e-4 collapses float jitter from matrix re-multiplication of an unchanged
+* transform (so a genuinely static parent HITs) while keeping any visible move
+* to a distinct key (so a stale-CTM bitmap can never blit). The float is taken
+* verbatim into the string — no lossy truncation that could alias two CTMs.
+*/
+function transformKey(m) {
+	const q = (v) => Object.is(v, -0) ? "0" : String(Math.round(v * 1e4) / 1e4);
+	return `${q(m[0])},${q(m[1])},${q(m[2])},${q(m[3])},${q(m[4])},${q(m[5])}`;
+}
 /**
 * How far a filter chain can paint beyond its input (device px). Each stage
 * feeds the next, so outsets ADD. Gaussian reach: Skia truncates at 3σ and
@@ -1042,9 +1057,18 @@ var Raster2D = class {
 	images = /* @__PURE__ */ new Map();
 	videos = /* @__PURE__ */ new Map();
 	warnedShaders = false;
-	constructor(host, shaderCaps = "warn") {
+	/**
+	* §3.5 bitmap LRU: device-transform-qualified cacheKey → rasterized layer.
+	* A Map preserves insertion order, so the oldest key is `keys().next()` —
+	* touch-on-hit by delete+set keeps it a true LRU. Disabled (stays empty) when
+	* `cacheEnabled` is false, so cache-cold === cache-warm is testable directly.
+	*/
+	rasterCache = /* @__PURE__ */ new Map();
+	cacheEnabled;
+	constructor(host, shaderCaps = "warn", cacheEnabled = (globalThis.process?.env?.["RASTER_CACHE"] ?? "1") !== "0") {
 		this.host = host;
 		this.shaderCaps = shaderCaps;
+		this.cacheEnabled = cacheEnabled;
 	}
 	/** Register a decoded still (kind 'image' assets). */
 	setImageAsset(assetId, image) {
@@ -1056,6 +1080,7 @@ var Raster2D = class {
 	}
 	dispose() {
 		this.pool.length = 0;
+		this.rasterCache.clear();
 	}
 	resolveDrawable(res, id) {
 		if (res.kind === "image") {
@@ -1127,6 +1152,73 @@ var Raster2D = class {
 	release(canvas) {
 		if (this.pool.length < 8) this.pool.push(canvas);
 	}
+	/**
+	* §3.5 LRU insert with touch-on-hit + eviction-to-pool. Storing under a key
+	* that already holds a (different) canvas releases the old one first.
+	*/
+	cacheStore(key, entry) {
+		const prior = this.rasterCache.get(key);
+		if (prior) {
+			this.rasterCache.delete(key);
+			if (prior.canvas !== entry.canvas) this.release(prior.canvas);
+		}
+		this.rasterCache.set(key, entry);
+		while (this.rasterCache.size > RASTER_CACHE_CAP) {
+			const oldest = this.rasterCache.keys().next().value;
+			if (oldest === void 0) break;
+			const evicted = this.rasterCache.get(oldest);
+			this.rasterCache.delete(oldest);
+			this.release(evicted.canvas);
+		}
+	}
+	cacheTouch(key) {
+		const hit = this.rasterCache.get(key);
+		if (hit) {
+			this.rasterCache.delete(key);
+			this.rasterCache.set(key, hit);
+		}
+		return hit;
+	}
+	/**
+	* §3.4/§3.5 composite of a finished group layer onto its parent — the EXACT
+	* same save/resetTransform/clip/globalAlpha/filter/blend/drawImage sequence
+	* for both the freshly-rasterized miss path and a cache-blit hit, so a HIT is
+	* byte-identical to a MISS. `bounds`/`unbounded` come from the layer (miss) or
+	* the cache entry (hit); the composite params (opacity/blend/filters) always
+	* come from the LIVE pushGroup command, never the cache.
+	*/
+	composite(parent, parentLayer, drawable, bounds, unbounded, shaderReplaced, opacity, blend, filter, filters, w, h) {
+		const hasFilter = filter !== void 0 && filter !== "none";
+		const outset = hasFilter ? filterOutset(filters) : 0;
+		if (unbounded || blend !== "source-over") parentLayer.unbounded = true;
+		else if (bounds) accumulateRect(parentLayer, IDENTITY, bounds.minX - outset, bounds.minY - outset, bounds.maxX + outset, bounds.maxY + outset);
+		const clippable = hasFilter && !shaderReplaced && !unbounded && blend === "source-over";
+		if (clippable && bounds === null) return;
+		parent.save();
+		parent.resetTransform();
+		if (clippable && bounds) {
+			const x0 = Math.max(0, Math.floor(bounds.minX - outset));
+			const y0 = Math.max(0, Math.floor(bounds.minY - outset));
+			const x1 = Math.min(w, Math.ceil(bounds.maxX + outset));
+			const y1 = Math.min(h, Math.ceil(bounds.maxY + outset));
+			if (x0 >= x1 || y0 >= y1) {
+				parent.restore();
+				return;
+			}
+			const clip = this.host.newPath();
+			clip.moveTo(x0, y0);
+			clip.lineTo(x1, y0);
+			clip.lineTo(x1, y1);
+			clip.lineTo(x0, y1);
+			clip.closePath();
+			parent.clip(clip, "nonzero");
+		}
+		parent.globalAlpha = opacity;
+		if (hasFilter) parent.filter = filter;
+		parent.globalCompositeOperation = blend;
+		parent.drawImage(drawable, 0, 0);
+		parent.restore();
+	}
 	/** The command walk — order and operations identical to the pre-extraction twins. */
 	render(target, list) {
 		const { w, h } = list.size;
@@ -1147,167 +1239,157 @@ var Raster2D = class {
 		const top = () => layers[layers.length - 1];
 		let mat = IDENTITY;
 		const matStack = [];
-		for (const cmd of list.commands) switch (cmd.op) {
-			case "save":
-				matStack.push(mat);
-				ctxOf().save();
-				break;
-			case "restore":
-				mat = matStack.pop() ?? mat;
-				ctxOf().restore();
-				break;
-			case "transform":
-				mat = multiply(mat, cmd.m);
-				ctxOf().transform(cmd.m[0], cmd.m[1], cmd.m[2], cmd.m[3], cmd.m[4], cmd.m[5]);
-				break;
-			case "clip":
-				ctxOf().clip(this.path(list.resources, cmd.path), cmd.rule ?? "nonzero");
-				break;
-			case "fillPath": {
-				const ctx = ctxOf();
-				ctx.fillStyle = cmd.paint.color;
-				ctx.fill(this.path(list.resources, cmd.path));
-				const b = this.pathBounds(list.resources, cmd.path);
-				if (b) accumulateRect(top(), mat, b.minX, b.minY, b.maxX, b.maxY);
-				break;
-			}
-			case "strokePath": {
-				const ctx = ctxOf();
-				ctx.strokeStyle = cmd.paint.color;
-				ctx.lineWidth = cmd.stroke.width;
-				ctx.lineCap = cmd.stroke.cap ?? "butt";
-				ctx.lineJoin = cmd.stroke.join ?? "miter";
-				if (cmd.stroke.dash) {
-					ctx.setLineDash(cmd.stroke.dash);
-					ctx.lineDashOffset = cmd.stroke.dashOffset ?? 0;
+		const commands = list.commands;
+		for (let ci = 0; ci < commands.length; ci++) {
+			const cmd = commands[ci];
+			switch (cmd.op) {
+				case "save":
+					matStack.push(mat);
+					ctxOf().save();
+					break;
+				case "restore":
+					mat = matStack.pop() ?? mat;
+					ctxOf().restore();
+					break;
+				case "transform":
+					mat = multiply(mat, cmd.m);
+					ctxOf().transform(cmd.m[0], cmd.m[1], cmd.m[2], cmd.m[3], cmd.m[4], cmd.m[5]);
+					break;
+				case "clip":
+					ctxOf().clip(this.path(list.resources, cmd.path), cmd.rule ?? "nonzero");
+					break;
+				case "fillPath": {
+					const ctx = ctxOf();
+					ctx.fillStyle = cmd.paint.color;
+					ctx.fill(this.path(list.resources, cmd.path));
+					const b = this.pathBounds(list.resources, cmd.path);
+					if (b) accumulateRect(top(), mat, b.minX, b.minY, b.maxX, b.maxY);
+					break;
 				}
-				ctx.stroke(this.path(list.resources, cmd.path));
-				if (cmd.stroke.dash) {
-					ctx.setLineDash([]);
-					ctx.lineDashOffset = 0;
+				case "strokePath": {
+					const ctx = ctxOf();
+					ctx.strokeStyle = cmd.paint.color;
+					ctx.lineWidth = cmd.stroke.width;
+					ctx.lineCap = cmd.stroke.cap ?? "butt";
+					ctx.lineJoin = cmd.stroke.join ?? "miter";
+					if (cmd.stroke.dash) {
+						ctx.setLineDash(cmd.stroke.dash);
+						ctx.lineDashOffset = cmd.stroke.dashOffset ?? 0;
+					}
+					ctx.stroke(this.path(list.resources, cmd.path));
+					if (cmd.stroke.dash) {
+						ctx.setLineDash([]);
+						ctx.lineDashOffset = 0;
+					}
+					const b = this.pathBounds(list.resources, cmd.path);
+					if (b) {
+						const o = cmd.stroke.width * ((cmd.stroke.join ?? "miter") === "miter" ? 5 : 1);
+						accumulateRect(top(), mat, b.minX - o, b.minY - o, b.maxX + o, b.maxY + o);
+					}
+					break;
 				}
-				const b = this.pathBounds(list.resources, cmd.path);
-				if (b) {
-					const o = cmd.stroke.width * ((cmd.stroke.join ?? "miter") === "miter" ? 5 : 1);
-					accumulateRect(top(), mat, b.minX - o, b.minY - o, b.maxX + o, b.maxY + o);
+				case "fillText": {
+					const ctx = ctxOf();
+					ctx.font = fontString(cmd.font);
+					ctx.fillStyle = cmd.paint.color;
+					ctx.textBaseline = "alphabetic";
+					ctx.textAlign = cmd.align ?? "left";
+					ctx.fillText(cmd.text, cmd.x, cmd.y);
+					try {
+						const width = ctx.measureText(cmd.text).width;
+						const align = cmd.align ?? "left";
+						const x0 = align === "center" ? cmd.x - width / 2 : align === "right" ? cmd.x - width : cmd.x;
+						const m = cmd.font.size;
+						accumulateRect(top(), mat, x0 - m, cmd.y - 1.5 * m, x0 + width + m, cmd.y + .75 * m);
+					} catch {
+						top().unbounded = true;
+					}
+					break;
 				}
-				break;
-			}
-			case "fillText": {
-				const ctx = ctxOf();
-				ctx.font = fontString(cmd.font);
-				ctx.fillStyle = cmd.paint.color;
-				ctx.textBaseline = "alphabetic";
-				ctx.textAlign = cmd.align ?? "left";
-				ctx.fillText(cmd.text, cmd.x, cmd.y);
-				try {
-					const width = ctx.measureText(cmd.text).width;
-					const align = cmd.align ?? "left";
-					const x0 = align === "center" ? cmd.x - width / 2 : align === "right" ? cmd.x - width : cmd.x;
-					const m = cmd.font.size;
-					accumulateRect(top(), mat, x0 - m, cmd.y - 1.5 * m, x0 + width + m, cmd.y + .75 * m);
-				} catch {
-					top().unbounded = true;
+				case "drawImage": {
+					const res = list.resources[cmd.image];
+					if (!res) throw new Error(`drawImage references missing resource ${cmd.image}`);
+					const drawable = this.resolveDrawable(res, cmd.image);
+					const ctx = ctxOf();
+					if (cmd.smoothing !== void 0) ctx.imageSmoothingEnabled = cmd.smoothing;
+					const { x, y, w: dw, h: dh } = cmd.dst;
+					if (cmd.src) ctx.drawImage(drawable, cmd.src.x, cmd.src.y, cmd.src.w, cmd.src.h, x, y, dw, dh);
+					else ctx.drawImage(drawable, x, y, dw, dh);
+					accumulateRect(top(), mat, x, y, x + dw, y + dh);
+					break;
 				}
-				break;
-			}
-			case "drawImage": {
-				const res = list.resources[cmd.image];
-				if (!res) throw new Error(`drawImage references missing resource ${cmd.image}`);
-				const drawable = this.resolveDrawable(res, cmd.image);
-				const ctx = ctxOf();
-				if (cmd.smoothing !== void 0) ctx.imageSmoothingEnabled = cmd.smoothing;
-				const { x, y, w: dw, h: dh } = cmd.dst;
-				if (cmd.src) ctx.drawImage(drawable, cmd.src.x, cmd.src.y, cmd.src.w, cmd.src.h, x, y, dw, dh);
-				else ctx.drawImage(drawable, x, y, dw, dh);
-				accumulateRect(top(), mat, x, y, x + dw, y + dh);
-				break;
-			}
-			case "pushGroup": {
-				const parent = ctxOf();
-				const layerCanvas = this.acquire(w, h);
-				const layerCtx = this.host.context(layerCanvas);
-				layerCtx.resetTransform();
-				layerCtx.clearRect(0, 0, w, h);
-				layerCtx.setTransform(parent.getTransform());
-				layers.push({
-					ctx: layerCtx,
-					canvas: layerCanvas,
-					opacity: cmd.opacity,
-					blend: cmd.blend,
-					filter: filtersToCanvasFilter(cmd.filters),
-					filters: cmd.filters,
-					...cmd.shader !== void 0 ? { shader: cmd.shader } : {},
-					bounds: null,
-					unbounded: false
-				});
-				break;
-			}
-			case "popGroup": {
-				const layer = layers.pop();
-				if (!layer || layer.canvas === null) throw new Error("popGroup without matching pushGroup");
-				const parent = ctxOf();
-				let drawable = layer.canvas;
-				let shaderReplaced = false;
-				if (layer.shader !== void 0) {
-					const replaced = this.host.applyShader?.(layer.canvas, layer.shader, w, h) ?? null;
-					if (replaced !== null) {
-						drawable = replaced;
-						shaderReplaced = true;
-						layer.bounds = {
-							minX: 0,
-							minY: 0,
-							maxX: w,
-							maxY: h
-						};
-						layer.unbounded = false;
-					} else if (this.shaderCaps === "error") throw new Error("a ShaderEffect reached a backend without a shader runner (§3.7) — load @glissade/effects-webgpu in the browser, or accept passthrough with caps.shaders: warn");
-					else if (!this.warnedShaders) {
-						this.warnedShaders = true;
-						emitDevWarning("ShaderEffect pass skipped: no shader runner here (headless or webgpu-less browser) — subtree composites unfiltered (§3.7 caps.shaders)");
+				case "pushGroup": {
+					const parent = ctxOf();
+					const lruKey = this.cacheEnabled && cmd.cacheKey !== void 0 && cmd.shader === void 0 ? `${cmd.cacheKey}@${transformKey(mat)}` : void 0;
+					if (lruKey !== void 0) {
+						const hit = this.cacheTouch(lruKey);
+						if (hit) {
+							this.composite(parent, top(), hit.canvas, hit.bounds, hit.unbounded, false, cmd.opacity, cmd.blend, filtersToCanvasFilter(cmd.filters), cmd.filters, w, h);
+							let depth = 1;
+							while (depth > 0 && ++ci < commands.length) {
+								const c = commands[ci];
+								if (c.op === "pushGroup") depth++;
+								else if (c.op === "popGroup") depth--;
+							}
+							break;
+						}
 					}
-				}
-				const hasFilter = layer.filter !== void 0 && layer.filter !== "none";
-				const outset = hasFilter ? filterOutset(layer.filters) : 0;
-				const parentLayer = top();
-				if (layer.unbounded || layer.blend !== "source-over") parentLayer.unbounded = true;
-				else if (layer.bounds) accumulateRect(parentLayer, IDENTITY, layer.bounds.minX - outset, layer.bounds.minY - outset, layer.bounds.maxX + outset, layer.bounds.maxY + outset);
-				const clippable = hasFilter && !shaderReplaced && !layer.unbounded && layer.blend === "source-over";
-				if (clippable && layer.bounds === null) {
-					this.release(layer.canvas);
+					const layerCanvas = this.acquire(w, h);
+					const layerCtx = this.host.context(layerCanvas);
+					layerCtx.resetTransform();
+					layerCtx.clearRect(0, 0, w, h);
+					layerCtx.setTransform(parent.getTransform());
+					layers.push({
+						ctx: layerCtx,
+						canvas: layerCanvas,
+						opacity: cmd.opacity,
+						blend: cmd.blend,
+						filter: filtersToCanvasFilter(cmd.filters),
+						filters: cmd.filters,
+						...cmd.shader !== void 0 ? { shader: cmd.shader } : {},
+						bounds: null,
+						unbounded: false,
+						...lruKey !== void 0 ? { cacheStoreKey: lruKey } : {}
+					});
 					break;
 				}
-				parent.save();
-				parent.resetTransform();
-				if (clippable && layer.bounds) {
-					const x0 = Math.max(0, Math.floor(layer.bounds.minX - outset));
-					const y0 = Math.max(0, Math.floor(layer.bounds.minY - outset));
-					const x1 = Math.min(w, Math.ceil(layer.bounds.maxX + outset));
-					const y1 = Math.min(h, Math.ceil(layer.bounds.maxY + outset));
-					if (x0 >= x1 || y0 >= y1) {
-						parent.restore();
-						this.release(layer.canvas);
-						break;
+				case "popGroup": {
+					const layer = layers.pop();
+					if (!layer || layer.canvas === null) throw new Error("popGroup without matching pushGroup");
+					const parent = ctxOf();
+					let drawable = layer.canvas;
+					let shaderReplaced = false;
+					if (layer.shader !== void 0) {
+						const replaced = this.host.applyShader?.(layer.canvas, layer.shader, w, h) ?? null;
+						if (replaced !== null) {
+							drawable = replaced;
+							shaderReplaced = true;
+							layer.bounds = {
+								minX: 0,
+								minY: 0,
+								maxX: w,
+								maxY: h
+							};
+							layer.unbounded = false;
+						} else if (this.shaderCaps === "error") throw new Error("a ShaderEffect reached a backend without a shader runner (§3.7) — load @glissade/effects-webgpu in the browser, or accept passthrough with caps.shaders: warn");
+						else if (!this.warnedShaders) {
+							this.warnedShaders = true;
+							emitDevWarning("ShaderEffect pass skipped: no shader runner here (headless or webgpu-less browser) — subtree composites unfiltered (§3.7 caps.shaders)");
+						}
 					}
-					const clip = this.host.newPath();
-					clip.moveTo(x0, y0);
-					clip.lineTo(x1, y0);
-					clip.lineTo(x1, y1);
-					clip.lineTo(x0, y1);
-					clip.closePath();
-					parent.clip(clip, "nonzero");
+					this.composite(parent, top(), drawable, layer.bounds, layer.unbounded, shaderReplaced, layer.opacity, layer.blend, layer.filter, layer.filters, w, h);
+					if (layer.cacheStoreKey !== void 0 && !shaderReplaced) this.cacheStore(layer.cacheStoreKey, {
+						canvas: layer.canvas,
+						bounds: layer.bounds,
+						unbounded: layer.unbounded
+					});
+					else this.release(layer.canvas);
+					break;
 				}
-				parent.globalAlpha = layer.opacity;
-				if (hasFilter) parent.filter = layer.filter;
-				parent.globalCompositeOperation = layer.blend;
-				parent.drawImage(drawable, 0, 0);
-				parent.restore();
-				this.release(layer.canvas);
-				break;
 			}
 		}
 		if (layers.length !== 1) throw new Error("unbalanced pushGroup/popGroup in DisplayList");
 	}
 };
 //#endregion
-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 };
+export { ALL_FILTER_KINDS, Circle, ColdAssetError, DeterminismViolationError, DuplicateNodeIdError, FilterValidationError, FollowPath, Group, Highlight, IDENTITY, ImageNode, LayoutEngineMissingError, MEASURE_QUANTUM_PX, 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/layout.d.ts

@@ -1,4 +1,4 @@
-import { G as Node, K as NodeProps, U as EvalContext, Y as TextMeasurer, a as LayoutEngineMissingError, at as DisplayListBuilder, d as Group, i as LayoutEngine, l as setLayoutEngine, n as LayoutChildSpec, o as LayoutResult, q as PropInit, r as LayoutContainerSpec, s as getLayoutEngine, t as LayoutBox } from "./layoutEngine.js";
+import { G as Node, K as NodeProps, U as EvalContext, X as TextMeasurer, a as LayoutEngineMissingError, d as Group, i as LayoutEngine, l as setLayoutEngine, n as LayoutChildSpec, o as LayoutResult, ot as DisplayListBuilder, q as PropInit, r as LayoutContainerSpec, s as getLayoutEngine, t as LayoutBox } from "./layoutEngine.js";
 import { BindableSignal } from "@glissade/core";
 
 //#region src/layout.d.ts

package/dist/layout.js

@@ -1,5 +1,5 @@
-import { O as fallbackMeasurer, i as setLayoutEngine, n as getLayoutEngine, o as Group, r as requireLayoutEngine, t as LayoutEngineMissingError } from "./layoutEngine.js";
-import { signal } from "@glissade/core";
+import { i as setLayoutEngine, k as fallbackMeasurer, n as getLayoutEngine, o as Group, r as requireLayoutEngine, t as LayoutEngineMissingError } from "./layoutEngine.js";
+import { computed, signal } from "@glissade/core";
 //#region src/layout.ts
 /**
 * '@glissade/scene/layout' (DESIGN.md §3.2): the flexbox Layout node and the
@@ -32,12 +32,16 @@ var Layout = class extends Group {
 	/** Content-sized axes ('auto'): the size signal is ignored, Yoga computes it. */
 	autoWidth;
 	autoHeight;
-	#memoKey = "";
-	#memoResult = {
-		width: 0,
-		height: 0,
-		boxes: []
-	};
+	/**
+	* Sanctioned memoization (§2.1), core-`computed()`-backed: a pure function of
+	* the PARTICIPATING signals. The compute reads exactly the container props
+	* and child intrinsic-size signals it consumes, so the signal graph records
+	* those as deps and re-invokes Yoga only when one of THEM changes — a sibling
+	* mutating a non-participating signal does not invalidate the layout. Pulls
+	* the scene-injected measurer (the same one draw() uses via ctx.measurer);
+	* a caller-supplied non-default measurer bypasses this cache (see #compute).
+	*/
+	#memo = computed(() => this.#computeUncached(this.measurerSource?.() ?? fallbackMeasurer()));
 	constructor(props = {}) {
 		super(props);
 		this.autoWidth = props.width === "auto";
@@ -71,7 +75,17 @@ var Layout = class extends Group {
 		const m = measurer ?? this.measurerSource?.() ?? fallbackMeasurer();
 		return this.#compute(m).size;
 	}
+	/**
+	* Route through the #memo (the dependency-tracked computed) when `measurer`
+	* is the default the memo itself pulls; otherwise compute fresh & UNCACHED —
+	* a caller-supplied non-default measurer must never read (or poison) a cache
+	* keyed on the scene-singleton measurer (the `computedSize(customMeasurer)`
+	* escape hatch).
+	*/
 	#compute(measurer) {
+		return measurer === (this.measurerSource?.() ?? fallbackMeasurer()) ? this.#memo() : this.#computeUncached(measurer);
+	}
+	#computeUncached(measurer) {
 		const container = {
 			width: this.autoWidth ? "auto" : this.width(),
 			height: this.autoHeight ? "auto" : this.height(),
@@ -95,18 +109,13 @@ var Layout = class extends Group {
 			});
 			else absolute.push(child);
 		});
-		const key = JSON.stringify([container, flowable.map((f) => f.spec)]);
-		if (key !== this.#memoKey) {
-			this.#memoResult = requireLayoutEngine().compute(container, flowable.map((f) => f.spec));
-			this.#memoKey = key;
-		}
-		const size = {
-			w: this.autoWidth ? this.#memoResult.width : container.width,
-			h: this.autoHeight ? this.#memoResult.height : container.height
-		};
+		const result = requireLayoutEngine().compute(container, flowable.map((f) => f.spec));
 		return {
-			result: this.#memoResult,
-			size,
+			result,
+			size: {
+				w: this.autoWidth ? result.width : container.width,
+				h: this.autoHeight ? result.height : container.height
+			},
 			flowable,
 			absolute
 		};

package/dist/layoutEngine.d.ts

@@ -171,6 +171,23 @@ interface DisplayList {
 interface DisplayListBuilder {
   push(cmd: DrawCommand): void;
   resource(res: Resource): ResourceId;
+  /**
+   * §3.5 cacheKey seam — OPTIONAL so non-cache emits and lightweight mock
+   * builders never need them. `createDisplayListBuilder` supplies all three;
+   * `Node.emit` calls them only for `cache:true` nodes when present.
+   */
+  /** Count of commands emitted so far — a markpoint for cacheKey ranges. */
+  mark?(): number;
+  /**
+   * A stable hash of the command slice [start, end) plus the FULL content of
+   * every resource those commands reference (not just ids — interned ids are a
+   * per-list detail). Pure function of the slice; identical slices at two times
+   * hash equal, so a static subtree caches. Opaque buffers collapse to a length
+   * marker (mirrors cacheColdAudit's serializer). Undefined for an empty slice.
+   */
+  cacheKey?(start: number, end: number): string | undefined;
+  /** Stamp a cacheKey onto the pushGroup already emitted at index `i`. */
+  patchCacheKey?(i: number, key: string): void;
 }
 declare function createDisplayListBuilder(size: {
   w: number;
@@ -188,7 +205,15 @@ interface TextMetricsLite {
 interface TextMeasurer {
   measureText(text: string, font: FontSpec): TextMetricsLite;
 }
-/** §3.6 measurement quantum. */
+/**
+ * §3.6 measurement quantum (px). Scene-owned pre-measure quantizes every
+ * layout-feeding advance to this grid ONCE, then hands Yoga frozen integers —
+ * so sub-pixel measureText drift between Skia/HarfBuzz versions cannot move a
+ * whole layout. The single source of truth for the grid; `quantize` rounds to
+ * it. (Yoga's `setMeasureFunc` was considered and rejected — see DESIGN.md §3.6.)
+ */
+declare const MEASURE_QUANTUM_PX = 0.5;
+/** §3.6 measurement quantum — round to the MEASURE_QUANTUM_PX grid. */
 declare function quantize(v: number): number;
 /**
  * Process-wide fallback measurer for FACTORY-TIME measurement — component
@@ -254,6 +279,16 @@ interface NodeProps {
   filters?: PropInit<FilterSpec[]>;
   /** Placement point + transform pivot on the intrinsic box; default 'center'. */
   anchor?: AnchorSpec;
+  /**
+   * §3.5 cross-frame raster cache: FORCE this subtree into a group and stamp a
+   * cacheKey on its pushGroup, so a backend with the bitmap LRU re-blits an
+   * unchanged subtree under a moving parent instead of re-rasterizing it. A
+   * pure performance hint — semantics are byte-identical with the cache off
+   * (the cache key folds in the inherited device transform, so a stale CTM can
+   * never blit). OFF by default: a scene that never sets it emits ZERO extra
+   * groups and is byte-identical to before. Best for expensive STATIC subtrees.
+   */
+  cache?: boolean;
 }
 interface BindablePropTarget {
   bindSource(fn: () => unknown): void;
@@ -286,6 +321,8 @@ declare abstract class Node {
   readonly anchor: Vec2;
   /** True only when the author SET an anchor — unset keeps the legacy origin. */
   readonly hasAnchor: boolean;
+  /** §3.5: opt-in cross-frame raster cache. Forces a group + a stamped cacheKey. */
+  readonly cache: boolean;
   parent: Node | null;
   /** v2 §C.3: participates in hit testing; set implicitly by attaching a listener. */
   interactive: boolean;
@@ -787,4 +824,4 @@ declare function setLayoutEngine(e: LayoutEngine): void;
 declare function getLayoutEngine(): LayoutEngine | null;
 declare function requireLayoutEngine(): LayoutEngine;
 //#endregion
-export { quantize as $, ResolvedSketch as A, validateSketch as B, VideoProps as C, applyToPoint as Ct, roundedRectSegs as D, multiply as Dt, revealSchedule as E, matEquals as Et, hachureLines as F, Node as G, BindablePropTarget as H, resolveSketch as I, resolveAnchor as J, NodeProps as K, roughen as L, SketchValidationError as M, arcLength as N, HachureSpec as O, flatten as P, estimatingMeasurer as Q, sketchStrokes as R, Video as S, Mat2x3 as St, pathFromSegs as T, invert as Tt, EvalContext as U, AnchorSpec as V, HitArea as W, TextMetricsLite as X, TextMeasurer as Y, breakLines as Z, Rect as _, createDisplayListBuilder as _t, LayoutEngineMissingError as a, DisplayListBuilder as at, Text as b, validateFilters as bt, requireLayoutEngine as c, FilterValidationError as ct, Group as d, PathSeg as dt, segmentGraphemes as et, ImageNode as f, Rect$1 as ft, PathProps as g, StrokeStyle as gt, Path as h, ShaderRef as ht, LayoutEngine as i, DisplayList as it, SketchStyle as j, Polyline as k, setLayoutEngine as l, FontSpec as lt, LineBox as m, ResourceId as mt, LayoutChildSpec as n, setDefaultMeasurer as nt, LayoutResult as o, DrawCommand as ot, ImageProps as p, Resource as pt, PropInit as q, LayoutContainerSpec as r, BlendMode as rt, getLayoutEngine as s, FilterSpec as st, LayoutBox as t, segmentWords as tt, Circle as u, Paint as ut, RevealMark as v, filtersToCanvasFilter as vt, WordBox as w, fromTRS as wt, TextProps as x, IDENTITY as xt, ShapeProps as y, glow as yt, validateHachure as z };
+export { estimatingMeasurer as $, ResolvedSketch as A, validateSketch as B, VideoProps as C, Mat2x3 as Ct, roundedRectSegs as D, matEquals as Dt, revealSchedule as E, invert as Et, hachureLines as F, Node as G, BindablePropTarget as H, resolveSketch as I, resolveAnchor as J, NodeProps as K, roughen as L, SketchValidationError as M, arcLength as N, HachureSpec as O, multiply as Ot, flatten as P, breakLines as Q, sketchStrokes as R, Video as S, IDENTITY as St, pathFromSegs as T, fromTRS as Tt, EvalContext as U, AnchorSpec as V, HitArea as W, TextMeasurer as X, MEASURE_QUANTUM_PX as Y, TextMetricsLite as Z, Rect as _, StrokeStyle as _t, LayoutEngineMissingError as a, DisplayList as at, Text as b, glow as bt, requireLayoutEngine as c, FilterSpec as ct, Group as d, Paint as dt, quantize as et, ImageNode as f, PathSeg as ft, PathProps as g, ShaderRef as gt, Path as h, ResourceId as ht, LayoutEngine as i, BlendMode as it, SketchStyle as j, Polyline as k, setLayoutEngine as l, FilterValidationError as lt, LineBox as m, Resource as mt, LayoutChildSpec as n, segmentWords as nt, LayoutResult as o, DisplayListBuilder as ot, ImageProps as p, Rect$1 as pt, PropInit as q, LayoutContainerSpec as r, setDefaultMeasurer as rt, getLayoutEngine as s, DrawCommand as st, LayoutBox as t, segmentGraphemes as tt, Circle as u, FontSpec as ut, RevealMark as v, createDisplayListBuilder as vt, WordBox as w, applyToPoint as wt, TextProps as x, validateFilters as xt, ShapeProps as y, filtersToCanvasFilter as yt, validateHachure as z };

package/dist/layoutEngine.js

@@ -122,6 +122,28 @@ function glow(color, radius = 16, intensity = 2) {
 	});
 	return layers;
 }
+/**
+* Resource ids that appear in a draw command — only path/image/video draws
+* carry one. Keeps the cacheKey serializer in lockstep with DrawCommand.
+*/
+function commandResourceIds(cmd) {
+	switch (cmd.op) {
+		case "clip":
+		case "fillPath":
+		case "strokePath": return [cmd.path];
+		case "drawImage": return [cmd.image];
+		default: return [];
+	}
+}
+/** FNV-1a over a string → an 8-hex-digit stable token (no crypto dep, ESM-safe). */
+function fnv1a(s) {
+	let h = 2166136261;
+	for (let i = 0; i < s.length; i++) {
+		h ^= s.charCodeAt(i);
+		h = Math.imul(h, 16777619);
+	}
+	return (h >>> 0).toString(16).padStart(8, "0");
+}
 function createDisplayListBuilder(size) {
 	const commands = [];
 	const resources = [];
@@ -140,6 +162,45 @@ function createDisplayListBuilder(size) {
 			interned.set(k, id);
 			return id;
 		},
+		mark: () => commands.length,
+		cacheKey: (start, end) => {
+			if (end <= start) return void 0;
+			const localIds = /* @__PURE__ */ new Map();
+			const usedResources = [];
+			const remap = (id) => {
+				let local = localIds.get(id);
+				if (local === void 0) {
+					local = localIds.size;
+					localIds.set(id, local);
+					usedResources.push(resources[id]);
+				}
+				return local;
+			};
+			const sliceCmds = commands.slice(start, end).map((cmd) => {
+				if (commandResourceIds(cmd).length === 0) return cmd;
+				if (cmd.op === "drawImage") return {
+					...cmd,
+					image: remap(cmd.image)
+				};
+				return {
+					...cmd,
+					path: remap(cmd.path)
+				};
+			});
+			return fnv1a(JSON.stringify({
+				c: sliceCmds,
+				r: usedResources
+			}, (_k, value) => {
+				if (value instanceof ArrayBuffer) return `ab:${value.byteLength}`;
+				if (ArrayBuffer.isView(value)) return `view:${value.byteLength}`;
+				if (typeof value === "function") return void 0;
+				return value;
+			}));
+		},
+		patchCacheKey: (i, key) => {
+			const cmd = commands[i];
+			if (cmd && cmd.op === "pushGroup") cmd.cacheKey = key;
+		},
 		finish: () => ({
 			commands,
 			resources,
@@ -149,9 +210,17 @@ function createDisplayListBuilder(size) {
 }
 //#endregion
 //#region src/text.ts
-/** §3.6 measurement quantum. */
+/**
+* §3.6 measurement quantum (px). Scene-owned pre-measure quantizes every
+* layout-feeding advance to this grid ONCE, then hands Yoga frozen integers —
+* so sub-pixel measureText drift between Skia/HarfBuzz versions cannot move a
+* whole layout. The single source of truth for the grid; `quantize` rounds to
+* it. (Yoga's `setMeasureFunc` was considered and rejected — see DESIGN.md §3.6.)
+*/
+const MEASURE_QUANTUM_PX = .5;
+/** §3.6 measurement quantum — round to the MEASURE_QUANTUM_PX grid. */
 function quantize(v) {
-	return Math.round(v * 2) / 2;
+	return Math.round(v / MEASURE_QUANTUM_PX) * MEASURE_QUANTUM_PX;
 }
 /**
 * Estimating fallback measurer — used only when no backend has been injected
@@ -282,6 +351,8 @@ var Node = class {
 	anchor;
 	/** True only when the author SET an anchor — unset keeps the legacy origin. */
 	hasAnchor;
+	/** §3.5: opt-in cross-frame raster cache. Forces a group + a stamped cacheKey. */
+	cache;
 	parent = null;
 	#warnedAnchor = false;
 	/** v2 §C.3: participates in hit testing; set implicitly by attaching a listener. */
@@ -311,6 +382,7 @@ var Node = class {
 		this.filters = initScalar(signal([]), props.filters);
 		this.hasAnchor = props.anchor !== void 0;
 		this.anchor = resolveAnchor(props.anchor ?? "center");
+		this.cache = props.cache === true;
 		this.localMatrix = computed(() => {
 			const trs = fromTRS(this.position(), this.rotation(), this.scale());
 			const [sx, sy] = this.anchorShift();
@@ -418,21 +490,33 @@ var Node = class {
 		const local = this.localMatrix();
 		const isIdentity = matEquals(local, IDENTITY);
 		const shader = this.groupShader();
-		const group = this.requiresGroup() || shader !== void 0;
+		const group = this.requiresGroup() || shader !== void 0 || this.cache;
+		const wantsKey = this.cache && out.mark !== void 0;
 		out.push({ op: "save" });
 		if (!isIdentity) out.push({
 			op: "transform",
 			m: local
 		});
-		if (group) out.push({
-			op: "pushGroup",
-			opacity,
-			blend: this.blend(),
-			filters: this.filters(),
-			...shader !== void 0 ? { shader } : {}
-		});
+		let pushIdx = -1;
+		if (group) {
+			if (wantsKey) pushIdx = out.mark();
+			out.push({
+				op: "pushGroup",
+				opacity,
+				blend: this.blend(),
+				filters: this.filters(),
+				...shader !== void 0 ? { shader } : {}
+			});
+		}
+		const drawStart = wantsKey ? out.mark() : -1;
 		this.draw(out, ctx);
-		if (group) out.push({ op: "popGroup" });
+		if (group) {
+			if (wantsKey) {
+				const key = out.cacheKey(drawStart, out.mark());
+				if (key !== void 0) out.patchCacheKey(pushIdx, key);
+			}
+			out.push({ op: "popGroup" });
+		}
 		out.push({ op: "restore" });
 	}
 };
@@ -1740,4 +1824,4 @@ function requireLayoutEngine() {
 	return engine;
 }
 //#endregion
-export { segmentGraphemes as A, fromTRS as B, validateSketch as C, estimatingMeasurer as D, breakLines as E, filtersToCanvasFilter as F, matEquals as H, glow as I, validateFilters as L, setDefaultMeasurer as M, FilterValidationError as N, fallbackMeasurer as O, createDisplayListBuilder as P, IDENTITY as R, validateHachure as S, resolveAnchor as T, multiply as U, invert as V, flatten as _, Circle as a, roughen as b, Path as c, Video as d, pathFromSegs as f, arcLength as g, SketchValidationError as h, setLayoutEngine as i, segmentWords as j, quantize as k, Rect as l, roundedRectSegs as m, getLayoutEngine as n, Group as o, revealSchedule as p, requireLayoutEngine as r, ImageNode as s, LayoutEngineMissingError as t, Text as u, hachureLines as v, Node as w, sketchStrokes as x, resolveSketch as y, applyToPoint as z };
+export { quantize as A, applyToPoint as B, validateSketch as C, breakLines as D, MEASURE_QUANTUM_PX as E, createDisplayListBuilder as F, invert as H, filtersToCanvasFilter as I, glow as L, segmentWords as M, setDefaultMeasurer as N, estimatingMeasurer as O, FilterValidationError as P, validateFilters as R, validateHachure as S, resolveAnchor as T, matEquals as U, fromTRS as V, multiply as W, flatten as _, Circle as a, roughen as b, Path as c, Video as d, pathFromSegs as f, arcLength as g, SketchValidationError as h, setLayoutEngine as i, segmentGraphemes as j, fallbackMeasurer as k, Rect as l, roundedRectSegs as m, getLayoutEngine as n, Group as o, revealSchedule as p, requireLayoutEngine as r, ImageNode as s, LayoutEngineMissingError as t, Text as u, hachureLines as v, Node as w, sketchStrokes as x, resolveSketch as y, IDENTITY as z };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@glissade/scene",
-  "version": "0.9.1-pre.0",
+  "version": "0.10.0-pre.0",
   "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.9.1-pre.0"
+    "@glissade/core": "0.10.0-pre.0"
   },
   "repository": {
     "type": "git",