Performance and Microinteraction Architecture

Performance & Microinteraction Architecture

Engineering Principle: Responsiveness is not a cosmetic enhancement; it is a fundamental architectural requirement. An ~80,800-line monolithic application must feel instantaneous, stable, and completely free of visual flicker at 60 FPS.

---

⚡ 1. Microinteraction Stability & Zero-Flicker Design

Data-dense governance applications typically suffer from microinteraction instability: layout jumps, scrollbar oscillation, and boundary clipping. ProjectPulse implements strict mechanical rules to guarantee stable hit-testing.

flowchart LR
    subgraph Antipatterns["❌ Fragile Antipatterns"]
        A1["Aggressive transform: scale(1.15)"]
        A2["Dynamic border-radius on :hover"]
        A3["Unbounded position: absolute tooltips"]
        A4["Raw unthrottled mousemove events"]
    end

    subgraph Solutions["✅ ProjectPulse Invariants"]
        B1["Subtle translateY(-1px) elevation"]
        B2["Static border bounds + Inset box-shadow"]
        B3["Viewport-clamped position: fixed tooltips"]
        B4["requestAnimationFrame decoupled tracking"]
    end

    Antipatterns -->|"refactored to"| Solutions

Loading

The Inset Box-Shadow Invariant

In dense table grids and scheduling matrices (e.g., .matrix-cell, .heatmap-cell, .sc-cell):

• The Problem with Dynamic border-radius: Applying border-radius: 4px dynamically on :hover inside a border-collapse: collapse table invalidates shared cell borders. When the cursor lands near a border, the rounding shifts cell ownership back and forth, producing an infinite hover flicker loop.
• The ProjectPulse Solution: Cells maintain square layout bounds. Hover focus is rendered via box-shadow: inset 0 0 0 2px var(--color-primary), var(--shadow-sm) !important;. Because inset box shadows draw strictly inside the cell's allocated bounding box, neighbor borders are never invalidated, guaranteeing zero-jitter hover feedback.

---

🎯 2. Viewport-Clamped Tooltip Architecture

Tooltips in ProjectPulse (such as #matrix-tooltip and #sl-tooltip) use a specialized viewport clamping algorithm to eliminate document scrollbar thrashing.

flowchart TD
    CursorMove["Mouse Move Event (clientX, clientY)"] --> RAF{"rAF Frame Queued?"}
    RAF -->|"Yes"| Skip["Skip (Throttle to Display Refresh)"]
    RAF -->|"No"| ClampCalc["_posMatrixTip Calculation"]
    
    ClampCalc --> CheckX{"clientX + 280px > innerWidth - 12px?"}
    CheckX -->|"Yes (Near Right Edge)"| FlipX["Flip to Left: clientX - 292px"]
    CheckX -->|"No"| RightX["Offset Right: clientX + 15px"]
    
    ClampCalc --> CheckY{"clientY + Height > innerHeight - 12px?"}
    CheckY -->|"Yes (Near Bottom)"| ShiftY["Clamp Up: innerHeight - Height - 12px"]
    CheckY -->|"No"| DownY["Offset Down: clientY + 15px"]
    
    FlipX --> Render["Render with position: fixed"]
    RightX --> Render
    ShiftY --> Render
    DownY --> Render

Loading

Eliminating the Infinite Scrollbar Loop

• Previous Failure Mode: A tooltip positioned via position: absolute with pageX + 15px exceeds the document width when hovering columns near the right edge. The browser spawns a horizontal scrollbar, which reduces the viewport by ~15px. This shifts the table away from the cursor, firing mouseleave and removing the scrollbar, which immediately shifts the table back under the cursor and fires mouseenter again.
• Current Implementation:
  1. Positioned strictly as position: fixed; pointer-events: none;.
  2. Clamped using window.innerWidth and window.innerHeight.
  3. Decoupled from raw input events using requestAnimationFrame.
  4. Removes backdrop-filter: blur(...) during cursor motion to eliminate GPU texture re-allocation stutter on Chromium and WebKit.

---

🎨 3. Hybrid SVG vs. Canvas Rendering Strategy

ProjectPulse matches rendering engines to the mathematical requirements of each component:

View Component	Rendering Engine	Architectural Rationale
Gantt Dependency Timeline	SVG (<svg>)	Vector scaling, crisp lines at any DPI, DOM event bubbling on individual dependency arcs, and declarative CSS styling.
Swimlane Timeline	HTML5 Canvas (<canvas>)	High-density drawing of hundreds of concurrent task bars across months with zero DOM node overhead.
Burnup / EVM Trajectories	HTML5 Canvas (<canvas>)	Fast path clearing, smooth Bézier curves, and sub-millisecond redraws during What-If simulation slider adjustments.
Module Strategic Matrix	Virtual DOM / Table	Semantic tabular structure, keyboard accessibility, screen-reader compliance, and CSS grid responsiveness.

---

📐 4. Intelligent 5-Strategy Column Autofit Engine

Data tables in ProjectPulse adapt dynamically across different screen dimensions using five automated column layout strategies:

1. clip_wrap: Standard layout wrapping text when space permits and clipping with ellipsis when constrained.
2. clip_nowrap: Strict single-line layout for numerical IDs, currency, and date stamps.
3. wrap_balance: Typographic balance algorithm ensuring headers and multi-word titles break evenly across lines.
4. fill_distribute: Expands primary task name columns to absorb remaining container width after fixed-width columns have been allocated.
5. natural_scroll: Enables horizontal kinetic scrolling when the cumulative minimum column widths exceed the viewport width, protecting sticky freeze columns.