curiositech/gpui-rust-console

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 |

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 |

<!-- BEGIN BUNDLE INDEX (auto: index_references.py) -->

Skill Bundle Index

Every file in this skill, and when to open it. Auto-generated; run scripts/index_references.py --fix.

root

• .gitignore

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 test
• examples/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/

• schemas/script-io.schema.json — script io.schema (data/schema)

scripts/

• scripts/_envelope.py — Shared script-io envelope helpers for the gpui-rust-console skill.
• scripts/flag_resolve.py — Resolve a canonical agent-state string to its ICS maritime flag, meanings, and
• scripts/oklch_to_srgb.py — Convert OKLCH theme tokens to packed 0xRRGGBB sRGB — a faithful Python port of
• scripts/validate_skill.py — Self-check the gpui-rust-console skill: frontmatter, required references,
• scripts/verify_console.py — Run the real pd-console CI gate locally and report it as a script-io envelope.

templates/

• templates/new_pane.rs.tmpl
• templates/pane_tests.rs.tmpl

<!-- END BUNDLE INDEX -->