# Phase 8 Execution Plan: React + ELK Core Refactor

## Objective
Deliver the largest Schemeta refactor to date: migrate the frontend to a robust React architecture, replace fragile placement behavior with ELK-driven layout, harden routing/labeling readability, and establish production-grade quality gates.

This phase is OSS-only and budget-neutral.

## Non-Goals
- No paid/proprietary graph SDKs.
- No API contract break for `/compile`, `/analyze`, `/layout/auto`, `/layout/tidy`.
- No regression of current JSON schema compatibility.

## Architecture Target
- Frontend: React + TypeScript + Vite.
- Interaction layer: React Flow primitives for node/selection/viewport interactions.
- Layout: `elkjs` as primary placement engine.
- Routing: Schemeta incremental router with deterministic tie-net fallback.
- State: deterministic centralized action pipeline (undo/redo transaction model).

## Work Breakdown (Milestone #7)
- #37 P8-01 Frontend architecture migration to React + TS + Vite
- #38 P8-02 State model refactor with deterministic action pipeline
- #39 P8-03 Canvas subsystem rewrite with React Flow contracts
- #40 P8-04 ELK integration and constraints mapping
- #41 P8-05 Routing engine revamp (incremental reroute)
- #42 P8-06 Deterministic label placement and collision avoidance
- #43 P8-07 Symbol readability and pin-density standards
- #44 P8-08 JSON editor power-tool upgrade (schema-aware + diff apply)
- #45 P8-09 QA hardening (visual/readability gates)
- #46 P8-10 Cutover, migration, rollback

## Delivery Sequence (Critical Path)
1. Foundation
   - Complete #37 (React app shell) and #38 (state architecture).
   - Exit criteria: feature-parity shell + deterministic action store.
2. Interaction rewrite
   - Complete #39 on top of #37/#38.
   - Exit criteria: drag/multi-select/pan/zoom/edit stable and undoable.
3. Layout core
   - Complete #40 with adapter boundaries for constraints.
   - Exit criteria: ELK-based autolayout deterministic on fixtures.
4. Routing core
   - Complete #41 with local reroute and deterministic fallback behavior.
   - Exit criteria: moved components reroute only affected nets.
5. Readability system
   - Complete #42 + #43 for labels/pin-density constraints.
   - Exit criteria: baseline fixtures have no label/pin overlap failures.
6. Power-user JSON workflow
   - Complete #44 for schema-aware editing and safe apply previews.
7. Quality gates + ship safety
   - Complete #45 + #46; run cutover checklist.

## Technical Design Rules
- Determinism first: all ordered traversals sort by stable keys.
- Incremental operations default: no full relayout on drag/edit unless explicit.
- Readability constraints are hard constraints, not best-effort hints.
- Feature flags for risky changes during dual-run period.

## Quality Gates (Phase 8 Additions)
In addition to existing crossings/overlaps/detour metrics:
- Label collisions must be 0 in baseline fixtures.
- Pin text collisions must be 0 in baseline fixtures.
- Component overlap must remain 0.
- Drag action must not move untouched components.
- Snapshot test matrix across viewport sizes and render modes.

## Risks and Mitigation
- Risk: React migration stalls on parity gaps.
  - Mitigation: keep legacy UI in dual-run until parity checklist passes.
- Risk: ELK mapping mismatch with custom constraints.
  - Mitigation: fallback mapping with explicit unsupported-constraint diagnostics.
- Risk: routing regressions after layout changes.
  - Mitigation: incremental router tests and stress fixtures in CI.
- Risk: test flakiness due to persisted state.
  - Mitigation: force deterministic test bootstrapping and storage resets.

## Performance Budgets
- Compile latency p95 (sample): <= 180ms local.
- Drag-to-reroute p95 (affected nets only): <= 120ms local.
- Auto layout p95 (medium fixture): <= 600ms local.

## Release Readiness Checklist
- All milestone issues closed.
- CI green for unit + UI + readability metrics.
- Dual-run comparison report attached.
- Rollback validated with documented steps.
- Release notes include migration caveats and known limitations.

## Definition of Done
Phase 8 is done only when:
- React UI is default and legacy path can be disabled safely.
- ELK placement is primary in production path.
- Readability gates are enforced in CI.
- Drag/edit interactions are deterministic and locally incremental.
- JSON/AI workflows are schema-aware and operator-safe.