[Research] Progressive Migration Strategy

Research Objective

Define strategy for gradually migrating from Svelte to Web Components without breaking functionality.

Current State

• 21 Svelte components in production
• Svelte stores for state management
• Tauri desktop integration
• Playwright E2E tests

Migration Challenges

1. Coexistence

How can Svelte and Web Components run side-by-side?

Options:

• Svelte can render Web Components (supported)
• Web Components can contain Svelte (complex)
• Feature flags to toggle implementations

2. State Sharing

How to share state between Svelte and Web Components during migration?

Options:

• Bridge layer using CustomEvents
• Shared global state manager
• Duplicate state temporarily

3. Testing

How to test hybrid Svelte + Web Components?

Options:

• Update Playwright tests component-by-component
• Add Web Component testing framework
• Maintain parallel test suites

4. Routing

How to handle routing during migration?

Options:

• Keep Tinro until all components migrated
• Introduce Web Components router early
• Hybrid routing strategy

Migration Patterns to Research

Pattern 1: Bottom-Up (Leaf-First)

1. Migrate leaf components first
2. Svelte parents render Web Component children
3. Gradually move up the tree
4. App shell migrated last

Pros: Incremental, low risk
Cons: Long coexistence period

Pattern 2: Top-Down (Shell-First)

1. Migrate app shell to Web Components
2. Web Components shell renders Svelte components
3. Replace Svelte components progressively

Pros: Clean architecture early
Cons: Complex shell migration

Pattern 3: Feature-by-Feature

1. Migrate entire feature areas at once
2. Search, Chat, Graph as separate migrations
3. Feature flags control which implementation loads

Pros: Clear boundaries
Cons: Duplicate code maintenance

Pattern 4: Parallel Implementation

1. Build Web Components alongside Svelte
2. A/B test in production
3. Switch over when ready

Pros: Safest, allows comparison
Cons: Most effort, code duplication

Rollback Strategy

• How to revert individual component migrations?
• Preserve git history for easy rollback
• Feature flags for instant toggle
• Monitoring for regressions

Acceptance Criteria

• Migration pattern selected
• Step-by-step migration plan
• State sharing bridge designed
• Test strategy defined
• Rollback procedure documented
• Feature flag system designed
• Timeline with milestones

References

• Component hierarchy: desktop/src/App.svelte
• Store usage patterns: desktop/src/lib/stores.ts

Documentation

Findings will be documented in: .docs/research-progressive-migration.md

Read desktop/src/App.svelte and desktop/src/lib/stores.ts first, then compare the four migration patterns against the existing Playwright E2E setup and Tauri integration. Done means .docs/research-progressive-migration.md records a selected pattern, state-sharing and testing approach, rollback and feature-flag procedures, and milestones.