ComfyUI_frontend/src/lib/litegraph/AGENTS.md

Litegraph Guidelines

Code Philosophy

• Write concise, legible, and easily maintainable code
• Avoid repetition where possible, but not at expense of legibility
• Prefer running single tests, not the whole suite, for performance

Widget Serialization

See docs/WIDGET_SERIALIZATION.md for the distinction between widget.serialize (workflow persistence) and widget.options.serialize (API prompt). These are different properties checked by different code paths — a common source of confusion.

Code Style

• Prefer single line if syntax for concise expressions
• Take advantage of TypedArray subarray when appropriate
• The size and pos properties of Rectangle share the same array buffer
• Prefer returning undefined over null
• Type assertions are a last resort (acceptable for legacy code interop)

Circular Dependencies in Tests

CRITICAL: Always import from the barrel export for subgraph code:

// ✅ Correct - barrel import
import { LGraph, Subgraph, SubgraphNode } from '@/lib/litegraph/src/litegraph'

// ❌ Wrong - causes circular dependency
import { LGraph } from '@/lib/litegraph/src/LGraph'

Root cause: LGraph ↔ Subgraph circular dependency (Subgraph extends LGraph, LGraph creates Subgraph instances).

Known Limitations

• Subgraph dynamic input limitations (autogrow/matchtype): see src/core/graph/subgraph-dynamic-input-limitations.md

Test Helpers

import {
  createTestSubgraph,
  createTestSubgraphNode
} from './__fixtures__/subgraphHelpers'

function createTestSetup() {
  const subgraph = createTestSubgraph()
  const subgraphNode = createTestSubgraphNode(subgraph)
  return { subgraph, subgraphNode }
}