refactor(chart): introduce hybrid domain architecture

docs/architecture.md

@@ -0,0 +1,36 @@
+# Architecture
+
+Waveform Analysis uses a hybrid architecture. Vue Composition API remains the orchestration
+boundary, while classes are reserved for domain objects with lifecycle or algorithm-selection
+invariants.
+
+## Boundaries
+
+- `useWaveformChartController` is the facade for the chart. It composes composables and exposes the
+  existing reactive controller surface; it owns no independent copy of component props.
+- `useWaveformViewport` keeps refs, computed values, pointer events, DOM capture, D3 coordinates,
+  and emitted events. `ViewportInteractionStateMachine` is its domain collaborator: it has no Vue
+  or DOM dependency and accepts only legal `begin`, `move`, `finish`, `cancel`, and `reset`
+  transitions. Its state is a `box`/`pan` discriminated union, with `null` representing idle.
+- `RenderablePointSelectionStrategy` defines the replaceable rendering algorithm boundary.
+  `CompletePointSelectionStrategy` preserves the complete visible source range and
+  `PeakPreservingPointSelectionStrategy` preserves first/minimum/maximum/last points per bucket.
+  `resolveRenderablePointSelectionStrategy` resolves and reuses the strategy from rendering options. The
+  existing `selectRenderablePoints` function remains the compatibility facade used by rendering.
+- `normalizeWaveformData` and `normalizeWaveformSeries` are functional adapters from public data
+  shapes to the internal series model. `buildTrackLayouts` remains a functional builder because
+  layout construction is a stateless calculation, not a long-lived object.
+
+## Vue Integration
+
+The state-machine instance is stored in `shallowRef(markRaw(...))`. Vue receives defensive state
+snapshots through a shallow ref, while SVG overlay elements remain in the composable as DOM
+resources. Presentation mode, annotation editing, scales, domains, ticks, formatting, and other
+stateless calculations stay in their existing computed/composable or function boundaries.
+
+## Constraints
+
+Do not create classes solely to wrap Composition API refs, props, lifecycle hooks, D3 selections, or
+pure mathematical helpers. Do not add inheritance trees, global event buses, service locators, or
+duplicate prop state. A new class must own a real invariant or replaceable algorithm and must be
+used by a production path with isolated tests.