InteractionScope
Under frame pressure, background particle fields and ambient animations compete with active touch gestures and drags. InteractionScope prioritizes the user's active viewport region, shedding non-essential background tasks first so active manipulation remains locked at display refresh rate.
The InteractionScope component establishes a spatial execution lease across the FrameConductor. When a user interacts with a scoped region (via touch or pointer press), all frame subscribers rendered within that subtree inherit the active lease automatically.
When the conductor experiences frame budget pressure, non-essential work outside the active scope yields earlier, preserving spare frame time for the direct manipulation interaction. On healthy frames running within budget, execution order is untouched.
The component manages three activation modes: "pointer" (uncontrolled DOM capture listener that activates while a pointer is pressed inside), true (controlled programmatic lease for keyboard-driven cameras or open modal dialogs), and false (disabled).
◆Interaction Priority & Background Work Shedding
Quick start
Wrap any interactive component or canvas in an InteractionScope. Child useTick callbacks inherit scope priority automatically.
Pointer press detection uses native DOM capture-phase listeners, functioning reliably even when child components call stopPropagation().
Priority Bands & Shedding Thresholds
How the FrameConductor adjusts subscriber execution order and shedding thresholds when a scope is active.
| Priority Band | Default Threshold | Outside Active Lease | Execution Behavior |
|---|---|---|---|
| "essential" | Never shed | Never shed | Direct input listeners, core gestures, and physics state integration. |
| "enhanced" | 0.70 budget | 0.45 budget | Secondary transforms and interactive hover effects. |
| "decorative" | 0.45 budget | 0.20 budget | Ambient floating particles, blur passes, and background meshes. |
Native pointer down listeners attach in the capture phase. This guarantees activation occurs before child drag libraries intercept or stop event propagation. Drag completion is monitored on the global window, ensuring release triggers correctly even if the cursor leaves the element bounding box mid-drag.
API Reference
Syntax
Establishes a scoped region for interaction priority across all child useTick subscribers.
Parameters
| Parameters.field | Type | Default | Description |
|---|---|---|---|
| label | string | undefined | Human-readable label displayed in DevTools inspectors and performance telemetry. |
| active | "pointer" | boolean | "pointer" | "pointer" activates automatically on pointerdown; true holds active continuously; false disables. |
| asChild | boolean | false | Clones the single child element and attaches event listeners directly without rendering a wrapper div. |
| className | string | undefined | CSS class names applied to the container element when asChild is false. |
| style | CSSProperties | undefined | Inline styles applied to the container element when asChild is false. |
useInteractionScope()
| useInteractionScope().field | Return Value | Type | Description |
|---|---|---|---|
| scopeId | string | null | Opaque ID of the nearest enclosing InteractionScope, or null outside providers. |
useTick(lane, fn, options?)
| useTick(lane, fn, options?).field | Type | Default | Description |
|---|---|---|---|
| priority | "essential" | "enhanced" | "decorative" | "enhanced" | Shed order under frame pressure. |
| hz | number | Display rate | Maximum execution cadence in Hertz. Unexecuted dt is preserved. |
| label | string | "anonymous" | Diagnostic label for DevTools. |
| background | boolean | false | When true, opts out of surrounding scope protection to yield with ambient work. |
| enabled | boolean | true | Conditionally attach or detach the subscription. |
Scope Lifecycle & Subscription Management
InteractionScope automatically detaches DOM listeners and releases conductor claims on component unmount.
Lifecycle & Invariant Guarantees
- →Zero impact on healthy frames: On pages operating within the display frame budget, InteractionScope introduces zero execution delay or priority alterations.
- →Capture-phase reliability: Pointer listeners attach on the DOM capture phase, guaranteeing activation even when child gestures call stopPropagation.
- →Multi-touch tracking: Pointers are tracked by pointerId, ensuring active priority is retained until the final active finger lifts from the surface.
- →Automatic child inheritance: All useTick calls rendered within the subtree join the scope automatically without requiring manual property passing.
◆Production Examples
Battle-tested production patterns ready to copy directly into your codebase.
Protect gallery swipe gestures while allowing ambient background animations to yield under load.
When NOT to use this
Rules & Gotchas
- →Render interactive subscribers within the provider: Frame subscribers rendered inside InteractionScope inherit its protection automatically without manual prop wiring.
- →Prioritize direct manipulation gestures: Keep physical drag handlers essential, allowing decorative secondary effects to remain enhanced or decorative so they can yield.
- →Release imperative claims immediately on gesture completion: When manually managing active claims with getConductor().claimScope(), ensure release() is called as soon as interaction finishes.
- →Use asChild to preserve layout integrity: Pass asChild when wrapping items in CSS grid or flex containers to avoid introducing unnecessary wrapper div elements.