[0.2.0] Interaction quality and direct-manipulation foundation

[mberrys]

Problem

Loupe needs an explicit interaction-quality architecture so pointer movement, selection, pan, zoom, and direct manipulation remain responsive even while PDF parsing, rendering, preflight, OCR, AI, and file I/O are active. This is a cross-cutting product-quality initiative, not a duplicate of the closed historical performance records #105 and #115.

The target is predictable latency and frame pacing:

Interaction	Target
Pointer hover / selection feedback	next rendered frame
Drag / resize preview	display-refresh paced; no document-engine wait
Pan / zoom	continuous; no blocking
Page switch acknowledgement	<50 ms perceived
Expensive analysis	asynchronous and progressively surfaced

Child issues

• #140 Instrument input-to-frame latency and frame pacing
• #141 Decouple transient InteractionState from persistent PDF state
• #142 Add cached and progressive page rendering for pan and zoom
• #143 Render selections, guides, and preflight markers as independent overlays
• #144 Enforce async boundaries for preflight, OCR, AI, and file I/O
• #145 Add spatial-index hit testing and precise drag/zoom semantics
• #146 Automate interaction-performance regression traces

Scope

The child issues cover:

1. Interaction latency and frame instrumentation.
2. Transient InteractionState decoupled from persistent PDF state.
3. Cached/progressive page rendering for pan and zoom.
4. Overlay rendering for selections, guides, and preflight markers.
5. Strict async/UI-thread boundaries for preflight, OCR, AI, and file I/O.
6. Spatial-index hit testing and precise drag/zoom semantics.
7. Automated interaction-performance regression tests.

Acceptance criteria

• Every child issue has an implementation contract, acceptance criteria, dependencies, and test strategy.
• Pointer movement never requires a persistent PDF mutation or synchronous expensive analysis.
• Cached page content, transient interaction state, overlays, async jobs, and document commits have explicit revision/ownership boundaries.
• Representative traces cover hover, selection, drag, pan, zoom, page switch, and analysis running in the background.
• Performance results distinguish verified measurements from infrastructure-blocked or unavailable GPU/desktop runs.
• Any implementation that touches existing preflight finding navigation or partial-page rendering remains compatible with Add finding-to-canvas navigation and page/object overlays in the Editor #89 and [Deferred] Generalize partial-page render after second consumer #54; neither closed historical issue [Deferred epic] Performance infrastructure — measure first #105 nor [P2] Performance validation: zoom + automation diagnostic tests #115 is reopened or duplicated.

Dependencies

• [Interaction quality] Instrument input-to-frame latency and frame pacing #140 is the measurement foundation.
• [0.2.0] Decouple transient InteractionState from persistent PDF state #141 defines transient state and commit boundaries.
• [Interaction quality] Add cached and progressive page rendering for pan and zoom #142 and [Interaction quality] Render selections, guides, and preflight markers as independent overlays #143 build the page/overlay presentation path.
• [0.2.0] Enforce async boundaries for preflight, OCR, AI, and file I/O #144 protects the interactive thread and revision safety.
• [0.2.0] Add spatial-index hit testing and precise drag/zoom semantics #145 defines hit-test and direct-manipulation semantics.
• [0.2.0] Automate interaction-performance regression traces #146 depends on the preceding contracts and verifies them end to end.
• Coordinate with [Deferred] Generalize partial-page render after second consumer #54 and Add finding-to-canvas navigation and page/object overlays in the Editor #89 without absorbing their separate historical/deferred scopes.

Pseudocode

```cpp
void Canvas::onPointerMove(Point screenPoint) {
interaction.pointer = screenPoint;
interaction.hovered = spatialIndex.hitTest(viewport.toDocument(screenPoint));
if (interaction.drag.active)
interaction.preview = dragController.preview(screenPoint);
frameScheduler.request();
}

void Canvas::onPointerUp(Point screenPoint) {
if (interaction.drag.active)
documentQueue.submit(makeSemanticOperation(interaction.drag, screenPoint));
interaction.drag.reset();
}
```