37 lines
2.2 KiB
Markdown
37 lines
2.2 KiB
Markdown
|
# 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.
|