v0.37.0-alpha — Reference layers inside an edit

CHANGELOG.md

@@ -1,6 +1,18 @@
 # Changelog
 
-## v0.36.0-alpha - unreleased
+## v0.37.0-alpha - unreleased
+
+### Added
+
+- **Reference layers inside an edit** (Qwen-Image 2.1). Edit Image gets a Reference layers list with
+  Add Active Layer and Add Canvas. Name them in the prompt as `<image2>`, `<image3>`… — the layer you
+  are editing is `<image1>` — and bring their content in: *"put the woman from `<image2>` into the
+  mountain scene"*, *"replace the cart with the teapot from `<image2>`"*. Up to four references; each
+  keeps its own transparency, and it works with a captured layer, the canvas or a selection. A
+  selection edit with one reference took about 70 s on a 12 GB card. Research licence, as with every
+  Qwen-Image 2.1 preset.
+
+## v0.36.0-alpha - 2026-09-24
 
 Editing by instruction gets its own place on the Home screen.
 

README.md

@@ -47,7 +47,7 @@ a GPU with 8 GB VRAM or more (12 GB is what this project targets).
 OpenLayer is the Photoshop panel that talks to it — you work in Photoshop, ComfyUI does the
 generating in the background, and every result comes back as a layer.
 
-> **Alpha.** `v0.36.0-alpha` is a public testing checkpoint, not production software. It is stable
+> **Alpha.** `v0.37.0-alpha` is a public testing checkpoint, not production software. It is stable
 > enough to work with, and honest about where it stops — see [what works and what does
 > not](docs/known-limitations.md).
 
@@ -60,7 +60,7 @@ anywhere; ComfyUI runs on your own machine.
 | :--- | :--- |
 | **Text to Image** | Generate a new layer from a prompt — or a transparent cut-out |
 | **Image to Image** | Use the active layer as visual input |
-| **Edit Image** | Change a layer, or just a selection, by describing the change — "make the jacket red" |
+| **Edit Image** | Change a layer or a selection by describing it — "make the jacket red", or bring in a second layer: "put the teapot from `<image2>` here" |
 | **Sketch to Image** | Guide generation with your line art |
 | **Inpaint** | Repaint a Photoshop selection in place |
 | **Outpaint** | Extend canvas content beyond the edges |

bridge/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openlayer-mcp-bridge",
-  "version": "0.36.0",
+  "version": "0.37.0",
   "private": true,
   "description": "Lets an MCP client drive the OpenLayer Photoshop panel's existing tools",
   "license": "MIT",

bridge/src/tools.mjs

@@ -274,7 +274,9 @@ export const MCP_TOOLS = [
       "Change the layer or canvas already captured for Image to Image in the OpenLayer panel by " +
       "describing the change (\"make the jacket red\", \"remove the parked car\"). Requires a source " +
       "captured in the panel first — this tool cannot capture one. The rest of the picture stays " +
-      "where it is, and the result is the source's size. Only the parameters you pass are changed. " +
+      "where it is, and the result is the source's size. With edit-qwen-image-21 the edit also uses any " +
+      "reference layers the artist added in the panel, named <image2>, <image3>... in the prompt (the " +
+      "edited layer is <image1>); this tool cannot add them. Only the parameters you pass are changed. " +
       "Returns the panel's own status message.",
     schema: EDIT_IMAGE_SCHEMA,
     timeoutMs: GENERATION_TIMEOUT_MS

docs/become-a-tester.html

@@ -44,7 +44,7 @@
     <main id="top">
       <section class="hero" aria-labelledby="hero-title">
         <div class="hero-copy">
-          <p class="hero-badge"><span class="pulse-dot" aria-hidden="true"></span> Alpha v0.36.0 &middot; testers wanted</p>
+          <p class="hero-badge"><span class="pulse-dot" aria-hidden="true"></span> Alpha v0.37.0 &middot; testers wanted</p>
           <h1 id="hero-title">Five minutes to<br><span class="grad">your first AI layer.</span></h1>
           <p class="hero-lede">
             OpenLayer is an alpha. It works on the author's machine, and that is exactly the problem —
@@ -53,7 +53,7 @@ <h1 id="hero-title">Five minutes to<br><span class="grad">your first AI layer.</
             and an honest report of where those five minutes went wrong.
           </p>
           <div class="hero-actions">
-            <a class="button button-primary" href="https://github.com/MehranMarxian/OpenLayer/releases/tag/v0.36.0-alpha">Download v0.36.0-alpha</a>
+            <a class="button button-primary" href="https://github.com/MehranMarxian/OpenLayer/releases/tag/v0.37.0-alpha">Download v0.37.0-alpha</a>
             <a class="button button-secondary" href="https://github.com/MehranMarxian/OpenLayer/issues/new?template=tester_report.yml">Send a tester report</a>
           </div>
           <ul class="signal-list" aria-label="What testing costs you">
@@ -93,8 +93,8 @@ <h2 id="path-title">Install, connect, generate, import, report.</h2>
             <article class="setup-step">
               <span>1</span>
               <h3>Install OpenLayer</h3>
-              <p>Download <code>openlayer-v0.36.0-alpha.ccx</code> from the release and <strong>double-click it</strong>. Creative Cloud installs the panel — no developer tool, nothing to unzip. Creative Cloud will warn that the plugin is not verified by Adobe, because it is not from Adobe Exchange; that prompt is expected. Keep the file on the same drive as Photoshop. Then open Photoshop: <strong>Plugins &gt; OpenLayer</strong>.</p>
-              <p><strong>If double-clicking does nothing at all</strong> — a known Windows 11 quirk — the release also has <code>openlayer-v0.36.0-alpha.zip</code>, which loads through the <a href="https://developer.adobe.com/photoshop/uxp/2022/guides/devtool/">UXP Developer Tool</a>: <strong>Add Plugin</strong>, select the unzipped <code>manifest.json</code>, then <strong>Load</strong>. And if that is what you had to do, please say so in your report — the one-click path has only ever been verified on Windows 11 with Photoshop 2025.</p>
+              <p>Download <code>openlayer-v0.37.0-alpha.ccx</code> from the release and <strong>double-click it</strong>. Creative Cloud installs the panel — no developer tool, nothing to unzip. Creative Cloud will warn that the plugin is not verified by Adobe, because it is not from Adobe Exchange; that prompt is expected. Keep the file on the same drive as Photoshop. Then open Photoshop: <strong>Plugins &gt; OpenLayer</strong>.</p>
+              <p><strong>If double-clicking does nothing at all</strong> — a known Windows 11 quirk — the release also has <code>openlayer-v0.37.0-alpha.zip</code>, which loads through the <a href="https://developer.adobe.com/photoshop/uxp/2022/guides/devtool/">UXP Developer Tool</a>: <strong>Add Plugin</strong>, select the unzipped <code>manifest.json</code>, then <strong>Load</strong>. And if that is what you had to do, please say so in your report — the one-click path has only ever been verified on Windows 11 with Photoshop 2025.</p>
             </article>
             <article class="setup-step">
               <span>2</span>
@@ -195,15 +195,15 @@ <h2 id="closing-title">Ready?</h2>
             talk it through than file a report, the discussion board has a Setup Help category.
           </p>
           <div class="hero-actions">
-            <a class="button button-primary" href="https://github.com/MehranMarxian/OpenLayer/releases/tag/v0.36.0-alpha">Download v0.36.0-alpha</a>
+            <a class="button button-primary" href="https://github.com/MehranMarxian/OpenLayer/releases/tag/v0.37.0-alpha">Download v0.37.0-alpha</a>
             <a class="button button-secondary" href="https://github.com/MehranMarxian/OpenLayer/discussions">Open discussions</a>
           </div>
         </div>
       </section>
     </main>
 
     <footer class="site-footer">
-      <p>OpenLayer v0.36.0-alpha. Developed by Mehran Ahmadi, 2026.</p>
+      <p>OpenLayer v0.37.0-alpha. Developed by Mehran Ahmadi, 2026.</p>
       <p>
         <a href="./">Overview</a> &middot;
         <a href="https://github.com/MehranMarxian/OpenLayer">GitHub</a> &middot;

docs/index.html

@@ -33,10 +33,10 @@
       "operatingSystem": "Windows, macOS",
       "applicationCategory": "DesignApplication",
       "applicationSubCategory": "Adobe Photoshop plugin",
-      "softwareVersion": "0.36.0-alpha",
+      "softwareVersion": "0.37.0-alpha",
       "description": "Open-source Photoshop UXP plugin that connects to a local ComfyUI server for AI image generation: text to image, image to image, sketch to image, inpaint, outpaint, and upscale with Stable Diffusion, SDXL, and Flux models.",
       "url": "https://mehran-ahmadi.com/OpenLayer/",
-      "downloadUrl": "https://github.com/MehranMarxian/OpenLayer/releases/tag/v0.36.0-alpha",
+      "downloadUrl": "https://github.com/MehranMarxian/OpenLayer/releases/tag/v0.37.0-alpha",
       "offers": { "@type": "Offer", "price": "0", "priceCurrency": "USD" },
       "author": { "@type": "Person", "name": "Mehran Ahmadi", "url": "https://github.com/MehranMarxian" }
     }
@@ -67,7 +67,7 @@
     <main id="top">
       <section class="hero" aria-labelledby="hero-title">
         <div class="hero-copy">
-          <p class="hero-badge"><span class="pulse-dot" aria-hidden="true"></span> Alpha v0.36.0 · free &amp; open source</p>
+          <p class="hero-badge"><span class="pulse-dot" aria-hidden="true"></span> Alpha v0.37.0 · free &amp; open source</p>
           <h1 id="hero-title">Local AI layers,<br><span class="grad">inside Photoshop.</span></h1>
           <p class="hero-lede">
             OpenLayer connects Photoshop to <strong>your own ComfyUI server</strong>.
@@ -76,7 +76,7 @@ <h1 id="hero-title">Local AI layers,<br><span class="grad">inside Photoshop.</sp
             <strong>No cloud. No credits. No subscription.</strong>
           </p>
           <div class="hero-actions">
-            <a class="button button-primary" href="https://github.com/MehranMarxian/OpenLayer/releases/tag/v0.36.0-alpha">Download alpha</a>
+            <a class="button button-primary" href="https://github.com/MehranMarxian/OpenLayer/releases/tag/v0.37.0-alpha">Download alpha</a>
             <a class="button button-secondary" href="https://github.com/MehranMarxian/OpenLayer">Star on GitHub</a>
           </div>
           <ul class="signal-list" aria-label="Project signals">
@@ -390,7 +390,7 @@ <h2 id="setup-title">Run it locally in minutes</h2>
             <article class="setup-step">
               <span>1</span>
               <h3>Download and double-click</h3>
-              <p>Grab <code>openlayer-v0.36.0-alpha.ccx</code> from the <a href="https://github.com/MehranMarxian/OpenLayer/releases/tag/v0.36.0-alpha">latest release</a> and double-click it. Creative Cloud installs the panel — no developer tools, nothing to build.</p>
+              <p>Grab <code>openlayer-v0.37.0-alpha.ccx</code> from the <a href="https://github.com/MehranMarxian/OpenLayer/releases/tag/v0.37.0-alpha">latest release</a> and double-click it. Creative Cloud installs the panel — no developer tools, nothing to build.</p>
             </article>
             <article class="setup-step">
               <span>2</span>
@@ -437,7 +437,7 @@ <h3>An AI assistant can drive the panel</h3>
             </article>
             <article class="status-card">
               <h3>Testing alpha</h3>
-              <p>OpenLayer v0.36.0-alpha is for local testing and feedback. It is not production-ready yet.</p>
+              <p>OpenLayer v0.37.0-alpha is for local testing and feedback. It is not production-ready yet.</p>
             </article>
             <article class="status-card">
               <h3>Qwen-Image 2.1 is research-licensed</h3>
@@ -453,7 +453,7 @@ <h3>Unflatten is experimental, and needs depth</h3>
             </article>
             <article class="status-card">
               <h3>Inpaint is experimental</h3>
-              <p>v0.36.0 retains the upload and alignment fixes while output quality across checkpoints continues to be validated by testers.</p>
+              <p>v0.37.0 retains the upload and alignment fixes while output quality across checkpoints continues to be validated by testers.</p>
             </article>
             <article class="status-card">
               <h3>Flux Fill is experimental</h3>
@@ -476,7 +476,7 @@ <h3>Custom workflows are future work</h3>
               <li>Inpaint and Outpaint should be tested on duplicate layers first.</li>
               <li>Prompt from Layer requires the local Florence-2 PromptGen model and the comfyui-florence2 nodes. The custom-scripts pack is no longer needed.</li>
               <li>Upscale uses pixel/model upscale only. Generative upscale, tiled diffusion, and creative enhancement are future work.</li>
-              <li>Custom workflow import, batch variants, and true persistent Photoshop AI layer metadata are future work. v0.36.0 keeps the shared metadata foundation and session-history wiring.</li>
+              <li>Custom workflow import, batch variants, and true persistent Photoshop AI layer metadata are future work. v0.37.0 keeps the shared metadata foundation and session-history wiring.</li>
               <li>The LoRA list cannot be filtered by which model a LoRA suits: ComfyUI reports only a name and size. Entries are labelled from their filenames and likely matches sorted first, but a mismatched LoRA loads without error and quietly does nothing.</li>
               <li>CI does not run Photoshop, UXP, or ComfyUI integration tests.</li>
               <li>Live sampler previews require ComfyUI to be started with <code>--preview-method auto</code>.</li>
@@ -578,7 +578,7 @@ <h2 id="closing-title">Build local AI layers, one careful step at a time.</h2>
     </main>
 
     <footer class="site-footer">
-      <p>OpenLayer v0.36.0-alpha. Developed by Mehran Ahmadi, 2026.</p>
+      <p>OpenLayer v0.37.0-alpha. Developed by Mehran Ahmadi, 2026.</p>
       <p>
         <a href="https://github.com/MehranMarxian">GitHub</a> &middot;
         <a href="./privacy.html">Privacy Policy</a> &middot;

docs/known-limitations.md

@@ -36,7 +36,7 @@ Future placeholders are included for regional import alignment and selection pre
 ## Known boundaries
 
 - **Qwen-Image 2.1 is research-licensed.** Its three presets (Text to Image, Image to Image, Multi-Reference) use weights Qwen licenses for research and evaluation only; commercial use needs a separate licence from Qwen. Each preset carries "(research licence)" in its name, none is a default, and Setup gives you the links but never downloads the files itself. They also need ComfyUI 0.37.0 or newer; an older ComfyUI reports `TextEncodeQwenImage21` as a missing node.
-- **Qwen-Image 2.1 edits repaint the whole frame.** Objects stay within a pixel of where they were, but untouched areas can come back slightly darker — 6 to 12 levels, measured on photographs. Compare before you keep an edit. Editing *only a selection* is in Edit Image since v0.36 (Capture Selection): the edit is colour-matched from the untouched ring around the selection, which took the smooth-sky edge that cut it from v0.35 down to an invisible −0.47 levels. It needs the Qwen-Image 2.1 preset.
+- **Qwen-Image 2.1 edits repaint the whole frame.** Objects stay within a pixel of where they were, but untouched areas can come back slightly darker — 6 to 12 levels, measured on photographs. Compare before you keep an edit. Editing *only a selection* is in Edit Image since v0.36 (Capture Selection): the edit is colour-matched from the untouched ring around the selection, which took the smooth-sky edge that cut it from v0.35 down to an invisible −0.47 levels. It needs the Qwen-Image 2.1 preset, and so do reference layers inside an edit (v0.37, up to four; each adds about 30 s).
 - **Qwen-Image 2.1 does not replace Remove Background.** Its own background-removal prompt worked on the vendor's sample image and returned an empty, fully transparent frame on a real photograph of a person in a street, in four runs out of four across two text encoders. Remove Background stays on BiRefNet.
 - **Qwen-Image 2.1 lettering is strong, not guaranteed.** Clean type came back spelled exactly every time it was tested, at 1024² and 2048²; stylised hand-painted lettering on a wooden sign came back misspelled. At 2048² the model also runs slightly off its own sampling schedule until ComfyUI fixes [#16447](https://github.com/comfy-org/ComfyUI/issues/16447).
 - **Transparent Background only exists where the model can do it.** The toggle appears for Qwen-Image 2.1 alone. The same model keeps a cut-out layer a cut-out when you edit it in Image to Image; every other edit preset returns an ordinary opaque layer from a transparent one, as before.

docs/v0.37-plan.md

@@ -0,0 +1,33 @@
+# OpenLayer v0.37.0 — Reference layers inside an edit
+
+Mehran, 2026-09-24: "a must-have". Edit Image (Qwen-Image 2.1) gains a list of **reference layers**,
+so an instruction can bring something in from another layer: *"put the jacket from `<image2>` on
+her"*, *"replace the cart with the teapot from `<image2>`"*.
+
+## Proven before planning (2026-09-24, live, core nodes only)
+
+The v0.36 edit graph, a **selection** capture, plus one reference wired to `images.image_2` of the
+same `TextEncodeQwenImage21`: "Replace the wooden cart in `<image1>` with the red teapot from
+`<image2>`" put a transparent teapot layer into the selected area, lit to match, with no visible
+seam, in 66 s on the 12 GB rig. The edit target stays `<image1>`; references are 2..n.
+
+## Design
+
+- **Reuse, don't rebuild.** The encoder-slot wiring (`encoder-image-slots`) and the reference-list
+  UI both exist from Multi-Reference (v0.35). The edit preset gains a `referenceChain` of that kind
+  whose slot 1 is the edit target, so references start at slot 2.
+- **Screen:** under the source card in Edit Image, a compact "Reference layers" list with Add Layer /
+  Add Canvas, shown only for presets that accept references (Qwen-Image 2.1). The hint says to name
+  them `<image2>`, `<image3>`… in list order.
+- **Works with every source:** a captured layer, the canvas, or a selection (colour match and
+  corner anchors unchanged).
+- **Ceiling 4 references** at first (+~30 s each measured in v0.35), raised if tests allow.
+- **Agent Bridge:** `edit_image` cannot capture layers, like `multi_reference`; it uses the list the
+  panel holds.
+
+## Tasks (one commit each; Photoshop gate after each panel change)
+
+1. Builder: references on edit presets (slot offset 2), tests, live run through the builder.
+2. Screen: the reference list in Edit Image (markup gate alone).
+3. Wiring: upload in order, build, history records the references.
+4. Agent Bridge description; docs; release.

package.json

@@ -1,6 +1,6 @@
 {
   "name": "openlayer",
-  "version": "0.36.0",
+  "version": "0.37.0",
   "private": true,
   "description": "Local AI layers for Photoshop",
   "license": "MIT",

src/comfy/presetRegistry.ts

@@ -4771,6 +4771,19 @@ export const WORKFLOW_PRESETS: WorkflowPresetDefinition[] = [
       saveImage: target(QWEN_IMAGE_21_EDIT_NODES.saveImage, "images"),
       rgbaSource: QWEN_IMAGE_21_EDIT_NODES.outputScale
     },
+    // v0.37: reference layers inside an edit. Slot 1 is the layer being
+    // edited, so the builder passes [source, ...references] and references
+    // land on images.image_2 onwards, each rejoined with its own alpha.
+    // Four is a time bound (~30 s per reference, measured in v0.35).
+    referenceChain: {
+      kind: "encoder-image-slots",
+      loadImage: QWEN_IMAGE_21_EDIT_NODES.loadImage,
+      keepAlpha: QWEN_IMAGE_21_EDIT_NODES.keepAlpha,
+      encoder: QWEN_IMAGE_21_EDIT_NODES.textEncode,
+      inputPrefix: "images.image_",
+      generatedNodeIdPrefix: "ref",
+      maximumReferences: 5
+    },
     selectionEdit: {
       loadImage: QWEN_IMAGE_21_EDIT_NODES.loadImage,
       encoderImage: target(QWEN_IMAGE_21_EDIT_NODES.textEncode, "images.image_1"),