Roadmap item 2.1.2 introduces context-loss fallback and retry behaviour.
Roadmap item 2.2.1 adds WebGL allocation and fallback metrics. Follow these
rules when changing context-loss handling and renderer instrumentation:
- Keep context-loss handling in
lib/components/term.tsxwired throughonWebGLContextLoss. - On context-loss or pool-eviction events, immediately detach the WebGL addon and attach Canvas.
- Keep retry behaviour bounded via existing failure controls:
webglFailureCount,webglLastFailureAt,webglCooldownMs,webglFailureThreshold, andwebglFailureDecayMs. - Keep deterministic retry scheduling in
scheduleDeterministicRendererRetry()and preserve timer cleanup incomponentWillUnmount()to avoid leaked retries. - Keep retry entry through visibility/pool coordination
(
syncRendererForVisibilityandgetWebGLContextPool(...)) so retries occur only when pane visibility and pool capacity allow a safe WebGL reattach. - Keep fallback instrumentation observable through:
console.warn('WebGL context lost. Falling back to canvas-based rendering.')and renderer mode events fromTerm.reportRenderer(...)(info renderer, with optionalreasonvalues such ascontext-loss,pool-evicted, andwebgl-init-failed), which feed renderer summaries in the About dialog. - Keep allocation metrics aligned with renderer telemetry from
Term.reportRenderer(...)and main-process aggregation inapp/utils/renderer-utils.ts: - Current WebGL context count (
current) tracks active WebGL renderer assignments. - Peak WebGL context count (
peak) tracks the highest observedcurrentvalue during the process lifetime. - Keep diagnostics visibility in the About dialog detail output by including:
WebGL contexts: current <n>, peak <n>Renderer fallbacks: total <n>; reasons: ...- When tuning context-loss retry thresholds or fallback behaviour, update
docs/roadmap.md, this guide, and the related renderer/pool unit tests in the same change to avoid docs/runtime drift. - When adding or renaming fallback reasons or allocation metric fields, update
this guide,
docs/roadmap.md, and diagnostics tests in the same change.