53 KiB

Raw Blame History

Statusline segments - framing (Arc 4 stage 3)

Revision 3 - 2026-07-21. Implemented on branch statusline-segments against current main bb17ec9 (#123 atop #124, protocol v17). It advances the wire to v18, satisfies Acceptance 1-27, and is fully gated; awaiting review, not merged.

Revision 3: closes review findings on authoritative-empty baseline retention and the TUI's protected-suffix clipping boundary.

The implementation review corrected the record for the GPU's built-in-only narrow-band case: stage 3 deliberately changes the legacy clipping edge and now pins that behavior with a headless regression test.

Revision 2: closes review findings on invalidation, terminal-control-safe grapheme painting, separator ownership, detached-frontend latches, and the unknown-LSP label. Revision 1 was the initial post-#124 architecture scout.

Arc 4 names three deliverables: named UI faces, a live GPU font preference, and a Lua statusline-segment API (docs/roadmap-2026-07.md:83-90). Stages 1 and 2 landed as #120 and #124. This framing covers stage 3 only. It adds composable Lua providers to the per-window modeline, carries their text plus face names to semantic frontends at protocol v18, and uses the existing LSP status tracker as the first built-in provider. Completing this stage completes Arc 4.

Implementation record (2026-07-21)

The approved Q#SL1-Q#SL11 design is implemented without changing the framed ownership boundary:

pmacs.statusline owns a shared editor-global registry with strict registration, lifecycle/introspection, monotonic layout/face-set epochs, borrow-released three-phase evaluation, per-context failure latches, deterministic ordering, and bounded one-line results.
TUI composition preserves the legacy modeline when providers are absent, owns separators by adjacent segment face, shapes terminal-safe grapheme runs, and protects the right diagnostic/cursor/scroll suffix.
Protocol v18 appends complete StatuslineSegments replacements. The semantic producer distinguishes authoritative empty from no message, versions provider execution before callbacks, expands dynamic ThemeFacts, and resets buffer baselines symmetrically with BufferSnapshot.
The GPU consumes v18 atomically, resolves exact dynamic faces, clips provider runs without wrapping or displacing the protected suffix, deliberately right-pins over-wide built-in-only readouts, and preserves its prior valid state on malformed input.
builtin/runtime/lsp.lua registers the first pure right-side provider from its private attachment map; the Rust tracker exposes bounded init/ready/degraded/crashed/stopped/unknown labels.

The final gate run was sequential and clean: cargo fmt --check; workspace/all-target Clippy with -D warnings; 1,619 default and 1,793 CRDT library tests; 7 default and 8 CRDT stage-3 acceptance tests; 114 M4 acceptance tests (3 ignored, basedpyright filtered); 109 required GPU tests; and the one-invocation workspace sweep (2,718 passed across 78 suites, 19 ignored, basedpyright filtered). git diff --check was clean. No flaky rerun was needed.

Ground truth (as of `main` at `bb17ec9`, protocol v17)

There are two different bottom surfaces in the TUI

EditorCore.status: String is one global, one-line transient message (src/editor_core.rs:234-235). Lua writes it through pmacs.editor.set_status (src/lua_bindings/mod.rs:11414-11422). dispatch_key clears it at entry (src/editor.rs:677-685), and the optimistic CRDT self-insert path clears it too (src/daemon.rs:2159-2165).
Every TUI window reserves its own final row for a modeline. paint_frame renders all windows in the active frontend's layout, then calls paint_mode_line with buffer name, modified state, active-window marker, diagnostics, cursor L:C, and scroll state (src/editor.rs:2102-2240). The current formatter has a left string (+/-, modified marker, name) and a right string (diagnostics, L:C, scroll); the right side is right-aligned and dropped wholesale if it is wider than the window (:2556-2617).
The terminal's last physical row is a separate global echo row. build_status_line contains only core.status, the last captured Lua error, and an in-flight key prefix (src/editor.rs:2791-2827). Isearch or the minibuffer paints over that row afterward (:2244-2265). Per-window buffer facts deliberately do not live there.
ui.modeline owns the per-window row within its stage-1 {fg,bg,reverse} mask. ui.statusline owns the global echo row's foreground only. Search/minibuffer text uses ui.minibuffer (docs/theme-faces-framing.md Q#TH3/Q#TH5). The two face names are not synonyms.
Modeline width currently counts chars, not terminal display columns (editor.rs:2594-2616). A custom CJK or combining segment would therefore overlap its neighbor unless this stage moves the whole modeline through Unicode display-width discipline.
The cell protocol already has Glyph::Cluster for a UTF-8 grapheme plus Glyph::Continuation for its trailing columns, and the terminal emitter writes clusters verbatim (pmacs-protocol/src/cell.rs:65-77; src/frontend.rs:580-591). TextView still skips combining marks, but that older limitation need not be copied into this new painter. unicode-segmentation is currently only transitive through cosmic-text; using it in the core requires one direct manifest entry.

The GPU compresses those surfaces into one physical band

StatusFacts (protocol v8, widened at v15) carries daemon-owned buffer name, modified flag, error/warning counts, and the transient core.status message. Cursor and scroll deliberately stay frontend-derived so they follow the optimistic caret (pmacs-protocol/src/message.rs:764-792; docs/pmacs-gpu-status-band-framing.md Q#S1).
SemanticRenderState::last_status is a per-buffer peer-emission baseline. status_facts_msg frame-polls cheap Rust state and emits only on payload change (src/semantic_render.rs:176-180, :909-976). on_buffer_snapshot_sent removes that baseline because the frontend snapshot clears its buffer-scoped status mirror (:412-450).
GPU composition has one left glyphon buffer and one right glyphon buffer. The left side's priority is minibuffer, isearch, transient message, then buffer name/modified (pmacs-gpu/src/main.rs:4033-4087). The right side is diagnostics followed by optimistic L:C and scroll (:3971-4030). Both use string-equality shaping caches (:4089-4137); ThemeFacts clears those caches because colors can change while strings do not (:3035-3047).
The right buffer is measured and positioned flush right; the left buffer's clip ends before it (main.rs:5318-5408). Search, minibuffer, and transient messages replace only the left content. Diagnostics/cursor/scroll remain visible on the right.
Unlike the three popup buffers, neither status glyphon buffer is currently set to Wrap::None (main.rs:2171-2201). Long custom text would otherwise wrap before its measured origin can enforce the single-band clipping policy. In pinned glyphon 0.11, TextArea.left is an independent f32 origin and TextBounds performs clipping, so a negative origin is supported without reshaping away the protected right suffix.
BufferSnapshot clears spans, decorations, adornments, summary, completion, search, menu, and status_facts; it deliberately keeps global minibuffer, theme, and font state (main.rs:2736-2818). A new buffer's first closed prompt state may be suppressed, so every new buffer-scoped status mirror must join this symmetric reset contract rather than wait for a later close message.

The old `ModeLine` wire variant is not this feature's carrier

InstanceMessage::ModeLine(Vec<Cell>) has existed since the first protocol and remains unused (pmacs-protocol/src/message.rs:506-510; the only consumers are silent-drop/debug-name arms). It contains daemon-painted grid cells, not structured text and face names.
The status-band framing already rejected it: preformatted cells bake TUI layout into a frontend that owns font shaping and would make a daemon-formatted cursor visibly lag optimistic typing (docs/pmacs-gpu-status-band-framing.md Q#S1).
Changing that existing variant's shape would be a wire break under an already-shipped discriminant. Reusing it unchanged would contradict both the frontend-local-rendering boundary and this arc's requirement that segments carry face names rather than raw colors.

Lua has provider and error-isolation precedents, but no statusline registry

pmacs.completion.register { name, priority?, fn } returns a stable userdata handle and supports unregister, priority, enable, and introspection (src/lua_bindings/mod.rs:10624-10712). The completion registry establishes the repository pattern for composable Lua-defined providers.
Hooks snapshot callbacks before invocation so a callback can re-enter its registry without a RefCell double borrow (src/hook.rs:250-259). Hook callback errors are isolated and appended to *errors* (src/lua.rs:278-306).
paint_frame takes a mutable EditorCore borrow before walking windows and holds it through both bottom surfaces (src/editor.rs:2120-2250). Calling arbitrary Lua inside paint_mode_line would let an ordinary provider call pmacs.window.* or pmacs.buffer.* and immediately double-borrow the core. Provider evaluation must therefore happen before that paint borrow, against owned context snapshots.
The daemon stamps core.active_frontend before every frontend's projection (src/daemon.rs:958-960) and at session establishment (:1426-1428). pmacs.frontend.id() consequently has the correct per-session value during a pre-render provider fan-out.
EditorCore already owns distinct layouts/windows per FrontendId; active_window_for(fid) has no cross-frontend fallback (src/editor_core.rs:512-526). A grid frontend may have several visible windows, while the current semantic GPU has one active buffer/view. Provider output must be evaluated and cached per frontend/window context, never as one global string.

A real first consumer is already waiting

LspStatusTracker exists specifically as the stable higher-level state a modeline can read (src/lsp_status.rs:30-85). Its tracker labels are the bounded set init, ready, idx, degraded, crashed, and stopped; pmacs.lsp.modeline_label additionally returns "?" for a forgotten/unknown server id (src/lsp.rs:1190).
Lua already exposes pmacs.lsp.modeline_label(server) and a richer status_summary intended for one call per render frame (src/lua_bindings/mod.rs:8700-8805).
builtin/runtime/lsp.lua owns the authoritative buffer-handle-to-attachment map. Its public active_attachment deliberately reads only the active window (:721-731), but a statusline provider in that same Lua chunk can safely index the private map by a passed ctx.buffer, including passive TUI windows.
Despite comments saying LSP data feeds a modeline, no renderer currently consumes it. Stage 3 can prove the API on a shipped, useful segment instead of landing an unused extension point.

ThemeFacts currently cannot represent arbitrary segment faces

Theme::face(name) owns daemon-side dotted-prefix inheritance for ui/ui.* names and returns None when unset (src/highlight.rs:207-226).
The namespace predicate itself currently lives only in the main crate as highlight::is_face_name (src/highlight.rs:92-95). pmacs-gpu cannot import that crate without reversing the dependency graph, so merely calling two copied expressions "shared" would leave registration and the untrusted wire boundary free to drift.
The ThemeFacts producer resolves only the fixed twelve stage-1 face names in UI_FACES (src/semantic_render.rs:281-299, :1137-1177). Frontends perform exact-name lookup; they never walk parent names.
Therefore a segment naming ui.modeline.lsp cannot inherit a configured ui.modeline on the GPU unless the producer learns that exact referenced name and ships its resolved style. Sending raw theme entries and reimplementing the walk frontend-side would contradict Q#TH7.

Protocol placement

PROTOCOL_VERSION == 17; supported versions are 6..=17 (pmacs-protocol/src/message.rs:1414, :1472-1480).
FontFacts is the final variant. Postcard enum discriminants are ordinal; stage 2 pinned the byte encoding of the final pre-v17 ThemeFacts variant. Stage 3 must append after FontFacts and pin FontFacts bytes before changing the enum.

Decisions

Q#SL1 - Scope: additive per-window modeline segments; Arc 4 ends here

Stage 3 extends the per-window modeline/status band, not the global echo area:

TUI: custom left/right segments render on each visible window's modeline.
GPU: the same custom segments render in the existing status band, scoped to its current buffer.
The TUI echo row remains owned by core.status, Lua errors, pending keys, isearch, and minibuffer. pmacs.editor.set_status is unchanged.
GPU minibuffer/isearch/transient-message precedence remains unchanged. The physical single-band compromise is explicit in Q#SL5.
Existing buffer identity, modified state, diagnostics, cursor L:C, and scroll facts remain built in. This API is additive; replacing, removing, or arbitrarily reordering those built-ins is Deferred.
Cursor and scroll remain frontend-derived. A Lua provider receives no cursor/scroll value in its context; sending the daemon's cursor as a custom segment would regress optimistic freshness by design.

No popup, click action, second row, or new layout surface is in scope. Protocol v17 -> v18 is reserved for one additive segment-facts variant. When this stage lands, Arc 4 is complete.

Q#SL2 - Lua surface: composable provider registry

The new module is pmacs.statusline:

local handle = pmacs.statusline.register {
  name = "my-project",
  side = "left",               -- required: "left" or "right"
  priority = 20,               -- optional signed 32-bit integer; default 0
  face = "ui.modeline.project",-- optional; default "ui.modeline"
  fn = function(ctx)
    if not ctx.buffer then return nil end
    return "project"
  end,
}

pmacs.statusline.set_priority(handle, 50) -- true iff handle is live
pmacs.statusline.set_enabled(handle, false)
pmacs.statusline.unregister(handle)
local providers = pmacs.statusline.providers()

Contract:

A new SharedStatuslineRegistry is installed from EditorState::new before builtin/runtime/lsp.lua, stored on EditorState, and passed by reference to both grid and semantic renderers. User config still runs after all builtins, so it can discover and tune the built-in LSP provider. Bare test states construct an empty registry rather than an optional/absent surface.
register returns a stable StatuslineProviderId userdata. Names are non-empty display/debug labels, not unique keys; handles own lifecycle, matching completion providers and package unload discipline. Registrations start enabled; ids are monotonic and are never reused, so registration-id tie breaks remain stable. The binding captures caller_source(lua, 2) at registration for later error attribution.
The registration table is strict plain data. Raw keys are exactly name, side, priority, face, and fn; an unknown key is rejected with its name. Raw reads/traversal do not invoke __index/__pairs. name, side, face, integer range, and function type are completely validated before mutating the registry. Priority accepts a finite, mathematically integral Lua number in the signed-32-bit range on both LuaJIT and Lua 5.4; strings/fractional values do not coerce.
The namespace tests move to dependency-neutral protocol helpers: pmacs_protocol::is_ui_face_name retains the exact stage-1 name == "ui" || name.starts_with("ui.") reservation, while is_modeline_face_name accepts only ui.modeline or ui.modeline.*. The core's highlight::is_face_name delegates to the former; statusline registration, ThemeFacts expansion, and GPU wire validation delegate to the latter. A modeline segment cannot borrow another surface family's special mask/Default policy. Statusline registration additionally requires valid UTF-8, rejects control characters, and bounds name and face to MAX_STATUSLINE_PROVIDER_NAME_BYTES / MAX_STATUSLINE_FACE_BYTES (256 each).
face is static for the registration. Dynamic face changes use two providers or unregister/register; this keeps the authoritative face inventory knowable without executing user code.
The callback returns a valid UTF-8 string or nil. nil and the empty string omit the segment and contribute no separator. Invalid UTF-8 or any other return type is an isolated provider error.
At most MAX_STATUSLINE_PROVIDERS (64) registrations may be live. Disabled registrations still count; unregistering releases the slot. This makes the producer's wire-size bound structural rather than a lossy "drop some providers after evaluation" policy.
Returned text is flattened with the existing one-line policy: stop at the first \n, replace other control characters with spaces. A post-sanitization value above MAX_STATUSLINE_SEGMENT_BYTES (1024) is a provider error rather than an unbounded wire/shaping input.
providers() returns fresh plain metadata tables in registration order: handle, name, side, priority, face, enabled. It never exposes the stored function.
set_priority and set_enabled return false for a stale handle; an actual change advances registry state. Mutator arguments are also strict raw types (set_enabled accepts only a boolean, never Lua truthiness). unregister is idempotent and returns whether a live provider was removed.
The module/registry installs before builtin/runtime/lsp.lua and before user config. Registration and all mutators are live mid-session, not init-gated.

The registry carries two monotonic counters:

layout_epoch: register/unregister, actual priority changes, and enable changes. It guards evaluation snapshots and orders.
face_set_epoch: register/unregister and enable changes that alter the enabled referenced-face set. It keys ThemeFacts expansion (Q#SL6). Priority-only changes do not make every semantic session re-resolve theme faces.

Both advance from their prior values and never reset.

Q#SL3 - Callback context and evaluation lifecycle

Each enabled provider is called once per rendered window context:

ctx = {
  frontend = 7,       -- integer FrontendId
  window = 42,        -- integer WindowId
  buffer = buffer_id, -- normal pmacs buffer-handle userdata
  active = true,      -- focused window within that frontend
}

There is deliberately no terminal width, pixel width, cursor, scroll, or frontend-kind field. Layout stays frontend-local; providers produce semantic text, not presentation guesses. A provider that supports passive split windows must read ctx.buffer, not pmacs.window.buffer() (which names the focused window).

Evaluation is a three-phase, borrow-released transaction:

Borrow the core only long enough to capture the target frontend's visible (window, buffer, active) contexts. For the semantic path, capture only active_window_for(frontend_id) and require its buffer to match the declared viewport; during a snapshot -> new-viewport transition, emit nothing for the stale viewport.
Snapshot enabled provider definitions plus layout_epoch, release every core/registry borrow, then invoke Lua in the deterministic order from Q#SL4. Every call gets a fresh context table.
Re-read layout_epoch and the core contexts. Publish the owned results only if the registry epoch is unchanged and every (frontend, window) still exists on the same buffer with the same active flag. A callback that changes layout, switches/kills a buffer, or registers/unregisters/disables a provider makes this evaluation invalid. Invalid is not a silent dropped fan-out: for the declared matching v18 buffer, the producer emits an authoritative replacement StatuslineSegments { left: [], right: [] }, records that empty payload as the new emission baseline only after queuing the replacement, and discards every evaluated result. The next frame therefore stays silent if the surviving truth is also empty, or emits the newly evaluated non-empty truth as a change from empty. If a callback changed the initially matching window away from the declared buffer, the empty replacement clears that prior buffer's mirror before the next frame evaluates the new truth. A snapshot -> new-viewport transition that was already stale at phase 1 instead follows that phase's no-message rule: BufferSnapshot has already cleared the frontend mirror, and on_buffer_snapshot_sent owns the corresponding baseline removal. Thus no callback mutation can leave a prior non-empty GPU payload resident indefinitely, and no invalid evaluation creates a redundant second empty send.

The TUI calls the evaluator at the start of paint_frame, before the long-lived mutable core borrow. SemanticRenderState::render_frame calls it before producing StatuslineSegments, but only for a peer that negotiated v18. A v17 semantic peer pays no Lua callback cost for an unsupported surface. The daemon already stamps active_frontend before both paths, so pmacs.frontend.id() agrees with ctx.frontend.

Provider failures are independent:

One error or invalid return omits only that provider. Later providers still run and all built-in facts still render.
The first failure in a consecutive failure run is appended to *errors* with provider name and registration source. Repeating the same failing callback every frame does not flood the buffer. Latches are keyed by the full (provider_id, frontend_id, window_id, buffer_id, active) context: success in one split must not re-arm a provider that keeps failing in another, and switching a window to a different buffer or focus role starts a truthful new failure run. A successful string-or-nil result clears only that context's latch, so a later failure there is reportable again. Unregister and stale context cleanup discard the corresponding latches; disabling a provider clears all of its latches so re-enable begins a new run. Frontend detach also discards every latch keyed by that FrontendId (with a live-context sweep as defense in depth), so a detached session cannot retain failure suppression into a later reconnect.
Evaluation snapshots definitions before calls; a provider may unregister itself without a RefCell panic. The epoch guard drops the old fan-out's result and takes the authoritative-empty invalidation path above.
Providers are documented as pure, fast render functions. The binding cannot prevent a callback from invoking editor mutators, but the context/epoch guard prevents wrong-window publication; recurring mutation loops are user-code bugs, not an implicit scheduling API.

No content epoch is assumed. LSP/process/async state can change without touching the registry, so enabled callbacks are polled each render. Owned output is payload-compared before wire emission; an empty registry or no enabled providers is an O(1) fast path.

Q#SL4 - Composition, order, separators, and narrow-window policy

Current built-in positions remain anchored:

Left: the frontend's current active/modified/buffer-identity group, with its existing edge padding, then custom left segments.
Right: custom right segments, then the frontend's current diagnostic/cursor/scroll group with its existing internal and edge spacing.

The compositor inserts exactly one ASCII space between adjacent custom segments and at a custom/built-in boundary. Provider text does not need to carry padding. No separator is emitted for nil/empty results. Every compositor-inserted separator is a base ui.modeline run: it never inherits an adjacent custom segment face. Legacy built-in internal spacing retains its current base modeline styling too. This rule is identical in TUI cells and GPU rich text, so a face colors only the provider's visible text, not the gaps around it. Each legacy built-in group stays atomic and byte-for-byte unchanged inside: in particular, stage 3 does not normalize the GPU's existing two-space diagnostic/readout separators to the TUI's one-space formatting.

Priority means survival priority when horizontal space is tight:

Left custom providers are ordered by (priority descending, registration id ascending). Higher-priority items sit closest to the leading-edge buffer identity. Overflow clips the low-priority tail.
Right custom providers are displayed by (priority ascending, registration id ascending), placing higher-priority items closest to the protected diagnostic/cursor/scroll suffix. The complete right run is right-aligned; overflow clips its low-priority left edge.
The protected built-in suffix is never discarded merely because a custom provider is long. If the built-in suffix itself cannot fit, the TUI retains its legacy wholesale drop. The GPU deliberately changes its legacy narrow-band policy: before stage 3 it pinned the built-in group's left edge and clipped the right tail; stage 3 pins the right edge and clips the left so the readout tail survives. Custom-prefix clipping preserves the complete built-in suffix only when that suffix fits by itself.
The left group gets the space before the right group's measured origin and clips at the collision boundary, without the legacy GPU's extra 10-pixel gap. It never overwrites the right group. This anchors buffer identity at the leading edge but does not guarantee its survival: an over-wide right group may consume all available left space.

This asymmetric visual ordering is intentional: priority determines what survives, not a generic ascending sort that would protect opposite ends on the two sides. Registration id makes ties deterministic across TUI painting, payload comparison, and wire encoding.

Q#SL5 - Echo/minibuffer precedence on the single GPU band

The TUI always keeps modelines visible while its separate global row shows a message, search, or minibuffer. The GPU has one physical band, so exact topology parity is impossible without adding a second GPU surface (Deferred). Stage 3 follows the existing content priority:

Ordinary buffer-name state: buffer identity followed by custom left segments.
Minibuffer, isearch, or transient message state: that content owns the whole left group; custom left segments are suppressed.
Custom right segments remain visible with the existing diagnostic/cursor/scroll right group, just as that group remains visible during minibuffer/search/message state today.

This makes custom segments modeline content, never echo content. ui.statusline continues to color transient messages only.

Q#SL6 - Segment faces and dynamic ThemeFacts inventory

Every segment carries a face name, never raw color. The registered default is ui.modeline; a typical package uses a child such as ui.modeline.lsp.

Segment faces have a stage-3 component mask of visual {fg} only on both frontends:

The modeline/status-band background remains wholly owned by ui.modeline; a text segment cannot create a per-run background on one frontend only.
The default face name ui.modeline and an unresolved custom face keep the base modeline's EFFECTIVE text color after its own reverse mapping.
A resolved custom face applies only its logical fg as the POST-modeline visible glyph color when that component is concrete. Default means "use the effective base modeline text color": an exact all-default child still blocks a colored intermediate parent, but returns the run to the base rather than trying to express a terminal-default foreground through a reversed background channel. The visible background remains the base modeline surface. Out-of-mask bg/bold/italic/underline/reverse fields are ignored by both frontends.
The TUI's built-in modeline is normally reverse = true. To apply a visible glyph color without changing that surface, the cell painter writes the override into the base style's logical bg when reverse is set, and into logical fg otherwise. After the terminal performs reverse, the requested color is the glyph foreground in both cases. The GPU writes the same requested color into the glyphon run.
A ui.modeline.* custom child uses base-relative inheritance: walk exact child/intermediate entries but stop before ui.modeline; reaching the base means "no override", so the segment inherits the modeline's already-mapped effective text color. This avoids taking ui.modeline's pre-reverse logical fg and applying it as a post-reverse glyph color. One shared Theme::modeline_segment_face helper owns this rule for TUI resolution and ThemeFacts production. A concrete custom foreground returns a mask-normalized Style { fg, ..Default::default() }; a found Default foreground stops inheritance and returns None (base). Out-of-mask components never enter the dynamic wire table.
GPU performs exact lookup in ThemeFacts; absence means base modeline text. Existing Indexed palette divergence remains the stage-1 accepted behavior.

For semantic peers at v18, the ThemeFacts inventory becomes:

fixed stage-1 UI_FACES
UNION
distinct face names of enabled statusline providers

The union is sorted/deduplicated. Custom names resolve through Theme::modeline_segment_face: exact/intermediate concrete foreground overrides are shipped, while a name that reaches the base or finds a Default foreground is omitted and therefore uses the frontend's effective modeline text. Thus an unset ui.modeline.lsp correctly follows a configured, possibly reversed ui.modeline without shipping a pre-reverse component under a post-reverse mask. Frontend lookup remains exact; the Q#TH7 ownership boundary does not move.

theme_facts_msg keys its computation on (theme.face_epoch, statusline.face_set_epoch) for a v18 peer. Both cache records advance on computation; payload equality can suppress a send. Removing/disabling the last provider for a custom face removes that entry from the next authoritative table. For v16/v17 peers the inventory stays the fixed stage-1 list: they cannot render segments and pay no irrelevant face traffic.

If a face-table change and segment payload occur in one frame, ThemeFacts is ordered before StatuslineSegments. A theme-only recolor sends ThemeFacts but not unchanged segment text; the GPU face arm invalidates both status shaping caches, so existing runs reshape under the new color. The invalid-evaluation authoritative-empty path uses this same ordering: a provider removal may remove its dynamic face from ThemeFacts, but its prior non-empty segment payload is replaced by empty vectors in that frame rather than being retained beside the reduced face inventory.

Q#SL7 - Wire: `StatuslineSegments`, protocol v18, appended final

/// One daemon-produced custom modeline segment. Text has already been
/// sanitized to one line; `face` is ui.modeline or a child name. A
/// custom override, when set, is resolved in the authoritative
/// ThemeFacts table; absence means the base modeline text color.
#[derive(Clone, Debug, Eq, PartialEq, Serialize, Deserialize)]
pub struct StatuslineSegment {
    pub text: String,
    pub face: String,
}

/// Arc 4 stage 3 (protocol v18): custom Lua modeline output for the
/// semantic frontend's current buffer. Complete replacement each
/// send; empty vectors authoritatively mean no custom segments.
StatuslineSegments {
    buffer_id: BufferId,
    left: Vec<StatuslineSegment>,
    right: Vec<StatuslineSegment>,
},

Append after FontFacts, the final v17 variant. Before appending, add a byte-level encoding pin of representative FontFacts values; the new variant's own round-trip cannot detect an accidental ordinal shift of old channels.
PROTOCOL_VERSION becomes 18; supported versions become 6..=18; the ladder accepts 18 and rejects 19. Add populated and empty postcard round-trips.
Daemon write-loop and producer both gate at negotiated >=18. A v17 GPU keeps today's built-in band. The grid TUI silently drops the semantic-only variant if one is delivered unexpectedly.
The payload contains custom provider output only. Existing StatusFacts remains unchanged at v15; widening it would move its whole gate to v18 and unnecessarily darken buffer/diagnostic facts for v15-v17 peers.
docs/semantic-frontend-protocol.md records the v18 schema, authoritative-empty rule, ordering after ThemeFacts, snapshot reset, and the division between custom daemon text and frontend-derived cursor/scroll.

Wire values are untrusted at the GPU boundary. Before replacing current state, the GPU validates the whole message atomically. The provider, segment-text, face, and total-text limits live as public constants in pmacs-protocol; registration/production and consumption do not copy numeric policy:

no more than 64 segments total across both sides;
total text bytes no more than 64 KiB;
each text is non-empty, at most 1024 bytes, and contains no control character;
each face is at most 256 bytes, contains no control character, and satisfies pmacs_protocol::is_modeline_face_name.

An invalid message is logged and ignored wholesale; the prior valid state remains. These bounds protect shaping/layout even if a malformed peer bypasses the trusted Lua producer.

Q#SL8 - Producer, emission baselines, and snapshot symmetry

SemanticRenderState gains:

peer_knows_statusline_segments: bool;
last_statusline: HashMap<BufferId, (Vec<StatuslineSegment>, Vec<StatuslineSegment>)>.

After viewport declaration and only when the declared buffer matches the frontend's active daemon window, the producer evaluates the active context and compares the complete ordered payload:

First sight of every buffer emits an authoritative message, including (left=[], right=[]).
Changed output emits one complete replacement.
Byte-identical output is silent even though callbacks were evaluated.
Back-to-back state changes before one frame legitimately coalesce into the latest payload.
on_buffer_snapshot_sent(buffer_id) removes that buffer's baseline. An unchanged A -> B -> A revisit must re-send A's segment payload.

The GPU BufferSnapshot arm clears its custom left/right segment mirror alongside status_facts, search, and menu. ThemeFacts and the provider registry remain global and survive. This is the #120 snapshot/baseline contract applied symmetrically, not a new special case.

Q#SL9 - TUI rendering: styled runs and display-column correctness

paint_mode_line stops flattening each side to an unstyled String. It receives logical runs (text, effective Style) and uses one shared single-row painter:

Before grapheme segmentation, every logical run passes through a shared terminal-control sanitizer: provider text, buffer names, mode markers, diagnostics/readouts, and compositor separators alike have all control scalars (including CR, LF, and ESC) replaced with spaces. Provider-return sanitation remains an earlier validation boundary; this final run-level pass is defense in depth for core-owned text. Consequently Glyph::Cluster, whose frontend emitter writes bytes verbatim, can never carry a terminal control sequence.
Runs are split with UnicodeSegmentation::graphemes; width and clipping use UnicodeWidthStr on each complete grapheme. This stage adds unicode-segmentation as a direct dependency rather than relying on cosmic-text's transitive copy.
A one-scalar grapheme writes Glyph::Char; a multi-scalar printable grapheme writes Glyph::Cluster. Every extra display column writes a Glyph::Continuation; clipping never emits half a wide grapheme. A standalone zero-column grapheme is skipped, while a combining sequence such as e + U+0301 remains one visible cluster.
Left/right collision uses display columns, not scalar count or UTF-8 bytes.
The row is still filled once with the ui.modeline base style. Built-in runs keep that style. A set segment face replaces only the run's visible foreground per Q#SL6, writing logical bg rather than fg when the base row is reversed.
Every separator inserted by Q#SL4 is likewise painted with this base style, regardless of the faces on either side.
When the protected built-in right suffix fits by itself, clipping the combined right group removes only the low-priority custom prefix and preserves that suffix in full. If the built-in suffix itself does not fit, the TUI retains today's wholesale drop instead of introducing a new partial-suffix policy. Left clipping keeps the prefix. No run can write outside its window rect or into another split's modeline.

With no visible provider output, the resulting cells are byte-for-byte the current modeline for ordinary ASCII buffers.

Q#SL10 - GPU application: rich runs, cache invalidation, clipping

GPU state stores the latest validated custom segment vectors plus their buffer_id. Composition filters them against current_buffer_id, the same belt as StatusFacts.

Right custom segments are inserted before diagnostic/cursor/scroll spans. Each segment becomes a rich-text run. The color resolver special-cases ui.modeline and an absent child to the already-mapped base modeline text color; a present child maps only its concrete fg, with defensive Default handling also selecting the base. It never re-applies the base face's pre-reverse logical foreground.
Ordinary left composition becomes rich text: buffer-name/modified base run followed by custom left runs; each Q#SL4 separator is its own base-color rich run. Modal/message states produce their existing single content run and no custom left runs. Right-side custom/built-in separators are likewise base-color runs, never extensions of an adjacent provider face.
The two shaping caches become Option<Vec<(text, explicit_color)>>, seeded/invalidation-set to None, and retain the complete ordered rich-run vectors after shape. Concatenation is not a sufficient key once "buffer" + custom can equal a transient/minibuffer string byte-for-byte while requiring different attributes; an empty vector is legitimate content, not an invalidation sentinel. Cache state advances only after the matching rich text has been installed.
Applying a changed StatuslineSegments payload clears both status shaping caches before redraw. This is required even when concatenated text is unchanged but a face name changed.
Both status glyphon buffers use Wrap::None, set at construction and retained across the FontFacts metric transaction. They remain single-line surfaces even when a custom segment is wider than the viewport.
Right placement uses the full shaped width without clamping its origin to TEXT_LEFT: the run's right edge stays at the right pad, while a negative/left-of-surface origin clips low-priority custom prefixes and preserves the built-in tail. This intentionally changes the legacy built-in-only narrow case, which anchored the readout at TEXT_LEFT and clipped its right tail.
The left TextArea clips at the right group's actual origin rather than retaining the legacy extra STATUS_TEXT_PAD gap. The right group therefore owns collision priority and may fully obscure the left buffer identity in an extremely narrow band. Existing geometry bounds still keep all glyphs inside the band.
ThemeFacts continues to invalidate both caches. FontFacts already re-metrics/re-shapes both status buffers; the new rich runs ride that path without a new font transaction.

The message does not request a viewport re-declaration: status text changes no code geometry or visible-line count.

Q#SL11 - Built-in LSP segment proves the extension point

After pmacs.statusline is installed, builtin/runtime/lsp.lua registers one right provider:

pmacs.statusline.register {
  name = "lsp",
  side = "right",
  priority = 0,
  face = "ui.modeline.lsp",
  fn = function(ctx)
    local rec = attachments[tostring(ctx.buffer)]
    if not rec then return nil end
    return "LSP:" .. pmacs.lsp.modeline_label(rec.server)
  end,
}

It is pure: it never triggers attachment, flushes didChange, or mutates the server. It indexes the private attachment map by ctx.buffer, so passive split windows show their own buffer's state. No attachment means nil, preserving today's modeline outside LSP-backed buffers.

The face name is intentionally a new child. Unset, it inherits ui.modeline/the built-in segment color. A user can theme LSP state without changing the whole band:

pmacs.theme.merge {
  ["ui.modeline.lsp"] = { fg = 6 },
}

The provider handle appears in pmacs.statusline.providers(), so user config can disable or reprioritize it without a special LSP option.

Bets

Additive providers are sufficient for the first extensibility stage: they deliver real package/user value without turning optimistic cursor/scroll facts into stale daemon text or destabilizing the existing default layout.
Static registration faces plus the dynamic ThemeFacts inventory keep inheritance daemon-owned and make face availability independent of callback output. No frontend walk or raw color enters the API.
Per-render Lua polling is the honest freshness mechanism. Generic callbacks can depend on LSP/process/plugin state with no shared epoch; payload comparison keeps the wire quiet, and an empty registry takes the O(1) fast path. The existing status_summary API was already shaped for one call per render frame.
Three-phase evaluation prevents the known core/registry RefCell hazards and fails closed across context-changing callbacks. It does not pretend arbitrary mutating render code is a supported scheduling model.
One authoritative v18 message per buffer plus snapshot-symmetric reset makes first attach, late join, and unchanged A -> B -> A revisits correct without an epoch on the wire.
The priority-at-the-protected-edge rule is deterministic and keeps today's essential built-ins readable under narrow layouts.
The first built-in LSP provider validates passive-window context, live async updates, arbitrary child faces, and cross-frontend wire rendering in one useful feature.

Deferred (named)

Wholesale replacement/removal/reordering of built-in buffer, diagnostic, cursor, and scroll components; a frontend-local custom cursor/scroll token vocabulary; customization of the global echo row; a second GPU bottom surface that would keep modeline left segments visible during minibuffer/search/messages exactly like the TUI; segment click/hover actions and mouse hit maps; multi-row statuslines; icons/images/resources; per-segment backgrounds, reverse, bold/italic/underline, and wider chrome masks; ui.modeline.inactive; borrowing face families outside ui.modeline; dynamic face names returned by callbacks; async/yielding providers; provider-specific separators; timed refresh scheduling below/above the normal frame cadence; automatic package ownership/unregister (packages retain handles and use unload hooks today); GPU splits/multi-buffer status bands (Arc 8 structural work); horizontal scrolling/marquee and ellipsis policies; repurposing or deleting the legacy ModeLine(Vec<Cell>) variant.

Acceptance

Primary suite: tests/statusline_segments_acceptance.rs for Lua, TUI, producer, and daemon/wire behavior; protocol pins stay in src/protocol.rs; GPU routes live in the headless PMACS_REQUIRE_GPU=1 suite. Dispatch/render tests use real RenderState/semantic frame paths, not direct helper-only formatting.

Default preservation: with no visible provider output, scratch TUI cells and ordinary non-overlapping GPU modeline/status-band pixels are byte-identical to the pre-stage rendering. The deliberate GPU narrow-band exception pins an over-wide built-in readout's right edge and clips its left edge; a built-in-only headless fixture pins that behavior. The global TUI echo row is unchanged.
Lua strict contract: valid registration returns a handle and appears in providers; bad/unknown side, empty name, non-integer or out-of-range priority, non-function fn, non-modeline face (including another valid ui.* family), control or over-limit name/face, provider 65, and unknown key all error with the field/key named and leave registry epochs and provider list untouched. A value-providing or raising metatable is never invoked. Protocol, core, producer, and GPU tests pin the same namespace predicate table through the shared helpers.
Handle lifecycle: priority and enable changes affect order/output and advance only their specified epochs; no-op setters do not; unregister is true then false; stale-handle setters return false; fractional/coerced priority and truthy non-boolean enable values error without mutation.
Callback result contract: string renders; nil and empty string omit without separators; newline/control output is sanitized; invalid UTF-8, non-string, and over-limit output omit that provider and report an error.
Error isolation and latch: a failing provider between two good providers does not suppress either neighbor or built-ins; one error lands in *errors*, repeated frames do not append duplicates, a successful evaluation clears the latch, and a later failure reports once again. In two splits, success in B does not re-arm a provider that remains failing in A; closing A or unregistering the provider releases that context's latch, and disable/re-enable starts a new failure run. Detaching a frontend releases every latch carrying its FrontendId; reconnecting and failing again reports once rather than inheriting suppression from the detached session.
Re-entrant registry mutation: a provider unregistering itself during evaluation causes no borrow panic and discards the old fan-out by epoch guard. A semantic producer test first establishes a non-empty payload (and its custom face) for the matching buffer, then triggers self-unregister/disable: the invalid evaluation emits one authoritative empty replacement, the reduced ThemeFacts precedes that replacement, the resulting GPU frame has no prior text, and the empty replacement becomes the emission baseline. The provider is absent and a still-empty next frame is wire-silent; a surviving good provider instead reappears on that next frame as a change from empty.
Context-change guard: callbacks that switch the window buffer, close a split, or kill the source buffer cannot publish text under the old context; the next frame evaluates the surviving truth.
Per-window context: two TUI splits on different buffers receive distinct ctx.window, ctx.buffer, and ctx.active values and render their own text. Focusing the other split flips only active; two frontends cannot consume each other's context/output.
Ordering and separators: mixed left/right providers with tied and distinct priorities produce the exact Q#SL4 order, stable id tie break, and one-space custom boundaries with nil providers absent; the built-in groups retain their legacy internal spacing. With two visibly different custom faces, every custom/custom and custom/built-in separator is pinned to the base ui.modeline style in TUI cells and GPU rich runs/pixels.
TUI placement: buffer identity remains first on the left; custom right segments precede diagnostics/L:C/scroll; the global echo row still shows pmacs.editor.set_status independently.
TUI Unicode and clipping bite: CJK, combining, and ASCII custom runs beside a right suffix occupy correct display columns with cluster/continuation cells and no overlap; the combining sequence is emitted rather than silently dropped. A narrow-split fixture whose built-in suffix fits by itself clips the low-priority custom edges while retaining that suffix in full and never writes outside its rect. A second fixture where the built-in suffix itself does not fit pins the current TUI wholesale-drop behavior. A buffer name containing CR, LF, and ESC is sanitized before segmentation: its resulting Glyph::Char / Glyph::Cluster cells and captured terminal bytes contain no raw control scalar or escape sequence.
LSP built-in: an unattached buffer adds nothing. Attached buffers show LSP:init/ready/idx/degraded/crashed/stopped as the tracker changes without a buffer edit, and LSP:? for a forgotten server id; a passive split uses its own attachment. Disabling/reprioritizing the discovered provider handle works.
Version and placement pins: protocol is 18; ladder accepts 6..=18 and rejects 19; empty/populated StatuslineSegments round-trip; a byte-level FontFacts encoding pin proves the append shifted no v17 discriminant.
Authoritative first frame and live output: a v18 session's first matching-viewport frame carries empty vectors when no provider is visible, then silence. A callback-state change with no edit/registry mutation emits exactly one updated payload; unchanged polling is wire-silent.
Init and late join: a provider/theme established from init.lua is present in the first attachment's first matching frame. The same established state is present in a later second session without a post-attach mutation.
Version gate: a real-daemon v17 semantic peer receives neither StatuslineSegments nor dynamic provider-only ThemeFacts entries and does not execute the provider; a v18 peer receives both. Daemon producer and write-loop gates are independently pinned.
TUI drop arm: the grid frontend consumes an unexpected StatuslineSegments message without error.
Snapshot round trip: after A's segment payload is established, A -> B -> A at unchanged generations re-sends A because the producer baseline reset; the GPU snapshot clears A's mirror immediately and restores the exact A pixels only after the authoritative re-send.
Dynamic face inventory: registering enabled ui.modeline.lsp adds its daemon-resolved exact name to v18 ThemeFacts only when a custom override exists; a configured ui.modeline parent is inherited through base absence (no redundant child entry), while an intermediate custom parent is shipped under the exact referenced child name with only fg retained; disabling/removing the last reference removes any custom entry. A priority-only change does not recompute the face set.
Message ordering and recolor: when registration and theme change together, ThemeFacts precedes StatuslineSegments. Recoloring a segment face with constant text emits ThemeFacts only and changes both TUI cells and GPU pixels through cache invalidation.
Face mask parity: a segment face carrying {fg=F,bg=B,reverse=true,bold=true} renders exactly like {fg=F} on both frontends, including under the TUI's default reverse row; an exact empty child blocks a colored intermediate parent and returns to the effective base text while retaining the base modeline surface.
GPU normal composition: ordinary state renders buffer identity plus differently faced custom left runs, and custom right runs before colored diagnostics and optimistic cursor/scroll. A changed face name with identical concatenated text still reshapes.
GPU precedence: minibuffer, isearch, and transient status each suppress custom left segments while preserving custom right and the existing right facts; closing the modal/message restores the custom left payload without requiring a new segment message. A fixture makes the ordinary rich composition and transient message concatenate to identical bytes and proves both transitions reshape with the correct attributes.
GPU narrow-band clipping: an over-wide right provider is clipped at the left edge while diagnostic/L:C/scroll pixels remain at the right; left content stops before the right origin. Bounds contain all glyphs at both stage-2 font-size limits. A wrapping-sensitive fixture proves both status buffers remain one visual row.
GPU wire validation: direct messages with too many segments, excess bytes, control text, overlong/invalid face names, or a face outside ui.modeline are rejected atomically with the prior valid frame byte-identical and no panic; boundary-valid payloads apply. The predicate cases are the same table exercised by Lua/core tests, not a copied GPU interpretation.
Unsupported-peer cost: a semantic v17 render with an enabled side-effect-counting callback never invokes it. Grid TUI and v18 semantic renders invoke exactly once per target window per frame.
Docs/handoff: semantic protocol documents v18 and ownership; docs/package-author-guide.md shows register/unregister lifecycle and passive ctx.buffer use; the roadmap/handoff record Arc 4 complete once the implementation lands.

53 KiB Raw Blame History