diff --git a/docs/architecture/ecs/ecs-component-entity-data-audit.md b/docs/architecture/ecs/ecs-component-entity-data-audit.md new file mode 100644 index 00000000000..8b4b1d4e0ce --- /dev/null +++ b/docs/architecture/ecs/ecs-component-entity-data-audit.md @@ -0,0 +1,318 @@ +# ECS Component and Entity data audit + +Status: Scoped migration implemented; structural follow-up remains +Verified: 2026-08-21 against `73c3c633f` +Scope: Implementation record for +[Centralize remaining Component and Entity data](ecs-migration-plan.md#2-centralize-remaining-component-and-entity-data) + +This audit records the baseline, implementation, and remaining structural work +for every concern in that section. `Implemented` means the scoped authority move +landed with its compatibility boundary and tests. It does not mean all legacy +facades or broader ECS architecture work have been removed. + +## Summary + +All 19 scoped concerns are implemented. Compatibility facades remain where +extensions or legacy rendering require their object identity and mutation +behavior. Five larger structural slices remain and are listed separately below. + +| Concern | Status | Current boundary | +| ----------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------ | +| Graph and subgraph definitions | Implemented | Root-scoped records own ordered membership, registries, and subgraph definition metadata. | +| Remaining node visuals | Implemented | `NodeState` owns `boxcolor` behind an enumerable compatibility accessor. | +| Outputs and transient previews | Implemented | Store maps own reads; legacy output-map writes commit through stable nested mutation views. | +| Node ordering | Implemented | One action updates canonical layout z-index and legacy node-array order. | +| Store-driven serialization | Implemented | Graph, node, group, topology, reroute, and subgraph DTOs enumerate store authorities. | +| Legacy node geometry projection | Implemented | The layout adapter owns stable mutable geometry views and write-through. | +| Link non-topological state | Implemented | Separate persistent and runtime records follow topology lifecycle. | +| Plain slot descriptors | Implemented | Plain reactive descriptors back stable slot-class projections with native callback semantics. | +| Node properties | Implemented | `NodeState` owns the stable mutable property dictionary behind compatibility behavior. | +| Group presentation | Implemented | Graph-definition records own presentation while layout owns geometry. | +| Preview-exposure persistence | Implemented | Owner-scoped locators key runtime lookup and serialization; raw IDs are hydration-only input. | +| Extension persistence adapter | Implemented | Validated namespaced payloads and isolated hook views preserve canonical fields. | +| Graph metadata | Implemented | A graph-keyed store owns revision, config, and extra behind compatibility accessors. | +| Graph invalidation | Implemented | Graph-scoped batching coalesces composite mutations behind `_version`. | +| Unknown-node fallback | Implemented | `NodeState` owns opaque fallback DTOs behind `last_serialization`. | +| Execution order | Implemented | Graph-scoped derived records own execution order behind the node projection. | +| Entity ID allocation | Implemented | Root-keyed allocation state and shared helpers own minting and observation. | +| Delayed widget restoration | Implemented | Store-owned restoration state feeds registered and delayed widgets. | +| Widget and preview-exposure cleanup | Implemented | Removal, replacement, and teardown clear node-owned records; failed configure cleanup remains limited. | + +## Pre-migration baseline findings + +The following sections preserve the verified baseline used to derive the 19 +implementation commits. They describe the code before those commits, not the +current authority boundaries. + +### Graph definitions, metadata, execution order, and identity + +- `LGraph._nodes`, `_nodes_by_id`, `_groups`, `_subgraphs`, `config`, `extra`, + `revision`, and `state` remain the live authorities. `Subgraph.inputs`, + `outputs`, and `widgets` are ordered class-owned arrays. +- `LGraph.asSerialisable` enumerates those registries and calls class + serializers. Subgraph serialization does the same for definition metadata and + interfaces. +- `computeExecutionOrder` derives topology order and writes `node.order`; the + same mutable field remains in `ISerialisedNode` and normal node serialization. +- Allocation helpers centralize mint/observe behavior over root-shared + `LGraph.state`, but that state remains publicly replaceable and clipboard + import still advances counters through the live graph. +- Unknown node load stores the complete source DTO in `NodeState` behind the + `LGraphNode.last_serialization` compatibility accessor. Missing-node + serialization returns that DTO over current store-backed fields except for + selected compatibility overrides. + +Representative implementation: + +- `src/lib/litegraph/src/LGraph.ts`: graph fields, `add`, `removeNode`, + `computeExecutionOrder`, `configure`, `asSerialisable`, and `Subgraph`. +- `src/lib/litegraph/src/idAllocation.ts`: root-shared mint and observe helpers. +- `src/lib/litegraph/src/subgraph/subgraphDeduplication.ts`: recursive import + normalization. +- `src/lib/litegraph/src/LGraphNode.ts`: `order`, `last_serialization`, and + `serialize`. +- `src/platform/nodeReplacement/useNodeReplacement.ts`: unknown-node discovery + and replacement. + +Representative evidence: + +- `src/lib/litegraph/src/LGraph.test.ts`: shared counters, definition retention, + and cross-definition identity. +- `src/lib/litegraph/src/subgraph/SubgraphSerialization.test.ts`: interface, + membership, topology, and collision round trips. +- `src/lib/litegraph/src/idAllocation.test.ts`: mint and observe behavior. +- `src/platform/nodeReplacement/useNodeReplacement.test.ts`: unknown-node + replacement and compatibility values. + +### Node, group, slot, link, and layout projections + +- `NodeState` owns tracked shell fields including foreground/background color, + shape, flags, and mode. `boxcolor` remains a plain `LGraphNode` property. +- Persistent node/group/reroute geometry and node z-index live in `layoutStore`. + `LGraphNode` still owns `_posSize`, mutation views, geometry-version checks, + and layout write-through. These provide the stable indexed `pos` and `size` + references expected by extensions. +- `bringToFront` updates layout z-index and legacy `_nodes` order. + `sendToBack` changes only `_nodes`; renderer switching later re-sorts that + array from layout z-index. +- `NodeState.inputs` and `outputs` contain slot class instances. Their + connectivity facades read `linkStore`, while descriptor fields, node + back-references, drawing, geometry, and callbacks remain class behavior. +- `LLink` topology remains in `linkStore`. `linkStateStore` owns separately + categorized persistent color and runtime execution, interaction, render, and + hit-test state behind compatible `LLink` accessors and the same lifecycle. +- Group geometry is store-backed, but presentation fields remain on + `LGraphGroup`. + +Representative implementation: + +- `src/types/nodeState.ts`; `src/lib/litegraph/src/LGraphNode.ts`. +- `src/renderer/core/layout/operations/graphLayoutAttachment.ts` and + `layoutMutations.ts`. +- `src/lib/litegraph/src/LGraphCanvas.ts`: `bringToFront` and `sendToBack`. +- `src/renderer/core/canvas/litegraph/arrangeForLegacyRender.ts`. +- `src/lib/litegraph/src/node/SlotBase.ts`, `NodeSlot.ts`, `NodeInputSlot.ts`, and + `NodeOutputSlot.ts`. +- `src/lib/litegraph/src/LLink.ts` and + `src/renderer/core/canvas/litegraph/litegraphLinkAdapter.ts`. +- `src/lib/litegraph/src/LGraphGroup.ts`. + +Representative evidence: + +- `src/stores/nodeDataStore.test.ts`: shell transfer and slot-array identity. +- `src/lib/litegraph/src/LGraphNode.test.ts`: stable geometry views and + store-backed indexed writes. +- `src/renderer/core/layout/operations/layoutMutations.test.ts` and + `src/renderer/core/canvas/litegraph/arrangeForLegacyRender.test.ts`: z-order + mutation and legacy projection. +- `src/lib/litegraph/src/node/NodeInputSlot.test.ts`, + `NodeOutputSlot.test.ts`, and `slotEcosystemPatterns.test.ts`: derived + connectivity and extension compatibility. +- `src/lib/litegraph/src/canvas/LinkConnector.core.test.ts`: transient link + interaction state. + +### Outputs, properties, widgets, and preview exposures + +- `nodeOutputStore` maintains reactive output and preview maps, locator-aware + removal, object-URL cleanup, and workflow stash/restore. Its read/write paths + still synchronize in both directions with `app.nodeOutputs`, + `app.nodePreviewImages`, `node.images`, and `node.imgs`. +- `LGraphNode.properties` remains directly mutable. First-party code writes it + both through `setProperty` and directly. Serialization clones the whole map. +- Registered widget values and order are store-backed. General node configure + still restores from named or positional wire shadows, and delayed widget + creation plus some first-party consumers still read or write those shadows. +- `previewExposureStore` is further along than the prior plan wording implied: + subgraph configure hydrates it from the compatibility property, runtime reads + use it, and serialization projects from it. The remaining gap is scoped + identity and lifecycle cleanup, not initial authority. + +Representative implementation: + +- `src/stores/nodeOutputStore.ts`; `src/scripts/app.ts`. +- `src/lib/litegraph/src/LGraphNode.ts`: `properties`, `configure`, + `setProperty`, and `serialize`. +- `src/stores/widgetValueStore.ts`; `src/lib/litegraph/src/widgets/BaseWidget.ts`; + `src/extensions/core/widgetInputs.ts`. +- `src/stores/previewExposureStore.ts` and + `src/lib/litegraph/src/subgraph/SubgraphNode.ts`. + +Representative evidence: + +- `src/stores/nodeOutputStore.test.ts` and + `nodeOutputStore.workflowSwitch.test.ts`: mirrored maps, legacy image + projection, cleanup, and workflow switching. +- `src/lib/litegraph/src/LGraphNode.widgetOrder.test.ts`: named/positional + restoration and reorder behavior. +- `src/lib/litegraph/src/subgraph/SubgraphWidgetPromotion.test.ts`: store-backed + promoted values and preview-exposure round trips. +- `src/stores/previewExposureStore.test.ts`: graph isolation and root cleanup. + +### Serialization and extension boundary + +- `LGraph.asSerialisable`, `LGraphNode.serialize`, and the group/subgraph + serializers remain the wire-format oracle. No store-record serializer exists. +- Node and graph `onSerialize` hooks receive the complete mutable canonical DTO. + The repository has no adapter that extracts a validated namespaced extension + payload or rejects canonical-field writes. +- Prompt construction serializes the workflow and then invokes asynchronous + widget `serializeValue` hooks. At least one first-party hook mutates the + positional workflow widget projection, so prompt derivation is not isolated + from persistence DTOs. + +Representative implementation: + +- `src/lib/litegraph/src/LGraph.ts`: `asSerialisable` and graph `onSerialize`. +- `src/lib/litegraph/src/LGraphNode.ts`: node `serialize` and `onSerialize`. +- `src/utils/executionUtil.ts`: workflow and prompt construction. +- `src/extensions/core/dynamicPrompts.ts`: queue-time workflow projection write. + +## Corrections established by the baseline audit + +1. Preview-exposure persistence has already moved to a store for runtime reads + and serialization. Remaining work is scoped host/source cleanup and the + compatibility hydration boundary. +2. `_version` increments use one method, but mutation callers still own + invalidation policy. The missing boundary is centralized policy and batching, + not an increment helper. +3. `nodeOutputStore` already owns substantial locator, object-URL, and workflow + cleanup. It is not authoritative because it still reads legacy maps and + accepts live node image fields as reverse synchronization inputs. +4. Slot connectivity and persistent geometry already have store authorities. + The remaining work concerns plain descriptors and compatibility projection + ownership, not moving connectivity or duplicating geometry. +5. Widget and preview-exposure stores have root cleanup. They lack complete + node/owner cleanup across remove, replacement, failed configure, and released + subgraphs. + +## Implemented migration sequence rationale + +The implemented sequence followed the serialization dependencies: + +1. Finished narrow authorities and lifecycle first: `boxcolor`, ordering, + output/preview directionality, widget/preview owner cleanup, and graph + metadata/identity ownership. +2. Moved class projections behind compatibility adapters: node geometry, + slot descriptors, group presentation, link runtime categories, properties, + and unknown-node fallback records. +3. Parsed widget and extension compatibility payloads at workflow boundaries + and removed first-party writes to wire shadows. +4. Added a store-record serializer beside the mutable serializer and proved + normalized differential parity before changing production serialization. + +This ordering does not require a universal ECS world, command replay, or a new +undo model. + +## Progress record + +Each concern is completed in its own commit. The order follows the dependency +sequence above rather than the summary-table order. + +| Sequence | Concern | Status | Commit | Result | +| -------- | ----------------------------------- | -------- | ------------ | ------------------------------------------------------------------------------------------------------ | +| 1 | Remaining node visuals | Complete | `fa5dcd8ca` | `boxcolor` moved into `NodeState` with an enumerable tracked compatibility accessor. | +| 2 | Node ordering | Complete | `06ae14e8b` | One action now updates layout z-index and the legacy node array for front/back order. | +| 3 | Outputs and transient previews | Complete | `570b38c2a` | Store maps own reads; the legacy output map commits mutations through a compatibility view. | +| 4 | Preview-exposure persistence | Complete | `2212ed302` | Host exposures use owner-scoped locators; raw node-ID entries are hydration-only input. | +| 5 | Widget and preview-exposure cleanup | Complete | `ecd148fa0` | Removal, replacement, and teardown clear node-owned records; failed configure cleanup remains limited. | +| 6 | Graph metadata | Complete | `298bf3da0` | Revision, config, and extra now use graph-keyed store records behind compatibility accessors. | +| 7 | Entity ID allocation | Complete | `7fbd10624` | Root-keyed allocation state now backs graph accessors; clipboard allocation uses shared helpers. | +| 8 | Graph and subgraph definitions | Complete | `8923225fb` | Root-scoped records now own ordered membership, the registry, and subgraph definition metadata. | +| 9 | Legacy node geometry projection | Complete | `854f68fb2` | The layout adapter now owns stable legacy views, synchronization, and geometry write-through. | +| 10 | Plain slot descriptors | Complete | `cc53dad291` | Plain store descriptors now back stable extension-visible slot class projections. | +| 11 | Group presentation | Complete | `3ac7b726a` | Graph-definition records now back mutable presentation fields and serialization. | +| 12 | Link non-topological state | Complete | `38b40988a` | Separate persistent and runtime records now back compatible link fields with topology lifecycle. | +| 13 | Node properties | Complete | `f75b30dbd` | Node state now owns stable mutable properties across lifecycle, callbacks, and serialization. | +| 14 | Unknown-node fallback | Complete | `ba4757f4c` | Node state now owns unknown-node fallback records behind the compatibility accessor. | +| 15 | Delayed widget restoration | Complete | `972947d939` | Store-owned restoration state now hydrates configured and delayed widgets from wire shadows. | +| 16 | Extension persistence adapter | Complete | `287bf33f38` | Validated payloads round trip through a namespace while legacy hooks mutate isolated DTO views. | +| 17 | Execution order | Complete | `7f6c2783dd` | Graph-scoped derived records own execution order behind the compatible node projection. | +| 18 | Graph invalidation | Complete | `335b69420c` | Graph-scoped batching coalesces composite invalidations behind the compatible version counter. | +| 19 | Store-driven serialization | Complete | `458d292f1` | Store authorities now build wire DTOs after normalized parity against mutable serialization. | + +Final full-suite verification also tightened slot-projection deletion and +updated test fixtures to preserve their store scope and projected-array +contract. + +Post-review regression verification restored legacy output-map write-through, +kept widget output changes observable by preview rendering, and removed a +redundant MatchType slot wrapper that hid descriptor updates from Vue. + +| Review follow-up | Commit | Result | +| ----------------------------------- | ----------- | --------------------------------------------------------------------------------------- | +| Graph extension isolation | `b8fdbf860` | Configure payloads remain in isolated persistence records and hook views. | +| Nested legacy output mutations | `cceb56330` | Output fields and their immediate arrays commit through stable mutation views. | +| Populated graph ID changes | `17546ff13` | Populated graphs reject ID reassignment instead of splitting scoped store state. | +| Native slot callback array behavior | `73c3c633f` | Callback-bearing array methods now receive and mutate the extension-visible slot array. | + +## Verified current limitations + +- Slot descriptors remain behind a virtual slot-class array. Native callback + behavior is preserved, but complete reflection compatibility still requires + restoring real extension-visible slot arrays. +- `graphDefinitionStore` still contains live node, group, subgraph, and + interface instances. Persisted UUIDs remain runtime store keys; populated + graph IDs are therefore immutable until instance-scoped identity replaces + that keying model. +- Store-driven persistence joins and compatibility adaptation still live in + and around `LGraph`. +- Replacement configure is destructive on failure, while additive configure + has only best-effort rollback. +- `SubgraphNode` still owns promoted-widget projection, preview hydration, and + host persistence responsibilities. + +## Structural follow-up plan + +These are future structural improvements, not incomplete rows in the scoped +19-concern migration. They should proceed as vertical slices rather than adding +more projections to `LGraph` and `LGraphNode`. + +1. **Replace the slot virtual array.** Keep extension-visible input and output + arrays as real slot-class arrays. Derive plain serializable descriptors at + the node-state boundary until a complete ID-based slot record can replace + both representations. Remove `slotDescriptorView` only after ecosystem + tests cover indexed access, mutation methods, reflection, and stable slot + identity. +2. **Introduce one plain graph record.** Replace live node, group, subgraph, and + interface instances in `graphDefinitionStore` with ordered IDs and plain + component records. Resolve runtime adapters through one instance-scoped + registry. The instance scope must allow two loaded graphs with the same + persisted UUID without rekeying one graph's state over the other. +3. **Extract persistence from `LGraph`.** Move store joins, invariant checks, + extension payload adaptation, and DTO construction into a focused graph + persistence adapter. Keep the mutable serializer as the compatibility + oracle until canonicalized DTOs compare with exact equality for root graphs, + nested subgraphs, groups, reroutes, widgets, unknown nodes, and extensions. +4. **Make configure transactional.** Stage graph records and topology before + publishing them, then swap atomically. This replaces the current best-effort + rollback for additive configuration and gives failed root replacement the + same no-partial-state guarantee. +5. **Decompose subgraph hosting.** Move promoted-widget projection, preview + exposure hydration, and host persistence out of `SubgraphNode` into focused + adapters, returning the class below the 1,000-line boundary without adding + another general-purpose manager. + +Each slice needs focused unit tests for its pure boundary plus the existing +Playwright bridge-history scenarios for delete/undo/redo, renderer switching, +navigation, and reload. Production authority should switch only after exact +serializer parity and the browser suite pass together. diff --git a/docs/architecture/ecs/ecs-extension-compatibility-audit.md b/docs/architecture/ecs/ecs-extension-compatibility-audit.md index 62dae0b77f7..ffe6998d71b 100644 --- a/docs/architecture/ecs/ecs-extension-compatibility-audit.md +++ b/docs/architecture/ecs/ecs-extension-compatibility-audit.md @@ -127,14 +127,18 @@ Derived first-party rows are recomputed on read; extension entries remain on ### Persistence hooks `node.onSerialize`, `node.onConfigure`, `graph.onSerialize`, and -`graph.onConfigure` remain compatibility surfaces, but currently expose full -node/workflow DTOs or live objects. Extensions can therefore mutate canonical -store-backed persistence fields outside store actions. -The migration must measure this usage before replacing it with a controlled -adapter for validated, namespaced plain-data payloads. This phase requires the -adapter to define serialization and configuration behavior without allowing -extension payload hooks to rewrite canonical fields. Replay and command-based -undo contracts are later architecture work. +`graph.onConfigure` remain compatibility surfaces. Serialize hooks receive a +mutable DTO view: changes to canonical fields are applied to that serialization, +while JSON-compatible noncanonical fields are persisted under `extensions`. +Configure hooks receive an isolated clone containing canonical data plus the +owner's extension payload; mutating that clone does not reconfigure the graph. + +Extensions should persist JSON-compatible data under a unique key in +`data.extensions` and read it from the same key in `onConfigure`. Legacy flat +fields are still projected into configure views, but migrate them to a +namespaced key. Do not use `onConfigure` to rewrite nodes, links, or other +canonical workflow fields; perform graph mutations through supported graph APIs +after configuration instead. ### Custom-widget constructors diff --git a/docs/architecture/ecs/ecs-migration-plan.md b/docs/architecture/ecs/ecs-migration-plan.md index dff2ddd8689..e0fc9667ae0 100644 --- a/docs/architecture/ecs/ecs-migration-plan.md +++ b/docs/architecture/ecs/ecs-migration-plan.md @@ -1,7 +1,7 @@ # ECS migration plan -Status: Partial -Verified: 2026-08-20 against `13a302eadda871b939b148ecb87e3d845ceefff2` +Status: Scoped data centralization implemented; structural follow-up remains +Verified: 2026-08-21 against `73c3c633f` This plan records completed ECS migration work and the work that remains. Detailed evidence and unresolved risks are in the focused audits under @@ -38,22 +38,22 @@ this phase. ## Work completed -| Concern | Current result | -| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| Node shell | `nodeDataStore` owns `NodeState`. `LGraphNode` adopts the registered reactive proxy; renderer-only node mirrors and `useGraphNodeManager` were removed. | -| Link topology | `linkStore` owns `LinkTopology` by root-wide `LinkId`, with owner, target, and origin indexes. `LLink` endpoint properties are compatibility accessors over the registered state. | -| Slot connectivity | Input and output connectivity is derived from `linkStore`. `input.link` and `output.links` are deprecated read-only compatibility accessors; writes are ignored. | -| Reroute chains | `rerouteStore` owns parent/floating chain state. Link membership is derived from link parent chains rather than stored on reroutes. | -| Widget state | `widgetValueStore` owns widget values, render metadata, and root-scoped per-node order. `BaseWidget` adopts registered state. | -| Layout | Yjs-backed `layoutStore` owns persistent node, group, and reroute geometry. Entity lifecycle attaches geometry independently of renderer lifecycle, and layout writes use `LayoutOperation`. | -| Renderer integration | Vue and legacy renderers read the same persistent geometry. Vue slot endpoints reactively derive from store-owned node layout plus measured offsets. Renderer switches clear transient view geometry rather than reseeding entity layout. | -| Renderer consumers | `GraphCanvas` reads node shells from `nodeDataStore`; minimap topology reads `linkStore`; selection, arrangement, traversal, pricing, and widget consumers use store-backed topology or geometry where migrated. Live classes remain adapters for schema, callbacks, and legacy rendering. | -| Badges | Badge rows are derived by `badgeSystem`; the temporary badge store was removed. Badge data is transient and is not serialized or independently mutated. | -| Error presentation | Error stores are authoritative inputs for Vue error rendering. `node.has_errors` remains a legacy-canvas projection, including promoted-widget and container error resolution, rather than an independent persisted authority. | -| Identity | Root graph allocation and import normalization enforce unique node, link, group, and reroute IDs across nested definitions. Owner indexes retain graph-local queries and teardown. | -| Lifecycle | Graph add, configure, replace, remove, subgraph release, and clear register, transfer, or release migrated state. Typed graph lifecycle events let internal observers avoid replacing extension callback slots. Clear handles reentrant and failing removal callbacks; normal node removal can retain widget entries, and `configure(keep_old)` provides weaker cleanup. | -| Persistence | Serialization, subgraph conversion, copy/paste, and workflow insertion preserve the existing workflow format while normalizing conflicting identities. | -| Compatibility | Legacy graph, node, link, slot, widget, geometry, and callback surfaces remain available where practical. Changed behavior is documented in the extension migration references. | +| Concern | Current result | +| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Node shell | `nodeDataStore` owns `NodeState`. `LGraphNode` adopts the registered reactive proxy; renderer-only node mirrors and `useGraphNodeManager` were removed. | +| Link topology | `linkStore` owns `LinkTopology` by root-wide `LinkId`, with owner, target, and origin indexes. `LLink` endpoint properties are compatibility accessors over the registered state. | +| Slot connectivity | Input and output connectivity is derived from `linkStore`. `input.link` and `output.links` are deprecated read-only compatibility accessors; writes are ignored. | +| Reroute chains | `rerouteStore` owns parent/floating chain state. Link membership is derived from link parent chains rather than stored on reroutes. | +| Widget state | `widgetValueStore` owns widget values, render metadata, and root-scoped per-node order. `BaseWidget` adopts registered state. | +| Layout | Yjs-backed `layoutStore` owns persistent node, group, and reroute geometry. Entity lifecycle attaches geometry independently of renderer lifecycle, and layout writes use `LayoutOperation`. | +| Renderer integration | Vue and legacy renderers read the same persistent geometry. Vue slot endpoints reactively derive from store-owned node layout plus measured offsets. Renderer switches clear transient view geometry rather than reseeding entity layout. | +| Renderer consumers | `GraphCanvas` reads node shells from `nodeDataStore`; minimap topology reads `linkStore`; selection, arrangement, traversal, pricing, and widget consumers use store-backed topology or geometry where migrated. Live classes remain adapters for schema, callbacks, and legacy rendering. | +| Badges | Badge rows are derived by `badgeSystem`; the temporary badge store was removed. Badge data is transient and is not serialized or independently mutated. | +| Error presentation | Error stores are authoritative inputs for Vue error rendering. `node.has_errors` remains a legacy-canvas projection, including promoted-widget and container error resolution, rather than an independent persisted authority. | +| Identity | Root graph allocation and import normalization enforce unique node, link, group, and reroute IDs across nested definitions. Owner indexes retain graph-local queries and teardown. | +| Lifecycle | Graph add, configure, replace, remove, subgraph release, and clear register, transfer, or release migrated state. Typed graph lifecycle events let internal observers avoid replacing extension callback slots. Clear handles reentrant and failing removal callbacks; failed and additive configure still have the cleanup limits described below. | +| Persistence | Serialization, subgraph conversion, copy/paste, and workflow insertion preserve the existing workflow format while normalizing conflicting identities. | +| Compatibility | Legacy graph, node, link, slot, widget, geometry, and callback surfaces remain available where practical. Changed behavior is documented in the extension migration references. | ## PR 14246 change traceability @@ -86,58 +86,23 @@ not separate architecture changes. ## Current boundaries -The following authority boundaries remain in this phase: - -- `NodeState.inputs` and `outputs` contain slot class instances. Slot data is - not yet a plain component model. -- Widget order exists in both the store and `LGraphNode.widgets` during the - compatibility period. Vue filters store order through live widget objects and - still invokes their callbacks. -- Live graph object registries and store records coexist and must be attached - and detached together. -- Graph membership, graph metadata, groups, subgraph definitions and ordered - interfaces, node properties, group presentation, and extension-owned data - remain authoritative on live `LGraph`, `Subgraph`, node, and group objects. -- `LGraphNode.boxcolor` remains class-owned durable render state outside - `NodeState`, despite other shell visual fields being store-backed. -- Unknown nodes retain `last_serialization`, an opaque full-node record that - overrides normal serialization and can shadow migrated node, slot, widget, - and render state. -- Execution `order` is recomputed from topology but also restored and persisted - on `LGraphNode`; its derived-versus-wire-compatibility contract is not yet - enforced. -- Serialized `LGraph.state` allocation counters are directly mutable and - influence future durable IDs outside a command/store boundary. -- `node.widgets_values` and `widgets_values_named` form another widget-value - representation used for delayed dynamic-widget restoration and direct - production writes; property-bound widgets can also mirror values in - `node.properties`. -- `nodeOutputStore` mirrors `app.nodeOutputs` and `app.nodePreviewImages`, and - legacy render output also projects into live node image fields. It is not yet - the sole output authority. -- `LGraph._version` is manually incremented across graph, node, canvas, widget, - slot, and subgraph mutation callers rather than derived at one committed - transaction boundary. -- Durable graph `config`, `extra`, and `revision` metadata remains class-owned - and directly mutable; graph metadata is not yet included in the explicit - command schema. -- Node and graph `onSerialize` hooks can mutate complete persistence DTOs, while - generic configure assignment and `onConfigure` expose equivalent load-time - mutation channels. These extension hooks can override store-backed fields - without schema, ownership, replay, transaction, or undo boundaries. -- Prompt construction awaits arbitrary widget `serializeValue` hooks. Current - hooks can mutate widget/workflow shadows, choose random values, capture media, - upload files, and update UI state, so execution input assembly is neither a - pure store read nor isolated from unrelated effects. -- Node z-order exists in layout state and legacy `_nodes` ordering. - `sendToBack` currently updates only the legacy ordering path. -- Node and input-slot error flags are mutable legacy drawing projections of - error-store state and require synchronization by app hooks. -- Widget and preview stores lack the owner-scoped cleanup available in node, - link, and reroute stores. Subgraph release and failed operations can retain - records until root cleanup. -- Link paths, slot bounds, and hit-test geometry are transient renderer caches, - not persistent layout components. +The scoped authority migration is complete. These structural boundaries remain: + +- Slot descriptors sit behind a virtual extension-visible slot-class array. + Native callback semantics are preserved, but complete reflection compatibility + requires restoring real arrays at that boundary. +- `graphDefinitionStore` still contains live adapter instances, and persisted + graph UUIDs remain runtime store keys. Populated graph IDs are immutable until + an instance-scoped registry replaces that keying model. +- Store-driven persistence joins and extension adaptation still live in and + around `LGraph`. +- Replacement configure is destructive on failure; additive configure provides + only best-effort rollback rather than an atomic staged transaction. +- `SubgraphNode` still combines promoted-widget projection, preview hydration, + and host persistence responsibilities. +- Prompt construction still awaits effectful widget `serializeValue` hooks. +- Link paths, slot bounds, and hit-test geometry remain transient renderer + caches rather than persistent components. The current implementation also has no system-wide command protocol, workflow transaction, command replay, or command-based undo. These are factual limits, @@ -178,48 +143,17 @@ unless they cover a new invariant. ### 2. Centralize remaining Component and Entity data -- Add plain store-owned graph and subgraph definition records for membership, - metadata, ordered entity IDs, and subgraph interfaces. Keep live object - registries as runtime adapters rather than serialization authorities. -- Move remaining durable node visuals, including `boxcolor`, into the - store-owned shell or a focused visual component. -- Make `nodeOutputStore` authoritative for output and preview maps; expose - legacy `app` and node-image fields as compatibility projections. -- Make one layout ordering action update both Vue z-index and the legacy draw - projection; remove the asymmetric `sendToBack` mutation. -- Extract serialization only after stores contain sufficient authoritative - data and parity can be checked against the existing wire format. -- Move legacy geometry projection ownership out of `LGraphNode` without - changing `pos` and `size` extension behavior. -- Separate remaining link visual/runtime state when a renderer or interaction - system can consume plain records directly. -- Extract plain slot state only when it removes a real class dependency; retain - array order semantics and keep connectivity in `linkStore`. -- Move node properties, group presentation, preview-exposure persistence, and - extension-owned durable fields behind scoped store actions while retaining - compatibility property facades. -- Preserve serialization compatibility through a controlled adapter: isolate - namespaced extension payloads as validated plain data and prevent persistence - hooks from mutating canonical workflow and store-backed fields. -- Move graph `config`, `extra`, and `revision` into a focused store-owned plain - data record while preserving serialization compatibility. -- Derive graph invalidation from authoritative store revisions or one - centralized compatibility projection; remove scattered caller-owned - `_version` increments. -- Store opaque unknown-node fallback records by scoped node identity, define - their remapping and replacement lifecycle, and retain `last_serialization` - only as a compatibility facade. -- Treat execution order as a derived topology projection. Define whether - serialized `order` is ignored and recomputed or retained only as explicit - wire compatibility, not as an independent mutation channel. -- Move allocation counters behind the workflow identity owner. Creation/import - must no longer derive IDs from mutable state distributed across class and - import paths. -- Route delayed widget restoration through scoped store state and isolate - serialized widget arrays/maps as wire compatibility projections rather than - production mutation channels. -- Add owner/node cleanup for widget and preview records before treating failed - configure, replacement, and subgraph release as contained operations. +All 19 scoped concerns are implemented. The authoritative commit-by-commit +record is in the Component and Entity data audit's +[progress record](ecs-component-entity-data-audit.md#progress-record), with +current boundaries under [verified current limitations](ecs-component-entity-data-audit.md#verified-current-limitations). + +Remaining work is the audit's five-part +[structural follow-up plan](ecs-component-entity-data-audit.md#structural-follow-up-plan): +restore real slot arrays, introduce an instance-scoped plain graph record, +extract persistence from `LGraph`, make configure transactional, and decompose +subgraph hosting. These improvements do not reopen the completed 19-concern +authority migration. ### 3. Retire duplicate state and synchronization bridges @@ -289,6 +223,7 @@ CRDT compatibility are explicitly not completion criteria for this phase. - [Executive summary](ecs-migration-summary.md) - [Decision traceability](ecs-decision-traceability.md) - [State authority audit](ecs-state-authority-audit.md) +- [Component and Entity data audit](ecs-component-entity-data-audit.md) - [Lifecycle audit](ecs-lifecycle-audit.md) - [Mutation audit](ecs-mutation-audit.md) - [Identity and scope audit](ecs-identity-scope-audit.md) diff --git a/src/components/breadcrumb/SubgraphBreadcrumb.vue b/src/components/breadcrumb/SubgraphBreadcrumb.vue index 25ed74b98c0..99f25767790 100644 --- a/src/components/breadcrumb/SubgraphBreadcrumb.vue +++ b/src/components/breadcrumb/SubgraphBreadcrumb.vue @@ -54,7 +54,7 @@ import Breadcrumb from 'primevue/breadcrumb' import Button from 'primevue/button' import type { MenuItem } from 'primevue/menuitem' -import { computed, onUpdated, ref, watch } from 'vue' +import { computed, onBeforeUnmount, onMounted, onUpdated, ref } from 'vue' import SubgraphBreadcrumbItem from '@/components/breadcrumb/SubgraphBreadcrumbItem.vue' import WorkflowActionsDropdown from '@/components/common/WorkflowActionsDropdown.vue' @@ -135,20 +135,14 @@ const handleBackClick = () => { void useCommandStore().execute('Comfy.Graph.ExitSubgraph') } -const breadcrumbElement = computed(() => { - if (!breadcrumbRef.value) return null - - const el = (breadcrumbRef.value as unknown as { $el: HTMLElement }).$el - const list = el?.querySelector('.p-breadcrumb-list') as HTMLElement - return list -}) - // Check for overflow on breadcrumb items and collapse/expand the breadcrumb to fit let overflowObserver: ReturnType | undefined -watch(breadcrumbElement, (el) => { - overflowObserver?.dispose() - overflowObserver = undefined +onMounted(() => { + const breadcrumb = breadcrumbRef.value + if (!breadcrumb) return + const root = (breadcrumb as unknown as { $el: HTMLElement }).$el + const el = root.querySelector('.p-breadcrumb-list') if (!el) return overflowObserver = useOverflowObserver(el, { @@ -193,6 +187,8 @@ watch(breadcrumbElement, (el) => { }) }) +onBeforeUnmount(() => overflowObserver?.dispose()) + // If e.g. the workflow name changes, we need to check the overflow again onUpdated(() => { if (!overflowObserver?.disposed.value) { diff --git a/src/components/graph/GraphCanvas.vue b/src/components/graph/GraphCanvas.vue index 8b8950d58d7..ece7bde5a46 100644 --- a/src/components/graph/GraphCanvas.vue +++ b/src/components/graph/GraphCanvas.vue @@ -287,8 +287,6 @@ watch( ) watchEffect((onCleanup) => { - if (!shouldRenderVueNodes.value) return - const canvas = canvasStore.canvas if (canvas) onCleanup(notifyLayoutChanges(canvas)) }) diff --git a/src/components/maskeditor/BrushCursor.test.ts b/src/components/maskeditor/BrushCursor.test.ts index 27947622dfb..b79809cf414 100644 --- a/src/components/maskeditor/BrushCursor.test.ts +++ b/src/components/maskeditor/BrushCursor.test.ts @@ -1,5 +1,5 @@ -import { render, screen } from '@testing-library/vue' -import { nextTick, reactive } from 'vue' +import { render, screen, waitFor } from '@testing-library/vue' +import { reactive } from 'vue' import { beforeEach, describe, expect, it, vi } from 'vitest' import BrushCursor from '@/components/maskeditor/BrushCursor.vue' @@ -113,7 +113,7 @@ describe('BrushCursor', () => { expect(style).toContain('top: 305px') }) - it('should subtract container offset when containerRef is provided', () => { + it('should subtract container offset when containerRef is provided', async () => { mockStore.cursorPoint = { x: 200, y: 300 } mockStore.panOffset = { x: 0, y: 0 } mockStore.brushSettings.size = 20 @@ -136,55 +136,12 @@ describe('BrushCursor', () => { renderCursor(container) // left = 200 + 0 - 20 - 30 = 150; top = 300 + 0 - 20 - 60 = 220 + await waitFor(() => { + expect(styleOf(getBrushEl())).toContain('left: 150px') + }) const style = styleOf(getBrushEl()) - expect(style).toContain('left: 150px') expect(style).toContain('top: 220px') }) - - it('should read the container rect once per position, not once per axis', async () => { - mockStore.cursorPoint = { x: 200, y: 300 } - mockStore.panOffset = { x: 0, y: 0 } - mockStore.brushSettings.size = 20 - mockStore.brushSettings.hardness = 1 - mockStore.zoomRatio = 1 - - const container = document.createElement('div') - const readRect = vi - .spyOn(container, 'getBoundingClientRect') - .mockReturnValue({ - left: 30, - top: 60, - right: 0, - bottom: 0, - width: 0, - height: 0, - x: 0, - y: 0, - toJSON: () => ({}) - } as DOMRect) - - renderCursor(container) - - // `getBoundingClientRect` forces a synchronous layout and the cursor - // moves on every mousemove, so reading it per axis doubled the cost for - // one rect. - expect( - readRect, - 'left and top come from the same rect; reading it twice is two forced layouts per mousemove' - ).toHaveBeenCalledTimes(1) - - mockStore.cursorPoint = { x: 201, y: 301 } - await nextTick() - - // The other half of the guarantee, and the one that keeps the offset - // correct while the dialog is dragged: a DOMRect is not reactive, so - // caching it across moves would pass the assertion above and silently - // stop tracking the container. - expect( - readRect, - 'a moved cursor must re-read the rect; a cached one goes stale the moment the dialog moves' - ).toHaveBeenCalledTimes(2) - }) }) describe('gradient preview', () => { diff --git a/src/components/maskeditor/BrushCursor.vue b/src/components/maskeditor/BrushCursor.vue index f135a031fe7..2d7ca40f196 100644 --- a/src/components/maskeditor/BrushCursor.vue +++ b/src/components/maskeditor/BrushCursor.vue @@ -26,6 +26,7 @@