[joshistoast]

Summary

Adds Clarity, Texture and Dehaze as non-destructive adjustments on raster layers and raster groups, using the same kernels as the backend nodes from #9891.

• Matches the nodes: results are byte-identical to the backend nodes run on the layer's alpha-trimmed pixels, so they don't depend on the bbox or crop.
• Off the main thread: a background worker computes them. While a job runs, the canvas shows only the colour adjustments (an interim) and then installs the exact result. A layer row shows a delayed spinner while computing, or a warning when an adjustment can't run (over 16.8 MP, over the memory budget, or a worker error).
• Exact or refused: generation, export, gallery save, Merge Down, rasterize, PSD export, extract, filter and Select Object inputs, crop, copy and painting all either use the exact adjusted pixels or refuse with a message naming the layer and the reason. A spatial adjustment is never silently dropped.
• Settings: Amount runs from −200 to 200. Size uses a log scale: 4–1000 px for Clarity, 1–100 px for Texture.

Shares canvas schema v5 with the Noise adjustment (#9933).

Related Issues / Discussions

Closes #9813
Builds on #9891 (backend nodes) and #9933 (Noise adjustment, schema v5).

QA Instructions

Automated (Node 22.14, pnpm 10):

• pnpm check:release passes: lint, 11,179 unit tests, 3,345 browser tests, fixtures, both performance gates, the project-file journey and accessibility journeys.
• Python: pytest tests/backend/image_util passes, including the shared parity fixture that pins the TS kernels to the Python output.

Manual, on the mock backend:

1. Add a raster layer and paint on it. Right-click → Add adjustment → Clarity, Texture or Dehaze.
2. Scrub Amount: the canvas updates within about 0.1 s at 1024². For example, Dehaze +200 lifts a 127 grey to 136, which matches the worker output.
3. Toggle the entry off and on: pixels return to the original values and back.
4. Reload: the entries persist (the document is written as v5).

Not yet done: a real-backend comparison of a canvas result with the node on the same alpha-trimmed image.

Screenshots, on the mock backend:

Add adjustment menu on a raster layer:

Texture +80, Clarity +120 and Dehaze +60 on one layer, with Clarity selected:

Dehaze settings and hint:

Before and after, with the three adjustments off, then on:

Row status: the spinner while a job runs on a 3072² layer, and the warning with its tooltip on a 4100² layer:

Review

Resolved findings:

• Cooldown cancellations: cooldown no longer cancels the exact jobs that generation waits on.
• Painting refusals: painting on a layer whose adjustment can't run now gets a specific message.
• Size-limit retries: an oversized layer no longer retries on every slider tick.
• Group status: a group's status no longer flips between the canvas and overview reads.
• Stale warnings: a hidden layer's warning clears once its adjustment is removed.

Known limits:

• Offscreen thumbnails: offscreen layers that have never been drawn show only the colour adjustments in their thumbnail.
• PSD groups: PSD export approximates spatial group stacks per layer (documented).
• Previews in groups: while a filter preview or floating selection sits inside a spatial group, the canvas and the overview each compute the group.
• Large layers: layers over 16.8 MP are refused; tiled evaluation is a follow-up.

Compatibility / Rollout

• Schema: documents holding any of the three adjustments, enabled or not, save as canvas schema v5. This is shared with Noise (feat(canvas): noise adjustment for film grain #9933), so older builds refuse those documents instead of silently dropping the adjustment stack. Documents without them keep their current version.

• Bundle size: measured against feat(canvas): noise adjustment for film grain #9933's build:

  • about +22 KB raw startup script on editor routes and +30 KB on canvas;
  • +2.4 KB of locale strings;
  • +7.7 KB when the canvas widget opens;
  • no new requests.

  The browser baseline re-records only byte figures and startup-module lists; timings are unchanged. The kernels load lazily in a 9 KB worker chunk.

• Memory: worker scratch (at most about 400 MB, one job at a time per engine) is outside the raster memory budget. The pixel buffer each job uses is reserved.

Checklist

• The PR has a short but descriptive title, suitable for a changelog
• Meaningful regression coverage added / updated where needed; obsolete tests/code removed
• Persisted-state and API changes include required migrations / compatibility validation
• Relevant performance/efficiency opportunities considered; material claims have evidence
• Material review findings resolved and relevant checks rerun
• Documentation added / updated (if applicable)
• Updated What's New copy (if doing a release after this PR)

[JPPhoto]

Merge blockers:

1. Must fix - Raster-to-control conversion and copy drop enabled spatial adjustments. invokeai/frontend/webv2/src/workbench/widgets/layers/layerOps.ts:483 clones the raw source for control layers. The context menu reaches this path for both conversion and copy at invokeai/frontend/webv2/src/workbench/widgets/layers/LayerContextMenu.tsx:473 and :730. A converted layer loses its adjustment stack; a copied control layer receives unadjusted pixels. Bake the exact result or refuse the action when evaluation fails. If skipped, control inference can use pixels different from the displayed layer. This happens whenever an affected layer has an enabled spatial adjustment. Conversion can be undone, but generated results from the copied pixels must be rerun. Add coverage that asserts exact pixels or refusal for both actions.

Other findings/issues:

2. Should fix - The parity test does not enforce the byte-identical claim. invokeai/frontend/webv2/src/workbench/canvas-engine/render/spatial/evaluateSpatialSteps.test.ts:51 allows up to 1 byte of difference and up to 1% differing visible channels at lines 57-58. Tighten the assertion to exact bytes, or revise the claim to state the accepted tolerance. Otherwise small output drift can pass while the PR still claims exact backend parity. Add a test that enforces the chosen contract.

[JPPhoto]

Good!