diff --git a/docs/h4_toolkit_brief.html b/docs/h4_toolkit_brief.html index bf4ac81..5d3304a 100644 --- a/docs/h4_toolkit_brief.html +++ b/docs/h4_toolkit_brief.html @@ -1,662 +1,1141 @@ - - - - - h4 Toolkit :: Cyberpunk Ops Dossier - - - - -
-

h4 Toolkit Operations Log

-

- Cyberpunk diagnostics dossier detailing the build-out of the h4 Toolkit custom nodes for ComfyUI. - Use this as the canonical reference for architecture, behaviour, and future-proofing tactics before shipping. -

-
- - - -
-
-

Mission Recap

-
-
- Objective -

Deliver a polished, stability-focused node suite for ComfyUI that feels native while remaining hyper-observable during development.

-
    -
  • h4 : The Engine (h4_PlotXY) orchestrates checkpoint loading, sampler/scheduler swaps, LoRA layering, grid assembly, and fast previews.
    • -
  • h4_Debug-a-Tron suite provides console-first monitoring plus a lightweight router variant for live passthroughs.
    • -
  • UX polish via JavaScript injects placeholders, tooltips, and dynamic sockets without bloating the node count.
    • -
-
-
- Guiding Principles -
    -
  • Ship production-ready code in a single pass: no placeholders, no silent branches, no half-written functions.
    • -
  • Stay resource-light: defer heavy work until needed, reuse latents, and keep previews in low-cost lanes.
    • -
  • Maintain clairvoyant visibility: every meaningful action emits colour-coded console traces.
    • -
-
-
-
- Maintainer Marker — confirm TOOLKIT_VERSION, PLOT_NODE_VERSION, and DEBUG_NODE_VERSION stay aligned with release notes before packaging. -
-
- -
-

Incident Remediation Log

-

- October 2025 brought a cascade of ComfyUI sampler API changes that detonated our previously stable - h4_PlotXY pipeline powering h4 : The Engine. The following dossier captures every mitigation deployed to restore single-image - runs while future-proofing the node against the next upstream mutation. -

- -

Root Cause

- - -

Step-by-Step Fixes

-
    -
  1. - Sampler kwarg triage. Injected the latent tensor's device into the sampler kwargs and began precomputing - sigmas via calculate_sigmas, coercing list outputs back into on-device tensors. -
    2. -
  2. - Adaptive signature mapper. Expanded the compatibility shim so renamed keywords (device, sigmas, - model_sampling) land on whatever the new sampler signature accepts, with warnings when required fields are still missing. -
    3. -
  3. - Sigma generator hardening. Wrapped calculate_sigmas with introspection that feeds only the parameters it - advertises, surfaces missing requirements, and gracefully downgrades to log-only failure when upstream breaks format. -
    4. -
  4. - Clip skip sanity. Introduced idempotent logging that reports unavailable clip-skip helpers exactly once and added - additional fallbacks to reach any nested set_clip_skip hook without spamming the console. -
    5. -
  5. - Model sampling intelligence. Authored _extract_model_sampling to traverse wrapped diffusion models, - returning concrete sampler metadata (sigma_min/sigma_max/schedule/model_type) and wiring it into both the - sampler kwargs and the sigma scheduler. -
    6. -
  6. - Callable safety net. Hardened _callable_or_value so torch modules without a real forward (or callables demanding - positional/variadic arguments) are treated as data instead of being invoked, preventing NotImplementedError loops. -
    7. -
  7. - Latent payload alignment. Passed the raw latent tensor to the sampler (matching the new .to() contract) and - rewrapped tensor results into the legacy dict structure for downstream consumers. -
    8. -
  8. - Sampler factory bridge. Implemented _resolve_sampler_object to locate and invoke sampler factory functions - from comfy.samplers or the model itself, capturing the instantiated sampler object whenever available and falling back to a - one-time warning when factories are absent. -
    9. -
  9. - Metadata propagation. Streamed all discovered sampler metadata (including model type and sigma schedule hints) into the - compatibility shim so future API bumps can consume them without further code edits. -
    10. -
  10. - Verification cadence. After each code change, executed py_compile h4_Plot/nodes.py to guarantee syntax integrity, - then reran Engine single-image workflows until the sampler pathway completed cleanly. -
    11. -
  11. - Kwarg remap automation. Upgraded the compatibility shim to interrogate the live sampler signature, automatically - renaming legacy keywords (steps, cfg, latent) before the first call, eliminating the "unexpected keyword" cascade in - the latest ComfyUI builds. -
    12. -
  12. - Preview resiliency. Added a capability detector that falls back to modern comfy.utils helpers (or disables previews once) - when latent_preview is missing, stopping the per-step warning spam while keeping previews alive where supported. -
    13. -
  13. - Grid tensor correction. Normalised decoded tensors to channel-last layout before stitching the master grid, resolving Pillow's - "Cannot handle this data type" failure during multi-plan exports and guarding against mismatched tile shapes. -
    14. -
  14. - On-image labelling. Added a Pillow-backed overlay that stamps each grid tile with its plan label, keeping comparison runs - readable once exported or shared outside of ComfyUI. -
    15. -
- -

Outcome

-

- With the fixes above, The Engine now negotiates the latest sampler API without runtime crashes, emits - trace-level breadcrumbs for factory detection, produces grid composites that downstream save nodes accept, and - silence-preview fallbacks keep runs clean on environments missing old preview hooks. Future upgrades can layer - new sampler parameters into the available_values map without touching the call sites. -

-

- Latest validation runs confirm The Engine is fully operational: labelled grids export crisply, placeholders stay - in their lane, and the loader / engine combo shreds through plan matrices without a single warning. Mission - accomplished for generation maths; next stop is the Debug-a-Tron, where these hardened utilities will feed the - console-grade inspector. -

- -
- Maintainer Marker — when ComfyUI ships another sampler revision, update the factory discovery list here first so downstream - nodes inherit the resilience for free. -
-
- -
-

Debug-a-Tron Modernisation Log — 11 Oct 2025

-

This log captures every action taken during the latest session to stabilise and elevate the Debug-a-Tron experience, matching The Engine’s polish while preparing the router for dual-branch diagnostics.

- -

Sequence of Operations

-
    -
  1. Console node slim-down. Removed the legacy faux-terminal widget, collapsed redundant status text, refreshed branding, and enforced compact default sizing so the node docks neatly beside Engine outputs.
    2. -
  2. Go Plus Ultra! UX sweep. Front-end script now strips the ultra_ prefix from widget labels, enforces a predictable collapsed height, and fully detaches advanced controls when the toggle is off (no latent layout jitter).
    3. -
  3. Router overhaul blueprint. Added overridable class attributes to h4_DebugATron3000 (SLOT_DEFINITIONS, SLOT_TOOLTIPS, VAE_MODEL_FALLBACKS, BRANCH_DISPLAY_NAMES) so downstream variants can redefine sockets without copy/paste.
    4. -
  4. Metadata-driven INPUT/OUTPUT tables. Reworked INPUT_TYPES(), RETURN_TYPES, and RETURN_NAMES to derive directly from the active slot table, ensuring subclasses inherit correct wiring automatically.
    5. -
  5. Router branch duplication. Crafted router-specific slot dictionaries that double every inlet/outlet with _a/_b suffixes, human-friendly labels (e.g. “Branch A · Latent”), and branch-aware tooltips.
    6. -
  6. Branch-aware diagnostics. Implemented helper methods (_slot_variants, _slot_branch_suffix, _branch_label, _matching_branch_slot) so both nodes can reason about sibling slots, VAE fallbacks, and conditioning coverage per branch.
    7. -
  7. Go Plus Ultra telemetry upgrade. Snapshots, anomaly checks, token previews, JSON logging, and preview image capture now tag their output with branch + slot context, making dual-lane routing transparent.
    8. -
  8. Branch summaries. Added a condensed summary that lists the connection ratio for Branch A/B, highlights missing sockets, and appends warnings directly to the console/log output.
    9. -
- -

Errors & Resolutions

- - -

Validation Cadence

- - -
- Maintainer Marker — when introducing new branch layouts (e.g., triple routes), declare the suffix map in ROUTER_BRANCH_SUFFIXES and the rest of the stack will adapt automatically.
-
- -
-

Architecture & Pipelines

-

Core Files

- - -

Execution Flow

-
    -
  1. Startup — __init__.py checks/installs dependencies, emits update notices, imports nodes, then renders the neon-lit banner.
    2. -
  2. User Interaction — the UI script decorates widgets, spawns dynamic connectors, and keeps layout toggles responsive.
    3. -
  3. The Engine Run -
      -
    • Axis descriptors parsed with knowledge of on-disk checkpoints/Loras.
      • -
    • Generation plans computed (cartesian product across axes).
      • -
    • Checkpoint, sampler, scheduler, clip skip, and VAE/CLIP overrides orchestrated per plan.
      • -
    • DPM++ 2M SDE + Karras sampler runs with rapid previews pushed via latent_preview when present.
      • -
    • Decoded outputs assembled into square-first grids; stacked tensor and tiling grid returned.
      • -
    -
    4. -
  4. Debug-a-Tron Run — console node prints formatted logs while router variant defaults to passthrough using shared dynamic sockets.
    5. -
- -
- Telemetry Hooks -

All helpers and node methods route through ToolkitLogger. Flip the TRACE flag to silence console chatter post-debug. Preview failures are downgraded to warnings to avoid collapsing the run.

-
- -
- Maintainer Marker — when adding new nodes, respect the “three-node ceiling” mantra and expand NODE_CLASS_MAPPINGS only with explicit user consent. -
-
- -
-

The Engine Deep Dive (h4_PlotXY)

-

The Engine node (h4_PlotXY) is a self-contained composer that can operate standalone or accept mid-pipeline overrides. Highlights:

- - -

Observability

-

Every stage logs to console (loading checkpoints, encoding prompts, applying LoRAs, publishing previews). The returned stack pairs cleanly with Debug-a-Tron for in-graph comparison panels.

- -
- Maintainer Marker — when introducing new axis presets or overrides, update both the widget tooltips in js/h4_ui.js and this checklist. -
-
- -
-

Debug-a-Tron Suite

-

The Debug-a-Tron family ships in two flavours: the console-heavy h4_DebugATron3000 and the stream-lined h4_DebugATronRouter. Both now inherit from a metadata-driven base that keeps slot definitions, labels, tooltips, and fallbacks in sync.

- -

Shared Platform Features

- - -

Main Console Node — h4_DebugATron3000

- - -

Router Variant — h4_DebugATronRouter

- - -

Inline Diagnostics

-

Drop the console node near noisy subgraphs to capture shape/device metadata without disrupting flow, or slot the router variant wherever you need branch-aware passthrough plus breadcrumbs. Summary text now explicitly lists Branch A/B health, making graph triage near-instant.

- -
- Maintainer Marker — if ComfyUI introduces new socket types, extend the wildcard count and UI type dictionary in tandem for both variants. Branch naming is controlled centrally inside ROUTER_BRANCH_SUFFIXES.
-
- -
-

Dependencies & Telemetry

- - -
- Deployment Notes -
    -
  • Set TRACE logging off before public release to quiet console spam.
    • -
  • Maintain requirements.txt in lockstep with DEPENDENCIES to keep manual installs frictionless.
    • -
-
- -
- Maintainer Marker — plan a VS-aware configuration so the banner can display the current ComfyUI/Stability Matrix version once the upstream API exposes it.
-
- -
-

Code Appendix

-

Quick reference snippets for the primary modules. Consult the repository for up-to-the-minute source.

- -

nodes.py

- 
# nodes.py quick reference (v2.1.0)
-- Global discovery helpers: build sampler/scheduler choice tables, normalise lookup keys, and guard against missing ComfyUI modules.
-- ToolkitLogger: colour-coded INFO/WARN/TRACE emitter used everywhere.
-- AxisDescriptor: dataclass powering Engine's grid planning overrides.
-- _invoke_sampler_with_compatibility(...): signature-aware shim that renames/drops kwargs to match active sampler expectations.
-- h4_PlotXY.run_pipeline(...): orchestrates plan execution (axis parsing, LoRA injection, latent prep, sampler invocation, preview publishing, grid assembly, labelled export).
-- h4_DebugATron3000 (base class):
-  • SLOT_DEFINITIONS / SLOT_TOOLTIPS / VAE_MODEL_FALLBACKS / BRANCH_DISPLAY_NAMES metadata drive input/output wiring.
-  • INPUT_TYPES() auto-builds optional controls (including Go Plus Ultra toggles) from that metadata.
-  • route(...) clones passthrough payloads, logs descriptors, runs Go Plus Ultra diagnostics, writes previews/JSON, and now aggregates per-branch summaries.
-  • Helper matrix (_slot_variants, _slot_branch_suffix, _branch_label, _matching_branch_slot) coordinates branch-aware lookups.
-  • _collect_latent_snapshots / _tensor_anomalies / _preview_conditioning_tokens feed diagnostics.
-- h4_DebugATronRouter: overrides slot/tooltips/fallback maps with Branch A/B variants, inherits route() implementation, and ships default mode = passthrough.
-- Export dictionaries (NODE_CLASS_MAPPINGS / DISPLAY / TOOLTIP) register every node with ComfyUI.
-
- -

__init__.py

- 
# __init__.py quick reference
-- ensure_dependencies() installs or warns about colorama, numpy, torch.
-- Imports NODE_CLASS_MAPPINGS / DISPLAY / TOOLTIP dictionaries from nodes.py.
-- Emits status banner listing h4 : Plot XY, Debug-a-Tron-3000, and Router load states.
-- Exposes WEB_DIRECTORY so ComfyUI pulls js/h4_ui.js automatically.
-
- -
- Maintainer Marker — after every refactor, refresh these excerpts or link to generated API docs. -
-
- -
-

Future-Proof Planning

-

Immediate Enhancements

- - -

Version Awareness Initiative

- - -

Maintenance Rituals

- -
- -
-

Final Product Briefing

-

The h4 Toolkit now ships as a cohesive triad: a battle-tested sampler engine, a clairvoyant debugging suite, and a UI companion that keeps controls ergonomic. This section articulates every feature and function in their final form.

- -

End-to-End Overview

- - -

Function-by-Function Detail — h4_Plot/nodes.py

- - -

Function-by-Function Detail — h4_Plot/js/h4_ui.js

- - -

Behavioural Guarantees

- - -

Validation Summary

- - -
- Maintainer Marker — revisit this briefing after every release; the final product description doubles as the acceptance checklist for future regressions.
-
-
- - - - - - - + + + + + h4 Toolkit :: Cyberpunk Ops Dossier + + + + +
+

h4 Toolkit Operations Log

+

+ Cyberpunk diagnostics dossier detailing the build-out of the h4 Toolkit custom nodes for ComfyUI. + Use this as the canonical reference for architecture, behaviour, and future-proofing tactics before shipping. +

+
+ + + +
+
+

Mission Recap

+
+
+ Objective +

Deliver a polished, stability-focused node suite for ComfyUI that feels native while remaining hyper-observable during development.

+
    +
  • h4 : The Engine (h4_PlotXY) orchestrates checkpoint loading, sampler/scheduler swaps, LoRA layering, grid assembly, and fast previews.
    • +
  • h4_Debug-a-Tron suite provides console-first monitoring plus a lightweight router variant for live passthroughs.
    • +
  • UX polish via JavaScript injects placeholders, tooltips, and dynamic sockets without bloating the node count.
    • +
  • New specialty nodes add HTML reporting (h4_DebugATron3000Console), seed fan-out (h4_SeedBroadcaster), and console mirroring (h4_ExecutionLogger).
    • +
+
+
+ Guiding Principles +
    +
  • Ship production-ready code in a single pass: no placeholders, no silent branches, no half-written functions.
    • +
  • Stay resource-light: defer heavy work until needed, reuse latents, and keep previews in low-cost lanes.
    • +
  • Maintain clairvoyant visibility: every meaningful action emits colour-coded console traces.
    • +
+
+
+
+ Maintainer Marker — confirm TOOLKIT_VERSION, PLOT_NODE_VERSION, and DEBUG_NODE_VERSION stay aligned with release notes before packaging. +
+
+ +
+

Latest Field Notes — 15 Oct 2025

+

+ Quick rundown of the restoration sprint that brought the toolkit back online after the accidental node purge + and the Axis Driver overlay hiccup. +

+ +
+ +
+

Incident Remediation Log

+

+ October 2025 brought a cascade of ComfyUI sampler API changes that detonated our previously stable + h4_PlotXY pipeline powering h4 : The Engine. The following dossier captures every mitigation deployed to restore single-image + runs while future-proofing the node against the next upstream mutation. +

+ +

Root Cause

+ + +

Step-by-Step Fixes

+
    +
  1. + Sampler kwarg triage. Injected the latent tensor's device into the sampler kwargs and began precomputing + sigmas via calculate_sigmas, coercing list outputs back into on-device tensors. +
    2. +
  2. + Adaptive signature mapper. Expanded the compatibility shim so renamed keywords (device, sigmas, + model_sampling) land on whatever the new sampler signature accepts, with warnings when required fields are still missing. +
    3. +
  3. + Sigma generator hardening. Wrapped calculate_sigmas with introspection that feeds only the parameters it + advertises, surfaces missing requirements, and gracefully downgrades to log-only failure when upstream breaks format. +
    4. +
  4. + Clip skip sanity. Introduced idempotent logging that reports unavailable clip-skip helpers exactly once and added + additional fallbacks to reach any nested set_clip_skip hook without spamming the console. +
    5. +
  5. + Model sampling intelligence. Authored _extract_model_sampling to traverse wrapped diffusion models, + returning concrete sampler metadata (sigma_min/sigma_max/schedule/model_type) and wiring it into both the + sampler kwargs and the sigma scheduler. +
    6. +
  6. + Callable safety net. Hardened _callable_or_value so torch modules without a real forward (or callables demanding + positional/variadic arguments) are treated as data instead of being invoked, preventing NotImplementedError loops. +
    7. +
  7. + Latent payload alignment. Passed the raw latent tensor to the sampler (matching the new .to() contract) and + rewrapped tensor results into the legacy dict structure for downstream consumers. +
    8. +
  8. + Sampler factory bridge. Implemented _resolve_sampler_object to locate and invoke sampler factory functions + from comfy.samplers or the model itself, capturing the instantiated sampler object whenever available and falling back to a + one-time warning when factories are absent. +
    9. +
  9. + Metadata propagation. Streamed all discovered sampler metadata (including model type and sigma schedule hints) into the + compatibility shim so future API bumps can consume them without further code edits. +
    10. +
  10. + Verification cadence. After each code change, executed py_compile h4_Plot/nodes.py to guarantee syntax integrity, + then reran Engine single-image workflows until the sampler pathway completed cleanly. +
    11. +
  11. + Kwarg remap automation. Upgraded the compatibility shim to interrogate the live sampler signature, automatically + renaming legacy keywords (steps, cfg, latent) before the first call, eliminating the "unexpected keyword" cascade in + the latest ComfyUI builds. +
    12. +
  12. + Preview resiliency. Added a capability detector that falls back to modern comfy.utils helpers (or disables previews once) + when latent_preview is missing, stopping the per-step warning spam while keeping previews alive where supported. +
    13. +
  13. + Grid tensor correction. Normalised decoded tensors to channel-last layout before stitching the master grid, resolving Pillow's + "Cannot handle this data type" failure during multi-plan exports and guarding against mismatched tile shapes. +
    14. +
  14. + On-image labelling. Added a Pillow-backed overlay that stamps each grid tile with its plan label, keeping comparison runs + readable once exported or shared outside of ComfyUI. +
    15. +
+ +

Outcome

+

+ With the fixes above, The Engine now negotiates the latest sampler API without runtime crashes, emits + trace-level breadcrumbs for factory detection, produces grid composites that downstream save nodes accept, and + silence-preview fallbacks keep runs clean on environments missing old preview hooks. Future upgrades can layer + new sampler parameters into the available_values map without touching the call sites. +

+

+ Latest validation runs confirm The Engine is fully operational: labelled grids export crisply, placeholders stay + in their lane, and the loader / engine combo shreds through plan matrices without a single warning. Mission + accomplished for generation maths; next stop is the Debug-a-Tron, where these hardened utilities will feed the + console-grade inspector. +

+ +
+ Maintainer Marker — when ComfyUI ships another sampler revision, update the factory discovery list here first so downstream + nodes inherit the resilience for free. +
+
+ +
+

Debug-a-Tron Modernisation Log — 11 Oct 2025

+

This log captures every action taken during the latest session to stabilise and elevate the Debug-a-Tron experience, matching The Engine’s polish while preparing the router for dual-branch diagnostics.

+ +

Sequence of Operations

+
    +
  1. Console node slim-down. Removed the legacy faux-terminal widget, collapsed redundant status text, refreshed branding, and enforced compact default sizing so the node docks neatly beside Engine outputs.
    2. +
  2. Go Plus Ultra! UX sweep. Front-end script now strips the ultra_ prefix from widget labels, enforces a predictable collapsed height, and fully detaches advanced controls when the toggle is off (no latent layout jitter).
    3. +
  3. Router overhaul blueprint. Added overridable class attributes to h4_DebugATron3000 (SLOT_DEFINITIONS, SLOT_TOOLTIPS, VAE_MODEL_FALLBACKS, BRANCH_DISPLAY_NAMES) so downstream variants can redefine sockets without copy/paste.
    4. +
  4. Metadata-driven INPUT/OUTPUT tables. Reworked INPUT_TYPES(), RETURN_TYPES, and RETURN_NAMES to derive directly from the active slot table, ensuring subclasses inherit correct wiring automatically.
    5. +
  5. Router branch duplication. Crafted router-specific slot dictionaries that double every inlet/outlet with _a/_b suffixes, human-friendly labels (e.g. “Branch A · Latent”), and branch-aware tooltips.
    6. +
  6. Branch-aware diagnostics. Implemented helper methods (_slot_variants, _slot_branch_suffix, _branch_label, _matching_branch_slot) so both nodes can reason about sibling slots, VAE fallbacks, and conditioning coverage per branch.
    7. +
  7. Go Plus Ultra telemetry upgrade. Snapshots, anomaly checks, token previews, JSON logging, and preview image capture now tag their output with branch + slot context, making dual-lane routing transparent.
    8. +
  8. Branch summaries. Added a condensed summary that lists the connection ratio for Branch A/B, highlights missing sockets, and appends warnings directly to the console/log output.
    9. +
+ +

Errors & Resolutions

+ + +

Validation Cadence

+ + +
+ Maintainer Marker — when introducing new branch layouts (e.g., triple routes), declare the suffix map in ROUTER_BRANCH_SUFFIXES and the rest of the stack will adapt automatically.
+
+ +
+

Architecture & Pipelines

+

Core Files

+ + +

Execution Flow

+
    +
  1. Startup — __init__.py checks/installs dependencies, emits update notices, imports nodes, then renders the neon-lit banner.
    2. +
  2. User Interaction — the UI script decorates widgets, spawns dynamic connectors, and keeps layout toggles responsive.
    3. +
  3. The Engine Run +
      +
    • Axis descriptors parsed with knowledge of on-disk checkpoints/Loras.
      • +
    • Generation plans computed (cartesian product across axes).
      • +
    • Checkpoint, sampler, scheduler, clip skip, and VAE/CLIP overrides orchestrated per plan.
      • +
    • DPM++ 2M SDE + Karras sampler runs with rapid previews pushed via latent_preview when present.
      • +
    • Decoded outputs assembled into square-first grids; stacked tensor and tiling grid returned.
      • +
    +
    4. +
  4. Debug-a-Tron Run — console node prints formatted logs while router variant defaults to passthrough using shared dynamic sockets.
    5. +
+ +

Wiring Overview

+ 
+Axis Drivers ──▶ h4_PlotXY "The Engine" ──▶ h4_DebugATron stack ──▶ Outputs / Saves
+     │                   │                          │
+     ├─ X / Y / Z JSON ─┘                          ├─ h4_DebugATron3000Console (html_log + passthrough)
+     │                                              ├─ h4_ExecutionLogger (log_summary)
+     └─ Style payloads feed grid annotation         └─ h4_SeedBroadcaster can sit upstream of multiple samplers
+
+ +
+ Telemetry Hooks +

All helpers and node methods route through ToolkitLogger. Flip the TRACE flag to silence console chatter post-debug. Preview failures are downgraded to warnings to avoid collapsing the run.

+
+ +
+ Maintainer Marker — when adding new nodes, respect the “three-node ceiling” mantra and expand NODE_CLASS_MAPPINGS only with explicit user consent. +
+
+ +
+

The Engine Deep Dive (h4_PlotXY)

+

The Engine node (h4_PlotXY) is a self-contained composer that can operate standalone or accept mid-pipeline overrides. Highlights:

+ + +

Observability

+

Every stage logs to console (loading checkpoints, encoding prompts, applying LoRAs, publishing previews). The returned stack pairs cleanly with Debug-a-Tron for in-graph comparison panels.

+ +
+ Maintainer Marker — when introducing new axis presets or overrides, update both the widget tooltips in js/h4_ui.js and this checklist. +
+
+ +
+

Debug-a-Tron Suite

+

The Debug-a-Tron family ships in two flavours: the console-heavy h4_DebugATron3000 and the stream-lined h4_DebugATronRouter. Both now inherit from a metadata-driven base that keeps slot definitions, labels, tooltips, and fallbacks in sync.

+ +

Shared Platform Features

+ + +

Main Console Node — h4_DebugATron3000

+ + +

Router Variant — h4_DebugATronRouter

+ + +

Inline Diagnostics

+

Drop the console node near noisy subgraphs to capture shape/device metadata without disrupting flow, or slot the router variant wherever you need branch-aware passthrough plus breadcrumbs. Summary text now explicitly lists Branch A/B health, making graph triage near-instant.

+ +
+ Maintainer Marker — if ComfyUI introduces new socket types, extend the wildcard count and UI type dictionary in tandem for both variants. Branch naming is controlled centrally inside ROUTER_BRANCH_SUFFIXES.
+
+ +
+

Debug Console — HTML Telemetry Node

+

The h4_DebugATron3000Console takes the base Debug-a-Tron diagnostics and packages them into a neon HTML dossier while still mirroring payloads downstream. It is registered as an output node so the rendered report is immediately visible inside ComfyUI’s right-hand panel.

+ +

Display Deck

+ + +

Outputs

+ + +

Deployment Pattern

+
    +
  1. Place the console node at the tail of your diagnostic branch.
    2. +
  2. Set desired palette/verbosity. Leave display mode on both for development, flip to html_only when shipping reports.
    3. +
  3. Execute the workflow; the HTML transcript appears immediately. Optional: wire the string into a file writer for automatic archiving.
    4. +
+ +
Maintainer Marker — keep the color-scheme dictionary in sync with README screenshots. If a new socket type lands, ensure the HTML renderer recognises it with a colour swatch.
+
+ +
+

Utility Nodes

+

Two lightweight helpers join the toolkit to streamline workflow orchestration and audit trails.

+ +

h4_SeedBroadcaster

+ + +

h4_ExecutionLogger

+ + +
Maintainer Marker — if a future release adds additional scalar types (e.g., boolean toggles), extend SLOT_DEFINITIONS and the summary formatter in lockstep.
+
+ +
+

Dependencies & Telemetry

+ + +
+ Deployment Notes +
    +
  • Set TRACE logging off before public release to quiet console spam.
    • +
  • Maintain requirements.txt in lockstep with DEPENDENCIES to keep manual installs frictionless.
    • +
+
+ +
+ Maintainer Marker — plan a VS-aware configuration so the banner can display the current ComfyUI/Stability Matrix version once the upstream API exposes it.
+
+ +
+

Code Appendix

+

Quick reference snippets for the primary modules. Consult the repository for up-to-the-minute source.

+ +

nodes.py

+ 
# nodes.py quick reference (v2.1.0)
+- Global discovery helpers: build sampler/scheduler choice tables, normalise lookup keys, and guard against missing ComfyUI modules.
+- ToolkitLogger: colour-coded INFO/WARN/TRACE emitter used everywhere.
+- AxisDescriptor: dataclass powering Engine's grid planning overrides.
+- _invoke_sampler_with_compatibility(...): signature-aware shim that renames/drops kwargs to match active sampler expectations.
+- h4_PlotXY.run_pipeline(...): orchestrates plan execution (axis parsing, LoRA injection, latent prep, sampler invocation, preview publishing, grid assembly, labelled export).
+- h4_DebugATron3000 (base class):
+  • SLOT_DEFINITIONS / SLOT_TOOLTIPS / VAE_MODEL_FALLBACKS / BRANCH_DISPLAY_NAMES metadata drive input/output wiring.
+  • INPUT_TYPES() auto-builds optional controls (including Go Plus Ultra toggles) from that metadata.
+  • route(...) clones passthrough payloads, logs descriptors, runs Go Plus Ultra diagnostics, writes previews/JSON, and now aggregates per-branch summaries.
+  • Helper matrix (_slot_variants, _slot_branch_suffix, _branch_label, _matching_branch_slot) coordinates branch-aware lookups.
+  • _collect_latent_snapshots / _tensor_anomalies / _preview_conditioning_tokens feed diagnostics.
+- h4_DebugATronRouter: overrides slot/tooltips/fallback maps with Branch A/B variants, inherits route() implementation, and ships default mode = passthrough.
+- h4_DebugATron3000Console: output-node wrapper that prepends an HTML telemetry stream with palette/verbosity controls.
+- h4_SeedBroadcaster: broadcasts a single fixed or random seed to eight outlets for graph-wide synchronisation.
+- h4_ExecutionLogger: console-mirror output node logging payload metadata and returning a plaintext summary.
+- Export dictionaries (NODE_CLASS_MAPPINGS / DISPLAY / TOOLTIP) register every node with ComfyUI.
+
+ +

__init__.py

+ 
# __init__.py quick reference
+- ensure_dependencies() installs or warns about colorama, numpy, torch.
+- Imports NODE_CLASS_MAPPINGS / DISPLAY / TOOLTIP dictionaries from nodes.py.
+- Emits status banner listing h4 : Plot XY, Debug-a-Tron-3000, and Router load states.
+- Exposes WEB_DIRECTORY so ComfyUI pulls js/h4_ui.js automatically.
+
+ +
+ Maintainer Marker — after every refactor, refresh these excerpts or link to generated API docs. +
+
+ +
+

Axis Driver — Visual Configuration Engine

+ +

Purpose & Architecture

+

The h4_AxisDriver node (v0.6.0) transforms axis configuration from manual string entry into a rich visual interface with model dropdowns, item management, and style controls. When wired to The Engine's axis_x_payload, axis_y_payload, or axis_z_payload inputs, it automatically overrides manual widget settings — no mode matching required.

+ +

Wiring Diagram: Stupid-Simple Connection

+ 
+┌─────────────────────────────┐
+│  h4_AxisDriver              │
+│  [X Slot: lora]             │
+│  Items:                     │
+│    ├─ Label: Anime Style    │
+│    ├─ Value: [Dropdown ▼]  │ ──→ anime_v2.safetensors
+│    └─ Strength: 0.8         │
+│                             │
+│  [Y Slot: cfg]              │
+│  Items:                     │
+│    ├─ Label: Low CFG        │ ──→ 2.5
+│    └─ Label: High CFG       │ ──→ 7.5
+│                             │
+│  [Z Slot: none]             │
+└─────────────────────────────┘
+              │
+       Outputs: axis_x, axis_y, axis_z
+              │
+              ▼
+┌─────────────────────────────┐
+│  h4_PlotXY (The Engine)     │
+│                             │
+│  [axis_x_payload] ◀──────── Wire X here (auto-detects preset!)
+│  [axis_y_payload] ◀──────── Wire Y here (auto-detects preset!)
+│  [axis_z_payload] ◀──────── Wire Z here (reserved for 3D)
+│                             │
+│  Manual widgets ignored ✓   │
+└─────────────────────────────┘
+
+✅ NO MANUAL MODE MATCHING REQUIRED!
+✅ Driver is single source of truth
+✅ Change presets in Driver, Engine follows
+✅ Wire X→X, Y→Y, Z→Z — done!
+
+ +

Supported Presets & UI Elements

+ + + + + + + + + + + + + + + + + + + + + + + +
PresetInput TypeFeatures
none—Axis disabled
promptTextareaMulti-line prompt variations
checkpointDropdownModel list from ComfyUI API
loraDropdown + StrengthLoRA selection + 0-2.0 slider
vaeDropdownVAE model selection
clipDropdownCLIP text encoder selection
clip_visionDropdownCLIP vision model selection
samplerDropdownBuilt-in sampler list
schedulerDropdownBuilt-in scheduler list
cfgNumber (0.1 step)CFG scale sweep
stepsNumber (integer)Step count tests
denoiseNumber (0-1)Denoise strength
seedNumber (integer)Seed variations
+ +

Model Discovery System

+

The Axis Driver fetches models using a multi-endpoint strategy compatible with both standard ComfyUI and Stability Matrix installations:

+
    +
  1. /object_info/{NodeType} — Primary endpoint, queries ComfyUI's native node definitions
    2. +
  2. /api/assets/{kind} — Custom API fallback
    3. +
  3. /api/list?type={kind} — Alternative list endpoint
    4. +
  4. /api/models/{kind} — Additional fallback
    5. +
+

Asset Kind Mapping:

+ +

Models are cached per session, sorted alphabetically, and include all subfolders. Custom values not in the list are preserved with "(custom)" labels.

+ +

Critical Fixes & Debugging History

+
+

🚨 Node Sizing Catastrophe (October 2025)

+

Symptoms:

+
    +
  • Node exploded to massive size (90% of canvas) on ANY interaction
    • +
  • Zoom triggered infinite growth loops
    • +
  • Manual resize caused instant expansion ("shoots out like a bat out of hell")
    • +
  • Button clicks continuously enlarged the node
    • +
  • Node never shrank back to normal size
    • +
+ +

Root Causes Identified:

+
    +
  1. Feedback Loop Trinity: +
      +
    • ResizeObserver watching DOM → triggered on size changes
      • +
    • MutationObserver watching attributes → fired on every style change
      • +
    • Auto-sizing logic → measured, calculated, resized → triggered observers → repeat
      • +
    +
    2. +
  2. Math.ceil() Rounding: Every pixel→graph unit conversion rounded UP, preventing shrinkage
    3. +
  3. Math.max() Chains: Nested max() calls with multiple sources only allowed growth
    4. +
  4. computeSize() Hijacking: Custom compute function measured DOM and applied calculations during ComfyUI's resize operations
    5. +
  5. Manual Size Interference: Stored manual sizes fought with auto-adjustments
    6. +
+ +

Solution Strategy:

+
    +
  1. Disabled ALL Auto-Sizing: +
      +
    • Removed ResizeObserver completely
      • +
    • Removed window resize handler
      • +
    • Gutted MutationObserver (now disabled)
      • +
    • Emptied performAdjust() function
      • +
    +
    2. +
  2. Neutered Custom Handlers: +
      +
    • node.onResize → pass-through only, no custom logic
      • +
    • node.computeSize → pass-through to original, no measurements
      • +
    • h4AxisDriverAutoSize.compute() → returns input values unchanged
      • +
    +
    3. +
  3. Fixed Sizing Behavior: +
      +
    • Node starts at default size (560×580)
      • +
    • Manual resize works via standard ComfyUI mechanics
      • +
    • Content scrolls internally if needed
      • +
    • No automatic reactions to any interactions
      • +
    +
    4. +
+ +

Code Changes:

+ 
// BEFORE (broken):
+node.computeSize = function(arg1, arg2) {
+    const measurements = measurePixels();
+    const [graphWidth, graphHeight] = convertPixelsToGraphUnits(...);
+    return [Math.max(baseWidth, graphWidth), Math.max(baseHeight, graphHeight)];
+};
+
+// AFTER (fixed):
+node.computeSize = function(arg1, arg2) {
+    if (originalComputeSize) {
+        return originalComputeSize.apply(this, arguments);
+    }
+    return [
+        Number.isFinite(arg1) ? arg1 : DEFAULT_MIN_WIDTH,
+        Number.isFinite(arg2) ? arg2 : DEFAULT_MIN_HEIGHT
+    ];
+};
+
+ +

Lessons Learned:

+
    +
  • ❌ Never override ComfyUI's core sizing without complete understanding
    • +
  • ❌ Never use Math.ceil() for bidirectional size adjustments
    • +
  • ❌ Never create observer loops that trigger size calculations
    • +
  • ✅ Always default to vanilla ComfyUI behavior for node sizing
    • +
  • ✅ Always test zoom, manual resize, and button interactions separately
    • +
  • ✅ Always provide escape hatches to disable auto-sizing
    • +
+ +

Current Status: ✅ STABLE — Node uses standard ComfyUI sizing, manual resize works perfectly, no growth loops.

+
+ +

UI Component Architecture

+ + +

Label Layout Modes

+

The style payload now carries a label_layout field that controls how The Engine annotates its composite grid:

+ +

Axis Driver outputs always embed the style selection. When absent, The Engine falls back to its Python default (overlay) to keep legacy workflows stable.

+ +

Best Practices

+
    +
  1. One Driver Per Axis: Create separate Axis Driver nodes for X, Y, and Z
    2. +
  2. Preset Matching: Always match Engine axis_mode to Driver preset
    3. +
  3. Incremental Testing: Start with 2-3 items, expand gradually
    4. +
  4. Descriptive Labels: Labels appear in grid annotations, make them meaningful
    5. +
  5. Manual Sizing: Drag corners to preferred size, it will persist
    6. +
+
+ +
+

Future-Proof Planning

+

Immediate Enhancements

+ + +

Version Awareness Initiative

+ + +

Maintenance Rituals

+ +
+ +
+

Tips & Best Practices

+ +

🎯 Seed Behavior — Critical Understanding

+
+

CRITICAL: The Engine's seed control mode affects every grid cell differently!

+ + + + + + + + + + + + + +
fixedSame seed for ALL cells → ✅ Use for img2img/high-res fix
incrementSeed +1 per cell → Controlled variation
randomizeRandom seed per cell → ⚠️ txt2img only!
+
+ +

Common Mistake: Using randomize with img2img + denoise 0.55 still produces completely different images because each cell gets a different seed! The denoise value is ignored when the seed changes dramatically.

+ +

Solution for img2img workflows:

+
    +
  1. Set Engine seed mode to fixed
    2. +
  2. Match the seed from your input image generation
    3. +
  3. Now denoise works correctly: 0.55 denoise = 45% original structure + 55% variation
    4. +
+ +

🎚️ Denoise Value Guide

+ + + + + + + + + + + + + + + + + + + + + + + + + + +
RangeEffectUse Case
0.0 - 0.3Minimal changesFinal polish, style transfer
0.4 - 0.7Sweet spot✅ img2img / high-res fix (balanced variation)
0.8 - 0.95Major changesCreative reinterpretation
1.0Complete regenerationtxt2img from scratch
+ +

🔌 Wiring Best Practices

+ 
+✅ CORRECT Driver → Engine Wiring:
+  Driver.axis_x → Engine.axis_x_payload
+  Driver.axis_y → Engine.axis_y_payload  
+  Driver.axis_z → Engine.axis_z_payload
+
+❌ WRONG:
+  Driver.axis_x → Engine.x_axis_values (string input)
+  Mixing Driver outputs with manual mode dropdowns
+
+ +

📊 Grid Composition Strategy

+ + +

Grid Size Recommendations:

+ + +

+ Memory Formula: Rows × Columns × Model Size × Steps
+ Example: 6×6 grid = 36 images generated! +

+ +

🖼️ Latent Input Workflows

+

Three strategies for providing input to The Engine:

+ +
    +
  1. + Empty Latent (txt2img): + 
    EmptyLatentImage → Engine.latent_in
+Result: Fresh generation at Engine's width/height
    +
    2. + +
  2. + Image Input (img2img): + 
    LoadImage → Engine.image_in
+Result: Engine encodes to latent, then refines
    +
    3. + +
  3. + Latent Input (high-res fix): + 
    KSampler → LatentUpscale → Engine.latent_in
+Result: Engine uses latent directly (no encoding)
    +
    4. +
+ +
+ ⚠️ IMPORTANT: When using latent/image input with denoise < 1.0, ALWAYS use fixed seed mode to preserve the base image structure! +
+ +

🎨 Model Dropdown Tips

+

Checkpoint Selection:

+ + +

VAE/CLIP Selection:

+ + +

LoRA Strength Guidelines:

+ + +

⚡ Performance Optimization

+

Memory Management:

+ + +

Speed Tips:

+ + +

💡 Common Workflows

+ +

1. Sampler Comparison:

+ 
X Axis: sampler (euler, dpmpp_2m_sde, dpmpp_2m, uni_pc)
+Y Axis: cfg (4.0, 6.0, 8.0)
+Result: 4×3 grid = 12 images testing sampler×CFG
+ +

2. LoRA Testing:

+ 
X Axis: lora (LoRA A @ 0.75, LoRA B @ 0.75, LoRA C @ 1.0)
+Y Axis: prompt ("anime style", "realistic", "painterly")
+Result: 3×3 grid = 9 images testing LoRA×style
+ +

3. High-Res Fix Grid:

+ 
Initial Generation:
+  KSampler (steps: 40, cfg: 7, denoise: 1.0, seed: 8008135)
+  ↓
+Upscale:
+  LatentUpscale (2x)
+  ↓
+Refinement Grid:
+  Engine (seed: 8008135 FIXED, denoise: 0.55)
+  X Axis: sampler (test refinement samplers)
+  Y Axis: cfg (find optimal refinement CFG)
+ +

4. A/B Model Testing:

+ 
X Axis: checkpoint (modelA.safetensors, modelB.safetensors)
+Y Axis: prompt (various test prompts)
+Result: Compare model interpretations
+ +
+ +
+

Final Product Briefing

+

The h4 Toolkit now ships as a cohesive triad: a battle-tested sampler engine, a clairvoyant debugging suite, and a UI companion that keeps controls ergonomic. This section articulates every feature and function in their final form.

+ +

End-to-End Overview

+ + +

Function-by-Function Detail — h4_Plot/nodes.py

+ + +

Function-by-Function Detail — h4_Plot/js/h4_ui.js

+ + +

Behavioural Guarantees

+ + +

Validation Summary

+ + +
+ Maintainer Marker — revisit this briefing after every release; the final product description doubles as the acceptance checklist for future regressions.
+
+
+ + + + + + +