@glissade/scene 0.27.0 → 0.27.1

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.27.0";
+const RAW_VERSION = "0.27.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) {

package/dist/index.d.ts

@@ -506,6 +506,9 @@ interface Ctx2DLike<TPath, TDrawable> {
    * blit it (clip + drawImage). Both DOM and @napi-rs/canvas expose these. */
   createImageData(w: number, h: number): ImageDataLike;
   putImageData(data: ImageDataLike, x: number, y: number): void;
+  /** Read straight-RGBA back out — used to persist a cached layer's raster to
+   * the disk layer store (§3.5 tier). Both DOM and @napi-rs/canvas expose it. */
+  getImageData(sx: number, sy: number, sw: number, sh: number): ImageDataLike;
 }
 /** The structural ImageData surface the mesh blit drives — DOM ImageData and
  * @napi-rs/canvas ImageData both satisfy it (writable `.data`). */
@@ -534,10 +537,48 @@ interface Raster2DHost<TCanvas extends CanvasLike, TPath extends PathLike, TDraw
 }
 type ShaderCaps = 'warn' | 'error';
 declare function fontString(font: FontSpec): string;
+interface Bounds {
+  minX: number;
+  minY: number;
+  maxX: number;
+  maxY: number;
+}
+/**
+ * §3.5 DISK layer-cache tier. The in-memory raster LRU below spans one render;
+ * an injected `LayerStore` persists a cached layer's DEVICE-space RGBA across
+ * renders (and re-narrations), so an expensive static subtree — a blurred mesh
+ * backdrop — rasterizes ONCE and re-blits on later runs even when the whole-frame
+ * cache is defeated by a caption/timing change. The store is injected (scene stays
+ * Node-dep-free); the CLI provides an fs-backed impl that salts the key with the
+ * toolchain version + backend caps + frame size. A restored RGBA composites
+ * byte-identically to a fresh raster (getImageData → store → putImageData
+ * round-trips exactly — the same guarantee the frame cache relies on).
+ */
+interface LayerCacheEntry {
+  /** straight-RGBA of the full w×h device-space layer canvas */
+  readonly rgba: Uint8ClampedArray;
+  readonly w: number;
+  readonly h: number;
+  /** device-space painted bounds (or null); rides along — the hit can't recompute it */
+  readonly bounds: Bounds | null;
+  readonly unbounded: boolean;
+}
+interface LayerStore {
+  /** key = `<sub-DisplayList fnv1a>@<deviceTransformKey>` (the store salts version/caps/size). */
+  get(key: string): LayerCacheEntry | undefined;
+  put(key: string, entry: LayerCacheEntry): void;
+}
 declare class Raster2D<TCanvas extends CanvasLike, TPath extends PathLike, TDrawable> {
   private readonly host;
   /** caps.shaders (§3.7): what happens when a shader can't run here. */
   private readonly shaderCaps;
+  /**
+   * §3.5 disk layer-cache tier: an injected persistent store for cached-layer
+   * rasters (spans renders, survives re-narration). Undefined = in-memory only.
+   * Also settable post-construction (the CLI needs backend caps to salt the
+   * store's key, which aren't known until the backend exists).
+   */
+  private layerStore;
   private readonly pool;
   private readonly pathCache;
   private readonly pathBoundsCache;
@@ -560,7 +601,16 @@ declare class Raster2D<TCanvas extends CanvasLike, TPath extends PathLike, TDraw
    * 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);
+  cacheEnabled?: boolean,
+  /**
+   * §3.5 disk layer-cache tier: an injected persistent store for cached-layer
+   * rasters (spans renders, survives re-narration). Undefined = in-memory only.
+   * Also settable post-construction (the CLI needs backend caps to salt the
+   * store's key, which aren't known until the backend exists).
+   */
+  layerStore?: LayerStore | undefined);
+  /** Attach (or clear) the §3.5 disk layer-cache store after construction. */
+  setLayerStore(store: LayerStore | undefined): void;
   /** 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). */
@@ -641,4 +691,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, Echo, type EchoProps, 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, echo, 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 Bounds, 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, Echo, type EchoProps, 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 LayerCacheEntry, type LayerStore, 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, echo, 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

@@ -969,6 +969,7 @@ function segsBounds(segs) {
 var Raster2D = class {
 	host;
 	shaderCaps;
+	layerStore;
 	pool = [];
 	pathCache = /* @__PURE__ */ new WeakMap();
 	pathBoundsCache = /* @__PURE__ */ new WeakMap();
@@ -984,11 +985,16 @@ var Raster2D = class {
 	*/
 	rasterCache = /* @__PURE__ */ new Map();
 	cacheEnabled;
-	constructor(host, shaderCaps = "warn", cacheEnabled = (globalThis.process?.env?.["RASTER_CACHE"] ?? "1") !== "0") {
+	constructor(host, shaderCaps = "warn", cacheEnabled = (globalThis.process?.env?.["RASTER_CACHE"] ?? "1") !== "0", layerStore = void 0) {
 		this.host = host;
 		this.shaderCaps = shaderCaps;
+		this.layerStore = layerStore;
 		this.cacheEnabled = cacheEnabled;
 	}
+	/** Attach (or clear) the §3.5 disk layer-cache store after construction. */
+	setLayerStore(store) {
+		this.layerStore = store;
+	}
 	/** Register a decoded still (kind 'image' assets). */
 	setImageAsset(assetId, image) {
 		this.images.set(assetId, image);
@@ -1298,6 +1304,28 @@ var Raster2D = class {
 							}
 							break;
 						}
+						const disk = this.layerStore?.get(lruKey);
+						if (disk !== void 0 && disk.w === w && disk.h === h) {
+							const canvas = this.acquire(w, h);
+							const dctx = this.host.context(canvas);
+							dctx.resetTransform();
+							const img = dctx.createImageData(w, h);
+							img.data.set(disk.rgba);
+							dctx.putImageData(img, 0, 0);
+							this.cacheStore(lruKey, {
+								canvas,
+								bounds: disk.bounds,
+								unbounded: disk.unbounded
+							});
+							this.composite(parent, top(), canvas, disk.bounds, disk.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 layerCanvas = this.acquire(w, h);
 					const layerCtx = this.host.context(layerCanvas);
@@ -1343,12 +1371,23 @@ var Raster2D = class {
 						}
 					}
 					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);
+					if (layer.cacheStoreKey !== void 0 && !shaderReplaced) {
+						this.cacheStore(layer.cacheStoreKey, {
+							canvas: layer.canvas,
+							bounds: layer.bounds,
+							unbounded: layer.unbounded
+						});
+						if (this.layerStore !== void 0) {
+							const rgba = this.host.context(layer.canvas).getImageData(0, 0, w, h).data;
+							this.layerStore.put(layer.cacheStoreKey, {
+								rgba,
+								w,
+								h,
+								bounds: layer.bounds,
+								unbounded: layer.unbounded
+							});
+						}
+					} else this.release(layer.canvas);
 					break;
 				}
 			}

package/package.json

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