🏗️ Architecture: How should surgical DOM mutations work in Platform Elements ...

Date: 2026-03-25
Time: 21:47:13 UTC
Session: gspace1-270.3
Agent: architecture
Confidence: 95%
Status: ✅ Documented

📋 Decision Context

Question:

How should surgical DOM mutations work in Platform Elements without iframe reload?

Task: S270 Platform Elements Evolution

🎯 Decision Made

Chosen:

Typed mutation protocol with 6 ops (set-attr, remove-attr, insert, remove, replace, reorder). Dual application: same mutation hits live DOM (MutationExecutor) and DOMParser shadow document (MutationSourceSync) in parallel. Batch skip-and-continue semantics. Post-mutation hooks only for data elements needing fetchData().

Options Considered:

1. Full HTML string replacement + blob URL regeneration (50-100ms, loses element state)
2. Morphdom/idiomorph DOM diffing library (adds 3KB, may mishandle custom element state)
3. Typed mutation protocol with surgical DOM ops (chosen — <16ms, preserves state, no library)

💭 Reasoning

Verified against actual PE codebase: (1) ExpressionBindingManager already has MutationObserver on childList+subtree — new pe-* attributes auto-bind. (2) Action click handler uses global document delegation via closest('[pe-action]') — works on new elements automatically. (3) Element Inspector uses global document listeners — auto-works. (4) Custom elements auto-upgrade on insertAdjacentHTML. Only PlatformRouter lacked auto-discovery (fixed with filtered MutationObserver). Only data elements need manual fetchData(). This means 90% of the mutation infrastructure is free — the framework was already designed for it. The DOMParser shadow document avoids DOM-vs-source drift by applying the same typed mutation to both — no diffing needed.

📁 Files Involved

• libs/libs-structural/platform-elements/src/lib/runtime/mutation-types.ts
• libs/libs-structural/platform-elements/src/lib/runtime/mutation-executor.ts
• libs/libs-structural/platform-elements/src/lib/runtime/mutation-source-sync.ts
• libs/libs-structural/platform-elements/src/lib/runtime/mutation-receiver.ts

🔗 Related

• Decision ID: dev_1774475233179_ipudzwi
• Session: 270
• Workspace: gspace1

Auto-generated by MCP Smart Consolidation