| name | pvf-palette |
| description | Add, edit, rename, or review pvf palette behavior. Use when changing PaletteKind, PaletteProvider implementations, palette open options, provider snapshots, candidate rows, command-palette visibility, input modes, selection behavior, tab or submit behavior, palette-scoped key behavior, or palette rendering contracts. |
PVF Palette
Use this skill for pvf palette behavior and palette subsystem boundaries.
First Decision
Before touching code, decide whether the task changes the user's interaction.
- If yes, write the user-facing interaction contract first. Do not start
implementation until the user goal, operation, display, and feedback are clear
enough to test.
- If no, keep the work internal: preserve behavior, avoid UX speculation, and
use existing tests as the contract.
User-facing interaction contract means the concrete workflow: what the user is
trying to accomplish, the intuitive operation to get there, the shortest
keyboard path, what is shown or not shown, where it appears, title, initial
input, selected row, row text, assistive text, empty state, notices, Tab, Enter,
Escape, selection movement, text editing, history navigation, no matches,
unavailable state, repeated use, close, reopen, and recovery from mistakes.
Context
- Palette contract:
docs/reference.md Palette section.
- Ownership or snapshot boundary: relevant
docs/architecture.md section.
- Command-palette dispatch or visibility:
docs/reference.md Commands section.
- Test placement question:
docs/testing.md.
For implementation, start from the owning code:
- Common active-session behavior:
src/palette/session_controller.rs.
- Provider contract and context:
src/palette/provider.rs.
- Candidate ids, text, row construction, and matching text:
src/palette/candidate.rs, src/palette/text.rs, src/palette/row.rs.
- Registry wiring only:
src/palette/registry.rs.
- Built-in providers:
src/palette/providers/command.rs,
src/search/palette.rs, src/history/palette.rs,
src/outline/palette.rs.
Rules
- Providers own candidate generation, input mode, completion, submit,
assistive text, and provider-specific initial selection.
PaletteSessionController owns open/close, session id validation, input
editing, filtering, selection, completion routing, submit routing, and input
history navigation.- Open requests carry only common initialization (
PaletteOpenOptions).
Provider-owned UI data crosses through app/extension snapshots.
- Build candidates through
PaletteRow; displayed text and match text should
share the same formatting path.
- Use typed effects and commands. Providers must not mutate app state, key
routing, follow-up queues, or input history directly.
Tests And Docs
- Put provider-specific behavior tests next to that provider.
- Keep
session_controller tests about provider-neutral session behavior.
- Use command-dispatch, input, or rendering tests only for those boundaries.
- Update docs only for stable contracts, ownership, or compatibility policy.
Put executable behavior in tests and local details in code.
