40 lines
2.1 KiB
Markdown
40 lines
2.1 KiB
Markdown
---
|
|
name: ui-render-performance
|
|
description: 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
|
|
|
|
```bash
|
|
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
|
|
```
|