| name | gpui-rust-console |
| version | 0.2.0 |
| description | Build and extend pd-console — Port Daddy's GPU-native macOS operator console (GPUI 0.2.x, Zed's Rust UI). Covers the render-agnostic Block/Pane(Surface) contract, the two-thread reqwest↔smol refresh pipeline, Taffy flexbox layout, uniform_list virtual scroll, focus + keyboard nav, the OKLCH theme and ICS maritime flag badges, GPUI's missing text-input, and the real feature-gated cargo/CI gate. Use when adding panes, visual polish, or debugging GPUI rendering/layout/focus in core/pd-console. NOT for the TypeScript daemon, generic Rust toolchain/borrow-checker help (use rust-with-claude-code), or non-pd GPUI apps with a different theme/architecture.
|
| allowed-tools | Read,Write,Edit,Bash,Grep,Glob |
| author | port-daddy |
| license | Apache-2.0 |
| tags | ["gpui","rust","ui","native","macos","console","oklch","maritime","port-daddy"] |
| metadata | {"category":"Native UI & Rendering","argument-hint":"[task: add-pane|layout|scroll|theme|maritime|text-input|verify]","provenance":{"kind":"first-party","owners":["port-daddy"]},"pairs-with":[{"skill":"rust-with-claude-code","reason":"Generic Rust toolchain/borrow-checker/async help once you're past pd-console's own render-agnostic contracts."},{"skill":"rust-gpui-motion","reason":"with_animation/easing/pane transitions for a pane this skill already renders — motion is out of scope here."},{"skill":"gpui-shaders","reason":"Custom Metal/wgpu fragment passes behind/around a pane (e.g. a living-harbor background) beyond Block/Tone painting."},{"skill":"rust-app-distribution","reason":"Code-signing, notarization, and auto-update packaging once the pd-console binary builds clean."}],"io-contract":{"kind":"deliverable","consumes":[{"kind":"pane-surface-requirement","format":"markdown"},{"kind":"pane-spec","format":"json"}],"produces":[{"kind":"pane-implementation","format":"rust"},{"kind":"console-contract-audit","format":"json"}]}} |
gpui-rust-console
Authoritative skill for core/pd-console (crate pd-console v0.2.0, ADR-0046): a
GPU-native standalone macOS operator console built on GPUI 0.2.2, plus a headless ratatui
REPL that renders the same panes. The defining idea: a pane emits render-agnostic
Blocks; two renderers paint them. One pane, two faces — which is why every pane is
unit-tested on cheap Linux runners while the Metal window builds only on macOS.
When to Use
✅ Use for:
- Adding or extending a pane/surface in
core/pd-console/
- GPUI layout (Taffy flexbox), scroll (
uniform_list/list), focus, keyboard nav
- The OKLCH theme (
theme.rs) and ICS maritime flag badges (maritime.rs)
- Debugging the reqwest↔smol two-thread refresh pipeline or
cx.notify() storms
- Designing text input where GPUI ships no widget (the
pd tube cockpit)
- Getting the feature-gated
cargo/CI gate right
❌ NOT for:
- The TypeScript daemon, routes, or
agent.rs HTTP wiring beyond consuming it
- Generic Rust (borrow checker, async, FFI, testing idioms) →
rust-with-claude-code
- A non-pd GPUI app — the theme, the 17-pane model, and the daemon contract are specific
- Generic macOS app packaging / notarization →
rust-app-distribution
The Model in One Diagram
flowchart TD
D["DaemonClient (reqwest)"] -->|"GET /route per pane"| PR
subgraph PR["Producer: std::thread + current-thread tokio (2s loop)"]
R["pane.refresh(&client).await"] --> V["pane.view() → Vec<Block>"]
end
PR -->|"std::sync::mpsc: Vec<(nav_idx, Vec<Block>)>"| CO
subgraph CO["Consumer: GPUI foreground (smol, main thread, 500ms)"]
U["window.update → view.update_panes"] --> N["cx.notify()"]
end
N --> PAINT["ConsoleView::render: Block → GPUI element (Tone resolved to OKLCH)"]
CO -.->|"control_tx: ControlMsg::InterruptLane"| PR
reqwest needs tokio; GPUI runs smol; they cannot share an executor. The producer owns
the daemon + all 17 panes and mpscs Blocks to the consumer; control flows back on a
second channel. Use channels, never Arc<Mutex<State>> (it blocks the renderer — the #1
GPUI perf bug). Full detail: references/console-architecture.md.
Task Branches
| Branch | Do | Load |
|---|
add-pane | New surface end to end | examples/add-a-pane.md, templates/new_pane.rs.tmpl, templates/pane_tests.rs.tmpl |
layout | Taffy flexbox, three-panel skeleton | references/render-and-layout.md |
scroll | uniform_list vs list, bounded parents | references/render-and-layout.md |
theme | Add/preview an OKLCH tone | references/maritime-flags.md, examples/preview-theme.md, ./scripts/oklch_to_srgb.py |
maritime | ICS flag mapping / badge | references/maritime-flags.md, ./scripts/flag_resolve.py |
text-input | Cockpit chat / command entry | references/text-input.md |
verify | Run the real CI gate locally | references/build-and-ci.md, ./scripts/verify_console.py |
The Contracts You Must Not Break
- Panes are render-agnostic. Emit
Blocks with a Tone (meaning), never a color. The
renderer resolves Tone → theme OKLCH → rgb(u32) in one place (pane.rs::Tone::color).
trait Pane is object-safe (Box<dyn Pane> registry). refresh is a hand-rolled
boxed future (no #[async_trait]); mutate/subscription/on_stream have defaults so
read-only panes need zero changes. SurfaceAction is an enum, never a generic.view() is sync and IO-free. All fetching is in refresh() on the producer thread.
A failed fetch is recorded in last_error and rendered as an error state — never
propagated (one bad route must not blank the console).cx.notify() only on real state change. Never mutate self inside render.
Anti-Patterns
Sharing state with Arc<Mutex<T>> across the two threads
Novice: "Wrap the pane state in Arc<Mutex> so both threads can touch it."
Expert: The producer owns the panes; it mpscs Vec<Block> snapshots to the
consumer. A mutex under refresh contention stalls the GPUI render loop — visible jank.
Detection: any Mutex / RwLock reachable from a pane; reqwest called off the
producer thread.
Hardcoding a hex in a pane
Novice: div().bg(rgb(0xe3b56d)) inside a pane's view.
Expert: Emit Block::Chip { tone: Tone::Accent }. The amber lives once in
theme.rs (DARK.accent, which oklch_to_srgb.py confirms is e3b56d). Color resolves
at paint time so retheme/light-mode is free; an inline hex also trips the brand-color guard.
Detection: rgb(0x…) literals in *_pane.rs.
RUST_MIN_STACK for the "gpui stack overflow"
Novice: "GPUI macros overflow the stack — set RUST_MIN_STACK=16777216."
Expert: The error is a compile-time recursion limit, fixed by
#![recursion_limit = "512"] at the top of main.rs. RUST_MIN_STACK resizes a runtime
thread stack and does nothing for a compile error. CI sets neither — it runs plain
cargo check + cargo test with gpui feature-gated off on Linux.
Timeline: this corrected an earlier draft of this very skill; see references/build-and-ci.md.
Expecting a built-in text input
Novice: "Use GPUI's text field for the cockpit."
Expert: GPUI 0.2.x ships no text-input widget. Use the full-screen entry overlay
pattern (state on the view, not the busy stream pane) or build an Element (~300 LOC).
Detection: searching the API for text_input(); cursor state bolted onto the Lane pane.
Quality Gates
□ Pane emits Block+Tone only — zero rgb(0x…) in the pane
□ view() is sync and IO-free; refresh() records errors, never propagates
□ trait stays object-safe (boxed future; enum actions; no generics on dyn methods)
□ New pane proves 3 states (empty/error/populated) — templates/pane_tests.rs.tmpl
□ NAV index (app.rs) == producer slot index (main.rs)
□ Theme change is OKLCH in theme.rs, never inline hex; previewed via oklch_to_srgb.py
□ Maritime change keeps flag_resolve.py --selftest green (HITL→Foxtrot, mayday→Juliett)
□ python3 scripts/verify_console.py run --crate core/pd-console → cargo check + test ok
□ python3 scripts/validate_skill.py → 0 errors
□ No retired cinnabar hex / no daemon-URL literal outside agent.rs
Reference Files
| File | Consult When |
|---|
references/console-architecture.md | Two-thread pipeline, Block/Pane(Surface) contract, registry, FsAssets, window bootstrap |
references/render-and-layout.md | Render vs RenderOnce, Taffy flexbox, uniform_list/list, focus, keyboard, notify discipline, perf anti-patterns |
references/maritime-flags.md | ICS flag mapping + badge colors, the OKLCH theme and to_srgb8(), Tone→color resolution |
references/build-and-ci.md | The feature-gate, the real cargo/CI jobs, recursion_limit vs RUST_MIN_STACK, brand/URL guards |
references/text-input.md | GPUI has no input widget — defer / overlay / build-an-Element decision tree |
references/07-scripting-and-visual-proof.md | Driving a RUNNING console over the control socket (the REPL: focus/state/galaxy/rebind via console-ctl.py), daemon selection (console-daemon.url, source-mode profiles), and the verify-state-then-capture doctrine for PR visual evidence |
Scripts
| Script | Purpose |
|---|
./scripts/_envelope.py | Shared stdin/stdout script-io envelope (imported by the others) |
./scripts/oklch_to_srgb.py | Faithful port of theme.rs::to_srgb8; preview an OKLCH token's hex (oklch.to_srgb) |
./scripts/flag_resolve.py | Faithful port of maritime.rs; resolve agent-state → ICS flag + meanings (flag.resolve) |
./scripts/verify_console.py | Run the real CI gate locally: cargo check+test (+--features gpui on macOS) |
./scripts/validate_skill.py | Skill self-check: frontmatter, refs, schema, no phantom citations, script selftests |
Schemas
| File | Used By |
|---|
schemas/script-io.schema.json | The Request/Response envelope every script wraps stdin/stdout against |
Templates
| Template | Output |
|---|
templates/new_pane.rs.tmpl | A read-only Pane skeleton (error/empty/populated states, boxed-future refresh) |
templates/pane_tests.rs.tmpl | The three-state pane test suite (sync, no tokio, Linux-CI-safe) |
Examples
| Example | Walks Through |
|---|
examples/add-a-pane.md | Adding a "Voyages" pane end to end with real main.rs/app.rs cites |
examples/preview-theme.md | Designing a new OKLCH status tone and seeing its hex before touching Rust |
Skill Bundle Index
Every file in this skill, and when to open it. Auto-generated; run scripts/index_references.py --fix.
root
.gitignoreCHANGELOG.md — UgpuiUrustUconsole — Changelog — - Brought to the agentic-family standard: added io-contract/provenance/pairs-with frontmatter - Added a deterministic audit helper (ma
examples/
examples/add-a-pane.md — Example: Add a new pane to pd-console end to end — Goal: add a "Voyages" pane that lists active voyages from GET /voyages, slotted after Lane, fully unit-tested, no gpui needed for the testexamples/preview-theme.md — Example: Preview a new OKLCH status tone without compiling Rust — Goal: you want to add a Stalled status tone (a desaturated amber, distinct from the warning amber) and see its hex before wiring it into `
references/
references/build-and-ci.md — Building pd-console & the Real CI Gate — > Source of truth: core/pd-console/Cargo.toml and the rust-console / > rust-console-gpui jobs in .github/workflows/ci.yml.references/console-architecture.md — pd-console Architecture — The Unified Model — > Source of truth: core/pd-console/src/ (crate pd-console v0.2.0, ADR-0046).references/maritime-flags.md — ICS Maritime Flags & the OKLCH Theme — > Source: core/pd-console/src/maritime.rs and core/pd-console/src/theme.rs.references/render-and-layout.md — GPUI 0.2.x Rendering & Layout — the idioms that compile — > GPUI 0.2.2 (Cargo.toml: gpui = { version = "0.2.2", optional = true }).references/text-input.md — Text Input in GPUI 0.2.x — There Is No Widget — > The single most surprising gap for anyone coming from web/Qt/SwiftUI: GPUI 0.2.x ships > no text-input widget. Zed builds its own.
schemas/
scripts/
templates/
