Prototype incremental rendering

[SorraTheOrc]

Intake Draft — Prototype incremental rendering (WL-0MNAL79K20048STX)

Headline
Prototype incremental rendering to update only visible nodes on expand/collapse and scroll to reduce TUI latency and avoid full lockups.

Problem statement
The TUI currently shows measurable lag and occasional full lockups when users expand/collapse nodes and when scrolling the work‑item tree. This prototype will implement incremental rendering to compute and update only visible nodes during expand/collapse and scroll events to reduce UI latency and avoid event‑loop blocking.

Users

• Developers who interact with the terminal UI (TUI) for daily workflow.
• Product managers and producers who browse and triage work items in the TUI.

User stories

• As a developer, when I expand or collapse a node in the TUI, the visible tree updates immediately without blocking input.
• As a PM browsing items, scrolling the list should remain responsive, even with a few dozen items in the tree.

Success criteria

• Automated benchmark (30‑item tree) shows median interaction latency under 200 ms for expand/collapse and scroll actions.
• Manual smoke tests show no full lock‑up during typical expand/collapse/scroll scenarios.
• Prototype runs with instrumentation enabled and emits timing logs compatible with the existing perf tooling.
• Changes are covered by regression tests exercising expand/collapse and scroll interactions. Include at least one automated test that reproduces the 30-item benchmark scenario.

Constraints

• Keep changes confined to TUI rendering/layout code (preferably within src/tui/layout.ts and src/tui/controller.ts).
• Prefer minimal API surface changes; avoid large refactors unless necessary.

Risks & assumptions

• Risk: Refactor may introduce UI regressions. Mitigation: add regression tests and smoke tests; keep changes behind a feature flag if needed.
• Risk: Prototype may drift into full virtualization scope (scope creep). Mitigation: record virtualization work as a separate follow-up work item (WL-0MNAZFD1H004IKKN) and keep this prototype limited to incremental updates for visible nodes and scroll handling.
• Assumption: Existing perf instrumentation and benchmark harness will be available and usable for validation. If not available, the prototype must include minimal timings to make comparisons possible.

Existing state

• Current TUI implementation performs a full layout recompute when nodes are expanded/collapsed, leading to event‑loop blocking in some cases.
• Related artifacts: src/tui/layout.ts, src/tui/controller.ts, and existing perf instrumentation child item WL-0MNAL4SSQ003DFU2.

Desired change

• Implement an incremental layout renderer that computes and updates only visible nodes on expand/collapse and on scroll.
• Wire the prototype into the existing perf instrumentation and logging so results are reproducible and comparable.
• Add targeted unit and integration tests to validate behaviour and prevent regressions.

Related work

• WL-0MNAGHQ33005BVY6 — Slow down investigation (parent epic). Brief: Investigation into TUI freezes on expand/collapse. (parent of this item)
• WL-0MNAL4SSQ003DFU2 — Add performance instrumentation (recommended dependency). Brief: Timing/logging for expand/collapse. (see: instrumentation child created in parent epic)
• WL-0MNAL6OXK0072IGQ — Create benchmark harness (recommended dependency). Brief: Harness for automated latency measurement.
• WL-0MNAZFD1H004IKKN — Full virtualization of work‑item tree (future work / larger scope).

Potentially related files

• src/tui/layout.ts — current layout & rendering helpers.
• src/tui/controller.ts — input handling and event wiring that triggers layout recompute.

Related work (automated report)

• WL-0MNAGHQ33005BVY6 — Slow down investigation (parent epic). Relevance: this prototype is a child of the investigation epic and captures focused work to reduce expand/collapse and scroll latency.
• WL-0MNAL4SSQ003DFU2 — Add performance instrumentation. Relevance: provides existing timing/logging hooks (including a --perf flag) that the prototype should reuse to emit reproducible metrics.
• WL-0MNAL6OXK0072IGQ — Create benchmark harness. Relevance: the harness will be used to run the 30-item benchmark and compare median latencies before/after the change.
• WL-0MNAZFD1H004IKKN — Full virtualization of work‑item tree. Relevance: a larger follow-up option if incremental rendering is insufficient; record as separate work item to avoid scope creep.
• src/tui/layout.ts — Relevance: primary file for implementing incremental layout and visible-node calculation.
• src/tui/controller.ts — Relevance: where expand/collapse and scroll events are handled and where perf hooks currently write metrics.

Appendix: Clarifying questions & answers

• Q: "Should 'Prototype incremental rendering' depend on the performance instrumentation (WL-0MNAL4SSQ003DFU2) and benchmark harness (WL-0MNAL6OXK0072IGQ)?" — Answer (user): "Yes (Recommended)". Source: interactive reply. Final: yes.
• Q: "Should the prototype focus only on expand/collapse (visible node updates) or also include scroll and other layout triggers?" — Answer (user): "Include scrolling". Source: interactive reply. Final: include scroll.

[SorraTheOrc]

effort_and_risk_skill

Effort and Risk Report

Effort | Medium | 18.67h
Risk | Low | 4/20
Confidence | 71% | unknowns: Whether full virtualization is required after the prototype; Terminal-specific rendering variance

{
  "effort": {
    "unit": "hours",
    "tshirt": "Medium",
    "o": 8.0,
    "m": 16.0,
    "p": 40.0,
    "expected": 18.67,
    "recommended": 30.67,
    "range": [
      20.0,
      52.0
    ]
  },
  "risk": {
    "probability": 2.12,
    "impact": 2.12,
    "score": 4,
    "level": "Low",
    "top_drivers": [],
    "mitigations": [
      "Add targeted tests and integration checks",
      "Lock dependencies and add compatibility tests",
      "Schedule extra review for risky components"
    ]
  },
  "confidence_percent": 71,
  "assumptions": [
    "Benchmarks and instrumentation are available (WL-0MNAL4SSQ003DFU2, WL-0MNAL6OXK0072IGQ)",
    "Changes limited to TUI layout/controller code"
  ],
  "unknowns": [
    "Whether full virtualization is required after the prototype",
    "Terminal-specific rendering variance"
  ]
}