ausboss-ComfyUI-AusBoss/CONTRIBUTING.md

Contributing

Bug reports, workflow ideas and pull requests are welcome.

Reporting a problem

The most useful report names:

• the ComfyUI and frontend versions (Settings → About),
• the pack version from the console banner (AusBoss vX.Y.Z | N nodes loaded),
• the node, what you expected, and what happened instead,
• the smallest workflow that shows it, plus a screenshot for anything visual.

Security problems go through SECURITY.md instead of a public issue.

Pull requests

• Read the contributor guide below first, and a new public node follows docs/adding_a_node.md. A new node is a conversation before it is a pull request.

• Mapping keys, input names and order, and output order are a permanent API: saved workflows depend on them. Append optional inputs and outputs instead of renaming or reordering. tests/test_node_api.py checks this against a snapshot; its docstring shows how to refresh the snapshot after a compatible change.

• Leave version in pyproject.toml alone. A version change that reaches main publishes to the Comfy Registry.

• Run the offline checks. None of them needs a GPU; the Python tests need ComfyUI's Python environment.

  python scripts/validate_nodes.py
  python scripts/release_preflight.py
  python scripts/run_python_tests.py
  node --test tests/*.test.mjs
  

• Frontend changes are checked on a real canvas as well as in tests. docs/live_testing.md describes the headless browser harness and what to screenshot.

• A fix PR says what was wrong, adds a test that fails before the fix and passes after it, and shows before/after results.

Contributor guide

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. A file is picked from a list and named below one of those folders the way ComfyUI names it (clip.mp4 [output]); no input opens a whole path as given. A route answers with data it made (JSON, a small picture), never a file by its path (web.FileResponse), and its error text goes through safe_route_error (nodes/_route_errors.py). Besides those the pack only reads its registered model folders (the one write there is LoRA Loader's Civitai button: a .civitai.info file and a .preview.jpg picture, saved beside a LoRA, never replacing a picture) 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's server code makes no network requests: no HTTP or socket client in shipped Python (release_preflight.py fails on one). The one outbound call is LoRA Loader's click-only Civitai lookup, made by the browser to a fixed civitai.com address with a plain SHA256, plus the LoRA's picture from image.civitai.com on the same click (js/lora_loader/index.js, js/shared/civitai_lookup.mjs). release_preflight.py allows a raw fetch( only there and in js/cache_guard, which only talks to the pack's own server. 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().
• The mouse wheel over a node zooms the graph, on every part of its face. js/canvas_passthrough/ hands the wheel on from the pack's panels, and keeps it only for a box that can still scroll or a field being typed in, so a panel adds no wheel listener of its own (tests/canvas_passthrough.test.mjs lists the few that exist). After a change to a node face, scripts/dev/wheel_sweep.mjs turns the wheel at every point of every node and must find no dead spot, in both renderers.
• 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, Mask by Name, 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. A fixedByDesign card also calls pinVuePanelHeight: its own computeSize only pins it in the classic renderer, and Nodes 2.0 would stretch it with the node and squeeze a picture under it. Run Timer does not: its readout fills the node on purpose.
• A picture or clip in a stage sits out of flow. Nodes 2.0 sizes a node by its content, so an in-flow portrait clip drawn at full width held Load Video at 965 px where classic goes to 584 px. Position the media absolute in its stage, and the stage takes its size from the node alone. A picture is centred at its own size (js/input_preview/); a player fills the stage so its controls stay along the bottom edge (js/shared/video_ui.mjs). Text that is fitted to its box follows the same rule: the Callout's text is absolute in its card (js/callout/index.js), or the text sizes the card it is fitted to. tests/panel_guards.test.mjs holds all three.
• A panel's declared minimum width is its node's real floor. Pass exactMinWidth: true to fillNodeHeight; a constant-height card that keeps its own computeSize calls holdNodeMinWidth instead. Left alone, the frontend adds 104 px to a growing panel's number and ignores a pinned card's number altogether (the node falls to its 210 px default), so a declared 320 meant 424 for one and 210 for the other. Prove each face on a real canvas at that width in both renderers; a panel that clips there gets a larger minimum, not a broken face. Nodes 2.0 never goes under 225 px whatever a panel declares.
• A growing panel's declared minimum height holds in Nodes 2.0 too. Nodes 2.0 lays a node out by its content, not by the floor a widget declares, so a panel whose content has no height of its own was dragged flat there. fillNodeHeight also writes the floor to the panel's element as a CSS min-height, less WIDGET_FRAME, while the panel sits inside a Nodes 2.0 node. So declare minHeight as what the element needs plus WIDGET_FRAME, and never assign a growing panel's computeLayoutSize by hand. Prove the floor with a real corner drag up in both renderers.
• 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.

A ComfyUI update can break a node without a line of the pack changing. So the pack is run against the newest ComfyUI every night (.github/workflows/comfyui_compat.yml): its newest release and its development head, on the CPU, with no model files. Three checks, which also run by hand against any ComfyUI:

AUSBOSS_COMFY_ROOT=<ComfyUI> python tests/test_comfy_core_contract.py
python scripts/compat_boot.py --url http://127.0.0.1:8188
node scripts/dev/face_smoke.mjs <chrome port>            # and again with --vue

• test_comfy_core_contract.py reads the pack's own source for everything it takes from ComfyUI and looks each thing up in the real one. It finds imports by itself. A call to one of ComfyUI's own nodes by name (SAM3_Detect), or an internal read with a fallback, goes in the tables at the top of that file; the test fails on a node call that is not listed.
• compat_boot.py asks a running ComfyUI which nodes it offers: every public node of the pack, and every node and required input the examples use.
• face_smoke.mjs puts every node on a graph and fails when a face does not come up or something throws.

A failure on the release opens an issue labelled comfyui-update. What these cannot see is anything that needs a model: run the real thing on a GPU before a release that follows a ComfyUI update.

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.

The Registry shows notes with each version. They are that version's section of CHANGELOG.md, one line per entry: its bold opening, and for a new node the sentence that says what it does (scripts/changelog_notes.py). So open every entry with a bold line that makes sense on its own.

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.