@melite/models-qwen-img-edit-21 0.1.4-alpha → 0.1.5-pre-alpha

package/README.md

@@ -0,0 +1,45 @@
+---
+description: Qwen Image Edit 2.1 — the cached-reference edit lane over the shared 2.1 checkpoint; up to 16 images, edits at the stated target resolution.
+kind: package-library
+---
+
+# qwen-img-edit-21
+
+qwen-img-edit-21 registers Qwen Image Edit 2.1 (form `form_edit`, label "Qwen Image Edit 2.1", genre `image`): the instruction-edit lane over the SAME physical 2.1 checkpoint as the t2i sibling. The lane: UNETLoader → QwenImage21Cache (the reference-prefix KV cache wrapped around the base unet — no separate edit weights exist) → TextEncodeQwenImage21 conditioning on the anchor images through its `image_N` autogrow slots (positive AND negative from ONE node) → EmptyLatentImage at the stated target resolution → KSampler → decode and save under `<run>/edit`. This is not the 2511 lane (VAEEncode-of-source at source resolution); the branch key is the lane's `text_encode_node`.
+
+## Params and law
+
+Declared surface: `input_images`, `image1`, `image2`, `image3`, `reference_images`, `input_mask` (validation-only aliases the lane admits as wire keys), `prompt`, `negative_prompt`, `width`, `height`, `seed`, `steps`, `cfg`, `sampler`, `scheduler`. Laws: `width` and `height` ride together — an EmptyLatentImage takes both axes or neither, bounds 256–1536; `prompt` is required (the instruction, not a description of the image); an anchor is required — the ordered `input_images` list or a legacy spelling (`image1` / `image2` / `image3` / `reference_images`). The image cap is 16 total, anchor included (`max_images`).
+
+Defaults: 25 steps, `euler` / `simple`, cfg 1, 1024×1024. Variants: `int8` (about 7.3 GB unet, about 24 GB VRAM, DEFAULT — provisioning required; without the 2.1 files the engine refuses loud) and `bf16` (about 14.2 GB, about 48 GB). Recipes: `remove_background` (the official template's canned prompt verbatim), `upstream_solvers`, `default`.
+
+## Mod surface
+
+The DECL boards `mask` only: the bare flavor whose region contract rides the crop_stitch detailer over the cached model; automatic inpainting with a named field refuses — the LanPaint sampler is 2511's lane. `./mods/loras` is the seam with an empty row set (no first-party 2.1 adapters); nothing is fetched from either subpath.
+
+## Model Experience
+
+### Request context and condition
+
+A run needs the anchor image and the edit instruction; target resolution and the sampling block ride defaults. Reference sets beyond the anchor go in `input_images` order, up to the 16-image ceiling.
+
+#### What the model sees
+
+The anchor and reference images (up to 16), the instruction, the target resolution, and the sampling block; the cached lane above.
+
+#### Token effect
+
+Zero-direct: an engine graph, not a token stream.
+
+#### KV Cache effect
+
+Within a run, the cache is the lane's point: QwenImage21Cache prefixes reference KV around the base unet, so the edit shares context with its anchors. Across runs it stays independent.
+
+## Known Limitations and Deferred Work
+
+- **16-image ceiling** — beyond `max_images` the kit refuses loud; larger reference sets need trimming.
+- **Resolution pair rides together** — a lone width or height is refused (the range rule made law).
+- **No LoRA rows** — the `./mods/loras` seam is empty until first-party adapters land.
+- **Live behavior unobserved** — not verified against the running model.
+
+Exports: the plugin root, `./package.json`, `./mods/loras`, `./mods/mask`.

package/lib/actions.js

@@ -1,6 +1,6 @@
 import { loadTextPair, decodeSave, stackLoras, orderedInputImages, regionSegs, detailerSave, isSpell, laneSampler, laneScheduler } from "@melite/comfyui-card-kit";
 import { fireLoras } from "@melite/comfyui-card-kit/guard";
-import { requireText } from "@melite/comfyui-card-kit/facts";
+import { parseDiffusionLaneFacts, parseEditCap } from "@melite/comfyui-card-kit/facts";
 import { EDIT_DIFFUSION_BOUNDS, diffusionParamRows } from "@melite/comfyui-card-kit/paramRows";
 /** The edit facts door: the resolved lane_inputs parsed into the
  *  closed shape. A drifted encoder class refuses here, never
@@ -10,23 +10,11 @@ import { EDIT_DIFFUSION_BOUNDS, diffusionParamRows } from "@melite/comfyui-card-
  *  @param raw the resolved lane_inputs (family ⊕ variant)
  *  @returns the typed facts the segment factory reads */
 export function parseEditFacts(raw) {
-    const text = (key) => requireText(raw, key, "qwen-img-edit-21 edit");
-    const node = raw.text_encode_node;
-    if (node !== "TextEncodeQwenImage21") {
-        throw new Error(`qwen-img-edit-21 edit: lane_inputs.text_encode_node = ${JSON.stringify(node)} — this family's edit action builds on TextEncodeQwenImage21`);
-    }
-    const cap = raw.max_images;
-    if (typeof cap !== "number" || !Number.isFinite(cap) || cap < 1) {
-        throw new Error(`qwen-img-edit-21 edit: lane_inputs.max_images = ${JSON.stringify(cap)} — a number ≥ 1 is required`);
-    }
-    return {
-        unet: text("unet"),
-        text_encoder: text("text_encoder"),
-        vae: text("vae"),
-        clip_type: text("clip_type"),
-        text_encode_node: node,
-        max_images: Math.floor(cap),
-    };
+    // The checks + refusal prose live in the kit (J3 consolidation,
+    
+    // into the family's own typed shape (B4).
+    const f = parseDiffusionLaneFacts(raw, "qwen-img-edit-21 edit", { key: "text_encode_node", node: "TextEncodeQwenImage21" }, false);
+    return { unet: f.unet, text_encoder: f.text_encoder, vae: f.vae, clip_type: f.clip_type, text_encode_node: f.node, max_images: parseEditCap(raw, "qwen-img-edit-21 edit") };
 }
 /** The edit action: the cached-reference lane — loaders → lora
  *  stack → text pair → per-slot LoadImage anchors →
@@ -51,6 +39,7 @@ export const edit = {
         { name: "image3", type: "string" },
         { name: "reference_images", type: "image_list" },
         ...diffusionParamRows(EDIT_DIFFUSION_BOUNDS),
+        { name: "match_input_resolution", type: "boolean" },
         { name: "use_stock_nodes", type: "boolean" },
         { name: "double_reference", type: "boolean" },
     ],

package/lib/index.d.ts

@@ -1,6 +1,7 @@
 import type { Plugin } from "@deepseek-ai/cordis";
-import type { ModelDecl } from "@melite/comfyui-cordis/model-contract";
+import type { ModelDecl } from '@melite/comfyui-card-kit/model-contract';
 export declare const DECL: ModelDecl;
 export declare const family: Plugin;
 export { edit, parseEditFacts, type EditFacts, type EditParams } from "./actions.js";
+export { family as default };
 //# sourceMappingURL=index.d.ts.map

package/lib/index.js

@@ -22,16 +22,6 @@ export const DECL = {
         "width": 1024,
         "height": 1024
     },
-    "prompt_guide": {
-        "title": "Qwen Image 2.1 Edit Prompting Guide",
-        "sections": [
-            "GuideSection(label='Edit', body='State the change and the anchor: what stays identical. One edit per instruction.', list=[])",
-            "GuideSection(label='CFG', body='Flow-matching lane: Guidance stays low (default 1.0).', list=[])",
-        ],
-        "label": "CFG",
-        "body": "Flow-matching lane: keep Guidance low (default 1.0)",
-        "list": []
-    },
     "genre": "image",
     // THE LANE SURFACE (fix shapes 1+2 — the model is the author of
     // what it accepts; the card's visible_when guard list dies). The
@@ -41,7 +31,11 @@ export const DECL = {
     // reference_images, input_mask — hidden carriers, but a wire key
     // the lane admits, so the surface owns them) and THIS lane's
     // target resolution pair — the 2.1 edit lane samples an
-    // EmptyLatentImage at stated size, so width/height are 2.1's.
+    // EmptyLatentImage at stated size, so width/height are 2.1's —
+    // plus the card-owned match toggle (ON by default: output matches
+    // the anchor; OFF: the custom pair rides). The toggle is admitted
+    // on BOTH edit lanes (the 2511 lane holds it as a no-op — it
+    // always edits at source resolution).
     // use_stock_nodes/double_reference are 2511's edit-tuning pair
     // and are NOT here: with a declared surface the bench-write door
     // refuses them on this family in the field's voice.
@@ -56,6 +50,7 @@ export const DECL = {
         "negative_prompt",
         "width",
         "height",
+        "match_input_resolution",
         "seed",
         "steps",
         "cfg",
@@ -149,11 +144,16 @@ export const DECL = {
             "size_bytes": 675509688
         }
     ],
+    // THE 2.1 MATRIX ON THE EDIT LANE (the variant-axis law,
+    
+    // weights): Variant = Base/Turbo, Quant = int8_convrot/bf16;
+    // the quant cell owns its tier's unet spelling
+    // (CellRow.lane_inputs — the cell-lane cascade).
     "variants": [
         {
-            "id": "int8",
-            "label": "INT8 ConvRot",
-            "hint": "The official template pick — 7.3GB unet, int8 convrot (DEFAULT). Requires provisioning: the 2.1 files are NOT on this box by default; without them the engine validation refuses LOUD (the honest face — the 2511 weights are what ship).",
+            "id": "base",
+            "label": "Base",
+            "hint": "The 2.1 base checkpoint on the edit lane — 25 steps (the official template's own count), both download tiers below, the cache-wrapped edit compose. Requires provisioning: the 2.1 files are NOT on this box by default; without them the engine validation refuses LOUD (the honest face — the 2511 weights are what ship).",
             "group": "Variant",
             "route": "qwen-img-edit-21",
             "order": 0,
@@ -171,30 +171,65 @@ export const DECL = {
                         "dest_sub": "diffusion_models",
                         "size_hint_gb": 7.3
                     }
+                },
+                {
+                    "quant": "bf16",
+                    "label": "BF16",
+                    "route": "qwen-img-edit-21-bf16",
+                    "vram_peak_gb": 48,
+                    "lane_inputs": {
+                        "unet": "qwen_image_2.1_bf16.safetensors",
+                        "text_encoder": "qwen3vl_8b_bf16.safetensors"
+                    },
+                    "artifact": {
+                        "source_url": "https://huggingface.co/Comfy-Org/Qwen-Image-2.1/resolve/main/diffusion_models/qwen_image_2.1_bf16.safetensors",
+                        "size_bytes": 14230280616,
+                        "sha256": "89f4158d066cc33906a199fca85634f766892dd78f49b6698dabf187ac86c4bc",
+                        "dest_root": "COMFYUI_ROOT",
+                        "dest_sub": "diffusion_models",
+                        "size_hint_gb": 14.3
+                    }
                 }
             ]
         },
         {
-            "id": "bf16",
-            "label": "BF16",
-            "hint": "Full precision unet + bf16 encoder — 14.2GB unet, highest fidelity, most VRAM. Requires provisioning: the 2.1 files are NOT on this box by default; without them the engine validation refuses LOUD (the honest face — the 2511 weights are what ship).",
+            "id": "turbo",
+            "label": "Turbo",
+            "hint": "The distilled turbo weights on the edit lane — 8 steps instead of the base 25 (upstream: 'Turbo uses 8 steps'), both download tiers below, same cache-wrapped edit compose. Requires provisioning: the 2.1 turbo files are NOT on this box by default; without them the engine validation refuses LOUD (the honest face — the 2511 weights are what ship).",
             "group": "Variant",
-            "route": "qwen-img-edit-21-bf16",
+            "route": "qwen-img-edit-21-turbo",
             "order": 1,
-            "lane_inputs": {
-                "unet": "qwen_image_2.1_bf16.safetensors",
-                "text_encoder": "qwen3vl_8b_bf16.safetensors"
-            },
+            "resolver_defaults": { "steps": 8 },
             "cells": [
+                {
+                    "quant": "int8_convrot",
+                    "label": "INT8 ConvRot",
+                    "route": "qwen-img-edit-21-turbo-int8",
+                    "vram_peak_gb": 24,
+                    "lane_inputs": {
+                        "unet": "qwen_image_2.1_turbo_int8_convrot.safetensors"
+                    },
+                    "artifact": {
+                        "source_url": "https://huggingface.co/Comfy-Org/Qwen-Image-2.1/resolve/main/diffusion_models/qwen_image_2.1_turbo_int8_convrot.safetensors",
+                        "size_bytes": 7256787829,
+                        "sha256": "8144a0182964aa8403ad6dbc011db837304167d235161b9aabaa8532e967314c",
+                        "dest_root": "COMFYUI_ROOT",
+                        "dest_sub": "diffusion_models",
+                        "size_hint_gb": 7.3
+                    }
+                },
                 {
                     "quant": "bf16",
                     "label": "BF16",
-                    "route": "qwen-img-edit-21-bf16",
+                    "route": "qwen-img-edit-21-turbo-bf16",
                     "vram_peak_gb": 48,
+                    "lane_inputs": {
+                        "unet": "qwen_image_2.1_turbo_bf16.safetensors"
+                    },
                     "artifact": {
-                        "source_url": "https://huggingface.co/Comfy-Org/Qwen-Image-2.1/resolve/main/diffusion_models/qwen_image_2.1_bf16.safetensors",
+                        "source_url": "https://huggingface.co/Comfy-Org/Qwen-Image-2.1/resolve/main/diffusion_models/qwen_image_2.1_turbo_bf16.safetensors",
                         "size_bytes": 14230280616,
-                        "sha256": "89f4158d066cc33906a199fca85634f766892dd78f49b6698dabf187ac86c4bc",
+                        "sha256": "8b74237a7f505773e2c66726fa696444b4c704585c93a347cff9044937f7914a",
                         "dest_root": "COMFYUI_ROOT",
                         "dest_sub": "diffusion_models",
                         "size_hint_gb": 14.3
@@ -275,4 +310,9 @@ export const family = {
 // The family's offered actions (the atom vocabulary): the edit
 // action the image-edit card binds.
 export { edit, parseEditFacts } from "./actions.js";
+// The Loader-row face: DSH loads plugin rows by bare specifier and
+// unwraps `exports.default ?? exports` (vendor/cordis_plugins/loader
+// unwrapExports) — the default export IS the row-loadable plugin. The
+// named `family` stays the library face (engine loadFamilies).
+export { family as default };
 //# sourceMappingURL=index.js.map

package/lib/mods/loras.d.ts

@@ -1,3 +1,3 @@
-import type { Context } from '@deepseek-ai/cordis';
+import type { Context } from '@melite/comfyui-card-kit/card-definition';
 export declare const inject: string[];
 export declare function apply(ctx: Context): void;

package/lib/mods/mask.d.ts

@@ -1,3 +1,3 @@
-import type { Context } from '@deepseek-ai/cordis';
+import type { Context } from '@melite/comfyui-card-kit/card-definition';
 export declare const inject: string[];
 export declare function apply(ctx: Context): void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@melite/models-qwen-img-edit-21",
-  "version": "0.1.4-alpha",
+  "version": "0.1.5-pre-alpha",
   "license": "SSPL-1.0",
   "type": "module",
   "exports": {
@@ -19,8 +19,7 @@
     }
   },
   "dependencies": {
-    "@melite/comfyui-cordis": "0.1.4-alpha",
-    "@melite/comfyui-card-kit": "0.1.4-alpha"
+    "@melite/comfyui-card-kit": "0.1.5-pre-alpha"
   },
   "devDependencies": {
     "@types/node": "^22.20.0",