singularity-forge/docs/extending-pi/22-key-rules-gotchas.md

Key Rules & Gotchas

Must-Follow Rules

1. Use StringEnum for string enums — Type.Union/Type.Literal breaks Google's API.
2. Truncate tool output — Large output causes context overflow, compaction failures, degraded performance.
3. Use theme from callback — Don't import theme directly. Use the theme parameter from ctx.ui.custom() or render functions.
4. Type the DynamicBorder color param — Write (s: string) => theme.fg("accent", s).
5. Call tui.requestRender() after state changes in handleInput.
6. Return { render, invalidate, handleInput } from custom components.
7. Lines must not exceed width in render() — use truncateToWidth().
8. Session control methods only in commands — waitForIdle(), newSession(), fork(), navigateTree(), reload() will deadlock in event handlers.
9. Strip leading @ from path arguments in custom tools — some models add it.
10. Store state in tool result details for proper branching support.

Common Patterns

• Rebuild on invalidate() when your component pre-bakes theme colors
• Check signal?.aborted in long-running tool executions
• Use pi.exec() instead of child_process for shell commands
• Overlay components are disposed when closed — create fresh instances each time
• Treat ctx.reload() as terminal — code after it runs from the pre-reload version

---