refactor(engine)!: GPU pass fusion — record-then-plan pipeline with fused shader passes

.claude/skills/beutl-agent-source-grounding/SKILL.md

@@ -32,7 +32,7 @@ If the user explicitly forbids source-code reading, do not use this skill. Recor
 | Shape sizing and local drawing | `src/Beutl.Engine/Graphics/Shapes/Shape.cs`, `RectShape.cs`, `RoundedRectShape.cs`, `EllipseShape.cs` | Bounds size, stroke inflation, and draw origin. |
 | GeometryShape geometry positioning | `src/Beutl.Engine/Graphics/Shapes/Shape.cs` (`OnDraw`, `MeasureCore`) | The `-shapeBounds.Position` normalization is commented out and `MeasureCore` returns only `geometry.Bounds.Size`, so a path is drawn offset by `geometry.Bounds.Position`. Author paths around `(0,0)` or `measure_object_bounds` + compensate. Closed Pen-only paths render when the `Pen` brush/thickness and path bounds are valid. |
 | Transform numeric meaning | `src/Beutl.Engine/Graphics/Transformation/TranslateTransform.cs`, `ScaleTransform.cs`, `TransformGroup.cs`, `CanonicalTransformLayout.cs` | Whether values are absolute positions, offsets, percentages, or ordered transform children. `ScaleTransform` values are percentages (`100` = 1x), not normalized multipliers. |
-| Render-node transform and bounds behavior | `src/Beutl.Engine/Graphics/Rendering/TransformRenderNode.cs`, `src/Beutl.Engine/Graphics/Rendering/RenderNodeProcessor.cs`, `src/Beutl.Engine/Graphics/Rendering/RenderNodeContext.cs` | Operation bounds aggregation, bounds transformation, hit-test inversion, and density rescale. |
+| Render-node transform and bounds behavior | `src/Beutl.Engine/Graphics/Rendering/TransformRenderNode.cs`, `src/Beutl.Engine/Graphics/Rendering/RenderNodeContext.cs`, `src/Beutl.Engine/Graphics/Rendering/Planning/RenderRequestExecutor.cs` | Operation bounds aggregation, bounds transformation, hit-test inversion, and density rescale. |
 | Toolkit examples and generated snippets | `src/Beutl.AgentToolkit/Schema/SchemaGenerator.cs`, `CompositionTemplates.cs` | How toolkit examples choose translate values, animation discriminators, and reusable object shapes. |
 | Quality analyzer assumptions | `src/Beutl.AgentToolkit/Rendering/QualityAnalyzer.cs` | How text/plate bounds, centers, foreground rect dominance, and typography overload are estimated. |
 | Still and motion verification | `src/Beutl.AgentToolkit/Rendering/StillRenderer.cs`, `MotionVariationAnalyzer.cs` | Which warnings should block export and how frame coverage is computed. |

.claude/skills/beutl-filter-effect/SKILL.md

@@ -235,7 +235,65 @@ Create your own resource files inside the extension project, or pass a literal s
 
 ### SKSL (SkiaShaderLanguage) pattern
 
-Compile the shader in the static constructor and apply it through `CustomEffect`:
+> **Prefer `context.Shader(...)` for per-pixel work.** A `ShaderDefinition<TState>` recorded through
+> `FilterEffectContext.Shader` is a typed fragment the planner can fuse with neighbouring shader stages
+> into one GPU pass. `SKSLScriptEffect` also records supported scripts declaratively and exposes them to
+> the fusion planner: `half4 main(float2 fragCoord)` becomes `WholeSource`, which can head a fusion run
+> and absorb later per-pixel work but not upstream operations, while `half4 apply(half4 color)` becomes
+> fully fusable `CurrentPixel` work. Scripts
+> that cannot be represented declaratively—including reserved `__beutl*`/`fe*_*` names, multi-declarator
+> uniforms, non-literal array lengths, or uniform types without a canonical zero value—automatically fall
+> back to the legacy `CustomEffect` path, so existing scripts do not break. Using `CustomEffect`
+> directly remains the right tool for raw-target allocation, sampling, or drawing, but it is opaque to the
+> planner and forms a fusion boundary.
+
+| Authoring construct | Fusion behavior | Limit or boundary |
+|---|---|---|
+| `CurrentPixel` shaders; immutable opacity | Fusable | May join a compatible fusion run. |
+| `WholeSource` shaders | Can be the head of a fusion run | May absorb later per-pixel work; upstream work cannot fold into it. |
+| Skia image filters (`Blur`, `DropShadow`, `Dilate`, `Erode`); `CustomEffect`; Geometry; 3D; raw canvas access | Not fusable | Forms a fusion boundary. |
+| Sampler/child budget | Portable: 12; Vulkan/Metal: 12 | The implicit `src` sampler consumes one slot; exceeding the cap falls back to a standalone pass. |
+
+Declare the shader once as a `static readonly ShaderDefinition<TState>` and record a call of it per frame.
+The definition holds the shape — source, uniform and resource bindings — and `.Call(state)` supplies this
+frame's values, so the planner sees a typed fragment it can fuse:
+
+```csharp
+public partial class MosaicEffect : FilterEffect
+{
+    private static readonly ShaderDefinition<Size> s_definition =
+        ShaderDefinition<Size>.WholeSource(
+            """
+            uniform shader src;
+            uniform float2 tileSize;
+
+            half4 main(float2 fragCoord) {
+                float2 blockIndex = floor(fragCoord / tileSize);
+                float2 sampleCoord = blockIndex * tileSize + tileSize * 0.5;
+                return src.eval(sampleCoord);
+            }
+            """,
+            RenderBoundsContract.Identity,
+            static bindings => bindings.Uniform("tileSize", static tileSize => tileSize.ToVector2()));
+
+    public override void ApplyTo(FilterEffectContext context, FilterEffect.Resource resource)
+    {
+        var r = (Resource)resource;
+        context.Shader(s_definition.Call(r.TileSize));
+    }
+}
+```
+
+The definition callback must be pure and non-capturing: its `MethodInfo` is the shader's structural
+identity, so two frames that differ only in `tileSize` reuse one compiled program. If several effects share
+one source, parse it once with `SkslSource.WholeSource(...)` or `SkslSource.CurrentPixel(...)` and pass the
+result to the matching factory instead of the raw string.
+
+### The `CustomEffect` fallback
+
+Reach for this only when the work cannot be expressed declaratively — raw target allocation, sampling
+outside the declared input, or drawing onto the target. It is opaque to the planner and forms a fusion
+boundary. The same mosaic, written the imperative way:
 
 ```csharp
 public partial class MosaicEffect : FilterEffect

.github/workflows/dotnet.yml

@@ -1,4 +1,4 @@
-name: .NET
+name: .NET
 
 on:
   push:
@@ -52,6 +52,34 @@ jobs:
           # SwiftShader Vulkan ICD fails to load; see GpuGoldenSuiteCanaryTests.
           BEUTL_REQUIRE_GPU: "1"
 
+      # A validation error names API misuse the driver is not required to diagnose - a render pass instance
+      # begun inside another, a handle submitted to a device that never created it - so a suite that runs
+      # green while reporting one has already entered undefined behaviour. The layer stays off for the run
+      # above because it costs time on all 7,000 tests and is only meaningful for the GPU-backed ones; this
+      # step turns it on for exactly those. VulkanTestEnvironment/GpuTestEnvironment compare the validation
+      # log around every render-thread invocation, so an error fails the test that reported it, and
+      # VulkanValidationGateTests fails if the layer was requested but did not load - a gate that cannot
+      # observe anything must not pass quietly.
+      - name: Install Vulkan validation layers
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y --no-install-recommends vulkan-validationlayers
+
+      # KnownVulkanSkiaLayoutInterop is excluded: Skia and the backend track the same image's layout
+      # independently and drift apart, which validation reports as InvalidImageLayout. Closing it needs a
+      # way to read back or command the layout Skia holds, which SkiaSharp 3.119 does not expose. Those
+      # tests still run in the step above; see TestCategories.KnownVulkanSkiaLayoutInterop and issue #2263,
+      # on whose close both TestCategory!= clauses below come out.
+      - name: GPU tests under Vulkan validation
+        run: |
+          dotnet test tests/Beutl.UnitTests/Beutl.UnitTests.csproj --no-build -f net10.0 \
+            --filter "(TestCategory=GpuPassFusionGpu|FullyQualifiedName~VulkanValidationGateTests|FullyQualifiedName~GpuGoldenSuiteCanaryTests)&TestCategory!=KnownVulkanSkiaLayoutInterop"
+          dotnet test tests/Beutl.Graphics3DTests/Beutl.Graphics3DTests.csproj --no-build -f net10.0 \
+            --filter "TestCategory!=KnownVulkanSkiaLayoutInterop"
+        env:
+          BEUTL_REQUIRE_GPU: "1"
+          BEUTL_VULKAN_VALIDATION: "1"
+
       - name: Merge coverage reports
         # Every test project now collects coverage (coverlet.collector is shared via
         # tests/Directory.Build.props), so dotnet test emits one cobertura file per test

.specify/memory/constitution.md

@@ -22,7 +22,7 @@ Beutl targets `net10.0` and `net10.0-windows`. Both targets must keep building.
 
 ### III. Test-First with NUnit
 
-- Test framework is NUnit + Moq. Tests are organized under `tests/` in per-area projects (e.g. `tests/Beutl.UnitTests/`, `tests/Beutl.Graphics3DTests/`, `tests/SourceGeneratorTest/`, `tests/Beutl.FFmpegIpc.Tests/`). `tests/Beutl.Graphics3DTests/` is a Vulkan-gated NUnit suite that self-skips when no Vulkan device is available.
+- Test framework is NUnit + Moq. Tests are organized under `tests/` in per-area projects (e.g. `tests/Beutl.UnitTests/`, `tests/Beutl.PublicApiContractTests/`, `tests/Beutl.Graphics3DTests/`, `tests/SourceGeneratorTest/`, `tests/Beutl.FFmpegIpc.Tests/`). `tests/Beutl.PublicApiContractTests/` is the non-friend compile gate for public authoring APIs; `tests/Beutl.Graphics3DTests/` is a Vulkan-gated NUnit suite that self-skips when no Vulkan device is available.
 - New logic in `src/` is incomplete without an accompanying test.
 - Benchmarks (`tests/Beutl.Benchmarks`, `tests/Beutl.FFmpegBenchmarks`) use BenchmarkDotNet and are excluded from regular `dotnet test` runs.
 - CI quality gate: `dotnet test Beutl.slnx -f net10.0 --settings coverlet.runsettings` must pass, with the coverage threshold configured in [`.github/workflows/dotnet.yml`](../../.github/workflows/dotnet.yml) honored.

.specify/scripts/bash/common.sh

@@ -264,29 +264,43 @@ get_feature_paths() {
 
     # Resolve feature directory.  Priority:
     #   1. SPECIFY_FEATURE_DIRECTORY env var (explicit override)
-    #   2. .specify/feature.json "feature_directory" key (persisted by /speckit.specify)
-    #   3. Branch-name-based prefix lookup (legacy fallback)
-    local feature_dir
+    #   2. Branch-name prefix lookup, when it names a feature directory that exists
+    #   3. .specify/feature.json "feature_directory" key (persisted by /speckit.specify)
+    #
+    # The branch outranks the pin because feature.json is a single checked-in value shared by every
+    # feature in the repo: whichever feature wrote it last would otherwise redirect the analysis,
+    # planning and task scripts on every other feature's branch to its own directory, silently.
+    # The pin still resolves a branch whose name says nothing about which feature it belongs to,
+    # which is the case it was added for.
+    local feature_dir=''
     if [[ -n "${SPECIFY_FEATURE_DIRECTORY:-}" ]]; then
         feature_dir="$SPECIFY_FEATURE_DIRECTORY"
         # Normalize relative paths to absolute under repo root
         [[ "$feature_dir" != /* ]] && feature_dir="$repo_root/$feature_dir"
-    elif [[ -f "$repo_root/.specify/feature.json" ]]; then
-        # Shared, set -e-safe parser: jq -> python3 -> grep/sed. Returns empty on
-        # missing/unparseable/unset so we fall through to the branch-prefix lookup.
-        local _fd
-        _fd=$(read_feature_json_feature_directory "$repo_root")
-        if [[ -n "$_fd" ]]; then
-            feature_dir="$_fd"
-            # Normalize relative paths to absolute under repo root
-            [[ "$feature_dir" != /* ]] && feature_dir="$repo_root/$feature_dir"
-        elif ! feature_dir=$(find_feature_dir_by_prefix "$repo_root" "$current_branch"); then
-            echo "ERROR: Failed to resolve feature directory" >&2
+    else
+        local _branch_dir=''
+        if ! _branch_dir=$(find_feature_dir_by_prefix "$repo_root" "$current_branch"); then
             return 1
         fi
-    elif ! feature_dir=$(find_feature_dir_by_prefix "$repo_root" "$current_branch"); then
-        echo "ERROR: Failed to resolve feature directory" >&2
-        return 1
+
+        if [[ -d "$_branch_dir" ]]; then
+            feature_dir="$_branch_dir"
+        else
+            # Shared, set -e-safe parser: jq -> python3 -> grep/sed. Returns empty on
+            # missing/unparseable/unset so we fall back to whatever the branch named.
+            local _fd
+            _fd=$(read_feature_json_feature_directory "$repo_root")
+            if [[ -n "$_fd" ]]; then
+                feature_dir="$_fd"
+                # Normalize relative paths to absolute under repo root
+                [[ "$feature_dir" != /* ]] && feature_dir="$repo_root/$feature_dir"
+            elif [[ -n "$_branch_dir" ]]; then
+                feature_dir="$_branch_dir"
+            else
+                echo "ERROR: Failed to resolve feature directory" >&2
+                return 1
+            fi
+        fi
     fi
 
     # Use printf '%q' to safely quote values, preventing shell injection

AGENTS.md

@@ -13,7 +13,7 @@ Beutl is a cross-platform video editing / compositing application built on Avalo
 
 - License: the main app is **MIT**; `Beutl.FFmpegWorker` alone is **GPL-3.0-or-later** (a separate process)
 - UI: Avalonia (XAML + ViewModel)
-- Tests: NUnit + Moq under `tests/` (per-area projects, e.g. `tests/Beutl.UnitTests/`, `tests/Beutl.Graphics3DTests/`, `tests/SourceGeneratorTest/`, `tests/Beutl.FFmpegIpc.Tests/`). `tests/Beutl.Graphics3DTests/` is a Vulkan-gated NUnit suite that self-skips when no Vulkan device is available — see `tests/CLAUDE.md`
+- Tests: NUnit + Moq under `tests/` (per-area projects, e.g. `tests/Beutl.UnitTests/`, `tests/Beutl.PublicApiContractTests/`, `tests/Beutl.Graphics3DTests/`, `tests/SourceGeneratorTest/`, `tests/Beutl.FFmpegIpc.Tests/`). `tests/Beutl.PublicApiContractTests/` is the non-friend compile gate for public authoring APIs; `tests/Beutl.Graphics3DTests/` is a Vulkan-gated NUnit suite that self-skips when no Vulkan device is available — see `tests/CLAUDE.md`
 - E2E / headless-UI tests: `tests/Beutl.E2ETests/` (library-level) and `tests/Beutl.HeadlessUITests/` (drives the real shell, the sole test referencing `src/Beutl`) on `Avalonia.Headless.NUnit`, with shared helpers in `tests/Beutl.Testing.Headless/`. They run on headless CI without xvfb or a GPU — see `tests/CLAUDE.md`
 - Build: Nuke (`nukebuild/`) or `dotnet` directly
 

Beutl.slnx

@@ -36,6 +36,7 @@
     <Project Path="tests\Beutl.UnitTests\Beutl.UnitTests.csproj" />
     <Project Path="tests\Beutl.E2ETests\Beutl.E2ETests.csproj" />
     <Project Path="tests\Beutl.HeadlessUITests\Beutl.HeadlessUITests.csproj" />
+    <Project Path="tests\Beutl.PublicApiContractTests\Beutl.PublicApiContractTests.csproj" />
     <Project Path="tests\Beutl.Testing.Headless\Beutl.Testing.Headless.csproj" />
     <Project Path="tests\SourceGeneratorTest\SourceGeneratorTest.csproj" />
     <File Path="tests\ArtifactProvider.cs" />

docs/ai-workflow/resolution-independent-rendering.md

@@ -12,7 +12,7 @@ filter effects, brushes, and shaders.
 | Scale | Type | Meaning |
 |---|---|---|
 | **Output scale `s_out`** | `Renderer.OutputScale` / `RenderNodeContext.OutputScale` | the final target only: device pixels per logical unit at the root. `1.0` = logical == device. |
-| **Effective scale** | `RenderNodeOperation.EffectiveScale` | the supply density an op's pixels actually exist at. Vector ops are `Unbounded`; bitmap ops report `At(scale)`. |
+| **Effective scale** | `RenderFragmentHandle.EffectiveScale` (also on `RenderFragmentMetadata`) | the supply density a recorded fragment's pixels actually exist at. Vector fragments are `Unbounded`; bitmap fragments report `At(scale)`. |
 | **Working scale `w`** | `FilterEffectContext.WorkingScale` (+ `RenderNodeContext.ResolveWorkingScale`) | the density a buffer-allocating boundary runs at, negotiated from the inputs' supply densities (falling back to `s_out` for vector-only inputs), capped by `MaxWorkingScale`. There is no per-effect policy knob. |
 
 ## What most authors need to do: nothing
@@ -52,7 +52,11 @@ the CTM handles it, and a manual `× w` would double-scale and regress the resul
   **no `ResolutionPolicy`**: the earlier `Inherit`/`ClampToOutput`/`Oversample(k)`/`PreserveSource` policy
   was removed because no built-in needed a non-default value. An effect that genuinely needs a different
   working scale (clamp-to-output for perf, oversample for SSAA) returns a `FilterEffectRenderNode` subclass from
-  `FilterEffect.Resource.CreateRenderNode()` and overrides `Process` to compute its own `w`.
+  `FilterEffect.Resource.CreateRenderNode()` and overrides `GetWorkingScaleContract()` to return a
+  `RenderScaleContract`. Overriding `Process` is for an effect that needs different topology or lowering, not
+  merely a different density; see
+  [`effect-scale-contract.md`](../specs/003-resolution-independent-pipeline/contracts/effect-scale-contract.md)
+  for a worked example.
 - **Bitmap sources.** A decoded image/video op reports its decoded density as `EffectiveScale.At(...)`,
   distinct from its logical footprint. Mixed-scale compositing resamples off-target bitmaps via
   `ImmediateCanvas.DrawRenderTargetScaled` / `DrawSurfaceScaled` (Mitchell). 003 ships only this seam; the