REQ. `vibe-actions` is a standalone Rust crate that models **what a UI can do** as first-class,
addressable **Actions**, independent of any rendering technology. It is the behaviour-layer twin of
`spec://`: `spec://` addresses facts, `action://` addresses behaviour.
REQ {#no-render-dep}. The crate has **zero rendering dependencies** — it must not depend on
`ratatui`, `crossterm`, any GUI/DOM toolkit, or any terminal type. This invariant is what makes every
surface (the TUI, a future web UI, an IDE plugin) and the headless **AIUI** (§11.3) possible; it is
verified by a dependency-graph check in the crate's gate. Nothing in `core / model / controller`
logic may reference a rendering type.
REQ. An action is named by an **`ActionAddr`** with the textual form
`action://<group>/<name>[?<params>]`, where `<group>` is a dotted namespace (e.g. `vibe.tree`,
`core`), `<name>` is a dotted/kebab identifier (e.g. `copy.markdown`, `search.everywhere`), and the
optional `<params>` is a `&`-separated `key=value` query carrying invocation parameters (§5).
`(group, name)` is the identity; the query is *not* part of identity. Examples:
`action://vibe.tree/copy.markdown`, `action://vibe.tree/sort?by=name&dir=asc`,
`action://core/search.everywhere`.
REQ {#address-parse}. `ActionAddr` round-trips: `parse(display(a)) == a` for the identity part, and
parsing rejects a malformed address with a typed error (never a panic).
REQ. `(group, name)` is **globally unique** within a running registry (§4.1). A **rename** is a *new
identity*; the old address is retired as a **tombstone** or kept as an explicit **alias** that
resolves to the new one — an address that has ever been published is never silently repurposed
(the `qualified-naming` rule, applied to behaviour). Aliases are resolvable and enumerable.
REQ. An **`Action`** carries exactly: its `ActionAddr`; a **`Presentation`** (§3.3); a **`ParamSchema`**
(§5, possibly empty); an **enablement** predicate (§6.2); an **`invoke`** (§7.1); a **`Capability`**
(§7.2); and **`SearchMeta`** (§10.4 — synonyms/aliases/abbreviations/keywords). No other state.
REQ. What a surface renders or an AI observes for an action is an **immutable resolved snapshot**
(address + resolved presentation + resolved enablement for a given context), never a live mutable
object. Change is delivered by re-resolution, not mutation (avoids the incumbents' live-mutable
`Presentation`/`Action` hazards).
REQ. `Presentation` carries a **name** and a **description**, plus an optional icon/glyph and
optional category. Both name and description are **mandatory, non-empty, meaningful** localizable
messages (§8) — an action with an empty or placeholder name/description is a **contract violation**
caught by the legibility gate (§8.4). Both are **first-class searchable fields** (§10 — the fallback
match lane). This is the owner's founding discipline (DO5): filling them is part of building any UI
on this system, not optional decoration.
REQ. Actions register into an enumerable **`Registry`**. Registering a `(group, name)` already present
is a **hard, deterministic error** (not a silent override, not a log-and-drop) — a *collision* in the
`qualified-naming` sense, distinct from a *conflict*. Registration returns a typed result; the error
names both the incumbent and the newcomer.
REQ {#registry-override}. Layered override, if ever needed, is an **explicit** operation
(`override_of(addr)`) with uniform semantics and is itself collision-checked — never an accidental
consequence of registration order.
REQ. Any reference to an action **by address** from another structure (a keymap binding §9, a menu
placement, a Search-Everywhere action provider §10.4) is **validated at registration/build time** —
a reference to an unregistered address **fails loud** then, never silently at click time (fixes the
incumbents' string-reference-with-no-check gap, DO2).
REQ. The registry is **fully enumerable** — every registered action (and alias) is reachable by
iteration. This backs the enumerable-registry golden (§12.2), Search Everywhere's action provider
(§10.4), and the AIUI `list_actions` (§11.3).
REQ. Enablement and invocation read a **typed context snapshot** — a `TypeId`-keyed typemap (`Ctx`)
holding strongly-typed values a surface has published (e.g. the current selection, the active mode).
Reading a key yields `Option<&T>` with the real type `T` — no stringly keys, no unchecked casts, no
nullable-`Object` (fixes VSCode's stringly `when` and IntelliJ's phantom `DataKey`, DO4).
REQ. An action's enablement is a **pure, fast function** `Fn(&Ctx) -> Enablement`, where
`Enablement { visible: bool, enabled: bool, reason: Option<Localized> }`. It **must not** render,
block, touch a UI thread, or mutate — it is evaluated over an immutable snapshot, so there is no
EDT/BGT hazard (the class of bug that is IntelliJ's biggest pain). Visibility (hide) and enablement
(grey-out) are the two independent axes (kept from VSCode's `when` vs `precondition`).
REQ. The context is **introspectable**: a surface (and the AIUI) can enumerate which keys a `Ctx`
carries, and a disabled action exposes its **`reason`** ("why disabled") — neither is possible in the
incumbents. This backs both the legibility of the UI and the AIUI.
REQ. `invoke(addr, params, ctx) -> Future<InvokeResult>` is **the** way an action runs; a key press,
a menu click, a Search-Everywhere selection, and an AIUI call are all thin callers of it. It is
**async**, returns a **typed result/error** (`InvokeResult`), validates params (§5.2) and the
capability (§7.2) first, and is **cancellable** (a cancellation token threads through). The result is
first-class (not recovered out-of-band as in IntelliJ).
REQ. Each action declares a **`Capability`** (e.g. `Safe`, `Mutating`, `Dangerous`), and `invoke`
checks it against the caller's granted scope before running. This is inert for the trusted local TUI
but is the seam a networked surface (a future web UI) or an AIUI needs to refuse an out-of-scope
action (DO14). No action bypasses the check.
REQ. Presentation strings are **`Msg { key, default_en }`** where `key` is **derived from the address**
(`action.<group>/<name>.name`, `.description`) — one canonical mapping, no second key namespace to
drift (IntelliJ's strength) — and `default_en` is the **inline English** default carried at the
declaration site (VSCode's strength: self-documenting, always present). A `Catalogue { locale,
entries, parent }` resolves a key through a parent chain terminating in an `en` catalogue **seeded
from the inline defaults**, so a release lookup can never miss (no sentinel, no panic). The on-disk
catalogue format is Fluent (`fluent`-family), with named args + plurals.
REQ. A resolved label is **`ResolvedLabel { value, original_en }`** — the localized value plus the
English original. Search Everywhere (§10) indexes **both**, so a user typing the English name finds
an action under any locale (copies VSCode `localize2`).
REQ. English is the **default, mandatory-complete** locale and the terminating fallback. Other locales
may lag and fall back silently. Locale switch is atomic (`ArcSwap<Catalogue>`); a package may ship
`locales/<lang>.ftl`, and a dedicated language-pack package may override, merged by explicit priority
(language-pack > package locale > inline English).
REQ (floor gate). A CI/floor gate enumerates the registry (§4.3) and asserts, **against the English
surface**, that every action's `name` and `description` are present, non-empty, and non-placeholder,
and that every derived `MessageKey` resolves in the shipped `en` catalogue. A violation fails the
floor, exactly as untested domain logic does. Other locales are not gated (they may lag). A `pseudo`
locale QA build surfaces un-externalized strings.
REQ. A **`Keymap`** maps a key (or chord) to a `(ActionAddr, ParamValues)` binding, gated by an
optional enablement/`when`-equivalent over the typed context. Bindings reference actions **by address**
and are subject to referential-integrity (§4.2).
REQ. Resolution is a **pure function** returning a **3-state result** — `NoMatch | NeedMoreChords |
Found(addr, params)` (copies VSCode's `ResultKind`). Ambiguity (several bindings on one key) is
resolved by enablement + weight (IntelliJ's first-enabled model). **Chord timers, IME, and focus
walking live in the surface adapter**, never in the resolver.
REQ. A binding conflict (two enabled bindings competing for one key/chord) is **surfaced** via an
introspection API — not resolved silently (fixes the incumbents' silent/advisory-only handling, DO11).
The acceptance feature: one window that searches packages, every package-card field, and all actions,
with a hybrid "All" tab + per-category tabs, invoking a found action in place.
REQ. A searchable source is a **`SearchProvider`** implementing the **two-phase** contract:
`enumerate(query) -> stream of cheap keys` (streamed, cancellable, scope-aware — never a full
materialization) and `resolve(key) -> hits` (heavy items, produced **only for matched keys**). It also
supplies identity + tab presentation (`id`, `group_name`, `sort_weight`, `separate_tab`), an
`ItemAccessor` (`{label, description, key}` for the one shared ranker), an `on_selected(hit, mods) ->
Close | Stay` (navigate/act), and a `render_row(hit) -> RowDescriptor` (§10.5). This is the minimal
"searchable structured universe" contract distilled from IntelliJ; it is open enough that new sources
plug in without touching the engine.
REQ. The engine, on each keystroke: **debounces** (~90–120 ms) and **cancels** the prior run; selects
the active provider set (one for a category tab, all filter-enabled for "All") with a per-provider cap
(single 30 / All 15); has each provider **enumerate** keys, **matches** them with one scorer, and
**resolves** only survivors. Hits are ranked on **one commensurable scale** (§10.3), **recency-weighted**
with an **exact-match floor**, **deduped keeping the higher score** across providers, and drained
**round-robin** from per-provider bounded queues into one flat list (the single-threaded adaptation of
IntelliJ's back-pressured merge). A per-provider **"more…"** row re-queries that provider and **freezes**
the rows above (no reshuffle under the cursor).
REQ. One scorer produces **both a score and the highlight ranges** (fixes VSCode's two-engine
mismatch, DO7). The match-tier ladder is: exact → prefix → CamelCase/subsequence → substring →
**word-in-name/description** (the fallback lane — the owner's "search by name and description when
other criteria don't match"). Ordering is score DESC, tie → provider `sort_weight` DESC. Providers
must emit scores on the **one shared scale** (the make-or-break hybrid-list rule).
REQ. Three providers ship: **`PackageProvider`** (keys = package FQNs from the `PackageTree`; navigate
= reveal the node); **`PackageFieldProvider`** (keys = **every field of every package detail card** —
name, version, kind, license, load-type, origin, path, deps, diagnostics…; navigate = open the card on
that field — the owner's "search inside all card fields"); **`ActionProvider`** (keys = action
address + name + description + `SearchMeta` synonyms/aliases/abbreviations; `on_selected` = **invoke** the
action — perform→`Close`, a toggle→`Stay`; disabled actions render greyed with their `reason` and
right-aligned keybinding). A **`StructureProvider`** (AI-Native specmap spec/code nodes) is **reserved
against the same trait** and added later **without engine changes** (DO16).
REQ. All result rows render through **one** normalized `RowDescriptor { icon?, primary, secondary
(e.g. a keybinding), group, enabled, kind }`, so every category looks uniform (the study's ADAPT note;
avoids IntelliJ's per-provider renderers).
REQ. Tabs are built **from the providers**: sort by `sort_weight`; prepend an **"All"** tab when there
is more than one provider; one tab per `separate_tab` provider. The "All" tab searches every
filter-enabled provider and carries a **category checkbox filter**; a single tab restricts to its
provider and hides group headers. `Tab`/`Shift-Tab` cycle. This is the IntelliJ hybrid-All + per-tab
UX the owner named.
REQ. A **`Surface`** is the adapter seam between the core and a concrete frontend: it `present`s a
`ModelView` and yields `Event`s. A visual surface renders; a headless surface's `present` is a no-op.
No core / model / controller code depends on a `Surface` implementation or a rendering type (§1
invariant).
REQ. The observable UI state is a **serialisable `ModelView`** snapshot (focus, open modals, visible
rows, current tree/selection, the active tab, the set of enabled actions with their addresses +
reasons). It is a pure projection of the Model and carries **no rendering types** — so an AI reads
structured state, never pixels.
REQ (**built**; the in-process form ships). The core offers a **headless AIUI** surface:
`list_actions(filter?)` (enumerate the registry with live enablement + reasons + params),
`invoke(addr, args)` (the same `invoke` as §7.1), `state() -> ModelView` (§11.2), and
`search(query, tab?)` (drive §10 programmatically). `vibe-actions/src/aiui.rs` implements
`list_actions` + `invoke`, and `vibe aiui state` projects the §11.2 `ModelView` live, citing this
section in its own `--help`. Because enablement is pure + introspectable, the
model is serialisable, and invocation is address-based, this surface is a thin adapter with a no-op
`present`. The architecture must keep it a thin adapter — it was **prototyped on the TUI**, and the
remaining JSON-RPC / MCP bindings are further adapters over the same surface. This is the founding
AIUI goal (DO18): the headless surface is the **reference**; visual surfaces are projections.