From b4785ed570367ceefb4bf0805ef75097a27d49c7 Mon Sep 17 00:00:00 2001 From: Connor Byrne Date: Wed, 13 May 2026 16:22:34 -0700 Subject: [PATCH] docs(litegraph): mark subgraph building blocks as @internal MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Per AUDIT-LG.9 §subgraph correction, these subgraph cluster exports are internal building blocks with no production importers — they leak into the published @comfyorg/extension-api ABI but should not be part of the public surface: - EmptySubgraphInput, EmptySubgraphOutput - SubgraphSlot (SubgraphSlotBase.ts), SubgraphIONodeBase - PromotedWidgetViewManager - subgraphDeduplication (deduplicateSubgraphNodeIds, topologicalSortSubgraphs) - subgraphUtils (splitPositionables, getBoundaryLinks, multiClone, groupResolvedByOutput, mapSubgraphInputsAndLinks, mapSubgraphOutputsAndLinks, getDirectSubgraphIds, findUsedSubgraphIds, isSubgraphInput, isSubgraphOutput, isNodeSlot) - SubgraphOutput Add @internal JSDoc tags so TypeDoc (with excludeInternal: true) strips them from the published ABI. Preserves SubgraphNode, Subgraph, SubgraphInput, ExecutableNodeDTO, and subgraphTest/createTestSubgraph test fixtures — those are external-facing. --- .../src/subgraph/EmptySubgraphInput.ts | 2 ++ .../src/subgraph/EmptySubgraphOutput.ts | 2 ++ .../src/subgraph/SubgraphIONodeBase.ts | 1 + .../litegraph/src/subgraph/SubgraphOutput.ts | 2 ++ .../litegraph/src/subgraph/SubgraphSlotBase.ts | 6 +++++- .../src/subgraph/subgraphDeduplication.ts | 9 +++++++++ .../litegraph/src/subgraph/subgraphUtils.ts | 18 ++++++++++++++++++ 7 files changed, 39 insertions(+), 1 deletion(-) diff --git a/src/lib/litegraph/src/subgraph/EmptySubgraphInput.ts b/src/lib/litegraph/src/subgraph/EmptySubgraphInput.ts index d8c37d39fc4..aeda751f4a7 100644 --- a/src/lib/litegraph/src/subgraph/EmptySubgraphInput.ts +++ b/src/lib/litegraph/src/subgraph/EmptySubgraphInput.ts @@ -10,6 +10,8 @@ import type { SubgraphInputNode } from './SubgraphInputNode' /** * A virtual slot that simply creates a new input slot when connected to. + * + * @internal */ export class EmptySubgraphInput extends SubgraphInput { declare parent: SubgraphInputNode diff --git a/src/lib/litegraph/src/subgraph/EmptySubgraphOutput.ts b/src/lib/litegraph/src/subgraph/EmptySubgraphOutput.ts index 14c9b97a957..472f43402e7 100644 --- a/src/lib/litegraph/src/subgraph/EmptySubgraphOutput.ts +++ b/src/lib/litegraph/src/subgraph/EmptySubgraphOutput.ts @@ -10,6 +10,8 @@ import type { SubgraphOutputNode } from './SubgraphOutputNode' /** * A virtual slot that simply creates a new output slot when connected to. + * + * @internal */ export class EmptySubgraphOutput extends SubgraphOutput { declare parent: SubgraphOutputNode diff --git a/src/lib/litegraph/src/subgraph/SubgraphIONodeBase.ts b/src/lib/litegraph/src/subgraph/SubgraphIONodeBase.ts index e40fb94a40f..f2df74f9947 100644 --- a/src/lib/litegraph/src/subgraph/SubgraphIONodeBase.ts +++ b/src/lib/litegraph/src/subgraph/SubgraphIONodeBase.ts @@ -30,6 +30,7 @@ import type { Subgraph } from './Subgraph' import type { SubgraphInput } from './SubgraphInput' import type { SubgraphOutput } from './SubgraphOutput' +/** @internal */ export abstract class SubgraphIONodeBase< TSlot extends SubgraphInput | SubgraphOutput > diff --git a/src/lib/litegraph/src/subgraph/SubgraphOutput.ts b/src/lib/litegraph/src/subgraph/SubgraphOutput.ts index ddadd266a7e..fe4711fe13d 100644 --- a/src/lib/litegraph/src/subgraph/SubgraphOutput.ts +++ b/src/lib/litegraph/src/subgraph/SubgraphOutput.ts @@ -27,6 +27,8 @@ import { isNodeSlot, isSubgraphInput } from './subgraphUtils' * You have "Subgraph Outputs", because they go from inside the subgraph and out, but links to them come from "node outputs". * * Functionally, however, when editing a subgraph, that "subgraph output" is the "target" or "input side" of a link. + * + * @internal */ export class SubgraphOutput extends SubgraphSlot { declare parent: SubgraphOutputNode diff --git a/src/lib/litegraph/src/subgraph/SubgraphSlotBase.ts b/src/lib/litegraph/src/subgraph/SubgraphSlotBase.ts index 1139abba812..51652cc9f87 100644 --- a/src/lib/litegraph/src/subgraph/SubgraphSlotBase.ts +++ b/src/lib/litegraph/src/subgraph/SubgraphSlotBase.ts @@ -37,7 +37,11 @@ interface SubgraphSlotDrawOptions { editorAlpha?: number } -/** Shared base class for the slots used on Subgraph . */ +/** + * Shared base class for the slots used on Subgraph . + * + * @internal + */ export abstract class SubgraphSlot extends SlotBase implements SubgraphIO, Hoverable, Serialisable diff --git a/src/lib/litegraph/src/subgraph/subgraphDeduplication.ts b/src/lib/litegraph/src/subgraph/subgraphDeduplication.ts index 49793a7ed1a..b606a69025e 100644 --- a/src/lib/litegraph/src/subgraph/subgraphDeduplication.ts +++ b/src/lib/litegraph/src/subgraph/subgraphDeduplication.ts @@ -171,6 +171,13 @@ function firstById( * `GraphCanvas.vue` also keys Vue node instances by bare `NodeId`, so * collisions could reuse a component across graph changes instead of * remounting it. + * + * @param subgraphs - Serialized subgraph definitions to deduplicate + * @param reservedNodeIds - Node IDs already in use by root-level nodes + * @param state - Graph state containing the `lastNodeId` counter (mutated) + * @param rootNodes - Optional root-level nodes with proxyWidgets to patch + * + * @internal */ export function deduplicateSubgraphNodeIds( subgraphs: ExportedSubgraph[], @@ -503,6 +510,8 @@ function patchRerouteReferences( * * Falls back to the original order if no reordering is needed or if the * dependency graph contains cycles. + * + * @internal */ export function topologicalSortSubgraphs( subgraphs: ExportedSubgraph[] diff --git a/src/lib/litegraph/src/subgraph/subgraphUtils.ts b/src/lib/litegraph/src/subgraph/subgraphUtils.ts index 5db88945107..9e28a13ff0f 100644 --- a/src/lib/litegraph/src/subgraph/subgraphUtils.ts +++ b/src/lib/litegraph/src/subgraph/subgraphUtils.ts @@ -46,6 +46,7 @@ interface FilteredItems { unknown: Set } +/** @internal */ export function splitPositionables( items: Iterable ): FilteredItems { @@ -98,6 +99,7 @@ interface BoundaryLinks { boundaryOutputLinks: LLink[] } +/** @internal */ export function getBoundaryLinks( graph: LGraph, items: Set @@ -226,6 +228,7 @@ export function getBoundaryLinks( } } +/** @internal */ export function multiClone(nodes: Iterable): ISerialisedNode[] { const clonedNodes: ISerialisedNode[] = [] @@ -253,6 +256,8 @@ export function multiClone(nodes: Iterable): ISerialisedNode[] { * Groups resolved connections by output object. If the output is nullish, the connection will be in its own group. * @param resolvedConnections The resolved connections to group * @returns A map of grouped connections. + * + * @internal */ export function groupResolvedByOutput( resolvedConnections: ResolvedConnection[] @@ -295,6 +300,7 @@ function mapReroutes( return lastId } +/** @internal */ export function mapSubgraphInputsAndLinks( resolvedInputLinks: ResolvedConnection[], links: SerialisableLLink[], @@ -376,6 +382,8 @@ export function mapSubgraphInputsAndLinks( * @param resolvedOutputLinks The resolved output links. * @param links The links to add to the subgraph. * @returns The subgraph output slots. + * + * @internal */ export function mapSubgraphOutputsAndLinks( resolvedOutputLinks: ResolvedConnection[], @@ -454,6 +462,8 @@ export function mapSubgraphOutputsAndLinks( * Collects all subgraph IDs used directly in a single graph (non-recursive). * @param graph The graph to check for subgraph nodes * @returns Set of subgraph IDs used in this graph + * + * @internal */ export function getDirectSubgraphIds(graph: GraphOrSubgraph): Set { const subgraphIds = new Set() @@ -472,6 +482,8 @@ export function getDirectSubgraphIds(graph: GraphOrSubgraph): Set { * @param rootGraph The graph to start from * @param subgraphRegistry Map of all available subgraphs * @returns Set of all subgraph IDs found + * + * @internal */ export function findUsedSubgraphIds( rootGraph: GraphOrSubgraph, @@ -625,6 +637,8 @@ export function reorderSubgraphInputs( * Type guard to check if a slot is a SubgraphInput. * @param slot The slot to check * @returns true if the slot is a SubgraphInput + * + * @internal */ export function isSubgraphInput(slot: unknown): slot is SubgraphInput { return ( @@ -639,6 +653,8 @@ export function isSubgraphInput(slot: unknown): slot is SubgraphInput { * Type guard to check if a slot is a SubgraphOutput. * @param slot The slot to check * @returns true if the slot is a SubgraphOutput + * + * @internal */ export function isSubgraphOutput(slot: unknown): slot is SubgraphOutput { return ( @@ -653,6 +669,8 @@ export function isSubgraphOutput(slot: unknown): slot is SubgraphOutput { * Type guard to check if a slot is a regular node slot (INodeInputSlot or INodeOutputSlot). * @param slot The slot to check * @returns true if the slot is a regular node slot + * + * @internal */ export function isNodeSlot( slot: unknown