Architecture: Should Platform Elements use Lit, vanilla Custom Elements, o...

Documentation for Sessions

🏗️ Architecture: Should Platform Elements use Lit, vanilla Custom Elements, o...

Date: 2026-03-25
Time: 02:54:58 UTC
Session: gspace1-268.3
Agent: angular
Confidence: 92%
Status: ✅ Documented

📋 Decision Context

Question:

Should Platform Elements use Lit, vanilla Custom Elements, or a custom renderer for the production platform framework?

Task: S268: Platform Elements Framework — replace Angular browser compilation with Custom Elements runtime

🎯 Decision Made

Chosen:

Hybrid approach: Lit for complex reactive elements (table, form, crud), vanilla Custom Elements for simple static elements (empty state, status badge). Both patterns coexist, sharing the same PlatformElement base class for Lit elements and using raw HTMLElement for vanilla ones.

Options Considered:

Build custom renderer from scratch (spec's original approach)
Use Lit exclusively for all elements
Use Stencil.js (JSX-based, heavier runtime)
Use FAST Element (Microsoft, uncertain direction)
Keep improving Angular JIT/AOT browser compilation

💭 Reasoning

Root cause analysis: The existing Angular browser compilation pipeline (rspack WASM + JIT/AOT) accumulated 15+ bugs across sessions S224-S267, loads 33MB+ before rendering, and takes 6-10 seconds for preview. The fundamental issue is that Angular was never designed for in-browser compilation. Custom Elements eliminate compilation entirely — HTML IS the artifact. Lit was chosen over custom renderer because: (1) Lit's reactive property system handles DOM diffing, attribute observation, and template caching in 5KB — reimplementing this from scratch would take weeks and produce more bugs. (2) Lit is backed by Google Chrome team, used in YouTube/Chrome DevTools, actively maintained. (3) Light DOM mode works via single createRenderRoot() override. (4) Multi-level class inheritance (LitElement → PlatformElement → PlatformTable) proven to work. Vanilla Custom Elements are available for simple elements that don't need reactive rendering, proving there's no vendor lock-in. Bundle result: 19.5KB gzipped for 10 elements + 4 themes + responsive CSS — vs 33MB+ for the current pipeline.

📁 Files Involved

libs/libs-structural/platform-elements/src/lib/runtime/platform-element.ts
libs/libs-structural/platform-elements/src/lib/elements/platform-table.ts
libs/libs-structural/platform-elements/src/lib/elements/platform-empty.ts

🔗 Related

Decision ID: dev_1774407298716_4arxzlf
Session: 268
Workspace: gspace1

Auto-generated by MCP Smart Consolidation