ausboss-ComfyUI-AusBoss/AGENTS.md

ComfyUI-AusBoss contributor guide

Rules for contributors: how the repo is laid out, the conventions every node follows, and the checks to run.

A suite of polished ComfyUI custom nodes by ausboss. Public nodes must solve a repeated workflow need, keep a compact graph footprint, and pass backend plus browser acceptance before release.

READ FIRST: write for the people who use the nodes

Everything a user reads starts with the plainest version. That covers node descriptions, tooltips, the ? help pages (js/docs/*.md), the README, example workflow notes, report and error text, and the CHANGELOG. Get more technical later in the text, or in its own section.

• Open with what it does and when to use it, in everyday words and short sentences. Someone new to ComfyUI should get it on the first read.
• A tooltip is one or two short sentences: what this is, and what to pick.
• Measurements, test results, edge cases and how it works go further down, under a heading such as "Technical details".
• Keep jargon out of the opening (resample, warp, frame, affine, estimator, canvas space). If a term is needed, say what it means the first time.
• Put a number up top only when it helps someone decide what to do.

If a sentence needs a second read, rewrite it.

Which nodes ship

A node ships only when its mapping key is listed in PUBLIC_NODE_IDS in scripts/validate_nodes.py; the validator fails on any registered key that is not listed there.

Hard rules

• Never modify LICENSE.
• Never bump version in pyproject.toml — a version bump that lands on main publishes to the Comfy Registry automatically (see Releasing).
• Keep diffs minimal: touch only the lines the task needs.

Third-party independence

• Never copy third-party code, assets, fonts, icons, CSS, or documentation.
• Review ecosystem overlap before accepting a public node. Generic overlap is fine, but implementation, naming, interaction design, and documentation must be this repository's own work.

Architecture

__init__.py       # NODE_MODULES list → importlib merge of all mappings.
                  # Fail-soft: a broken module logs and is skipped, the rest load.
nodes/
  node_<name>.py  # exactly one node (or one tight family) per file;
                  # exports NODE_CLASS_MAPPINGS + NODE_DISPLAY_NAME_MAPPINGS
  _<topic>_helpers.py  # shared backend logic, underscore prefix = not a node
js/
  <name>/index.js # frontend entry per node or pack-wide feature, e.g.
                  # appearance/ (.js files auto-load)
  shared/*.mjs    # import-only shared modules (.mjs files do NOT auto-load)
docs/             # developer docs
scripts/          # offline checks in stdlib Python. validate_nodes.py is
                  # the entry point; registry_contract.py holds the rules
                  # that keep nodes visible to registry scanners;
                  # registry_status.py reads the Registry API; dev/ is the
                  # Node.js canvas harness (docs/live_testing.md).
example_workflows/  # example workflows (regular workflow JSON, not API JSON)

Conventions

• Public mapping keys use AUSBOSS_NODES_<Purpose>. The mapping key is the workflow-compatibility contract and must never be renamed after release.
• Inputs and outputs only grow after a release: append an input as optional, append an output, and never rename, reorder, remove or newly require one. Saved workflows keep widget values by position and links by slot, and an API prompt must carry every required input. tests/test_node_api.py holds the pack to tests/fixtures/node_api.json; refresh that snapshot with the test's --update after a compatible change or a new node.
• Appending an input to a node with a card or panel takes one more step. Workflows saved by earlier releases end that node's values with an empty value for each card and panel, and values come back by position, so the new input opens holding that empty value. Give a widget input a resetUnknown fallback in its card (js/widget_cards/index.js), or a RESET_UNKNOWN beside NODE_CLASS in the node's own js/<name>/index.js if it has no card (as LoRA Loader does). The fallback equals the node's default, which is what an API prompt without the input runs with. Then list the input in tests/saved_widget_values.test.mjs. Cards and panels themselves are never saved: set widget.serialize = false right after addDOMWidget (options.serialize only keeps a widget out of the prompt).
• Write those keys as string literals inside NODE_CLASS_MAPPINGS and NODE_DISPLAY_NAME_MAPPINGS — never a NODE_ID variable. Registry scanners (ComfyUI-Manager) AST-parse the source without importing it, so a variable key makes every node invisible and "install missing custom nodes" stops offering the pack. scripts/validate_nodes.py enforces this.
• Assign each mapping once, at module level, to a non-empty dict literal, and never mention the name again — no update(), no del, no alias = NODE_CLASS_MAPPINGS. A scanner reads that one literal and stops, so anything done to the mapping afterwards is invisible to it. Both mappings must carry exactly the same keys.
• Display name: <Name> 🆎 — the emoji is the pack signature. Typing "ausboss" still surfaces every node through the 🆎 AusBoss/<Group> category, the AUSBOSS_NODES_ id prefix, and the "ausboss" entry every node keeps in SEARCH_ALIASES.
• Category: 🆎 AusBoss/<Group>. The emoji is safe here — categories reach the frontend as JSON and are never printed to the console at import time.
• Every node gets DESCRIPTION, input tooltips, and OUTPUT_TOOLTIPS.
• IMAGE tensors are BHWC float batches; MASK is BHW. Return tuples always, even for one output: (value,).
• Console output at import time must stay ASCII — ComfyUI on Windows often runs a cp1252 console, and a UnicodeEncodeError there kills the whole pack.
• Widget values and route parameters are attacker-controlled: ComfyUI's /prompt and the pack's routes need no login. Media reads and writes stay inside ComfyUI's input, output and temp folders - no opt-in switches, no "any folder" settings, no folder pickers. Besides those the pack only reads its registered model folders and keeps its own settings files in ComfyUI's user folder (user/ausboss/). Nothing is handed to a subprocess. The Registry bans versions for exactly this.
• The pack makes no network requests: no HTTP or socket client in shipped code (release_preflight.py fails on one). Graph links are made with linkSlots from js/shared/graph_links.mjs, never the index-based node.connect(...), which registry scans read as a network socket. SECURITY.md states the model for users.
• No new pip dependencies without an explicit decision; if truly optional, use [project.optional-dependencies] and fail soft at runtime.
• Frontend files import each other only with plain string literals (from "../shared/x.mjs", import("../shared/x.mjs")). The server adds a version tag to those paths (nodes/_frontend_cache.py) so an update never meets old copies from the browser's cache. A path built in code (new URL(...), "../shared/" + name) escapes the tag and loads a second, stale copy; tests/test_frontend_cache.py fails on one.
• Frontend JS never assigns prototype callbacks directly — use chainCallback from js/shared/index.mjs, or chainHandler where the return value matters (a truthy onMouseDown result is what stops a node drag). Messages to the user go through showToast, never alert().
• Every INT and FLOAT a public node exposes reaches the user as a scrub control, Adobe-style: drag the value to scrub, click to type, chevron arrows step, Shift is always the fine step. Use makeScrubInput from js/shared/scrub_input.mjs — never a bare <input type=number>, and never a classic canvas number widget on a finished node face. Units (px, MP, ×) ride inside the box in a fixed-width slot that every single-field row reserves, so the numbers down a card share one centre line. Known, deliberate exceptions: the Seed card's seed (typed) and Load Video's trim timecodes (typed).
• Node faces are widget cards. A node whose face would be classic LiteGraph widgets (full-width rows with an arrow at each end) gets an entry in js/widget_cards/index.js instead: mountWidgetCard from js/shared/widget_card.mjs hides the standard widgets and mirrors them in one compact DOM card — numbers → scrub, ≤ 4 short choices → segmented pill (else a select), booleans → an off | on pill as wide as the other controls (never a small switch inside a card), strings → text field, multiline → kind: "textarea" (grow: true takes the node's spare height), hex colors → swatch. Rows can depend on other values (when) and fold behind a disclosure (group). The widgets underneath stay the single source of truth (save/load, undo, API, links).
• One linkable widget per row. The frontend (≥ 1.10.4, "Widget Input Socket" RFC #9) gives every widget an input socket drawn at the widget's own row, only while a link is dragged, hovered or connected; "convert to input" no longer exists. The card lends each hidden widget its row's position, so two widgets on one row would stack two sockets on one pixel and nobody could aim. A pair row is therefore only allowed with top: true, which lifts its sockets into the node's slot column under the real inputs (Image Resize width/height); everything else is one widget per row. A value that is meant to be wired rather than typed is a backend forceInput: True socket (Math Expression a/b/c), and a multi-type string such as "FLOAT,INT" accepts either kind of link.
• Preview-carrying nodes (Select Frame, Mask Refine, LaMa Inpaint, Save Image) share js/input_preview/: a thin bar (node tools left, a small preview switch right) above the picture, the picture gone and the node shorter when the switch is off, backed by an optional preview BOOLEAN input that also skips the temp file. A new node with a result picture reuses it rather than growing its own.
• A DOM panel that shows a stage/preview claims the node's free height via fillNodeHeight from js/shared/panel_layout.mjs — never a hand-rolled computeSize, which pins the panel and leaves dead space when the node is dragged taller. tests/panel_guards.test.mjs enforces this pack-wide: a new panel entry must be added to its mustGrow set (or fixedByDesign for genuinely constant-height rows), so the choice is always explicit.
• Frontend settings use AusBoss.<Area>.<Name> ids with category: ["🆎 AusBoss", "<Area>", "<Leaf>"] and a distinct leaf per setting. Node color schemes live in js/shared/appearance.mjs.

Adding a node

Follow docs/adding_a_node.md. Short version: create nodes/node_<name>.py modelled on a small existing node such as nodes/node_image_size.py, add "node_<name>" to NODE_MODULES in __init__.py and the key to PUBLIC_NODE_IDS in scripts/validate_nodes.py, give it a help page at js/docs/<KEY>.md, optionally add js/<name>/index.js, then validate.

Validation

Run the offline checks before a pull request:

python scripts/validate_nodes.py
python scripts/release_preflight.py
python scripts/run_python_tests.py   # with ComfyUI's Python
node --test tests/*.test.mjs

Then restart ComfyUI fully (a changed INPUT_TYPES is only served after a restart), watch the AusBoss banner for failed modules, confirm the node appears in GET http://127.0.0.1:8188/object_info, queue a tiny API graph, and load its example workflow. After JS changes, hard-refresh the browser tab (Ctrl+Shift+R) — the frontend caches .mjs modules aggressively.

Frontend work is proven on a real canvas, not by reading code: the headless-Chrome harness in scripts/dev/ (recipe, gotchas and the screenshot convention in docs/live_testing.md) creates nodes, drives real mouse drags, and screenshots the result. A link-drop test that only checks which input got the link is not enough — look at the picture and ask whether a person could have aimed there.

Releasing

A new version in pyproject.toml that lands on main publishes to the Comfy Registry through the publish workflow (.github/workflows/publish_action.yml). Contributors never change version.

Example workflows

Examples are what most people run first, so each one must work for a stranger with only the files its Workflow Note lists.

• Every model loader selects the official file name, the basename of its download URL, carries that file in properties.models (name, url, directory), and the Note's model row names the same file. People who keep models in subfolders pick their copy.
• Media loaders (Load Image, Load Image + Pad, Load Video, Image Crop + Rotate + Pad and the video nodes) are saved blank. A file name is one the stranger doesn't have, and ComfyUI flags that node red when the workflow loads. The Workflow Note tells people to load their own picture; the sample files stay in example_workflows/inputs/ for anyone who wants to try one.
• Save nodes use a filename prefix without a folder. Seeds are fixed.
• Numbered groups hold every node, nothing overlaps (title bars included), the saved zoom is at least 0.6 so widget text draws, the workflow id is a real uuid4, and the .jpg beside the .json shows a real output.
• The frontend saves widget values twice, by position and by name (widgets_values_named), and can restore by name; both copies must agree.
• scripts/workflow_contract.py checks links, groups, overlaps, the note, the id, the zoom, the named copies, the download info and the save prefixes. Whether the note tells the truth about the graph is review.
• Text-to-image examples have no source to describe. Edit and inpaint examples keep an explicit change instruction: a description of the old scene is not an edit. MiniMax H3 and Klein caption their sources with Qwen3-VL 8B because their own text encoders returned only punctuation when asked to describe an image.