pi-config/extensions/pi-crew/skills/ui-render-performance/SKILL.md

name, description

name	description
ui-render-performance	Non-blocking Pi TUI render workflow. Use when changing widgets, powerbar/statusbar segments, dashboard panes, overlays, snapshot caches, or live UI refresh behavior.

ui-render-performance

Use this skill for Pi/pi-crew TUI work.

Source patterns distilled

• Pi TUI is synchronous immediate-mode/string rendering: source/pi-mono/packages/coding-agent/src/modes/interactive/interactive-mode.ts
• Pi extension examples use event-driven state updates, not render-time loading.
• pi-crew UI: src/extension/register.ts, src/ui/run-dashboard.ts, src/ui/run-snapshot-cache.ts, src/ui/crew-widget.ts, src/ui/powerbar-publisher.ts, src/ui/render-scheduler.ts

Rules

• Treat every render(width) and widget/powerbar update as a hot synchronous path.
• Render from in-memory snapshots only. Preload config, manifests, snapshots, agents, and mailbox counts asynchronously.
• Use RenderScheduler.schedule() to coalesce renders; avoid direct repeated rendering.
• Prefer snapshotCache.get(runId) in render paths. If a sync fallback is unavoidable, classify it as first-load/rare and document why.
• Keep dashboard panes pure: accept a snapshot/model and format strings; do not call fs.readFileSync, fs.readdirSync, fs.statSync, or network APIs from pane render methods.
• On session switch, cancel timers and ensure in-flight async preloads cannot update stale session UI.
• Watch TTL interactions: a preload interval shorter than cache TTL prevents render-time refresh gaps.

Anti-patterns

• Do not call loadConfig(), manifestCache.list(), or refreshIfStale() repeatedly inside renderTick() unless backed by preloaded frame data.
• Do not do large JSON parsing or directory scans inside widget render/update functions.
• Do not show stale health warnings for completed/cancelled/failed runs.

Verification

cd pi-crew
npx tsc --noEmit
node --experimental-strip-types --test test/unit/run-snapshot-cache.test.ts test/unit/crew-widget.test.ts test/unit/powerbar-publisher.test.ts test/unit/run-dashboard.test.ts
npm test