@glissade/scene 0.33.0 → 0.34.0-pre.1

package/dist/chart.d.ts

@@ -1,4 +1,4 @@
-import { V as NodeProps, i as Group, u as Rect } from "./nodes.js";
+import { H as NodeProps, a as Group, d as Rect } from "./nodes.js";
 
 //#region src/chart.d.ts
 

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.33.0";
+const RAW_VERSION = "0.34.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) {
@@ -52,7 +52,10 @@ function expectsToType(expects) {
 * only each node's OWN construction surface.
 */
 const CONSTRUCTION_PROP_META = {
-	Group: { children: { type: "Node[]" } },
+	Group: {
+		children: { type: "Node[]" },
+		clip: { type: "{ w, h, r?, x?, y? } | PathSeg[]" }
+	},
 	Rect: {
 		sketch: { type: "SketchStyle" },
 		sketchFill: { type: "HachureSpec" },
@@ -190,6 +193,7 @@ const LAYOUT_CONSTRUCTION_META = {
 function describeLayoutNode() {
 	const props = describeNode(new Group(), "Group").props;
 	delete props.children;
+	delete props["clip"];
 	for (const [prop, spec] of Object.entries(LAYOUT_ANIMATABLE)) {
 		const arity = arityOf(spec.type);
 		props[prop] = {
@@ -351,6 +355,12 @@ const HELPERS = [
 		import: "@glissade/scene",
 		usage: "motionBlur(child: Node, opts?: { id?, shutter?: number, samples?: number }): MotionBlur"
 	},
+	{
+		name: "trackMatte",
+		summary: "Track-matte: mask CONTENT by a MATTE layer's alpha (default) or luminance ('luma'). Content renders into an isolated layer, then the matte composites destination-in — pixels survive only where the matte is opaque. Both subtrees animate like ordinary nodes (a sliding shape wipes text in, a scaling blob irises a photo). Byte-exact on Skia; browser-vs-Skia pixel parity is perceptual at anti-aliased matte edges; backend-dom (preview tier) degrades with data-approx.",
+		import: "@glissade/scene",
+		usage: "trackMatte(content: Node, matte: Node, opts?: { id?, mode?: 'alpha' | 'luma' }): TrackMatte"
+	},
 	{
 		name: "clip",
 		summary: "A reusable, target-agnostic motion captured once as a relative-time key schedule, then applied to a node at a wall-clock start time. Build-time sugar: clip.apply() compiles to ordinary Track[].",

package/dist/displayList.d.ts

@@ -174,6 +174,17 @@ type DrawCommand = {
   filters: FilterSpec[];
   shader?: ShaderRef;
   cacheKey?: string;
+  /**
+   * 0.34 track-matte: this layer is a MATTE for the layer it composites
+   * onto — 'alpha' keeps destination pixels where this layer is opaque
+   * (native destination-in, byte-exact); 'luma' first converts this
+   * layer's luminance to alpha via the shared straight-alpha CPU kernel
+   * (the mesh-kernel discipline), then applies destination-in. Emitted
+   * by trackMatte() inside its isolated outer group; an optional field
+   * on the shader?/cacheKey? extension precedent — BlendMode stays a
+   * closed union.
+   */
+  matte?: 'alpha' | 'luma';
 } | {
   op: 'popGroup';
 };

package/dist/grid.d.ts

@@ -1,4 +1,4 @@
-import { V as NodeProps, i as Group, z as Node } from "./nodes.js";
+import { B as Node, H as NodeProps, a as Group } from "./nodes.js";
 
 //#region src/grid.d.ts
 

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 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 { $ 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 { $ as isEstimatingMeasurer, A as hachureLines, B as Node, C as HachureSpec, D as SketchValidationError, E as SketchStyle, F as validateSketch, G as MEASURE_QUANTUM_PX, H as NodeProps, I as AnchorSpec, J as WrappedTextMetrics, K as TextMeasurer, L as BindablePropTarget, M as roughen, N as sketchStrokes, O as arcLength, P as validateHachure, Q as estimatingMeasurer, R as EvalContext, S as roundedRectSegs, T as ResolvedSketch, U as PropInit, V as NodeConstructionError, W as resolveAnchor, X as assertFiniteFontSize, Y as __resetEstimateWarnings, Z as breakLines, _ as VideoProps, a as Group, b as pathFromSegs, c as LineBox, d as Rect, et as measureWrappedText, f as RevealMark, g as Video, h as TextProps, i as GraphemeBox, it as setDefaultMeasurer, j as resolveSketch, k as flatten, l as Path, m as Text, n as ClipRegion, nt as segmentGraphemes, o as ImageNode, p as ShapeProps, q as TextMetricsLite, r as Custom, rt as segmentWords, s as ImageProps, t as Circle, tt as quantize, u as PathProps, v as WordBox, w as Polyline, x as revealSchedule, y as coercePathData, z as HitArea } from "./nodes.js";
 import { t as collapseReplacer } from "./collapseReplacer.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";
@@ -464,6 +464,30 @@ declare class MotionBlur extends Group {
  * sub-frame motion blur. Wrap the moving content; its background stays crisp. */
 declare function motionBlur(child: Node, props?: Omit<MotionBlurProps, 'children'>): MotionBlur;
 //#endregion
+//#region src/matte.d.ts
+interface TrackMatteProps extends NodeProps {
+  /** the visible content — masked by the matte. */
+  content: Node;
+  /** the mask — its alpha (or luma) decides which content pixels survive. */
+  matte: Node;
+  /** 'alpha' (default): matte opacity masks. 'luma': matte brightness masks
+   *  (white = keep, black = erase), via the shared deterministic CPU kernel. */
+  mode?: 'alpha' | 'luma';
+}
+declare class TrackMatte extends Group {
+  get describeType(): string;
+  readonly content: Node;
+  readonly matte: Node;
+  readonly mode: 'alpha' | 'luma';
+  constructor(props: TrackMatteProps);
+  /** destination-in must not leak past this node — always isolate in a layer. */
+  protected requiresGroup(): boolean;
+  protected draw(out: DisplayListBuilder, ctx: EvalContext): void;
+}
+/** `trackMatte(photo, circleWipe)` — photo visible only inside the (animatable)
+ * circle. Pass `{ mode: 'luma' }` to mask by matte brightness instead of alpha. */
+declare function trackMatte(content: Node, matte: Node, props?: Omit<TrackMatteProps, 'content' | 'matte'>): TrackMatte;
+//#endregion
 //#region src/raster2d.d.ts
 /** A backend gradient handle (DOM CanvasGradient and @napi-rs CanvasGradient both satisfy it). */
 interface CanvasGradientLike {
@@ -669,6 +693,13 @@ declare class Raster2D<TCanvas extends CanvasLike, TPath extends PathLike, TDraw
    * the cache entry (hit); the composite params (opacity/blend/filters) always
    * come from the LIVE pushGroup command, never the cache.
    */
+  /**
+   * 0.34 luma matte: convert a layer's LUMINANCE to its alpha, in place —
+   * `a' = round(luma(r,g,b) × a / 255)` with Rec.709 integer coefficients over
+   * STRAIGHT (non-premultiplied) RGBA, the same discipline as the mesh kernel,
+   * so both backends run one deterministic CPU pass and the result byte-compares.
+   */
+  private lumaToAlpha;
   private composite;
   /** The command walk — order and operations identical to the pre-extraction twins. */
   render(target: TCanvas, list: DisplayList): void;
@@ -710,4 +741,4 @@ declare function meshRasterSize(bw: number, bh: number): {
   h: number;
 };
 //#endregion
-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, MotionBlur, type MotionBlurProps, 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, motionBlur, 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, type ClipRegion, 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, MotionBlur, type MotionBlurProps, 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, TrackMatte, type TrackMatteProps, 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, motionBlur, multiply, pathFromSegs, quantize, rasterizeMesh, requireLayoutEngine, resolveAnchor, resolveSketch, revealSchedule, roughen, roundedRectSegs, segmentGraphemes, segmentWords, setDefaultMeasurer, setLayoutEngine, sketchStrokes, textCursor, trackMatte, typewriter, validateFilters, validateHachure, validateSceneFonts, validateSketch, withDeterminismGuards };

package/dist/index.js

@@ -671,6 +671,52 @@ var ShaderEffect = class extends Group {
 		};
 	}
 };
+//#endregion
+//#region src/matte.ts
+var TrackMatte = class extends Group {
+	get describeType() {
+		return "TrackMatte";
+	}
+	content;
+	matte;
+	mode;
+	constructor(props) {
+		const { content, matte, mode, ...rest } = props;
+		super({
+			...rest,
+			children: [content, matte]
+		});
+		if (mode !== void 0 && mode !== "alpha" && mode !== "luma") throw new Error(`trackMatte mode must be 'alpha' or 'luma', got ${JSON.stringify(mode)}`);
+		this.content = content;
+		this.matte = matte;
+		this.mode = mode ?? "alpha";
+	}
+	/** destination-in must not leak past this node — always isolate in a layer. */
+	requiresGroup() {
+		return true;
+	}
+	draw(out, ctx) {
+		this.content.emit(out, ctx);
+		out.push({
+			op: "pushGroup",
+			opacity: 1,
+			blend: "source-over",
+			filters: [],
+			matte: this.mode
+		});
+		this.matte.emit(out, ctx);
+		out.push({ op: "popGroup" });
+	}
+};
+/** `trackMatte(photo, circleWipe)` — photo visible only inside the (animatable)
+* circle. Pass `{ mode: 'luma' }` to mask by matte brightness instead of alpha. */
+function trackMatte(content, matte, props = {}) {
+	return new TrackMatte({
+		...props,
+		content,
+		matte
+	});
+}
 const smoothstep = (u) => u * u * (3 - 2 * u);
 const GAUSS_K = 2.4;
 const GAUSS_NORM = 1 - Math.exp(-5.76 / 2);
@@ -1143,6 +1189,24 @@ var Raster2D = class {
 	* the cache entry (hit); the composite params (opacity/blend/filters) always
 	* come from the LIVE pushGroup command, never the cache.
 	*/
+	/**
+	* 0.34 luma matte: convert a layer's LUMINANCE to its alpha, in place —
+	* `a' = round(luma(r,g,b) × a / 255)` with Rec.709 integer coefficients over
+	* STRAIGHT (non-premultiplied) RGBA, the same discipline as the mesh kernel,
+	* so both backends run one deterministic CPU pass and the result byte-compares.
+	*/
+	lumaToAlpha(ctx, w, h) {
+		const t = ctx.getTransform();
+		ctx.resetTransform();
+		const img = ctx.getImageData(0, 0, w, h);
+		const d = img.data;
+		for (let i = 0; i < d.length; i += 4) {
+			const luma = (d[i] * 2126 + d[i + 1] * 7152 + d[i + 2] * 722) / 255e4;
+			d[i + 3] = Math.round(luma * d[i + 3]);
+		}
+		ctx.putImageData(img, 0, 0);
+		ctx.setTransform(t);
+	}
 	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;
@@ -1295,7 +1359,7 @@ var Raster2D = class {
 					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);
+							this.composite(parent, top(), hit.canvas, hit.bounds, hit.unbounded, false, cmd.opacity, cmd.matte !== void 0 ? "destination-in" : cmd.blend, filtersToCanvasFilter(cmd.filters), cmd.filters, w, h);
 							let depth = 1;
 							while (depth > 0 && ++ci < commands.length) {
 								const c = commands[ci];
@@ -1317,7 +1381,7 @@ var Raster2D = class {
 								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);
+							this.composite(parent, top(), canvas, disk.bounds, disk.unbounded, false, cmd.opacity, cmd.matte !== void 0 ? "destination-in" : cmd.blend, filtersToCanvasFilter(cmd.filters), cmd.filters, w, h);
 							let depth = 1;
 							while (depth > 0 && ++ci < commands.length) {
 								const c = commands[ci];
@@ -1340,6 +1404,7 @@ var Raster2D = class {
 						filter: filtersToCanvasFilter(cmd.filters),
 						filters: cmd.filters,
 						...cmd.shader !== void 0 ? { shader: cmd.shader } : {},
+						...cmd.matte !== void 0 ? { matte: cmd.matte } : {},
 						bounds: null,
 						unbounded: false,
 						...lruKey !== void 0 ? { cacheStoreKey: lruKey } : {}
@@ -1370,7 +1435,8 @@ var Raster2D = class {
 							emitDevWarning("ShaderEffect pass skipped: no shader runner here (headless or webgpu-less browser) — subtree composites unfiltered (§3.7 caps.shaders)");
 						}
 					}
-					this.composite(parent, top(), drawable, layer.bounds, layer.unbounded, shaderReplaced, layer.opacity, layer.blend, layer.filter, layer.filters, w, h);
+					if (layer.matte === "luma" && !shaderReplaced) this.lumaToAlpha(layer.ctx, w, h);
+					this.composite(parent, top(), drawable, layer.bounds, layer.unbounded, shaderReplaced, layer.opacity, layer.matte !== void 0 ? "destination-in" : layer.blend, layer.filter, layer.filters, w, h);
 					if (layer.cacheStoreKey !== void 0 && !shaderReplaced) {
 						this.cacheStore(layer.cacheStoreKey, {
 							canvas: layer.canvas,
@@ -1396,4 +1462,4 @@ var Raster2D = class {
 	}
 };
 //#endregion
-export { ALL_FILTER_KINDS, Circle, ColdAssetError, Custom, DeterminismViolationError, DuplicateNodeIdError, EachError, Echo, FilterValidationError, Group, Highlight, IDENTITY, ImageNode as Image, ImageNode, LayoutEngineMissingError, MEASURE_QUANTUM_PX, MESH_DOWNSCALE, MESH_SHEPARD_POWER, MESH_SIGMA, MotionBlur, 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, echo, estimatingMeasurer, evaluate, filtersToCanvasFilter, flatten, fontString, fromTRS, getLayoutEngine, glow, hachureLines, highlight, invert, isEstimatingMeasurer, matEquals, measureWrappedText, meshRasterSize, motionBlur, 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, Echo, FilterValidationError, Group, Highlight, IDENTITY, ImageNode as Image, ImageNode, LayoutEngineMissingError, MEASURE_QUANTUM_PX, MESH_DOWNSCALE, MESH_SHEPARD_POWER, MESH_SIGMA, MotionBlur, NODE_TAXONOMY, Node, NodeConstructionError, Path, Raster2D, Rect, ReservedNodeIdError, ShaderEffect, SketchValidationError, Text, TextCursor, TrackMatte, Video, __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, motionBlur, multiply, pathFromSegs, quantize, rasterizeMesh, requireLayoutEngine, resolveAnchor, resolveSketch, revealSchedule, roughen, roundedRectSegs, segmentGraphemes, segmentWords, setDefaultMeasurer, setLayoutEngine, sketchStrokes, textCursor, trackMatte, typewriter, validateFilters, validateHachure, validateSceneFonts, validateSketch, withDeterminismGuards };

package/dist/layoutCtors.d.ts

@@ -1,5 +1,5 @@
 import { r as DisplayListBuilder } from "./displayList.js";
-import { G as TextMeasurer, H as PropInit, L as EvalContext, V as NodeProps, i as Group, z as Node } from "./nodes.js";
+import { B as Node, H as NodeProps, K as TextMeasurer, R as EvalContext, U as PropInit, a as Group } from "./nodes.js";
 import { r as LayoutContainerSpec } from "./layoutEngine.js";
 import { BindableSignal } from "@glissade/core";
 

package/dist/motion.d.ts

@@ -1,4 +1,4 @@
-import { H as PropInit, V as NodeProps, c as Path, z as Node } from "./nodes.js";
+import { B as Node, H as NodeProps, U as PropInit, l as Path } from "./nodes.js";
 import { BindableSignal, PathValue, Vec2 } from "@glissade/core";
 
 //#region src/motionPath.d.ts

package/dist/nodes.d.ts

@@ -434,6 +434,22 @@ declare function sketchStrokes(segs: readonly PathSeg[], style: SketchStyle, see
 declare abstract class Custom extends Node {}
 /** Rounded-rect path segments — Rect's outline, shared with Highlight. */
 declare function roundedRectSegs(x: number, y: number, w: number, h: number, r: number): PathSeg[];
+/**
+ * A Group clip region (0.34), in the group's LOCAL coordinates: a (rounded)
+ * rect centered on `[x ?? 0, y ?? 0]` — matching the center-anchor convention —
+ * or an explicit `PathSeg[]` outline (`pathFromSvg(...)` output works directly).
+ * Children paint only inside the region; it clips the group's own layer, so a
+ * rounded corner anti-aliases in LOCAL space and the whole subtree byte-compares
+ * on Skia. Construction-only (not a track target); clipping is render-time only
+ * — hit-testing is unaffected in v1 (a clipped child still hits).
+ */
+type ClipRegion = {
+  w: number;
+  h: number;
+  r?: number;
+  x?: number;
+  y?: number;
+} | PathSeg[];
 declare class Group extends Node {
   #private;
   /**
@@ -448,8 +464,11 @@ declare class Group extends Node {
    */
   get describeType(): string;
   readonly children: Node[];
+  /** Clip region for this group's children (0.34) — see {@link ClipRegion}. */
+  readonly clip?: ClipRegion;
   constructor(props?: NodeProps & {
     children?: Node[];
+    clip?: ClipRegion;
   });
   /** Record the structural version as a dependency — call inside a computed
    * that walks `children` so add()/remove() invalidate it. */
@@ -457,6 +476,10 @@ declare class Group extends Node {
   add(child: Node): this;
   /** Remove a child (the reactive counterpart to add()); no-op if absent. */
   remove(child: Node): this;
+  /** A clip demands a group layer: children must rasterize into an isolated
+   *  layer the region applies to (and the clip op lands INSIDE the cacheKey'd
+   *  draw slice, so a changed region correctly misses the layer cache). */
+  protected requiresGroup(): boolean;
   protected draw(out: DisplayListBuilder, ctx: EvalContext): void;
 }
 /** A color string is sugar for a solid `color` Paint; a Paint passes through. */
@@ -900,4 +923,4 @@ interface RevealMark {
  */
 declare function revealSchedule(text: Text, reveal: Track<number>, measurer?: TextMeasurer): RevealMark[];
 //#endregion
-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 };
+export { isEstimatingMeasurer as $, hachureLines as A, Node as B, HachureSpec as C, SketchValidationError as D, SketchStyle as E, validateSketch as F, MEASURE_QUANTUM_PX as G, NodeProps as H, AnchorSpec as I, WrappedTextMetrics as J, TextMeasurer as K, BindablePropTarget as L, roughen as M, sketchStrokes as N, arcLength as O, validateHachure as P, estimatingMeasurer as Q, EvalContext as R, roundedRectSegs as S, ResolvedSketch as T, PropInit as U, NodeConstructionError as V, resolveAnchor as W, assertFiniteFontSize as X, __resetEstimateWarnings as Y, breakLines as Z, VideoProps as _, Group as a, pathFromSegs as b, LineBox as c, Rect as d, measureWrappedText as et, RevealMark as f, Video as g, TextProps as h, GraphemeBox as i, setDefaultMeasurer as it, resolveSketch as j, flatten as k, Path as l, Text as m, ClipRegion as n, segmentGraphemes as nt, ImageNode as o, ShapeProps as p, TextMetricsLite as q, Custom as r, segmentWords as rt, ImageProps as s, Circle as t, quantize as tt, PathProps as u, WordBox as v, Polyline as w, revealSchedule as x, coercePathData as y, HitArea as z };

package/dist/nodes.js

@@ -469,7 +469,7 @@ const LAYOUT = [
 	"children"
 ];
 const NODE_CONSTRUCTION_PROP_NAMES = {
-	Group: ["children"],
+	Group: ["children", "clip"],
 	Rect: SKETCH,
 	Circle: SKETCH,
 	Path: SKETCH,
@@ -1251,6 +1251,8 @@ var Group = class Group extends Node {
 		return "Group";
 	}
 	children;
+	/** Clip region for this group's children (0.34) — see {@link ClipRegion}. */
+	clip;
 	/** Version bumped on structural child mutation, so a dependency-tracked memo
 	* (e.g. Layout's computed) re-runs when the child SET changes — not only when
 	* a participating prop signal does. */
@@ -1258,6 +1260,7 @@ var Group = class Group extends Node {
 	constructor(props = {}) {
 		super(props);
 		this.children = props.children ?? [];
+		if (props.clip !== void 0) this.clip = props.clip;
 		for (const child of this.children) child.parent = this;
 		if (new.target === Group) this.checkProps(props);
 	}
@@ -1282,12 +1285,31 @@ var Group = class Group extends Node {
 		}
 		return this;
 	}
+	/** A clip demands a group layer: children must rasterize into an isolated
+	*  layer the region applies to (and the clip op lands INSIDE the cacheKey'd
+	*  draw slice, so a changed region correctly misses the layer cache). */
+	requiresGroup() {
+		return this.clip !== void 0 || super.requiresGroup();
+	}
 	draw(out, ctx) {
+		if (this.clip !== void 0) {
+			const segs = Array.isArray(this.clip) ? this.clip : roundedRectSegs((this.clip.x ?? 0) - this.clip.w / 2, (this.clip.y ?? 0) - this.clip.h / 2, this.clip.w, this.clip.h, this.clip.r ?? 0);
+			out.push({ op: "save" });
+			out.push({
+				op: "clip",
+				path: out.resource({
+					kind: "path",
+					segs
+				}),
+				rule: "nonzero"
+			});
+		}
 		const sorted = this.children.map((node, i) => ({
 			node,
 			i
 		})).sort((a, b) => a.node.zIndex() - b.node.zIndex() || a.i - b.i).map((e) => e.node);
 		for (const child of sorted) child.emit(out, ctx);
+		if (this.clip !== void 0) out.push({ op: "restore" });
 	}
 };
 /** A color string is sugar for a solid `color` Paint; a Paint passes through. */

package/dist/scene.d.ts

@@ -1,5 +1,5 @@
 import { n as DisplayList, s as FontSpec } from "./displayList.js";
-import { G as TextMeasurer, I as BindablePropTarget, i as Group, q as WrappedTextMetrics, z as Node } from "./nodes.js";
+import { B as Node, J as WrappedTextMetrics, K as TextMeasurer, L as BindablePropTarget, a as Group } from "./nodes.js";
 import { BoundTimeline, CompiledTimeline, Playhead, Timeline } from "@glissade/core";
 
 //#region src/scene.d.ts

package/dist/tokens.d.ts

@@ -1,5 +1,5 @@
 import { r as DisplayListBuilder } from "./displayList.js";
-import { H as PropInit, L as EvalContext, V as NodeProps, _ as WordBox, p as Text, z as Node } from "./nodes.js";
+import { B as Node, H as NodeProps, R as EvalContext, U as PropInit, m as Text, v as WordBox } from "./nodes.js";
 import { Vec2 } from "@glissade/core";
 
 //#region src/tokenHighlight.d.ts

package/dist/type.d.ts

@@ -1,4 +1,4 @@
-import { G as TextMeasurer, _ as WordBox, i as Group, m as TextProps, p as Text, r as GraphemeBox, s as LineBox } from "./nodes.js";
+import { K as TextMeasurer, a as Group, c as LineBox, h as TextProps, i as GraphemeBox, m as Text, v as WordBox } from "./nodes.js";
 
 //#region src/type.d.ts
 

package/package.json

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