V3: designer-focused composition and experimental graphics

.changeset/alpha-compositing-foundation.md

@@ -0,0 +1,5 @@
+---
+"@basementstudio/shader-lab": patch
+---
+
+Preserve alpha when copying external input textures and applying effect passes. Source layers use straight-alpha source-over blending; effect passes preserve input coverage and retain their existing alpha-as-strength behavior. Opaque compositions and legacy mask semantics are unchanged.

.changeset/annotations-layer.md

@@ -0,0 +1,5 @@
+---
+"@basementstudio/shader-lab": minor
+---
+
+Add an Annotations effect layer: seeded, edge-guided or painted placement of decorative technical marks (target rings, dashed circles and boxes, crosshairs, rulers, connectors, readouts, metadata blocks) with presets, editable text, monochrome or palette colors, rendered identically in the editor and runtime.

.changeset/annotations-regions-rotation.md

@@ -0,0 +1,5 @@
+---
+"@basementstudio/shader-lab": minor
+---
+
+Annotations can place marks by image regions, draw connected dots and turn individual elements. Placement → Regions groups the image below into areas of similar tone and color from the same low-resolution field Edges already reads, then frames regions with boxes, traces their outlines with dots and tags them with labels; region ids persist across video frames so marks follow the image instead of flickering. Connected Dots adds small constellations of dots linked to their nearest neighbours. Rotation Jitter turns rings, crosses and boxes by a seeded angle, and Align to Edges turns them along the image edges or each region's long axis. All new controls default to off, so existing annotations render exactly as before.

.changeset/blob-inner-effects.md

@@ -0,0 +1,5 @@
+---
+"@basementstudio/shader-lab": patch
+---
+
+Blob Tracking inner effects cover every current effect, including Blur, Glass, Gradient Map, Grain, Lumen Print, Photocopy, Relief, Erosion and Signal Rot. A newly picked inner effect now starts from its default settings instead of rendering nothing until a setting was changed.

.changeset/blob-tracking-annotations.md

@@ -0,0 +1,5 @@
+---
+"@basementstudio/shader-lab": minor
+---
+
+Blob Tracking gains corner-bracket frames, edge dots along each blob's silhouette, and decorative label modes (prefix + seeded ID, custom list). Existing scenes keep their outline and coordinate labels.

.changeset/brush-mask-feather.md

@@ -0,0 +1,5 @@
+---
+"@basementstudio/shader-lab": minor
+---
+
+Brush masks gain Feather: painted mask edges soften by a keyframable distance measured from the painted edge, the same way ellipse and rectangle masks soften. Feather 0 keeps a hard painted edge; the existing default of 0.01 softens old brush masks very slightly.

.changeset/cell-edge-scatter.md

@@ -0,0 +1,5 @@
+---
+"@basementstudio/shader-lab": minor
+---
+
+Add optional, seeded Edge Scatter to Photographic Cells regions and painted reveals. Scatter fragments boundaries without moving source detail or adding texture samples. Missing values and zero preserve existing projects.

.changeset/connected-dots-edge-snap.md

@@ -0,0 +1,5 @@
+---
+"@basementstudio/shader-lab": minor
+---
+
+Connected Dots gains Edge Snap, which pulls each point onto the strongest image edge inside its cell so dots, links and mesh triangles trace contours, and two styles that use it: Contour Graph and Facets. At 0 (the default, and for every existing style and saved project) the output is unchanged. Mesh mode now reads its points from the per-cell pre-pass, about twice as fast at 1080p with identical pixels.

.changeset/connected-dots-layer.md

@@ -0,0 +1,5 @@
+---
+"@basementstudio/shader-lab": minor
+---
+
+Add a Connected Dots effect layer: the image becomes jittered points linked to their neighbors. Graph links dots by tone with links that thicken in the darks; Blobs melts dots and links into organic masses; Plexus draws thin lines that fade with distance. Circle, square, plus or ring dots sized by tone, a tone cutoff that drops the background, palette-by-tone (flat bands from an editable ramp of up to 8 stops), source or ink color, a color, image or transparent background, and Drift so links form and break over time. Four starting styles (Portrait Graph, Ink Blobs, Plexus, Constellation).

.changeset/connected-dots-mesh.md

@@ -0,0 +1,5 @@
+---
+"@basementstudio/shader-lab": minor
+---
+
+Connected Dots gains a Mesh mode (flat-colored triangles between the points, with Fill, Wire and Wire Color) and six new styles: Molecule, Circuit, Neural, Riso, Low Poly and Wireframe.

.changeset/depth-parallax.md

@@ -0,0 +1,5 @@
+---
+"@basementstudio/shader-lab": patch
+---
+
+Image layers accept a grayscale depth map as a second asset (`depthAsset` in the runtime config) and gain Depth controls: invert, range, focus plane, orbit/sway/nod/dolly camera motion with amount and speed, a keyframable camera offset, stretched or transparent edges, march quality and a depth preview. The pass marches depth layers from near to far with binary refinement so nearer content covers what is behind it. Layers without a depth map keep the previous shader. An **Estimate** button generates the depth map in the browser with Depth Anything V2 Small (transformers.js in a Web Worker, WebGPU with a WASM fallback) and attaches it as a local asset. The image pass publishes its displaced depth as scene depth for the layers above: ASCII, Halftone, Pattern and Gradient Map gain `input: "luminance" | "depth"`, and layer masks gain a `depth` shape with a near/far range. Mask center, size, rotation and feather are keyframable and audio-linkable as `mask.*` tracks, evaluated in the editor and the runtime.

.changeset/displaced-rings.md

@@ -0,0 +1,5 @@
+---
+"@basementstudio/shader-lab": minor
+---
+
+Add Displaced Rings with rings/half-discs, progressive transforms, seeded offsets, and Distort/Cutout output. Support transformed coverage in the editor and runtime so grouped photographic cutouts reveal external layers, with opacity interpolating color and alpha together.

.changeset/dot-grid-layer.md

@@ -0,0 +1,5 @@
+---
+"@basementstudio/shader-lab": minor
+---
+
+Add a Dot Grid effect layer: an exact, unrotated dot grid fixed to the artboard where every cell gets a dot that grows with the tone, with Level, Contrast, Softness, circle or square dots, single-color or source ink, a background and a blurred underlay. Four starting styles (Coordinate, Source Dots, Night, Pixel Grid). It renders identically in the editor, exports and the runtime package. Halftone is unchanged.

.changeset/editor-groups.md

@@ -0,0 +1,5 @@
+---
+"@basementstudio/shader-lab": minor
+---
+
+Support isolated groups in exported ShaderLabConfig layer lists using group layers and parentId references. Evaluate group visibility and opacity before building the render tree, preserving child effect scope in composition and headless rendering. Existing flat configs remain compatible.

.changeset/erosion-layer.md

@@ -0,0 +1,5 @@
+---
+"@basementstudio/shader-lab": minor
+---
+
+Add an Erosion effect layer that crumbles the image into speckle along its edges, light or dark tones, or the border of a cutout, with Erode, Edge Width, Speckle Size, Clumping and Scatter (fragments thrown across the edge), revealing paper or transparent holes, frozen or animated. Three starting styles (Disintegrate, Paper Erosion, Crumbled Cutout). It renders identically in the editor, exports and the runtime package.

.changeset/flares-layer.md

@@ -0,0 +1,5 @@
+---
+"@basementstudio/shader-lab": minor
+---
+
+Add a Flares effect layer: light flares from the brightest small points in the image, with Threshold, Isolation (large bright areas stay clean), Intensity, 1 to 16 rays, rotation, length, secondary ray length, length jitter, thickness, falloff, ray and core colors and a core glow. Five starting styles (Cross, Star, Starburst, Asterisk, Anamorphic). Flares extend over transparent areas. It renders identically in the editor, exports and the runtime package.

.changeset/focus-blur-layer.md

@@ -0,0 +1,5 @@
+---
+"@basementstudio/shader-lab": minor
+---
+
+Add a Blur effect layer built on a seven-level blur pyramid with B-spline sampling, so any radius stays smooth and the blur size can change per pixel. Blur From: Uniform, Depth (depth of field from the scene depth map), Linear and Radial focus zones, or Luminance, with Focus, Focus Range, Transition, Center, Band Angle and Invert Focus. Kinds: Gaussian, Lens bokeh with Highlights, and Motion. Grain keeps large blurs from banding. Five starting styles (Depth of Field, Tilt-Shift, Vignette, Soft, Motion). Directional Blur, Progressive Blur and Fluted Glass leave the add-layer menu; saved projects keep rendering them.

.changeset/glass-layer.md

@@ -0,0 +1,5 @@
+---
+"@basementstudio/shader-lab": minor
+---
+
+Add a Glass effect layer that replaces Fluted Glass: reeded (round or sharp flutes), hammered, pyramid, hex or frosted glass where every cell is a small lens, the scene blurs with its distance behind the glass (uniform or from the depth map, through the shared blur pyramid), and thin rims, grooves, frost, dispersion and tint make it read as glass. Six starting styles (Reeded, Frosted Reeded, Hammered, Pyramid, Hex, Frosted). The Blur layer now shares the same blur pyramid module.

.changeset/gradient-map-keyframes.md

@@ -0,0 +1,5 @@
+---
+"@basementstudio/shader-lab": minor
+---
+
+Gradient Map ramps can be animated. Timeline tracks with the new `gradient` value type blend between two ramps: stops glide when both ramps have the same number of stops, and when the counts differ the shorter ramp gains stops that leave its look unchanged, so the in-between frames stay a smooth crossfade. Each keyframe keeps its easing. Scenes without ramp tracks render exactly as before.

.changeset/gradient-map-layer.md

@@ -0,0 +1,5 @@
+---
+"@basementstudio/shader-lab": minor
+---
+
+Add a Gradient Map effect layer that recolors by tone with an editable ramp, presets, Amount and Invert. It renders identically in the editor, exports and the runtime package, and can be scoped with groups and masks. The global Color Map is unchanged.

.changeset/grain-layer.md

@@ -0,0 +1,5 @@
+---
+"@basementstudio/shader-lab": minor
+---
+
+Add a Grain effect layer: photographic film grain for photos and video, with Amount, Size in document pixels, Roughness, Clumping, Chroma that leaves brightness unchanged, a tonal Response that favors the midtones like film, and Soft Light, Overlay or Add blending. Speed 0 holds one pattern; above 0 it steps to a new pattern 24 times a second like film. Five starting styles (Fine 35mm, Color Negative, 16mm, Pushed, Digital Noise). It renders identically in the editor, exports and the runtime package.

.changeset/group-drag-drop.md

@@ -0,0 +1,4 @@
+---
+---
+
+Fix editor layer dragging so dropping into or out of a group updates membership and order together. Add destination indicators, subtree movement, cancellation, and edge scrolling. This editor-only change does not require a package release.

.changeset/isolated-group-rendering.md

@@ -0,0 +1,5 @@
+---
+"@basementstudio/shader-lab": patch
+---
+
+Add isolated, nested group rendering to the internal renderer frame contract. Group children render against transparent targets before the combined result is blended into the parent. Existing flat public shader configs retain their behavior; editor grouping controls and persisted groups follow separately.

.changeset/layer-masks.md

@@ -0,0 +1,5 @@
+---
+"@basementstudio/shader-lab": minor
+---
+
+Add reusable layer masks: linear and radial gradients, ellipse, rectangle and brush on any layer or group. Masks either limit an effect or cut coverage, support invert and feather (measured from the true shape edge, so stretched ellipses soften evenly), and render identically in the editor, PNG/video export and the runtime package.

.changeset/lumen-print-layer.md

@@ -0,0 +1,5 @@
+---
+"@basementstudio/shader-lab": minor
+---
+
+Add a Lumen Print effect layer: an analog photographic print with sun-print toning through an editable palette, solarization with edge lines, diffusion and halation, highlights washed into paper, burned borders and grain. Six starting styles (Lumen, Cyanotype, Burned, Sabattier, Washed, Eroded). It renders identically in the editor, exports and the runtime package.

.changeset/mcp-layer-masks.md

@@ -0,0 +1,5 @@
+---
+"@basementstudio/shader-lab-mcp": minor
+---
+
+`update_layer` accepts a `mask`: linear, radial, ellipse, rectangle or brush shapes in centered shorter-edge composition units, scoped to the effect or the content, with invert, rotation and feather. Pass `null` to reset it.

.changeset/mesh-gradient-v2.md

@@ -0,0 +1,5 @@
+---
+"@basementstudio/shader-lab": minor
+---
+
+Mesh Gradient gets eight new smooth presets (Peach, Lagoon, Dusk, Citrus, Mint, Aurora, Ink, Basement), a Simple distortion mode with Softness, Warp and Detail, and motion styles (Drift, Breathe, Swirl, Flow) that loop seamlessly over the timeline duration. Passes receive the timeline duration through a new `updateTimelineDuration` hook. Saved gradients keep their exact look: they load in Advanced mode with their Original motion.

.changeset/outline-layer.md

@@ -0,0 +1,5 @@
+---
+"@basementstudio/shader-lab": minor
+---
+
+Add an Outline effect layer on a jump-flood distance field: solid, double, dashed or scalloped cloud outlines around text, cutouts or dark and light shapes, with offset (negative draws inside), width, repeated rings, fill between shape and outline, and a line-only mode. Six starting styles (Stroke, Cloud, Sticker, Contour Rings, Cut Line, Double).

.changeset/pattern-motif-palette.md

@@ -0,0 +1,5 @@
+---
+"@basementstudio/shader-lab": minor
+---
+
+Pattern motifs can recolor their SVG files. With Color Mode set to Motif colors, the editor lists every color found in the SVG motifs under File colors, and each one can be replaced, the same way SVG shapes work. Image motifs and projects without a palette render exactly as before.

.changeset/pattern-motifs.md

@@ -0,0 +1,5 @@
+---
+"@basementstudio/shader-lab": minor
+---
+
+Pattern layers can use your own motifs: set `preset: "custom"` and list up to ten images or SVGs in `patternAssets`, ordered from the lightest tones to the darkest. Each motif takes an equal band of tones, and Invert reverses the order. The new `colorMode: "original"` keeps each motif's own colors; the other color modes use the motif's alpha as its shape.

.changeset/photocopy-layer.md

@@ -0,0 +1,5 @@
+---
+"@basementstudio/shader-lab": minor
+---
+
+Add a Photocopy effect layer: crushed toner over paper with Threshold, Contrast and Generations (a copy of a copy), uneven fill, toner speckle, drum streaks, misregistration, grain and fold creases, any toner and paper color or transparent paper. Five starting styles (Office Copy, Zine, Fax, Blueprint Copy, Pink Flyer).

.changeset/photographic-cell-paint.md

@@ -0,0 +1,5 @@
+---
+"@basementstudio/shader-lab": minor
+---
+
+Add persisted Paint selection to Photographic Cells. Painted coverage shares cell geometry and perimeter outlines with automatic regions, stays anchored in composition space, and reuses its GPU texture while the source animates.

.changeset/photographic-cell-regions.md

@@ -0,0 +1,5 @@
+---
+"@basementstudio/shader-lab": minor
+---
+
+Add coherent Photographic Cells regions with separate region and cell sizes, image-guided or seeded selection, and None/Perimeter/Every Cell outline modes. Preserve saved cell layouts and contour settings while new layers start with connected regions and fine perimeter outlines.

.changeset/photographic-cells.md

@@ -0,0 +1,5 @@
+---
+"@basementstudio/shader-lab": minor
+---
+
+Add Photographic Cells with light/dark/random selection, irregular rectangular cells, full-resolution photographic interiors, alpha cutouts, and optional outlines. Support the effect in runtime configs and grouped compositions. Apply user-curated editor defaults to new Displaced Rings layers while preserving saved settings and renderer fallbacks.

.changeset/plotter-rework.md

@@ -0,0 +1,5 @@
+---
+"@basementstudio/shader-lab": minor
+---
+
+Rework Plotter into a pen-plotter drawing: Hatch (crosshatch layers by tone), Flow (dense lines following the forms), Contour (smooth tone contours), Squiggle (rows that wave in the darks), Spiral (one continuous spiral whose line thickens with tone) and Stipple (dots by density), with pen width, pressure, wobble, ink bleed, ink, source or three pens, paper color, grain or transparent paper, and seven starting styles. The original parameters and their defaults are kept, so saved plotter layers still open.

.changeset/relief-layer.md

@@ -0,0 +1,5 @@
+---
+"@basementstudio/shader-lab": minor
+---
+
+Add a Relief effect layer that embosses or debosses the image into a lit surface, with height from luminance, scene depth or a cutout's alpha, Depth, Bevel, light angle, elevation and ambient, a single material or the source colors with specular highlights, grain, and optional parallel or radial engraving. Five starting styles (Silver Plate, Letterpress, Blind Emboss, Gold Foil, Source Relief). It renders identically in the editor, exports and the runtime package.

.changeset/ring-shapes.md

@@ -0,0 +1,5 @@
+---
+"@basementstudio/shader-lab": minor
+---
+
+Displaced Rings gains ring shapes (Circle, Triangle, Square, Polygon with Sides) alongside the Full/Half cut, per-band Rotation Jitter and Width Jitter driven by Seed, and Lines: thin strokes on the band boundaries that can keep repeating across the canvas beyond the outer band, with width, color and opacity. New controls default to off, so existing layers and saved projects look the same.

.changeset/shape-layers.md

@@ -0,0 +1,5 @@
+---
+"@basementstudio/shader-lab": minor
+---
+
+Add a Shape source layer: ellipse, rectangle, triangle, polygon, star, ring and blades silhouettes with color, outline, softness and canvas handles. Renders identically in the editor, exports and the runtime package, and combines with blend modes and layer masks.

.changeset/signal-rot-layer.md

@@ -0,0 +1,5 @@
+---
+"@basementstudio/shader-lab": minor
+---
+
+Add a Signal Rot effect layer for scanner drag and decaying signal: held streaks, snaking wobble, uneven scan speed, torn bands with paper dropouts, chroma drift, crushed levels and line noise, frozen or animated. Three starting styles (Scanner Drag, Signal Rot, Torn Scan). It renders identically in the editor, exports and the runtime package.

.changeset/stable-artboard.md

@@ -0,0 +1,5 @@
+---
+"@basementstudio/shader-lab": minor
+---
+
+Add a stable artboard: any composition aspect other than Screen (adaptive) is a fixed document size, centered in the editor and letterboxed in the community player, so framing, masks and text no longer follow the window. Screen mode and older scenes are unchanged.

.changeset/svg-shapes.md

@@ -0,0 +1,5 @@
+---
+"@basementstudio/shader-lab": minor
+---
+
+Shape layers can draw an SVG: set `shape: "svg"` and give the layer an image `asset` pointing at the file. The SVG becomes a signed distance field, so its edges stay sharp at any size and Softness and Outline work as on the built-in shapes. `svgColorMode: "original"` keeps the file's colors, and `svgPalette` (a JSON map from a file color to a new color) recolors them; `"single"` fills the shape with `color`.

.changeset/text-editing.md

@@ -0,0 +1,5 @@
+---
+"@basementstudio/shader-lab": minor
+---
+
+Text layers support multiline content, explicit alignment, line height, rotation and font sizes down to 8px, rendered identically in the editor and runtime. The editor adds in-place editing by double-click and canvas handles for position, rotation and size.

.changeset/text-texture-resize.md

@@ -0,0 +1,5 @@
+---
+"@basementstudio/shader-lab": patch
+---
+
+Text layers redraw at the right size after the canvas or composition is resized. The text texture kept its first size on the GPU, so a resized canvas showed the text scaled down.

.changeset/three-185.md

@@ -0,0 +1,5 @@
+---
+"@basementstudio/shader-lab": minor
+---
+
+Require three 0.185: the `three` peer dependency is now `^0.185.0` (was `^0.183.0`). Projects still on three 0.183 need to update three together with this release.

.changeset/threshold-colors.md

@@ -0,0 +1,5 @@
+---
+"@basementstudio/shader-lab": minor
+---
+
+Add darkColor and lightColor to Threshold, retaining black/white fallbacks. Recolor the existing threshold field without another render pass; softness, noise, inversion and source coverage retain their behavior.

.changeset/transparent-media-bounds.md

@@ -0,0 +1,5 @@
+---
+"@basementstudio/shader-lab": patch
+---
+
+Support transparent borders for contained image and video layers with `params.transparentBounds: true`. Existing runtime configs without the setting retain black borders.

.changeset/transparent-text-defaults.md

@@ -0,0 +1,4 @@
+---
+---
+
+New editor text uses normal composition over a transparent background. Clarify the background opacity control and preserve the solid fallback for saved text that omits the setting. This editor-only change does not require a package release.

.changeset/v3-render-performance.md

@@ -0,0 +1,5 @@
+---
+"@basementstudio/shader-lab": patch
+---
+
+Render the V3 effect layers with less GPU work and no visual change: Connected Dots reads its dot sites from a per-cell pre-pass (about 9x faster at 1080p), and Displaced Rings, Glass, Blur, Plotter, Signal Rot, Outline, Photocopy, Erosion, Lumen Print, Dot Grid and Relief skip work their current settings don't use. Blob Tracking stops requesting continuous rendering once its output settles on a still image, and Annotations only re-read their Edges field when the image below changes. Outline, Flares and Relief no longer read the wrong texture when their shader compiles before the first frame.

.gitattributes

@@ -17,3 +17,5 @@
 #   - Prevents merge conflicts caused by line ending differences
 
 * text=auto eol=lf
+*.hdr binary
+*.wasm binary