max / alloy_tui

Say which repo the docs/*.md references name The design docs stayed in the alloy repo when this crate was split out, so every `docs/TOKENS.md` or `docs/CONSOLE.md` in these doc comments points at a file docs.rs does not publish and a reader here cannot find. Qualify the first mention on each module page, and state it once at the crate root, since a docs.rs reader can land on a module without passing through lib.rs. Prose rather than URLs: alloy is not pushed to mnw, so a makenot.work/git/max/alloy link would 404 today.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: Max Johnson <me@maxj.phd> · 2026-08-01 14:55 UTC

Signed with PGP, not checked

Commit: 86dd9d1a3b65a86a5d71985942becf0d61f5740c

Parent: 633f6ff

8 files changed, +29 insertions, -24 deletions

M src/bevel.rs +4 -4

			@@ -52,10 +52,10 @@
52	52
53	53		/// Which way a surface is lit, which is to say what it is.
54	54		///
55		-	/// Per docs/DESIGN-LANGUAGE.md the presence of an edge is itself the affordance:
56		-	/// a bordered thing is a control and a flush thing is data. [`Elevation`] makes
57		-	/// that a physical claim rather than a convention, and adds the two states a
58		-	/// flat border could not express.
	55	+	/// Per the Alloy repo's docs/DESIGN-LANGUAGE.md the presence of an edge is
	56	+	/// itself the affordance: a bordered thing is a control and a flush thing is
	57	+	/// data. [`Elevation`] makes that a physical claim rather than a convention,
	58	+	/// and adds the two states a flat border could not express.
59	59		#[derive(Debug, Clone, Copy, PartialEq, Eq)]
60	60		pub enum Elevation {
61	61		/// Flush on its surface. Data panels and tabular regions, which carry the

M src/focus.rs +1 -1

			@@ -1,7 +1,7 @@
1	1		//! The focus ring — the one piece ratatui does not provide.
2	2		//!
3	3		//! Rendering is immediate-mode, but input is event-driven, so something has to
4		-	//! remember which pane the next keystroke belongs to. Per
	4	+	//! remember which pane the next keystroke belongs to. Per the Alloy repo's
5	5		//! docs/COMPONENT-LIBRARY.md that model lives here, and it is deliberately
6	6		//! minimal: an index into a fixed number of focusable slots, wrapping in both
7	7		//! directions. Apps map their own pane enum onto the index.

M src/keys.rs +5 -5

			@@ -1,11 +1,11 @@
1	1		//! Reserved keymap: the constants every Alloy TUI navigates by, and the
2	2		//! classifier that turns a raw key event into one of them.
3	3		//!
4		-	//! Per docs/COMPONENT-LIBRARY.md the reserved keys live in exactly one place so
5		-	//! apps match against `Action` rather than hardcoding keycodes: `Tab` /
6		-	//! `Shift-Tab` move focus, `l` / `h` move between tabs, `Enter` activates,
7		-	//! `Esc` cancels, `Ctrl-S` saves, `q` quits, `?` opens help, `/` filters, `:`
8		-	//! opens the command line.
	4	+	//! Per the Alloy repo's docs/COMPONENT-LIBRARY.md the reserved keys live in
	5	+	//! exactly one place so apps match against `Action` rather than hardcoding
	6	+	//! keycodes: `Tab` / `Shift-Tab` move focus, `l` / `h` move between tabs,
	7	+	//! `Enter` activates, `Esc` cancels, `Ctrl-S` saves, `q` quits, `?` opens
	8	+	//! help, `/` filters, `:` opens the command line.
9	9		//!
10	10		//! Tabs get `l` / `h` rather than `Tab` because `Tab` already means focus and
11	11		//! that meaning is documented across every view. Two navigation axes need two

M src/layout.rs +4 -3

			@@ -1,9 +1,10 @@
1	1		//! The console frame: body, command-log pane, footer.
2	2		//!
3	3		//! sysop-tui split a screen into body plus a one-row footer. Alloy adds the
4		-	//! command-log pane between them, which docs/CONSOLE.md settled as always-on —
5		-	//! the "console teaches its own primitives" claim only lands if the log of
6		-	//! underlying CLI invocations is visible without being asked for.
	4	+	//! command-log pane between them, which the Alloy repo's docs/CONSOLE.md
	5	+	//! settled as always-on — the "console teaches its own primitives" claim only
	6	+	//! lands if the log of underlying CLI invocations is visible without being
	7	+	//! asked for.
7	8
8	9		use ratatui::layout::{Constraint, Layout, Rect};
9	10

M src/lib.rs +4

			@@ -9,6 +9,10 @@
9	9		//! enforced here: chrome is tinted-greyscale, accents live on text via
10	10		//! `Severity`.
11	11		//!
	12	+	//! Every `docs/*.md` path in this crate's documentation names a file in the
	13	+	//! Alloy repo, not this one. The design docs stayed behind when `alloy_tui`
	14	+	//! was split out, so they are not published alongside these pages.
	15	+	//!
12	16		//! Beyond the widgets, the crate carries the two things ratatui leaves to the
13	17		//! app and every Alloy TUI must agree on: the reserved keymap ([`keys`]) and
14	18		//! the focus ring ([`focus`]). Both descend from mountaineer-sysop's

M src/selection.rs +2 -2

			@@ -3,8 +3,8 @@
3	3		//! Ported from sysop-tui's `selection.rs`, retinted from the theme. The marker
4	4		//! stays a plain triangle rather than a Nerd Font glyph so selection survives
5	5		//! a console without the patched font — the TTY before the session starts, a
6		-	//! remote shell, `alloy` over SSH. Per docs/ICONOGRAPHY.md, Nerd Font glyphs
7		-	//! decorate; they never carry state on their own.
	6	+	//! remote shell, `alloy` over SSH. Per the Alloy repo's docs/ICONOGRAPHY.md,
	7	+	//! Nerd Font glyphs decorate; they never carry state on their own.
8	8
9	9		use ratatui::style::{Modifier, Style};
10	10

M src/theme.rs +2 -2

			@@ -9,8 +9,8 @@
9	9		//!
10	10		//! # The two tokens that stayed, and why they are not duplication
11	11		//!
12		-	//! Per docs/TOKENS.md, Alloy derives two tokens locally so theme files stay
13		-	//! minimal and cross-app compatible:
	12	+	//! Per the Alloy repo's docs/TOKENS.md, Alloy derives two tokens locally so
	13	+	//! theme files stay minimal and cross-app compatible:
14	14		//!
15	15		//! - `border-subtle = mix(line.border, surface.page, 60%)` decorative divider
16	16		//! - `border-strong = mix(line.border, content.primary, 65%)` focus / selection

M src/widgets.rs +7 -7

			@@ -1,12 +1,12 @@
1	1		//! Themed ratatui widget wrappers.
2	2		//!
3		-	//! v1 target per docs/CONSOLE.md: `AlloyBlock`, `AlloyList`, `AlloyForm`,
4		-	//! `AlloyTable`, `AlloyStatusBar`, `AlloyLog`, plus form-field widgets driven
5		-	//! by the config schema. The four the console shell needs to render a screen
6		-	//! end to end — block, list, log pane, status bar — plus the `Severity` accent
7		-	//! they all compose with, and, as of 1.2, the form: `AlloyForm`, a single
8		-	//! `AlloyField` carrying a `FieldKind` value cell, and a display-only
9		-	//! `AlloyTable`.
	3	+	//! v1 target per the Alloy repo's docs/CONSOLE.md: `AlloyBlock`, `AlloyList`,
	4	+	//! `AlloyForm`, `AlloyTable`, `AlloyStatusBar`, `AlloyLog`, plus form-field
	5	+	//! widgets driven by the config schema. The four the console shell needs to
	6	+	//! render a screen end to end — block, list, log pane, status bar — plus the
	7	+	//! `Severity` accent they all compose with, and, as of 1.2, the form:
	8	+	//! `AlloyForm`, a single `AlloyField` carrying a `FieldKind` value cell, and a
	9	+	//! display-only `AlloyTable`.
10	10
11	11		use ratatui::buffer::Buffer;
12	12		use ratatui::layout::Rect;