ModApi: UI Layout & Display primitives

[Fletu94]

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.panel() / cmd.ui.divider() — native layout helpers

Problem: Every mod that wants to display a panel or separator has to rewrite the same ~50 lines of utilities (terminal width handling, ANSI, padding). There's no visual consistency across community mods.

Use case: Any mod that displays structured output in the feed currently duplicates the same layout boilerplate. A shared cmd.ui.panel(['line 1'], { title: 'my-mod' }) and cmd.ui.divider() would give all mods a consistent look for free.

---

2. cmd.ui.table() — structured data display

Problem: Displaying a formatted table requires manual .padEnd() per column, which breaks as soon as data changes or the terminal is too narrow.

Use case: Any mod that shows structured data with multiple columns (name, value, status, etc.) would benefit from a standard table primitive rather than fragile manual padding.

cmd.ui.table({
  headers: ['Name', 'Value', 'Status'],
  rows: [['item-1', '42', 'ok']],
  align: ['left', 'right', 'left'],
});

---

3. cmd.ui.spacing() — explicit spacing

Problem: Adding blank lines between display blocks currently requires console.log(""). This is non-standard and bypasses the API.

Use case: Any mod that displays multiple panels or sections needs a clean, idiomatic way to add vertical spacing.

cmd.ui.spacing(2); // 2 blank lines

---

4. cmd.ui.clearFeed() — clear the feed

Problem: There's no way to clear old messages from the feed. A mod that displays updates periodically accumulates lines that stay forever.

Use case: A mod that shows a regularly updated report should be able to clear its previous output and redisplay cleanly, rather than appending duplicate blocks on every update.

cmd.ui.clearFeed({ keepLast: 5 });

---

PART2

1. cmd.ui.layout() — Native layout system (flexbox/grid)

Problem: There is no way to position elements relative to each other. Every mod stacks panel() on top of panel() and manually handles padding and width. When the terminal is too narrow, everything breaks. There is no visual consistency across community mods because each one reinvents its own layout boilerplate.

Use case: A mod that displays a dashboard with stats on top and a chart below must manually calculate widths, handle line wrapping, and adapt to terminal size. A native layout system would solve this in one call.

cmd.ui.layout({
  direction: 'column',
  children: [
    cmd.ui.box({ flex: 1, children: [statsPanel] }),
    cmd.ui.box({ flex: 2, children: [chartPanel] }),
  ],
});

References: OpenTUI (native Flexbox with Box and Text components — used in production by OpenCode), Ink (React Flexbox for terminals — used by Claude Code, Amp, Gemini CLI), Ratatui (constraints system with min/max widths — used by Netflix, AWS, OpenAI), terminui (layout engine with JSX — 10+ widgets). The TUI Renaissance article (2026) notes: "Every modern TUI has a layout system — it's the foundation."

---

2. Responsive layout — Terminal resize handling

Problem: When the user resizes the terminal window, mod outputs break — panels overflow, text gets cut off, alignment is lost. There is no way for a mod to react to resize events or define minimum sizes.

Use case: A mod that displays a table with 5 columns should collapse to 3 columns when the terminal is narrow, or switch to a compact view. Currently it just wraps ugly and becomes unreadable.

cmd.ui.onResize(({ width, height }) => {
  if (width < 80) setCompactMode(true);
});

References: OpenTUI (terminal-aware rendering with layout constraints), Ink (automatic resize handling via React reconciler), Ratatui (layout constraints with min/max widths — flexgrow/flexshrink), Bubble Tea (WindowMsg for resize events). Every modern TUI handles this gracefully.

---

3. Native Code / Markdown / Diff components

Problem: Displaying code blocks, markdown, or diffs requires manual ANSI formatting. There is no syntax highlighting, no markdown rendering, no word-level diff — just raw text with bold/italic. Mods that show code reviews or file changes produce unreadable output.

Use case: A mod that shows a code review or file diff should display syntax-highlighted code with proper indentation, not plain text with manual color codes. A mod that displays documentation should render markdown headings, lists, and code blocks correctly.

cmd.ui.code({ language: 'typescript', content: codeString });
cmd.ui.markdown({ content: readmeContent });
cmd.ui.diff({ old: original, new: modified });

References: OpenTUI (Code, Markdown, Diff, Tree-sitter components — native syntax highlighting for any language), bat (syntax highlighting for 200+ languages — 63K GitHub stars), delta (word-level diff with syntax highlighting — used by Claude Code), Tree-sitter (incremental parsing — used by Neovim, Zed). These are solved problems in the TUI ecosystem.

7. cmd.ui.image() — Native image rendering with thumbnail/expand

Problem: There is no way to display images inline in the terminal feed. Mods that want to show visual content must use a text placeholder like [#1image] or skip them entirely.

Use case: A mod that generates reports, previews, or visual summaries should display a small thumbnail image in the feed. When the user selects it, the image expands to full size. On terminals that support image protocols (Kitty, Sixel, iTerm2), thumbnails render as actual images. On unsupported terminals, a styled placeholder is shown.

cmd.ui.image({
  path: '/path/to/chart.png',
  width: 20,  // thumbnail width in columns
  expandable: true,  // click to view full size
});

References: OpenTUI (native Image component), Ratatui (ratatui-image — Kitty/Sixel/iTerm2), Textual (textual-image), Ink (ink-image), chafa (auto-detects protocol — 4.9K stars), timg (image + video viewer — 2.7K stars). Three protocols exist today: Kitty graphics (best quality), Sixel (broadest compat), iTerm2 inline (macOS). WezTerm supports all three. Fallback on unsupported terminals shows a styled placeholder.

No response

Additional Context

No response

How important is this to you?

None