fix(web): pause behavior + label overflow + back-edge corridor

[naorsabag]

Three independent fixes from a debug session over the order-flow demo. Each commit covers one concern; reviewable separately.

1. Pause freezes current step + carrots scale with zoom (f408bbc)

Pause regression — pause used to clear activeStep / activeEdgeIds / etc, so the visible step nuked itself; on resume the chain restarted from advanceStep and jumped to the next step.

Refactor useFlowAnimation:

• Track current phase ('pixel-active' or 'gap') + a timestamp
• On pause: cancel the timer, don't clear active state, capture elapsed in current phase
• On resume: re-enter the same phase with the captured offset
• DataPixel's rAF now keeps ticking while paused (re-anchoring startTimeRef so elapsed stays constant) so zoom changes still apply

Zoom drift — the rAF was regex-parsing viewport.style.transform; some transform formats didn't match and scale fell back to 1 → carrot stayed at base size and drifted off the path on zoom. Replaced with useViewport() from @xyflow/react.

Subtle bugs cleaned up along the way:

• startTimeRef initialized on the first tick regardless of pause state — without this, a manual click-to-fire pixel that started while paused saw startTimeRef = 0, computed elapsed = timestamp (huge), and the carrot snapped to the destination node
• Manual click-to-fire pixels no longer receive paused — pause is for autoplay only

2. Node labels render outside their parent flex bound (b23c5fc)

The label <span> was a flex column child inside a wrapper that auto-sized to the 108px building, so the span was pinned to 108px regardless of maxWidth. Long labels overlapped neighbors.

• Wrap label in a 48px-tall full-width slot (so the progress bar below keeps its position)
• Absolute-position the label inside, left: 50% / translateX(-50%) — escapes the flex parent's cross-size constraint, label sizes to its content
• Cap at --openhop-label-max-width (default 200px, live-tweakable from DevTools), clamp to 2 lines + ellipsis past that
• pointer-events: none on the absolute label so it doesn't intercept clicks meant for an adjacent node when it overlaps

Skill update: agents are told to keep label ≤ 4 words (matches the 2-line × 2-words clamp).

3. Back-edges no longer shadow forward roads (d77837e)

Adds four elk.spacing options so ELK pulls edge corridors apart. Symptom: orion flow's results → api back-edge was routing at x=774, parallel to api → jenkins at x=864 — looked like two roads between the same pair, only one actually animating. With the bumped spacing, the back-edge now routes under the layout via the far-left margin.

Verification

• npm run typecheck — clean
• npm run lint — 0 errors, 18 warnings (no net change from master)
• npm test — 40/40 pass

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features

  • Phase-aware animation pause/resume so autoplay preserves progress and resumes smoothly; completion callbacks now fire only when animations truly finish.

• UI/UX Improvements

  • Node labels now support multi-line display with smart truncation and avoid intercepting clicks.
  • Autoplay overlay now respects the playing state.

• Layout

  • Increased spacing between edges and nodes to reduce visual overlap.

• Documentation

  • Clarified node label length constraint (≤4 words).

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 8118a402-2ac2-4606-80cd-7fbcffed536c

📥 Commits

Reviewing files that changed from the base of the PR and between d77837e and 345c35e.

📒 Files selected for processing (3)

• packages/web/src/components/nodes/FlowNode.tsx
• packages/web/src/hooks/useFlowAnimation.ts
• skills/openhop/SKILL.md

🚧 Files skipped from review as they are similar to previous changes (1)

• packages/web/src/hooks/useFlowAnimation.ts

---

Walkthrough

This PR adds pause/resume support with phase-aware timing, switches DataPixel to use the live React Flow viewport for per-frame positioning, ties autoplay pixels to the global playing state, updates node label rendering to a 2-line clamped slot, and increases ELK layout spacing; docs enforce label length limits.

Changes

Pause/Resume Animation Flow

Layer / File(s)	Summary
Pause Prop Interface Contract packages/web/src/components/DataPixel.tsx	DataPixelProps adds optional paused?: boolean; DataPixel destructures paused = false.
React Flow Viewport Synchronization packages/web/src/components/DataPixel.tsx	Imports useViewport; stores live viewport in a ref; per-frame tick reads x,y,zoom from store instead of parsing DOM transforms; adds last-tick timing refs.
Per-Frame Pause Timing Logic packages/web/src/components/DataPixel.tsx	Tick logic initializes/advances startTimeRef; when paused shifts startTimeRef by paused duration to freeze elapsed time while still updating position/scale; onAnimationComplete fires only when finished and not paused.
Flow Canvas Animation Control packages/web/src/components/FlowCanvas.tsx	FlowCanvas passes paused={!playing} to autoplay DataPixel overlay; manual click-to-fire pixels remain always animating (comment updated).
Phase-Aware Ref Structure packages/web/src/hooks/useFlowAnimation.ts	Adds refs to track current phase (pixel-active/gap), phase start timestamp, phase offset for pause/resume, and a stable advanceStepRef.
Phase Entry & Timer Callback packages/web/src/hooks/useFlowAnimation.ts	Adds enterPhase and updates advanceStep wiring so phases schedule timers using performance.now() and offset; clears highlights at end of pixel-active and advances after gap.
Phase-Aware Pause/Resume Logic packages/web/src/hooks/useFlowAnimation.ts	Replaces nested timeouts with phase-aware pause/resume: on pause capture elapsed offset without clearing active highlights; on resume re-enter phase with remaining time; fresh start delays then advances.

UI Label and Layout Refinements

Layer / File(s)	Summary
Node Label Rendering with Clipping packages/web/src/components/nodes/FlowNode.tsx	Adds title={label} and replaces single-line span with a fixed-height label slot and absolutely centered span that clamps to 2 lines, ellipsizes, constrains width via --openhop-label-max-width, and disables pointer events on label elements.
ELK Layout Spacing Configuration packages/web/src/lib/flow-layout.ts	buildElkGraph adds ELK spacing options (elk.spacing.edgeEdge, elk.spacing.edgeNode, elk.layered.spacing.edgeEdgeBetweenLayers, elk.layered.spacing.edgeNodeBetweenLayers) to separate back-edge corridors from forward edges.
Schema Validation Rule skills/openhop/SKILL.md	Adds validation rule: node label must be ≤ 4 words and documents truncation behavior.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Possibly related PRs

• naorsabag/OpenHop#60: Both PRs touch DataPixel.tsx and FlowCanvas.tsx.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 20.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely summarizes the three main fixes in the changeset: pause behavior improvements, label overflow handling, and back-edge corridor spacing.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/animation-pause-and-label-overflow

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 2

🧹 Nitpick comments (1)

packages/web/src/hooks/useFlowAnimation.ts (1)

200-230: 💤 Low value

The enterPhase callback with empty deps creates a stale closure over advanceStep.

enterPhase has [] deps but calls advanceStep (line 226), which has [steps.length] deps. If steps changes mid-playback, enterPhase will invoke a stale advanceStep reference. The eslint-disable acknowledges this, and it's acceptable if steps are immutable during playback, but worth documenting.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@packages/web/src/hooks/useFlowAnimation.ts` around lines 200 - 230,
enterPhase currently has an empty dependency array and therefore closes over a
possibly-stale advanceStep; either add advanceStep to enterPhase's dependency
array (i.e., useCallback(..., [advanceStep])) and remove the eslint-disable, or
store advanceStep in a stable ref (advanceStepRef.current = advanceStep) and
call advanceStepRef.current() from inside enterPhase; update references to
enterPhase, advanceStep and phaseRef accordingly so the callback always calls
the current advanceStep implementation.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@packages/web/src/components/nodes/FlowNode.tsx`:
- Around line 242-247: The span that renders the clamped label in the FlowNode
component has title={label} but pointerEvents: 'none' prevents the browser
tooltip from appearing; move the title attribute off the inner span and onto the
outer clickable node container (the element wrapping the node in the FlowNode
render that handles clicks/hover) and remove title from the span so the tooltip
works while preserving pointerEvents: 'none' on the clamped label element.

In `@skills/openhop/SKILL.md`:
- Line 87: The Node.label guidance is inconsistent: keep the Later "Node.label"
schema text in SKILL.md aligned with the earlier rule by updating the freeform
sentence (the paragraph describing Node.label) to state the validation rule
“Node label must be ≤ 4 words” and clarify that labels should be short noun
phrases; update any sentence that currently says “freeform, anything
human-readable” to instead reference the validation constraint and give the same
examples/format as the earlier rule (e.g., “Order Service”, “Auth API”, not long
descriptive names) so the Node.label schema and the rule are consistent.

---

Nitpick comments:
In `@packages/web/src/hooks/useFlowAnimation.ts`:
- Around line 200-230: enterPhase currently has an empty dependency array and
therefore closes over a possibly-stale advanceStep; either add advanceStep to
enterPhase's dependency array (i.e., useCallback(..., [advanceStep])) and remove
the eslint-disable, or store advanceStep in a stable ref (advanceStepRef.current
= advanceStep) and call advanceStepRef.current() from inside enterPhase; update
references to enterPhase, advanceStep and phaseRef accordingly so the callback
always calls the current advanceStep implementation.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: faed6dd8-b4b7-40f2-819f-7dd3abda4c41

📥 Commits

Reviewing files that changed from the base of the PR and between b448a85 and d77837e.

📒 Files selected for processing (6)

• packages/web/src/components/DataPixel.tsx
• packages/web/src/components/FlowCanvas.tsx
• packages/web/src/components/nodes/FlowNode.tsx
• packages/web/src/hooks/useFlowAnimation.ts
• packages/web/src/lib/flow-layout.ts
• skills/openhop/SKILL.md