V3: reusable layer masks (gradient, ellipse, rectangle, brush)

.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/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/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/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/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, and render identically in the editor, PNG/video export and the runtime package.

.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/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.

.github/workflows/ci.yml

@@ -5,6 +5,7 @@ on:
     branches:
       - main
       - git-chad/shader-lab-v3-plan
+      - git-chad/v3-*
   push:
     branches:
       - main
@@ -50,3 +51,24 @@ jobs:
       - name: Ensure changeset exists for PR changes
         if: github.event_name == 'pull_request'
         run: bunx changeset status --since=origin/${{ github.base_ref }}
+
+  composition:
+    # Linux Chromium/SwiftShader currently drops its GPU instance during these
+    # texture-backed shader compilations. Keep the full GPU checks on macOS.
+    runs-on: macos-14
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v4
+      - uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+      - run: bun install --frozen-lockfile
+      - run: bunx playwright install chromium
+      - run: bun run test:composition
+      - name: Upload rendered compositions
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: composition-actuals
+          path: .context/composition-test/
+          if-no-files-found: ignore

AGENTS.md

@@ -0,0 +1,5 @@
+# Shader Lab development instructions
+
+Before deciding how a shader behaves or looks, open the relevant images listed in [V3-VISUAL-REFERENCES.md](V3-VISUAL-REFERENCES.md). This is an explicit user requirement. Read that guide for reference locations, visual goals, and review criteria; a prose description or passing GPU tests does not replace looking at the images.
+
+Keep prototype acceptance distinct from completing the visual direction in V3-ROADMAP.md. Preserve the stacked PR workflow; do not merge V3 into main until the plan is complete.