ModApi: Widget system & Footer

Feature Description

Disclaimer: This message was synthesized by an AI from a long, unstructured Markdown file of notes accumulated while building real mods. Use cases have been kept intentionally simple and generic. If anything seems off or incoherent, feel free to ask for clarification.

1. cmd.ui.widget() — actually wired in the TUI

Problem: cmd.ui.widget() exists in the API and is used in community mods (e.g. David Thyresson's weather mod), but it's currently a no-op — the widget renders nowhere. The docs explicitly say: "Widgets are not wired into the TUI yet."

Use case: Any mod that wants to show persistent information above the editor (status, live counter, etc.) is currently blocked. The code exists; it just needs to be wired up.

---

2. w.update() — update a widget without recreating it

Problem: To update a widget's content, you have to .dispose() it and create a new one. This causes flickering and unnecessary boilerplate.

Use case: Any widget displaying live or periodically refreshed data needs to update its content without destroying and recreating the whole component.

const w = cmd.ui.widget({ render: () => ['loading...'] });
// later:
w.update(() => [`${count} items`]);

---

3. Structured cmd.ui.setStatus() with colored badges

Problem: setStatus() only supports plain text in the footer. No color, no icon, no badge styling.

Use case: A mod that tracks some state would benefit from a colored, iconified badge in the footer rather than unformatted text.

cmd.ui.setStatus([
  { text: 'active', color: 'green', icon: '●' },
  { text: '14 items', color: 'yellow', icon: '📦' },
]);

---

4. Theming / shared color palette across mods

Problem: Every mod hardcodes its own colors. There's no way to share a theme across multiple mods, or let the user customize the visual style.

Use case: An author publishing a set of related mods would want them to share a consistent visual identity without duplicating ANSI constants across every file. Users would benefit from being able to adjust colors to match their terminal theme.

#PART 2

4. Double-buffering — Flicker-free rendering

Problem: When a mod updates its display (widget refresh, status change, progress bar), the entire screen redraws character by character, causing visible flicker. This is the TUI equivalent of a 1995 web page. The user sees the screen flash on every update, which makes live data displays unusable.

Use case: A mod that updates a live counter or progress bar every second produces visible flickering that makes the interface feel broken. Double-buffering renders to an off-screen buffer first, then swaps atomically — zero flicker, smooth updates.

// Implicit — the TUI renderer handles it
// But needs to be enabled/wired at the framework level
cmd.ui.enableDoubleBuffer();

References: terminui (double-buffered by default — "renders to an off-screen buffer, then flushes to the terminal in one write"), Ratatui (full double-buffer with implicit flush — the standard for Rust TUIs), Ink (React reconciliation = implicit double-buffer via virtual DOM diffing). No modern TUI renders directly to stdout anymore. The old approach causes flicker because each character write triggers a terminal repaint.

Use Case

No response

Additional Context

No response

How important is this to you?

None

Inizia individuando i punti di ingresso cmd.ui.widget(), w.update() e cmd.ui.setStatus() e il renderer TUI a cui alimentano. Definisci l’ambito del rendering dei widget, dei badge di stato, del theming condiviso e del double-buffering prima di modificare qualsiasi cosa; il lavoro è completato quando i comportamenti richiesti funzionano senza sfarfallio e sono utilizzabili dai mods.