JsonMatrixLab · JsonMatrixLab · Sep 9, 2026 · Sep 9, 2026 · Sep 9, 2026
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -0,0 +1,51 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: Python ${{ matrix.python-version }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.12"]
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v7
+      - name: Set up Python
+        uses: actions/setup-python@v7
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+      - name: Install CPU dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install --index-url https://download.pytorch.org/whl/cpu torch
+          python -m pip install Pillow aiohttp numpy scipy
+      - name: Run offline distribution tests
+        env:
+          NO_PROXY: "*"
+        run: python -m unittest discover -s tests -v
+
+  javascript:
+    name: JavaScript syntax
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v7
+      - name: Check shipped JavaScript syntax
+        shell: bash
+        run: |
+          found=0
+          while IFS= read -r -d '' file; do
+            node --check "$file"
+            found=1
+          done < <(find web -type f \( -name '*.js' -o -name '*.mjs' \) -print0)
+          test "$found" -eq 1
diff --git a/.gitignore b/.gitignore
@@ -2,4 +2,6 @@ __pycache__/
 *.py[cod]
 .pytest_cache/
 .env
-.env.*
+.env.*
+.codex/
+.claude/
diff --git a/AGENT-INSTALL.md b/AGENT-INSTALL.md
@@ -0,0 +1,31 @@
+# Installation contract for AI agents
+
+Install MATRIX LAB NODES package version 0.2.0 as one ComfyUI custom-node pack. Treat the installed `MANIFEST.json` as the exact class inventory.
+
+## Hard boundaries
+
+- Resolve the intended ComfyUI root from the launcher or operator configuration; never guess from a common path.
+- Do not overwrite, merge, delete, move, or replace an existing installation without explicit operator approval.
+- Refuse an existing target folder and refuse enabled legacy packs that register overlapping class IDs.
+- Do not change ComfyUI core or replace a working host Python, Torch, or CUDA environment.
+- Do not read, print, copy, log, or commit credential values.
+- Do not enable or queue the xAI **Generate Prompt** action, a paid provider operation, or a model workflow during installation verification.
+- Do not claim success from files or imports alone. Verify discovery in the visible ComfyUI UI.
+
+## Procedure
+
+1. Resolve and report the exact ComfyUI root, its launcher, and the Python interpreter used by that launcher.
+2. Stop ComfyUI through its normal controlled process.
+3. Inspect `custom_nodes` for the target and for older `MATRIXLAB-Nodes` or `MATRIXLAB-UI-Nodes` installations. If any conflict exists, stop and report the exact folder names; do not modify them.
+4. Obtain the exact operator-authorized commit or release archive. Record the commit SHA or SHA-256 before installation.
+5. Place it in a new direct child folder `custom_nodes/matrix-lab-nodes`. Refuse archive traversal, an extra wrapper directory, symlink or junction surprises, or files outside that folder.
+6. Verify that the root contains `__init__.py`, `MANIFEST.json`, `requirements.txt`, `_core/`, `nodes/`, and `web/`. Read `MANIFEST.json`; require `pack_id` `matrix-lab-nodes`, version `0.2.0`, fourteen unique class IDs, and six category groups.
+7. Resolve the declared Python dependencies with the same interpreter that runs ComfyUI. Preserve an already working Torch/CUDA stack. If dependency resolution would replace Torch, CUDA packages, or another host-critical package, stop and present the proposed changes.
+8. Restart ComfyUI through its normal launcher. Treat any pack import or frontend asset error as failure.
+9. In the visible UI, search for `MATRIX RESOLUTION`, `MATRIX PHOTO FINISHER`, and `MATRIX AUTO PROMPTER`; compare all discovered MATRIX classes with `MANIFEST.json`.
+10. Add `MATRIXLAB_Resolution`, choose `3:4` and `2K`, and verify 1536 by 2048. Do not queue any model, detector, sampler, or provider path.
+11. Report the installed source/hash, target folder, manifest version and classes, dependency actions, visible discovery result, geometry result, and every blocker. Distinguish offline verification from unperformed live model/renderer acceptance.
+
+## Credential and private-data boundary
+
+The Prompt Director credential must be supplied only by the operator through the masked node control or server environment. Never inspect an existing provider key or test it during installation. Do not upload images, prompts, workflows, logs, or screenshots. Diagnostics must exclude credentials, local paths, private media, prompt text, and provider response bodies.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -0,0 +1,19 @@
+# Changelog
+
+User-visible changes are recorded here. This file describes package content; publication tags and release channels are separate facts.
+
+## 0.2.0 - development candidate - 2026-09-09
+
+- Unified the surviving execution and UI nodes into one package with six stable category directories.
+- Preserved the public class IDs listed in `NODES.md` and retained `MATRIXLAB_EasyCrop`.
+- Replaced the retired finishing pair with `MATRIX_PhotoFinisher`, a local deterministic Torch node with `Clean Digital`, `Everyday Capture`, and `Low Light` creative profiles.
+- Set new Photo Finisher defaults to `Everyday Capture`, mix `1`, texture `1`, detail `1`, contrast `0`, warmth `0`, saturation `1`, and seed `42`.
+- Simplified the general and AI-influencer resolution nodes to two integer outputs and included `MATRIXLAB_AIInfluencerResolution2K4K` for current Krea 2 geometry selection.
+- Kept Prompt Director provider generation behind an explicit paid action; ordinary graph execution returns saved text without a network request.
+- Added public installation, migration, compatibility, node, license-notice, and agent-installation documentation.
+
+Full live acceptance of the current bytes across both ComfyUI renderers and all model-dependent paths remains pending.
+
+## 0.1.0
+
+- Initial unified-package development metadata.
diff --git a/INSTALL.md b/INSTALL.md
@@ -0,0 +1,60 @@
+# Installation for people
+
+Install MATRIX LAB NODES package version 0.2.0 as one ComfyUI custom-node pack.
+
+## Before you begin
+
+- Use a working ComfyUI installation with Python 3.10 or newer.
+- Back up important workflows and the current custom-node installation.
+- Close ComfyUI before changing custom nodes.
+- Check for folders that provide the older `MATRIXLAB-Nodes` or `MATRIXLAB-UI-Nodes` packs. They cannot remain enabled beside this unified package because class IDs overlap.
+- Preserve the host's working Python, Torch, and CUDA versions.
+
+## Install from Git
+
+From the `custom_nodes` directory of the intended ComfyUI installation:
+
+```bash
+git clone https://github.com/JsonMatrixLab/MATRIX-LAB-Nodes.git matrix-lab-nodes
+cd matrix-lab-nodes
+```
+
+If the repository is private, authenticate through your normal Git credential flow. Do not put a token in the clone URL, command history, or repository files.
+
+Use the Python interpreter that launches this ComfyUI instance to install the declared dependencies. Review the command before running it if your environment manager might replace Torch:
+
+```bash
+python -m pip install -r requirements.txt
+```
+
+For portable or embedded ComfyUI, replace `python` with that installation's bundled interpreter and adjust the relative path.
+
+## Install from an archive
+
+Extract the release archive to a new folder named `matrix-lab-nodes` directly under the intended ComfyUI `custom_nodes` directory. The package root must contain `__init__.py`, `MANIFEST.json`, `requirements.txt`, `_core/`, `nodes/`, and `web/`. Avoid an extra archive wrapper directory.
+
+## Restart and verify
+
+1. Start ComfyUI through its normal launcher and inspect startup output for import errors.
+2. Open node search and find `MATRIX RESOLUTION`, `MATRIX PHOTO FINISHER`, and `MATRIX AUTO PROMPTER`.
+3. Compare the installed classes with `MANIFEST.json`. The menu should retain six `MATRIX LAB` category groups.
+4. Add `MATRIXLAB_Resolution`, select `3:4` and `2K`, and confirm outputs of 1536 by 2048 without queueing a model workflow.
+5. Open a copy of an existing workflow and follow [docs/migration.md](docs/migration.md) if ComfyUI reports missing retired or incompatible classes.
+
+This verification proves discovery and the local geometry path only. It does not prove every model, detector, sampler, GPU, or frontend renderer.
+
+## External models and prompting
+
+Model weights are not bundled. Installing the pack does not acquire them, establish redistribution rights, or complete compatible inference-runtime setup. `MATRIX_SkinMask` and `MATRIX_EyeMask` fail when their registered assets or compatible runtimes are unavailable; do not bypass identity checks with a similarly named file. A successful package import is not proof that either mask node is ready to execute. Follow [the detector and segmentation setup guide](docs/detector-setup.md) for exact paths, hashes, source evidence, runtime boundaries, and unresolved license questions.
+
+`MATRIXLAB_PromptDirector` returns saved text during normal execution. Its explicit **Generate Prompt** control uses xAI and may incur charges. Configure credentials through its masked control or the documented server environment, never inside a workflow. Make the first provider call only after reviewing the selected model, reference images, request text, and cost boundary.
+
+## Update
+
+Back up workflows, record the installed commit or archive hash, and read [CHANGELOG.md](CHANGELOG.md) plus [docs/migration.md](docs/migration.md). Stop ComfyUI before updating. Do not merge a new archive over an existing tree; install the new version into a clean staging folder, verify its structure, then replace the disabled old folder using your normal recoverable file-management process.
+
+After restart, repeat node discovery and test copies of important workflows. Keep the previous package available as a disabled rollback until those checks pass.
+
+## Uninstall
+
+Stop ComfyUI, back up any files you need, and remove or move the single `matrix-lab-nodes` folder through your normal recoverable process. Restart ComfyUI and confirm its classes are absent. Removing the pack does not remove provider account data, external model weights, ComfyUI input/output images, or saved workflows.
diff --git a/MANIFEST.json b/MANIFEST.json
@@ -21,9 +21,9 @@
       "version": "1.0.0"
     },
     {
-      "content_hash": "9bbf3d99167453c45d8473b8f1207865fcd9bba369d7066b71289cf41a21219d",
+      "content_hash": "dcaf1a3ae2fc7ac78413342300aea580751b42ca019414b5cbb3c205a43d1611",
       "id": "ui.appearance",
-      "version": "0.5.0"
+      "version": "0.5.1"
     },
     {
       "content_hash": "fb98f796fea73106cfafb443d725f4db92bfacc3232b6fb00fd6807610a4ef12",
@@ -36,9 +36,9 @@
       "version": "0.2.3"
     },
     {
-      "content_hash": "01840c9fa972d067a24c93f20cff73eaff08e18b833f54c1cb23c6faefe4b725",
+      "content_hash": "4fda8c8c1fbce41aac7b6c4670aa7efd87a60adcaf4604a6af808b20f0c9195a",
       "id": "mask.skin-region",
-      "version": "0.3.0"
+      "version": "0.3.1"
     },
     {
       "content_hash": "7af6afab2008c90d1396302c3efd948ea6087369602db065a5918547f0d73d15",
@@ -61,14 +61,9 @@
       "version": "0.1.1"
     },
     {
-      "content_hash": "b0e2bc157eca2086faf3d5b57bf7ae685490c4ec34a7a4cfb3d00925391b112d",
-      "id": "image.renoise",
-      "version": "0.2.2"
-    },
-    {
-      "content_hash": "12c4b225fcff2a1028b361003f5c6b741aa1f3a109f86f8d23055f5237417432",
-      "id": "color.camera-look",
-      "version": "0.1.1"
+      "content_hash": "4e161007e22a23373d85333840fe9d8235cf8beb385633f775679840346613c7",
+      "id": "image.photo-finisher",
+      "version": "0.1.0"
     },
     {
       "content_hash": "869da644f94fb10c804e477bb2bd8062ffdab3545855f52f56580dbf5ad4f47f",
@@ -86,7 +81,7 @@
       "version": "0.1.0"
     },
     {
-      "content_hash": "5bb59338cab04e21642c98f1d7de92be6e90245531472960d16347ee245f0716",
+      "content_hash": "4e67bd73efebed6140e3531e5cf8a95f06d60d174f66afbbeb91e2c3c4e34e03",
       "id": "io.image-collection",
       "version": "0.2.1"
     },
@@ -113,67 +108,84 @@
     {
       "id": "prompt.director",
       "version": "0.2.1"
+    },
+    {
+      "content_hash": "a7cb4cc08e46e4a1603c4473221207e1db8b49ff959f9be6a0d312e5299d3648",
+      "id": "resolution.ai-influencer-2k4k",
+      "version": "1.0.0"
     }
   ],
+  "builder_sha256": "c2716a4a31e0f380576ebccccf3844353a379e0c7fd58af85f665084c1c3f87f",
   "categories": {
     "MATRIXLAB_AIInfluencerResolution": "MATRIX LAB/Resolution & Layout",
     "MATRIXLAB_EasyCrop": "MATRIX LAB/Image Processing",
     "MATRIXLAB_ImageBatchLoader": "MATRIX LAB/Input & Output",
     "MATRIXLAB_PromptDirector": "MATRIX LAB/Prompting",
     "MATRIXLAB_Resolution": "MATRIX LAB/Resolution & Layout",
     "MATRIXSpectralSampler": "MATRIX LAB/Sampling & Detail",
-    "MATRIX_CameraLook": "MATRIX LAB/Image Processing",
     "MATRIX_CropTailPaste": "MATRIX LAB/Sampling & Detail",
     "MATRIX_EyeMask": "MATRIX LAB/Masks & Detection",
     "MATRIX_LatentTail": "MATRIX LAB/Sampling & Detail",
     "MATRIX_OutputStage": "MATRIX LAB/Image Processing",
-    "MATRIX_Renoise": "MATRIX LAB/Image Processing",
+    "MATRIX_PhotoFinisher": "MATRIX LAB/Image Processing",
     "MATRIX_SaveClean": "MATRIX LAB/Input & Output",
-    "MATRIX_SkinMask": "MATRIX LAB/Masks & Detection"
+    "MATRIX_SkinMask": "MATRIX LAB/Masks & Detection",
+    "MATRIXLAB_AIInfluencerResolution2K4K": "MATRIX LAB/Resolution & Layout"
   },
+  "compiler_sha256": "b1ff75cd7cefd07caaf7fc224d2b4518d7a65954c89e3bdee770d867a37e1e07",
   "declaration_hashes": {
     "MATRIXLAB_AIInfluencerResolution": "8f6737741244227d88ed8a411548fd788fe311f776ca9aba68b67f34bf9695d9",
     "MATRIXLAB_EasyCrop": "e3e4d55649ba8fd8d1d5fb2abc526af8ca98b3b7a5b62665965eed080b0f3c2a",
     "MATRIXLAB_ImageBatchLoader": "bd6b56231c6d2842fb044ff7c5a2c775ca2043837a5879eff9a397569b153319",
-    "MATRIXLAB_PromptDirector": "4084dad0bdfe8b49430049245f4f8cc041a409d217b9e55394754f705249c0bc",
+    "MATRIXLAB_PromptDirector": "bbebce94b066143c8879239fa0003fc934207bebed40c6352d9d9bba882e54e4",
     "MATRIXLAB_Resolution": "38fea06eda599cb3c78a029b8e0478b3625bc1cd281019caec6cd9612a3ff521",
     "MATRIXSpectralSampler": "767c07ee23b36895169d5039756f8f425ef0aa0e70ca639d616b5af75c829306",
-    "MATRIX_CameraLook": "8c2132f6975da7120cb9fd51e883ba475651a9f2b31ad2365c90944f482f2541",
     "MATRIX_CropTailPaste": "7c0a5e925c00a9a08d445e9b8c9315909f17084d9279c37f3841cbce9c2670c7",
     "MATRIX_EyeMask": "c507e7a4ca5c6b959ab503b4229ec929856576567bc28a82b06e8f5cabebd7ef",
     "MATRIX_LatentTail": "8677264027158b709269b0ffe22c4ce7a9b81862f78d5d9057f964a0f362f83e",
     "MATRIX_OutputStage": "6ec9c264ab82dfd9b8c0e8640007a26db25818b3bf7a934db34e7403ba441bbc",
-    "MATRIX_Renoise": "78806798d0a4dcd256098631d76eb761898abf11d5a2d15a7530ebb2738ea713",
+    "MATRIX_PhotoFinisher": "eadad3bc1712edec30fa52fff0a929e4807a77b17b60fd5e51b4c4403d7bf809",
     "MATRIX_SaveClean": "3aaeea9d3b5b246e909df9a21ae9f2883bf251c055dcc9f8e89714beae65a3ce",
-    "MATRIX_SkinMask": "e17b320fdc4ab7535fb6f017578e43b87e6f8d90740adfba2aeabe1a377521f2"
+    "MATRIX_SkinMask": "e17b320fdc4ab7535fb6f017578e43b87e6f8d90740adfba2aeabe1a377521f2",
+    "MATRIXLAB_AIInfluencerResolution2K4K": "589e6e5dc7c7eb7ee22943b13729bf2012350baec8c4b35b0320badcbfd6b22c"
   },
   "display_name": "MATRIX LAB NODES",
   "frontend_entrypoints": [
-    "web/ai_influencer_resolution.ebb32f136a6a4294.js",
-    "web/easy_crop.3cd2d4db9e4387a9.js",
-    "web/halo_execution.41a5414872870fdf.js",
-    "web/image_collection.8677fd9cc9c550ba.js",
-    "web/prompt_director.b4c0409b1a3bd876.js",
-    "web/resolution_control_deck.355f138d9de085d8.js"
+    "web/ai_influencer_resolution.bd473fd081a9ee32.js",
+    "web/ai_influencer_resolution_2k4k.5a6f0a9d0be56983.js",
+    "web/easy_crop.e448d80a597cbf32.js",
+    "web/halo_execution.9c05a384226d4180.js",
+    "web/image_collection.57c26c1112198635.js",
+    "web/prompt_director.47d51c1218485744.js",
+    "web/resolution_control_deck.83ec2d2da93e1ef9.js"
   ],
   "nodes": [
     "MATRIXLAB_AIInfluencerResolution",
+    "MATRIXLAB_AIInfluencerResolution2K4K",
     "MATRIXLAB_EasyCrop",
     "MATRIXLAB_ImageBatchLoader",
     "MATRIXLAB_PromptDirector",
     "MATRIXLAB_Resolution",
     "MATRIXSpectralSampler",
-    "MATRIX_CameraLook",
     "MATRIX_CropTailPaste",
     "MATRIX_EyeMask",
     "MATRIX_LatentTail",
     "MATRIX_OutputStage",
-    "MATRIX_Renoise",
+    "MATRIX_PhotoFinisher",
     "MATRIX_SaveClean",
     "MATRIX_SkinMask"
   ],
   "pack_id": "matrix-lab-nodes",
-  "runtime_asset_registry_sha256": "ba2964519d538b65fafbbe2fbad5a9e7d16940334f49fcc517ddab041c59a5c4",
+  "runtime_asset_registry_sha256": "ab1955cfe5e8d05b832a4f63cae121d9afd6f74d3a9048b0107cf634659cada8",
   "status": "development",
-  "version": "0.1.0"
+  "version": "0.2.0",
+  "candidate_provenance": {
+    "strategy": "current-canonical-base-plus-additive-factory-node",
+    "base_builder_sha256": "c2716a4a31e0f380576ebccccf3844353a379e0c7fd58af85f665084c1c3f87f",
+    "compiler_sha256": "b1ff75cd7cefd07caaf7fc224d2b4518d7a65954c89e3bdee770d867a37e1e07",
+    "builder_sha256": "7df54e744e3aff1b58fd9699f5e1564e3f0c71d8370fe8b50b07aedf74dbeca9",
+    "existing_node_implementation_policy": "fresh-canonical-base-build",
+    "runtime_registry_policy": "owned-by-canonical-base-builder",
+    "runtime_asset_proof_sha256": "917902e05bb4e0758e6ba9b264075f89edbc0b2b39580fb2cb55d6e9c76945f8"
+  }
 }
diff --git a/NODES.md b/NODES.md
@@ -0,0 +1,22 @@
+# Node reference
+
+Package version 0.2.0 contains the fourteen classes below in six `MATRIX LAB` groups. The installed `MANIFEST.json` is authoritative for a particular artifact.
+
+| Display name | Class ID | Inputs | Outputs | Guide |
+| --- | --- | --- | --- | --- |
+| MATRIX METADATA KILLER | `MATRIX_SaveClean` | `images`; save options | output node | [Guide](docs/nodes/matrix-save-clean.md) |
+| MATRIX IMAGE BATCH LOADER | `MATRIXLAB_ImageBatchLoader` | `collection` | `images`, `masks` | [Guide](docs/nodes/image-batch-loader.md) |
+| MATRIX RESOLUTION | `MATRIXLAB_Resolution` | ratio, tier, custom dimensions | `width`, `height` | [Guide](docs/nodes/resolution.md) |
+| MATRIX AI INFLUENCER RESOLUTION | `MATRIXLAB_AIInfluencerResolution` | ratio, tier | `width`, `height` | [Guide](docs/nodes/ai-influencer-resolution.md) |
+| MATRIX AI INFLUENCER RESOLUTION 2K/4K | `MATRIXLAB_AIInfluencerResolution2K4K` | ratio, 2K/4K tier | `width`, `height` | [Guide](docs/nodes/ai-influencer-resolution-2k4k.md) |
+| MATRIX SPECTRAL SAMPLER | `MATRIXSpectralSampler` | sampler and spectral controls | `sampler` | [Guide](docs/nodes/spectral-sampler.md) |
+| MATRIX LATENT TAIL | `MATRIX_LatentTail` | model/noise/conditioning/latent; tail controls | `latent` | [Guide](docs/nodes/latent-tail.md) |
+| MATRIX CROP TAIL PASTE | `MATRIX_CropTailPaste` | image/mask/model/noise/conditioning/VAE; crop controls | `image` | [Guide](docs/nodes/crop-tail-paste.md) |
+| MATRIX SKIN MASK | `MATRIX_SkinMask` | image; part and mask controls | `mask`, `preview` | [Guide](docs/nodes/skin-mask.md) |
+| MATRIX EYE MASK | `MATRIX_EyeMask` | image; detector and mask controls | `mask`, `masks`, `bboxes`, `preview` | [Guide](docs/nodes/eye-mask.md) |
+| MATRIX PHOTO FINISHER | `MATRIX_PhotoFinisher` | image; optional mask and finish controls | `image` | [Guide](docs/nodes/photo-finisher.md) |
+| MATRIX EASY CROP | `MATRIXLAB_EasyCrop` | uploaded image and crop geometry | `image`, `mask` | [Guide](docs/nodes/easy-crop.md) |
+| MATRIX OUTPUT STAGE | `MATRIX_OutputStage` | image/model/noise/conditioning/VAE/target geometry; output controls | `image`, `info` | [Guide](docs/nodes/output-stage.md) |
+| MATRIX AUTO PROMPTER | `MATRIXLAB_PromptDirector` | saved prompt fields; optional images | `prompt` | [Guide](docs/nodes/auto-prompter.md) |
+
+`MATRIXLAB_AIInfluencerResolution2K4K` does not replace the base AI Influencer Resolution class.