## Summary
Documents the PrimitiveNode copy/paste bug mechanism and connection
lifecycle semantics in `WIDGET_SERIALIZATION.md`. This is tribal
knowledge from debugging
[#1757](https://github.com/Comfy-Org/ComfyUI_frontend/issues/1757) and
the related [Slack
discussion](https://comfy-organization.slack.com/archives/C09AQRB49QX/p1771806268469089).
## What's documented
- **The clone→serialize gap**: `_serializeItems()` calls
`item.clone()?.serialize()`. The clone has no `this.widgets`
(PrimitiveNode creates them on connection), so `serialize()` silently
drops `widgets_values`.
- **Why seed survives but control_after_generate doesn't**: Primary
widget value is copied from the target on reconnect; secondary widgets
read from `this.widgets_values` which was lost.
- **Current vs. proposed lifecycle**: Empty-on-copy → morph-on-connect
(current) vs. clone-configured-instance → empty-on-disconnect
(proposed).
- **Design considerations**: `input.widget` override flexibility,
deserialization ordering, and the minimal `serialize()` override fix.
## Related
- Issue: #1757
- Fix PR: #8938
- Companion: #9102 (initial WIDGET_SERIALIZATION.md), #9105 (type/JSDoc
improvements)
- Notion: COM-15282
┆Issue is synchronized with this [Notion
page](https://www.notion.so/PR-9119-docs-document-PrimitiveNode-copy-paste-semantics-and-widgets_values-loss-3106d73d3650816ba7f7d9e6f3bb3868)
by [Unito](https://www.unito.io)
* ADR: Add PrimeVue fork decision record
Adds ADR-0003 documenting the decision to fork PrimeVue as a monorepo workspace package. Key rationale includes transform coordinate system conflicts and virtual canvas scroll interference that require component-level modifications.
* ADR: Reject PrimeVue fork decision
- Change status from Proposed to Rejected
- Document rationale: implementation complexity with dual monorepos,
maintenance burden, alternative solutions available
- Add specific code citations and repository links
- Include alternative approach using shadcn/ui for selective replacement
- Rename 0004-crdt-based-layout-system.md to 0003-crdt-based-layout-system.md
- Update title from "4. Centralized..." to "3. Centralized..."
- Add ADR 0003 entry to docs/adr/README.md index table
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-authored-by: Claude <noreply@anthropic.com>
Co-authored-by: Alexander Brown <drjkl@comfy.org>
Adds ADR-0004 documenting the architectural decision to implement centralized layout management using CRDT backing store with command pattern architecture.
## Key Technical Decisions Documented
- **Centralized State Management**: Move from scattered `node.position` mutations to single authoritative layout store
- **CRDT Foundation**: Yjs-backed store provides conflict resolution and collaboration readiness
- **Command Pattern**: All spatial mutations flow through explicit commands for undo/redo and system coordination
- **Reactive Architecture**: Transition from O(n) diff-based change detection to O(1) signal-based reactivity
## Current Architecture Problems Addressed
- Performance bottlenecks from polling-based change detection in complex workflows
- Position conflicts between LiteGraph canvas and DOMwidgets.ts overlay systems
- Inability to support collaborative editing due to direct mutation patterns
- Renderer lock-in preventing alternative rendering backends
