[Research] Shadow DOM vs Light DOM Strategy

Research Objective

Determine optimal Shadow DOM strategy for Web Components migration.

Current State

• Svelte components use scoped styles
• Bulma CSS framework with global styles
• FontAwesome icons via global CSS
• Theme switching with CSS custom properties

Research Questions

1. Should we use Shadow DOM or Light DOM for each component type?
2. How to handle global Bulma styles in Shadow DOM?
3. What are the performance implications?
4. How does Shadow DOM affect third-party library integration?

Decision Matrix

Shadow DOM (Encapsulated)

Use For:

• Leaf components (buttons, inputs, chips)
• Self-contained widgets (theme switcher, shortcuts)
• Components with unique styling

Pros:

• Style isolation prevents conflicts
• True component encapsulation
• Can distribute as standalone

Cons:

• Need to import styles into each component
• Global CSS (Bulma, FontAwesome) not accessible
• More complex style inheritance
• Event delegation complexity

Light DOM (Open)

Use For:

• Layout components (app shell, navigation)
• Components requiring global Bulma classes
• Components integrating third-party libs (D3, TipTap)

Pros:

• Access to global styles
• Simpler third-party integration
• Standard event bubbling
• Easier debugging

Cons:

• Style conflicts possible
• Less encapsulation
• Cannot distribute independently

Components Classification Needed

Likely Shadow DOM:

• <terraphim-term-chip>
• <terraphim-back-button>
• <terraphim-theme-switcher>

Likely Light DOM:

• <terraphim-app> (shell)
• <terraphim-editor> (TipTap)
• <terraphim-rolegraph> (D3.js)

Needs Research:

• <terraphim-search> - uses Bulma Field/Input
• <terraphim-chat> - uses Bulma layout
• <terraphim-modal> - needs global positioning

Acceptance Criteria

• Component-by-component Shadow DOM decision
• Global CSS strategy documented
• Performance benchmark comparison
• Third-party library compatibility matrix
• Style inheritance pattern defined
• Event handling strategy documented

References

• Bulma usage: desktop/src/App.svelte
• Styled components: All .svelte files with <style> blocks

Documentation

Findings will be documented in: .docs/research-shadow-dom-strategy.md

Start with desktop/src/App.svelte and the .svelte files containing <style> blocks. Compare the listed Shadow DOM and Light DOM candidates against Bulma, FontAwesome, theme custom properties, TipTap, and D3 integration. Document component decisions, CSS and event strategies, benchmark results, and compatibility findings in .docs/research-shadow-dom-strategy.md.