LCOV - code coverage report
Current view: top level - src/workbench/extensions/agent/crdt - agentSubgraphDefinitions.ts Coverage Total Hit
Test: ComfyUI E2E Coverage Lines: 2.0 % 205 4
Test Date: 2026-11-17 04:17:53

            Line data    Source code
       1              : import {
       2              :   OPAQUE_WIDGETS_KEY,
       3              :   WIDGET_FORM_KEY,
       4              :   nodesMap
       5              : } from '@comfyorg/comfy-multi-player'
       6              : import * as Y from 'yjs'
       7              : 
       8              : import type { ExportedSubgraph } from '@comfyorg/graph-model/serialisation'
       9              : 
      10              : /**
      11              :  * Root map the op layer mints `definitions.subgraphs` into, keyed by
      12              :  * definition id. `@comfyorg/comfy-multi-player` reads it through its private
      13              :  * `definitionsMap()`, which is not part of the package's public surface.
      14              :  */
      15            1 : const DEFINITIONS_ROOT = 'definitions'
      16              : 
      17              : /** Mint-order registers kept beside the interior `nodes`/`links` maps. */
      18            1 : const NODE_ORDER = 'node_order'
      19            1 : const LINK_ORDER = 'link_order'
      20              : 
      21              : /**
      22              :  * Per-node bookkeeping the op layer's applier stamps on every node record
      23              :  * (`NODE_INCARNATION_KEY`, not exported by the package). Its own `project()`
      24              :  * drops it; so does this reader.
      25              :  */
      26            1 : const NODE_INCARNATION = '__incarnation'
      27              : 
      28              : /** The op layer reserves double-underscore definition keys for bookkeeping. */
      29            0 : function isDefinitionBookkeeping(key: string): boolean {
      30            0 :   return key.startsWith('__')
      31              : }
      32              : 
      33              : /**
      34              :  * Own-key filter shared by both record readers. Assigning through
      35              :  * `record['__proto__']` swaps the record's prototype, so a document carrying
      36              :  * that key would hand LiteGraph an object whose inherited keys it never wrote.
      37              :  */
      38            0 : function isReadableKey(key: string): boolean {
      39            0 :   return key !== '__proto__'
      40              : }
      41              : 
      42            0 : function withoutUnsafeKeys(value: unknown): unknown {
      43            0 :   if (Array.isArray(value)) return value.map(withoutUnsafeKeys)
      44            0 :   if (typeof value !== 'object' || value === null) return value
      45            0 :   const prototype = Object.getPrototypeOf(value)
      46            0 :   if (prototype !== Object.prototype && prototype !== null) return value
      47            0 :   return Object.fromEntries(
      48              :     Object.entries(value).flatMap(([key, nested]) =>
      49              :       isReadableKey(key) ? [[key, withoutUnsafeKeys(nested)]] : []
      50              :     )
      51              :   )
      52              : }
      53              : 
      54              : /**
      55              :  * A value slot's JSON view. Every shared type, and a subdocument, answers
      56              :  * `toJSON()`; `structuredClone` throws on all of them, and this reader runs
      57              :  * as a bare argument inside the follower's frame reconcile, where one throw
      58              :  * would stall every node on the canvas. The package only mints maps and
      59              :  * arrays; the rest arrive through a doc host folding in a raw update.
      60              :  */
      61            0 : function plain(value: unknown): unknown {
      62            0 :   if (value instanceof Y.AbstractType || value instanceof Y.Doc) {
      63            0 :     return withoutUnsafeKeys(value.toJSON())
      64              :   }
      65            0 :   return withoutUnsafeKeys(structuredClone(value))
      66              : }
      67              : 
      68            0 : function withoutDefinitionBookkeeping(source: unknown): unknown {
      69            0 :   if (typeof source !== 'object' || source === null || Array.isArray(source)) {
      70            0 :     return source
      71              :   }
      72            0 :   return Object.fromEntries(
      73              :     Object.entries(source).flatMap(([key, value]) => {
      74            0 :       if (isDefinitionBookkeeping(key)) return []
      75            0 :       if (key !== 'definitions') return [[key, value]]
      76            0 :       return [[key, withoutNestedDefinitionBookkeeping(value)]]
      77              :     })
      78              :   )
      79              : }
      80              : 
      81            0 : function withoutNestedDefinitionBookkeeping(source: unknown): unknown {
      82            0 :   if (typeof source !== 'object' || source === null || Array.isArray(source)) {
      83            0 :     return source
      84              :   }
      85            0 :   return Object.fromEntries(
      86              :     Object.entries(source).map(([key, value]) => [
      87              :       key,
      88              :       key === 'subgraphs' && Array.isArray(value)
      89              :         ? value.map(withoutDefinitionBookkeeping)
      90              :         : value
      91              :     ])
      92              :   )
      93              : }
      94              : 
      95              : /**
      96              :  * Register entries that name a record, first occurrence only, matching what
      97              :  * LiteGraph keeps when it normalizes a definition.
      98              :  */
      99            0 : function orderedKeys(register: unknown, map: Y.Map<unknown>): string[] {
     100            0 :   const order = Array.isArray(register)
     101              :     ? register.filter((key): key is string => typeof key === 'string')
     102              :     : [...map.keys()].sort()
     103            0 :   return [...new Set(order)].filter((key) => map.has(key))
     104              : }
     105              : 
     106              : /**
     107              :  * Interior node record → serialised node. Named widget values go to
     108              :  * `widgets_values_named`, the only name-keyed slot `LGraphNode.configure()`
     109              :  * reads; the opaque positional form stays `widgets_values`. A record whose
     110              :  * `widgets` is not a map cannot be read and is skipped, as the package's
     111              :  * `tryProjectNode()` skips it.
     112              :  */
     113            0 : function readInteriorNode(source: unknown): Record<string, unknown> | null {
     114            0 :   if (!(source instanceof Y.Map)) return null
     115            0 :   if (source.has('widgets') && !(source.get('widgets') instanceof Y.Map)) {
     116            0 :     return null
     117              :   }
     118            0 :   const node: Record<string, unknown> = {}
     119            0 :   source.forEach((value, key) => {
     120            0 :     if (key === NODE_INCARNATION || key === WIDGET_FORM_KEY) return
     121            0 :     if (!isReadableKey(key)) return
     122            0 :     if (key === 'widgets' && value instanceof Y.Map) {
     123            0 :       node.widgets_values_named = Object.fromEntries(
     124              :         [...value.entries()].flatMap(([name, widgetValue]) =>
     125              :           isReadableKey(name) ? [[name, plain(widgetValue)]] : []
     126              :         )
     127              :       )
     128            0 :     } else if (key === OPAQUE_WIDGETS_KEY) {
     129            0 :       node.widgets_values = plain(value)
     130              :     } else {
     131            0 :       node[key] = plain(value)
     132              :     }
     133              :   })
     134            0 :   return node
     135              : }
     136              : 
     137            0 : function isSkippedDefinitionKey(key: string): boolean {
     138            0 :   return (
     139              :     key === NODE_ORDER ||
     140              :     key === LINK_ORDER ||
     141              :     isDefinitionBookkeeping(key) ||
     142              :     !isReadableKey(key)
     143              :   )
     144              : }
     145              : 
     146            0 : function projectDefinitionNodes(
     147              :   source: Y.Map<unknown>,
     148              :   nodes: Y.Map<unknown>
     149              : ): Record<string, unknown>[] {
     150            0 :   return orderedKeys(source.get(NODE_ORDER), nodes).flatMap((id) => {
     151            0 :     const node = readInteriorNode(nodes.get(id))
     152            0 :     return node ? [node] : []
     153              :   })
     154              : }
     155              : 
     156            0 : function projectDefinitionLinks(
     157              :   source: Y.Map<unknown>,
     158              :   links: Y.Map<unknown>
     159              : ): unknown[] {
     160            0 :   return orderedKeys(source.get(LINK_ORDER), links).map((id) =>
     161              :     plain(links.get(id))
     162              :   )
     163              : }
     164              : 
     165            0 : function projectDefinitionEntry(
     166              :   source: Y.Map<unknown>,
     167              :   key: string,
     168              :   value: unknown,
     169              :   excludedDefinitionIds: ReadonlySet<string>
     170              : ): Array<[string, unknown]> {
     171            0 :   if (isSkippedDefinitionKey(key)) return []
     172            0 :   if (key === 'nodes' && value instanceof Y.Map) {
     173            0 :     return [[key, projectDefinitionNodes(source, value)]]
     174              :   }
     175            0 :   if (key === 'links' && value instanceof Y.Map) {
     176            0 :     return [[key, projectDefinitionLinks(source, value)]]
     177              :   }
     178            0 :   if (key === 'definitions') {
     179            0 :     if (value instanceof Y.Map) {
     180            0 :       return [[key, readNestedDefinitions(value, excludedDefinitionIds)]]
     181              :     }
     182            0 :     return [[key, withoutNestedDefinitionBookkeeping(plain(value))]]
     183              :   }
     184            0 :   return [[key, plain(value)]]
     185              : }
     186              : 
     187            0 : function projectSubgraphDefinition(
     188              :   source: Y.Map<unknown>,
     189              :   excludedDefinitionIds: ReadonlySet<string>
     190              : ): ExportedSubgraph {
     191              :   const definition = Object.fromEntries(
     192              :     [...source.entries()].flatMap(([key, value]) =>
     193              :       projectDefinitionEntry(source, key, value, excludedDefinitionIds)
     194              :     )
     195              :   )
     196            0 :   return definition as unknown as ExportedSubgraph
     197              : }
     198              : 
     199            0 : function isRecord(value: unknown): value is Record<string, unknown> {
     200            0 :   return typeof value === 'object' && value !== null && !Array.isArray(value)
     201              : }
     202              : 
     203            0 : function hasSafeInputs(value: unknown): boolean {
     204            0 :   return (
     205              :     value === undefined ||
     206              :     (Array.isArray(value) &&
     207              :       value.every(
     208              :         (input) =>
     209              :           isRecord(input) &&
     210              :           typeof input.name === 'string' &&
     211              :           (input.linkIds === undefined || Array.isArray(input.linkIds))
     212              :       ))
     213              :   )
     214              : }
     215              : 
     216            0 : function hasSafeNodes(value: unknown): boolean {
     217            0 :   return (
     218              :     value === undefined ||
     219              :     (Array.isArray(value) &&
     220              :       value.every(
     221              :         (node) =>
     222              :           isRecord(node) &&
     223              :           (node.inputs === undefined ||
     224              :             (Array.isArray(node.inputs) && node.inputs.every(isRecord)))
     225              :       ))
     226              :   )
     227              : }
     228              : 
     229            0 : function hasSafeLinks(value: unknown): boolean {
     230            0 :   return value === undefined || (Array.isArray(value) && value.every(isRecord))
     231              : }
     232              : 
     233            0 : function hasSafeNestedDefinitions(value: unknown): boolean {
     234            0 :   if (value === undefined) return true
     235            0 :   if (!isRecord(value)) return false
     236            0 :   const nested = value.subgraphs
     237            0 :   return (
     238              :     nested === undefined ||
     239              :     (Array.isArray(nested) && nested.every(isSafeDefinition))
     240              :   )
     241              : }
     242              : 
     243            0 : function isSafeDefinition(value: unknown): boolean {
     244            0 :   return (
     245              :     isRecord(value) &&
     246              :     hasSafeInputs(value.inputs) &&
     247              :     hasSafeNodes(value.nodes) &&
     248              :     hasSafeLinks(value.links) &&
     249              :     hasSafeNestedDefinitions(value.definitions)
     250              :   )
     251              : }
     252              : 
     253            0 : function isExcludedDefinition(
     254              :   source: Y.Map<unknown>,
     255              :   excludedDefinitionIds: ReadonlySet<string>
     256              : ): boolean {
     257            0 :   const id = plain(source.get('id'))
     258            0 :   return typeof id === 'string' && excludedDefinitionIds.has(id)
     259              : }
     260              : 
     261            0 : function readNestedDefinitions(
     262              :   source: Y.Map<unknown>,
     263              :   excludedDefinitionIds: ReadonlySet<string>
     264              : ): Record<string, unknown> {
     265            0 :   const definitions: Record<string, unknown> = {}
     266            0 :   source.forEach((value, key) => {
     267            0 :     if (key === 'subgraph_order' || !isReadableKey(key)) return
     268            0 :     if (key === 'subgraphs' && value instanceof Y.Map) {
     269            0 :       definitions.subgraphs = orderedKeys(
     270              :         source.get('subgraph_order'),
     271              :         value
     272              :       ).flatMap((id) => {
     273            0 :         const definition = value.get(id)
     274            0 :         if (
     275              :           definition instanceof Y.Map &&
     276              :           isExcludedDefinition(definition, excludedDefinitionIds)
     277              :         ) {
     278            0 :           return []
     279              :         }
     280            0 :         return [
     281              :           definition instanceof Y.Map
     282              :             ? readDefinition(definition, excludedDefinitionIds)
     283              :             : null
     284              :         ]
     285              :       })
     286              :     } else {
     287            0 :       definitions[key] = plain(value)
     288              :     }
     289              :   })
     290            0 :   return definitions
     291              : }
     292              : 
     293            0 : function readDefinition(
     294              :   source: Y.Map<unknown>,
     295              :   excludedDefinitionIds: ReadonlySet<string>
     296              : ): ExportedSubgraph | null {
     297            0 :   const definition = projectSubgraphDefinition(source, excludedDefinitionIds)
     298            0 :   return isSafeDefinition(definition) ? definition : null
     299              : }
     300              : 
     301            0 : function readField(source: unknown, key: string): unknown {
     302            0 :   if (source instanceof Y.Map) return source.get(key)
     303            0 :   if (
     304              :     typeof source !== 'object' ||
     305              :     source === null ||
     306              :     !isReadableKey(key) ||
     307              :     !Object.hasOwn(source, key)
     308              :   ) {
     309            0 :     return undefined
     310              :   }
     311            0 :   return Reflect.get(source, key)
     312              : }
     313              : 
     314            0 : function readList(source: unknown): unknown[] {
     315            0 :   if (source instanceof Y.Array) return source.toArray()
     316            0 :   return Array.isArray(source) ? source : []
     317              : }
     318              : 
     319            0 : function collectDefinitionIds(source: unknown, ids: string[]): void {
     320            0 :   const pending = [source]
     321            0 :   while (pending.length > 0) {
     322            0 :     const definition = pending.pop()
     323            0 :     const id = plain(readField(definition, 'id'))
     324            0 :     if (typeof id === 'string') ids.push(id)
     325            0 :     const container = readField(definition, 'definitions')
     326            0 :     const nested = readField(container, 'subgraphs')
     327            0 :     const definitions =
     328              :       nested instanceof Y.Map
     329              :         ? orderedKeys(readField(container, 'subgraph_order'), nested).map(
     330              :             (key) => nested.get(key)
     331              :           )
     332              :         : readList(nested)
     333            0 :     for (let index = definitions.length - 1; index >= 0; index--) {
     334            0 :       pending.push(definitions[index])
     335              :     }
     336              :   }
     337              : }
     338              : 
     339            0 : function definitionsMap(doc: Y.Doc): Y.Map<unknown> | null {
     340            0 :   const root = doc.share.get(DEFINITIONS_ROOT)
     341            0 :   if (!root) return null
     342            0 :   if (root instanceof Y.Map) return root
     343            0 :   if (root.constructor !== Y.AbstractType) return null
     344            0 :   return doc.getMap<unknown>(DEFINITIONS_ROOT)
     345              : }
     346              : 
     347              : /** The definitions root a deep observer can attach to. */
     348            0 : export function definitionsObserverRoot(doc: Y.Doc): Y.Map<unknown> {
     349            0 :   return doc.getMap<unknown>(DEFINITIONS_ROOT)
     350              : }
     351              : 
     352              : /** Interior widget values: named map, opaque array, or absent. */
     353              : type InteriorWidgetValues =
     354              :   | Record<string, unknown>
     355              :   | readonly unknown[]
     356              :   | undefined
     357              : 
     358            0 : function readInteriorWidgets(source: Y.Map<unknown>): InteriorWidgetValues {
     359            0 :   const widgets = source.get('widgets')
     360            0 :   if (widgets instanceof Y.Map) {
     361            0 :     return Object.fromEntries(
     362              :       [...widgets.entries()].flatMap(([name, value]) =>
     363              :         isReadableKey(name) ? [[name, plain(value)]] : []
     364              :       )
     365              :     )
     366              :   }
     367            0 :   const opaque = source.get(OPAQUE_WIDGETS_KEY)
     368            0 :   if (opaque !== undefined) {
     369            0 :     const value = plain(opaque)
     370            0 :     return Array.isArray(value) ? value : undefined
     371              :   }
     372              :   return undefined
     373              : }
     374              : 
     375            0 : function collectInteriorWidgets(
     376              :   source: Y.Map<unknown>,
     377              :   into: Map<string, Map<string, InteriorWidgetValues>>
     378              : ): void {
     379            0 :   const id = plain(source.get('id'))
     380            0 :   const nodes = source.get('nodes')
     381            0 :   if (typeof id === 'string' && nodes instanceof Y.Map) {
     382            0 :     const interiors = new Map<string, InteriorWidgetValues>()
     383            0 :     for (const nodeId of orderedKeys(source.get(NODE_ORDER), nodes)) {
     384            0 :       const node = nodes.get(nodeId)
     385            0 :       if (node instanceof Y.Map)
     386            0 :         interiors.set(nodeId, readInteriorWidgets(node))
     387              :     }
     388            0 :     into.set(id, interiors)
     389              :   }
     390            0 :   const nested = source.get('definitions')
     391            0 :   if (nested instanceof Y.Map) {
     392            0 :     const subgraphs = nested.get('subgraphs')
     393            0 :     if (subgraphs instanceof Y.Map) {
     394            0 :       subgraphs.forEach((value) => {
     395            0 :         if (value instanceof Y.Map) collectInteriorWidgets(value, into)
     396              :       })
     397              :     }
     398              :   }
     399              : }
     400              : 
     401              : /** Every definition's interior widget values, in mint order. */
     402            0 : export function readSubgraphInteriorWidgets(
     403              :   doc: Y.Doc
     404              : ): Map<string, Map<string, InteriorWidgetValues>> {
     405            0 :   const result = new Map<string, Map<string, InteriorWidgetValues>>()
     406            0 :   const root = definitionsMap(doc)
     407            0 :   if (!root) return result
     408            0 :   root.forEach((value) => {
     409            0 :     if (value instanceof Y.Map) collectInteriorWidgets(value, result)
     410              :   })
     411            0 :   return result
     412              : }
     413              : 
     414            0 : export function allSubgraphDefinitions(
     415              :   definitions: readonly ExportedSubgraph[]
     416              : ): ExportedSubgraph[] {
     417            0 :   return [
     418              :     ...definitions,
     419              :     ...definitions.flatMap((definition) =>
     420              :       allSubgraphDefinitions(definition.definitions?.subgraphs ?? [])
     421              :     )
     422              :   ]
     423              : }
     424              : 
     425            0 : export function readSubgraphDefinitionIds(doc: Y.Doc): string[] {
     426            0 :   const ids: string[] = []
     427            0 :   const root = definitionsMap(doc)
     428            0 :   if (!root) return ids
     429            0 :   root.forEach((value) => {
     430            0 :     if (value instanceof Y.Map) collectDefinitionIds(value, ids)
     431              :   })
     432            0 :   return ids
     433              : }
     434              : 
     435              : /**
     436              :  * Project the subgraph definitions the op layer minted into the follower doc
     437              :  * back to the `ExportedSubgraph` shape `LGraph.createSubgraphs()` consumes,
     438              :  * interior nodes and links in mint order.
     439              :  *
     440              :  * Mirrors the package's own `projectDefinition()` so that what the agent
     441              :  * seeded and what the canvas instantiates agree byte-for-byte on structure.
     442              :  * Excluded IDs are checked before projection so their bodies are not copied.
     443              :  */
     444            0 : export function readSubgraphDefinitions(
     445              :   doc: Y.Doc,
     446              :   excludedDefinitionIds: ReadonlySet<string> = new Set()
     447              : ): ExportedSubgraph[] {
     448            0 :   const definitions: ExportedSubgraph[] = []
     449            0 :   const root = definitionsMap(doc)
     450            0 :   if (!root) return definitions
     451            0 :   root.forEach((value) => {
     452            0 :     if (!(value instanceof Y.Map)) return
     453            0 :     if (isExcludedDefinition(value, excludedDefinitionIds)) return
     454            0 :     const definition = readDefinition(value, excludedDefinitionIds)
     455            0 :     if (definition) definitions.push(definition)
     456              :   })
     457            0 :   return definitions
     458              : }
     459              : 
     460              : /**
     461              :  * What the document knows about a node's promoted widget layout.
     462              :  *
     463              :  * `valueCount` sizes the positional array a promoted write indexes.
     464              :  * `promotedNames` reconstructs that array's exact name order from the
     465              :  * definition plus the instance's input mirror: a definition input is promoted
     466              :  * when the mirror either omits it or carries its widget marker. Neither source
     467              :  * is sufficient alone because the mirror can omit promoted values the array
     468              :  * still carries. An unreadable array or name sequence is represented by null
     469              :  * so the minter can fail closed.
     470              :  *
     471              :  * `promotedNames` separates ABSENT from UNREADABLE, because they license
     472              :  * opposite answers on a first write: `undefined` is a document carrying no
     473              :  * definition for the node, which contradicts no ordering and lets the live
     474              :  * order build the array, while `null` is a definition whose inputs cannot be
     475              :  * read, which must fail closed.
     476              :  */
     477              : export interface DocPromotedWidgets {
     478              :   valueCount: number | null
     479              :   declaredNames: readonly string[]
     480              :   promotedNames: readonly string[] | null | undefined
     481              : }
     482              : 
     483              : /** Null when the document holds no such node. */
     484            0 : export function readDocPromotedWidgets(
     485              :   doc: Y.Doc,
     486              :   nodeId: string
     487              : ): DocPromotedWidgets | null {
     488            0 :   const node = nodesMap(doc).get(nodeId)
     489            0 :   if (!(node instanceof Y.Map)) return null
     490            0 :   const stored = node.get(OPAQUE_WIDGETS_KEY)
     491            0 :   return {
     492              :     valueCount:
     493              :       stored === undefined
     494              :         ? 0
     495              :         : stored instanceof Y.Array || Array.isArray(stored)
     496              :           ? stored.length
     497              :           : null,
     498              :     declaredNames: declaredInputNames(doc, String(node.get('type') ?? '')),
     499              :     promotedNames: promotedInputNames(doc, node, String(node.get('type') ?? ''))
     500              :   }
     501              : }
     502              : 
     503            0 : function namedInputs(source: unknown): Array<[string, unknown]> | null {
     504            0 :   const inputs =
     505              :     source instanceof Y.Array
     506              :       ? source.toArray()
     507              :       : Array.isArray(source)
     508              :         ? source
     509              :         : null
     510            0 :   if (inputs === null) return null
     511            0 :   const named: Array<[string, unknown]> = []
     512            0 :   for (const input of inputs) {
     513            0 :     const name = readField(input, 'name')
     514            0 :     if (typeof name !== 'string') return null
     515            0 :     named.push([name, input])
     516              :   }
     517            0 :   return named
     518              : }
     519              : 
     520            0 : function promotedInputNames(
     521              :   doc: Y.Doc,
     522              :   node: Y.Map<unknown>,
     523              :   definitionId: string
     524              : ): string[] | null | undefined {
     525            0 :   const definition = definitionsMap(doc)?.get(definitionId)
     526            0 :   if (!(definition instanceof Y.Map)) return undefined
     527            0 :   const declared = namedInputs(definition.get('inputs'))
     528            0 :   const instance = namedInputs(node.get('inputs'))
     529            0 :   if (declared === null || instance === null) return null
     530            0 :   const instanceByName = new Map(instance)
     531            0 :   return declared.flatMap(([name]) => {
     532            0 :     const input = instanceByName.get(name)
     533            0 :     return input === undefined || readField(input, 'widget') !== undefined
     534              :       ? [name]
     535              :       : []
     536              :   })
     537              : }
     538              : 
     539            0 : function declaredInputNames(doc: Y.Doc, definitionId: string): string[] {
     540            0 :   const definition = definitionsMap(doc)?.get(definitionId)
     541            0 :   if (!(definition instanceof Y.Map)) return []
     542            0 :   return namedInputs(definition.get('inputs'))?.map(([name]) => name) ?? []
     543              : }
        

Generated by: LCOV version 2.0-1