[joshistoast]

Summary

A new control layer used to be an empty shell with a model guessed by name, a Filter button that stayed disabled until the layer had pixels, and no help choosing a ControlNet or the preprocessor that goes with it.

Control layers are now type-first. The Properties panel has fixed rows (Image, Type, Detection, Model, Weight, Steps, Priority) whose values change but whose positions never move. The user says what the image should control (Pose, Depth, Edges, Soft edges, Line art, Sketch, Color, Tile); the app picks the detector and resolves the model (explicit pick, remembered pick for the base and type, the only dedicated model, a Union model that covers the type, or asks), runs detection in the background, keeps the original beside the detected map so detection can be re-run, and explains each choice in one caption line.

• Entry points: Layers "+" adds an empty control layer and opens its Properties; gallery images get "Use as Control" (fills the selected empty control layer, else creates one); raster layers get "Use as control layer"; a control image dropped on the canvas fills an empty layer.
• Layer rows read "Type · Detector · weight", spin while a detector runs, and warn on issues. Invoke shows the issue count and jumps to the first offending layer.
• The canvas shows a drop hint over an empty control layer, a status chip while detection runs, and an Original / Map / Overlay view switch for a detected layer.
• Empty or untyped control layers only warn; Invoke stays enabled and they contribute nothing. Only a content-bearing layer that cannot resolve a model, or whose map is stale, blocks.
• FLUX Union ControlNets now receive instantx_control_mode from the control type.
• The adapter-kind select is gone: the kind is derived from the resolved model and adapter.kind stays persisted.
• Arrow keys on a focused radio group or slider no longer resolve to gallery navigation, so segmented controls work by keyboard.

The source button reads "Frame" (not "Canvas") to match the bbox rename in #9961.

Related Issues / Discussions

Overlaps #9961 (canvas v7 feedback) in wording; both touch the control layer panel and the layer menu. main is merged in (schema v5 is shared with the noise adjustment from #9933).

QA Instructions

From invokeai/frontend/webv2 on Node 22 / pnpm 10:

• pnpm check:release: passed on the branch after merging main (lint and architecture checks; 11,336 unit tests; 3,403 browser tests; mock-backend fixtures; architecture build and browser performance gates, 49 and 47 checks; project-file journeys; accessibility journeys including the new workbench-canvas-control-layer journey).
• Performance baselines were hand-edited for the new eager modules (owner sets) and for the byte growth of the merged locale and editor chunks. No timing baseline changed.
• Mock-backend walk (pnpm dev:mock, POST /__models {"set":"control-sdxl"} and {"set":"control-flux"}): empty layer rows and hint card; Type menu hints (model counts, "via Union", "Not installed"); Depth with two candidates asks and remembers the pick; Reset returns focus to the trigger; T2I via Edges dims Priority; Use as Control fills then creates; Invoke "· N issues" jumps to the layer; FLUX Depth resolves to the Control LoRA; keyboard operation of the view switch with gallery focus held; detection failure reverts the view switch with a notice.
• Not run: the real-backend walk (upload → Depth → spinner → map replaces pixels → undo; detector settings re-run; Replace › Frame; Draw; Invoke carrying the resolved adapter and FLUX instantx_control_mode; Original / Overlay rendering on screen). The mock backend cannot run detectors or decode its fixture images, so the running state, the detected map and the Original / Overlay rendering are covered by coordinator, compositor and engine tests only.

Screenshots (mock backend)

New control layer: fixed rows, "Set by type", drop hint on the canvas, row "Control Layer 1"

Type menu on SDXL: model counts per type, "Not installed" for types without a model Depth with two candidates: "Choose a depth model" and the caption naming both; row renamed "Depth 1" Model menu grouped: Made for depth, Union, Purpose not set After a pick: "your pick for depth" with Reset Pose: "your only pose model" Edges resolves to the T2I-Adapter; Priority is disabled SD 1.5 main with a drawn Edges layer: "No control models" with the starter-models link; Invoke counts 2 issues Invoke tooltip naming the offending layer Type menu on FLUX dev: "via Union" for the types the Union ControlNet covers FLUX Depth resolves to the Control LoRA; the detector failed on the mock backend, so the Detection row shows the failure with Run again FLUX Line art: "None for FLUX" with Find one

Review

Resolved: a transform bake now rebases the kept original and holds its asset refs; undo never restarts detection; stale detection results are dropped on layer removal, input change and document replace; untyped layers with a model keep their legacy summary; the control view ends on both locks and on stroke start, reports failed decodes distinctly, and skips hidden layers; a per-frame allocation in the compositor was removed; the retained original is tracked as detached pixels under the raster budget.

Limits: SDXL "union" models (xinsir) are offered as explicit picks only until the backend exposes union control types; a remembered pick applies to every AUTO layer of the same base and type; the backend recall path still understands only legacy *_image_processor ids, which the frontend classifier accepts alongside node ids; a superseded decode keeps its reservation until it settles, so two quick view switches near the budget limit can refuse once.

Compatibility / Rollout

Canvas documents adopt schema v5 per document when a control layer carries controlType, detection, original or originalTransform (a v4 build would strip these keys and lose the original on its next autosave). v5 is shared with the noise adjustment from main; the version requirement is one function over both reasons. Documents without them stay at their current version; nothing steps down. Legacy filtered control layers keep working as map-only layers until the image is replaced. WorkbenchPreferences gains controlModelMemory with a normalizer. The graph compiler input is unchanged except the optional InstantX mode on FLUX ControlNet nodes.

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)

---

^{Need help on this PR? Tag @codesmith-bot with what you need.}