@ssebastien/tcmd 0.1.3 → 0.1.7

package/src/js/tcmd/components/Frame.js

@@ -0,0 +1,324 @@
+// Project: TinyCommand
+// Author:  Sebastien Pierre
+// License: BSD
+// Created: 2026-10-02
+
+// Module: tcmd/components/Frame
+// Shared presentation helpers for the workspace chrome: the responsive
+// breakpoints driven by the `uiSize` cell, the pane borders, header rules, the
+// command-bar geometry and the overlay visibility gates. Everything here is
+// injected into each renderer's App binding. Viewport dimensions are in
+// monospace columns/rows; the browser measures them from its own font. The key
+// reference's text lives with its overlay in `Help.js`.
+
+import { unwrap } from "select/state/cells"
+import { commandBarStatus } from "./CommandBar.js"
+import pkg from "../../../../package.json" with { type: "json" }
+
+// Constant: VERSION
+// The published version, read from package.json so the identity bar can never
+// drift from what ships.
+const VERSION = `${pkg?.version ?? ""}`
+
+// Constant: MODE_SLOTS
+// Per-letter slots the identity bar draws the view-mode word through, one
+// `<text>` each so every letter can carry its own gradient colour (the same
+// trick the `TinyCmd` brand uses). Sized for the longest mode name; a shorter
+// one leaves the trailing slots empty, and an empty text node takes no column.
+const MODE_SLOTS = "commander".length
+
+// Function: modeWord
+// The view-mode name as it reads in the identity bar.
+function modeWord(viewMode) {
+	return viewMode === "explorer" ? "explorer" : "commander"
+}
+
+// Function: modeGradient
+// The `[from, to]` brand pair a mode word shimmers along: explorer takes the
+// Tiny blues, commander the Cmd oranges, so the mode reads as part of the
+// logo rather than as trailing status text.
+function modeGradient(env, viewMode) {
+	return viewMode === "explorer"
+		? [env.theme.brandTinyFrom, env.theme.brandTinyTo]
+		: [env.theme.brandCmdFrom, env.theme.brandCmdTo]
+}
+
+// Function: versionTrail
+// The identity bar's version tail, ` · 0.1.3`. It carries its leading space
+// so it follows the mode word's slots directly in both renderers.
+function versionTrail() {
+	return VERSION ? ` · ${VERSION}` : ""
+}
+
+// Below this the two-pane workspace is replaced by a resize hint.
+const MIN_WIDTH = 64
+const MIN_HEIGHT = 16
+// At or above this the inspector can sit beside the panes; below it becomes a
+// fullscreen overlay.
+const INSPECTOR_INLINE_WIDTH = 100
+
+// Function: sizeOf
+// Reads the viewport size from the App data, falling back to the renderer's
+// own dimensions so the gates work even when no `uiSize` cell is injected
+// (tests, web). Returns `null` when neither is known.
+function sizeOf(data, self) {
+	const size = unwrap(data?.uiSize)
+	if (size && (size.width || size.height)) return size
+	const width = Math.floor(self?.ctx?.width ?? 0)
+	const height = Math.floor(self?.ctx?.height ?? 0)
+	if (!width && !height) return null
+	return { width, height }
+}
+
+// Function: isNarrow
+// True when the viewport is known and too narrow for the inline inspector.
+function isNarrow(data, self) {
+	const size = sizeOf(data, self)
+	return Boolean(size && (size.width ?? 0) > 0 && size.width < INSPECTOR_INLINE_WIDTH)
+}
+
+// Function: isExplorer
+// True when the workspace is the three-column explorer view. Absent
+// `viewMode` data (tests, host-less bindings) means the two-pane commander.
+function isExplorer(data) {
+	return unwrap(data?.viewMode) === "explorer"
+}
+
+// Function: currentColumnId
+// The id of the column holding the current directory: the focused pane when
+// focus is on source/destination, the anchor pane otherwise. (`core/pane` has
+// the same question over a session; this one reads the view's data bag.)
+function currentColumnId(data) {
+	return `${unwrap(data?.currentId) ?? unwrap(data?.active) ?? "left"}`
+}
+
+// Constant: PANE_GROW
+// The explorer's current column is this much wider than the parent/preview
+// mirrors — enough to read as the working pane, not enough to starve its
+// neighbours. Both renderers apply the same ratio (the TUI's pane row growers
+// and the web CSS `.pane.is-major`), so the geometry has one source of truth
+// here.
+const PANE_GROW = 1.35
+
+// Function: paneColumnWidth
+// The columns a pane's column occupies at viewport `width` for the current
+// view. Explorer leads with the parent mirror and grows the current column by
+// PANE_GROW, so its mirrors are narrower than an even split; commander tiles
+// its two panes evenly. The inline inspector adds an equal column to either.
+// Panes hidden in the view, and an unknown viewport (`width <= 0`), are 0.
+//
+// The caller subtracts its own chrome (border, inset, safety) to get a content
+// budget: feeding every pane an even `width / columns` makes the narrower
+// mirror columns overflow, and the renderer then mangles their breadcrumbs.
+function paneColumnWidth(width, paneId, { viewMode, currentId, showPreview } = {}) {
+	const total = Math.floor(width ?? 0)
+	if (total <= 0) return 0
+	const weights = {}
+	if (viewMode === "explorer") {
+		weights.parent = 1
+		weights[`${currentId}` === "right" ? "right" : "left"] = PANE_GROW
+	} else {
+		weights.left = 1
+		weights.right = 1
+	}
+	if (Boolean(showPreview) && total >= INSPECTOR_INLINE_WIDTH) weights.preview = 1
+	const weight = weights[paneId] ?? 0
+	if (weight <= 0) return 0
+	const sum = Object.values(weights).reduce((acc, value) => acc + value, 0)
+	return Math.floor((total * weight) / sum)
+}
+
+// Function: paneListHeight
+// Rows available to a pane's listing: the viewport height minus the app header
+// (1 row in the web UI, 2 for the desktop toolbar), the pane border (2), pane
+// header + rule (2), entry detail (2), and the command bar when visible. Fed to
+// the windowed `filelist` so a large directory mounts only the visible slice.
+// `0` means "unknown — render everything to measure".
+function paneListHeight(data, self) {
+	const height = Math.floor(sizeOf(data, self)?.height ?? 0)
+	if (height <= 0) return 0
+	const desktop = Boolean(unwrap(data?.desktopMode))
+	// A notice or error keeps a one-line status in desktop mode; otherwise that
+	// renderer has no bottom command bar at all. The bar is always one line.
+	const bar = commandBarStatus(data) || !desktop ? 1 : 0
+	return Math.max(1, height - (desktop ? 8 : 7) - bar)
+}
+
+// Function: mixHex
+// Linear interpolation between two `#rrggbb` colours at `t` in [0, 1]. A
+// missing colour (the mono theme) yields `undefined` so the whole run falls
+// back to the terminal default.
+function mixHex(from, to, t) {
+	if (!from || !to) return undefined
+	const channel = (index) => {
+		const a = Number.parseInt(from.slice(index, index + 2), 16)
+		const b = Number.parseInt(to.slice(index, index + 2), 16)
+		return Math.round(a + (b - a) * t)
+			.toString(16)
+			.padStart(2, "0")
+	}
+	return `#${channel(1)}${channel(3)}${channel(5)}`
+}
+
+// Function: shineOf
+// One `{ letter, fg }` per letter of a brand word, interpolating `from` → `to`
+// across it so the word reads as a gradient; a missing colour (mono theme)
+// leaves every `fg` undefined and the run falls back to the terminal default.
+function shineOf(letters, from, to) {
+	return `${letters}`.split("").map((letter, index, all) => ({
+		letter,
+		fg: mixHex(from, to, index / (all.length - 1)),
+	}))
+}
+
+// Function: createFrameBehaviors
+// Behaviors for the App root and its chrome.
+function createFrameBehaviors(env) {
+	const tiny = shineOf("Tiny", env.theme.brandTinyFrom, env.theme.brandTinyTo)
+	const cmd = shineOf("Cmd", env.theme.brandCmdFrom, env.theme.brandCmdTo)
+	// The mode word, letter by letter: `modeL<i>` is the letter, `modeFg<i>`
+	// its gradient colour — the same per-letter trick the `TinyCmd` brand
+	// uses, since a terminal has no gradient to draw. The run is cached per
+	// word (there are only two), and both behaviors read the live `viewMode`,
+	// so flipping `t` redraws it in the other brand's colours.
+	const modeRuns = new Map()
+	const modeRun = (data) => {
+		const viewMode = unwrap(data?.viewMode)
+		const word = modeWord(viewMode)
+		let run = modeRuns.get(word)
+		if (!run) {
+			run = shineOf(word, ...modeGradient(env, viewMode))
+			modeRuns.set(word, run)
+		}
+		return run
+	}
+	const modeSlots = {}
+	for (let i = 0; i < MODE_SLOTS; i++) {
+		// The `when` gate matters: an empty text node still claims a column in
+		// the row, so the slots past the end of a shorter word are dropped
+		// from the layout instead of padding it.
+		modeSlots[`modeHas${i}`] = (_self, data) => modeRun(data)[i] !== undefined
+		modeSlots[`modeL${i}`] = (_self, data) => modeRun(data)[i]?.letter ?? ""
+		modeSlots[`modeFg${i}`] = (_self, data) => modeRun(data)[i]?.fg
+	}
+	return {
+		// Identity bar: "Tiny" shimmers along the brand blues, "Cmd" along a
+		// brighter orange than the mark accent, and the host trail follows in
+		// the heading colour. Everything else on screen belongs to the user's
+		// files; this one row is the app's own.
+		brandT: () => tiny[0].letter,
+		brandTFg: () => tiny[0].fg,
+		brandI: () => tiny[1].letter,
+		brandIFg: () => tiny[1].fg,
+		brandN: () => tiny[2].letter,
+		brandNFg: () => tiny[2].fg,
+		brandY: () => tiny[3].letter,
+		brandYFg: () => tiny[3].fg,
+		brandC: () => cmd[0].letter,
+		brandCFg: () => cmd[0].fg,
+		brandM: () => cmd[1].letter,
+		brandMFg: () => cmd[1].fg,
+		brandD: () => cmd[2].letter,
+		brandDFg: () => cmd[2].fg,
+		topBar: (_self, data) => {
+			const host = `${unwrap(data.appHost) ?? ""}`.trim()
+			return host ? ` - ${host} ` : " "
+		},
+		topBarFg: () => env.theme.textHeadingFg,
+		// Right-aligned trail: the version, following the gradiented mode word
+		// (`modeL*`) slot by slot. Dimmer than the brand, so the row still
+		// reads left to right.
+		topBarStatus: () => versionTrail(),
+		topBarStatusFg: () => env.theme.textSecondaryFg,
+		...modeSlots,
+
+		// Responsive gates. `uiSize` is absent in tests and the web, so the
+		// workspace renders normally there.
+		tooSmall: (self, data) => {
+			const size = sizeOf(data, self)
+			if (!size) return false
+			return (size.width ?? MIN_WIDTH) < MIN_WIDTH || (size.height ?? MIN_HEIGHT) < MIN_HEIGHT
+		},
+		minSizeTitle: () => "Terminal too small",
+		minSizeHint: (self, data) => {
+			const size = sizeOf(data, self) ?? { width: 0, height: 0 }
+			return `need ${MIN_WIDTH}x${MIN_HEIGHT}, have ${size.width ?? 0}x${size.height ?? 0}`
+		},
+		// The min-size gate text uses the heading/secondary text tokens.
+		titleFg: () => env.theme.textHeadingFg,
+		dimFg: () => env.theme.textSecondaryFg,
+
+		// Each pane is a complete box. Both draw all four edges (the middle
+		// shows two adjacent rules) so each pane's border colour can track its
+		// own focus independently — a shared edge would be owned by one pane
+		// and never highlight when the other is active.
+		leftBorder: () => ["top", "left", "bottom", "right"],
+		rightBorder: () => ["top", "left", "bottom", "right"],
+		// The header rule separates the pane header row from the listing body.
+		headRule: () => ["top"],
+
+		// The breadcrumb yields the pane header row to the filter while a
+		// filter is being edited or applied.
+		leftFilterOn: (_self, data) => Boolean(unwrap(data.leftFilter)),
+		rightFilterOn: (_self, data) => Boolean(unwrap(data.rightFilter)),
+		parentFilterOn: (_self, data) => Boolean(unwrap(data.parentFilter)),
+
+		// Which columns the workspace draws. Commander tiles source and
+		// destination; explorer drops destination for the parent of the
+		// current directory, which leads the row so the current pane stays in
+		// the middle. The inspector column follows `showInspectorInline` and
+		// completes the three columns in either mode. Maximizing the inspector
+		// (`⇧V`) hides every column so the preview can take the row.
+		showParentPane: (_self, data) => isExplorer(data) && !unwrap(data?.previewFull),
+		showLeftPane: (_self, data) =>
+			(!isExplorer(data) || currentColumnId(data) === "left") && !unwrap(data?.previewFull),
+		showRightPane: (_self, data) =>
+			(!isExplorer(data) || currentColumnId(data) === "right") && !unwrap(data?.previewFull),
+
+		// The inline inspector shows when the preview is on and the viewport is
+		// wide enough; the viewer overlay shows whenever it is open, at any
+		// width (`v` on a narrow terminal, or Enter on a file that cannot be
+		// edited). Maximizing (`⇧V`) replaces the column with
+		// `showPreviewFull` below.
+		inspectorNarrow: (self, data) => isNarrow(data, self),
+		showInspectorInline: (self, data) =>
+			Boolean(unwrap(data.showPreview)) && !isNarrow(data, self) && !unwrap(data?.previewFull),
+		showViewer: (_self, data) => Boolean(unwrap(data.viewerOpen)),
+		// The maximized inspector: the preview fills the pane row in either
+		// view mode, pushed by `view.maximize` (`⇧V`).
+		showPreviewFull: (_self, data) => Boolean(unwrap(data?.previewFull)),
+
+		// Help overlay visibility; the content lives in `Help.js` so the
+		// overlay has a single source of truth.
+		helpOpen: (_self, data) => Boolean(unwrap(data.helpOpen)),
+
+		// The shared list overlay (history / trash) is mounted whenever a mode
+		// is set; the component itself gates on `open`.
+		overlayOpen: (_self, data) => Boolean(unwrap(data.overlay)),
+
+		// The windowed listing height for both panes (they share the row).
+		listViewport: (self, data) => paneListHeight(data, self),
+
+		// The command bar's height: always a single line, status or key hints.
+		barHeight: () => 1,
+	}
+}
+
+export {
+	createFrameBehaviors,
+	currentColumnId,
+	INSPECTOR_INLINE_WIDTH,
+	isExplorer,
+	isNarrow,
+	MIN_HEIGHT,
+	MIN_WIDTH,
+	MODE_SLOTS,
+	modeGradient,
+	modeWord,
+	PANE_GROW,
+	paneColumnWidth,
+	sizeOf,
+	versionTrail,
+	VERSION,
+}
+// EOF

package/src/js/tcmd/components/Help.html

@@ -0,0 +1,15 @@
+<section class="help" when="open" role="dialog" aria-modal="true" aria-label="Key reference" tabindex="-1" on:click="!dialog:help-cancel">
+	<div class="help-dialog" on:click="dialogStop">
+		<header out="title"></header>
+		<div class="help-columns">
+			<div class="help-column" out="leftRows"></div>
+			<div class="help-column" out="rightRows"></div>
+		</div>
+		<footer class="help-footer">
+			<span class="help-bracket" out="hintOpen"></span>
+			<span class="help-title" out="hintHead"></span>
+			<span class="help-key" out="hintKeys"></span>
+			<span class="help-bracket" out="hintClose"></span>
+		</footer>
+	</div>
+</section>

package/src/js/tcmd/components/Help.js

@@ -0,0 +1,260 @@
+// Project: TinyCommand
+// Author:  Sebastien Pierre
+// License: BSD
+// Created: 2026-10-02
+
+// Module: tcmd/components/Help
+// Shared behavior for the `?` key reference overlay, plus the reference data
+// itself. The categories are built from the live keymap and command registry,
+// so they cannot drift from the actual bindings. The TUI keeps the bracket
+// shorthand (`[Open ⏎]`); the web renders toolbar-like action chips with Lucide
+// icons and key badges. Rows are balanced across two columns with bright
+// uppercase section headings. Both presentations (`Help.xml` / `Help.html`)
+// render the same row data through `HelpRow`.
+
+import { unwrap } from "select/state/cells"
+import { DEFAULT_KEYMAP, keyGlyph } from "../core/keymap.js"
+import { getCommands } from "../core/commands.js"
+import { commandLabel, keyGlyph as keyLabelGlyph } from "./CommandItem.js"
+
+// Constant: BRACKET
+// The shorthand delimiters, shared with the command bar.
+const OPEN = "["
+const CLOSE = "]"
+
+// Constant: CLOSE_HINT
+// The footer shorthand: Esc dismisses the overlay.
+const CLOSE_HINT = { title: "Close", keys: "Esc" }
+
+// Constant: BOLD
+// OpenTUI's `TextAttributes.BOLD` bit, set on section headings through the
+// TUI's `out:attributes` slot. The web bolds through CSS instead.
+const BOLD = 1
+
+// Constant: GROUP_ORDER / GROUP_TITLES
+// Help sections, in display order.
+const GROUP_ORDER = ["nav", "pane", "list", "bookmark", "view", "file", "history", "trash", "panel", "filter", "app"]
+const GROUP_TITLES = {
+	app: "Session",
+	bookmark: "Bookmarks",
+	file: "Files",
+	filter: "Filter",
+	history: "History",
+	list: "Selection",
+	nav: "Navigation",
+	panel: "Commands",
+	pane: "Panes",
+	trash: "Trash",
+	view: "View",
+}
+
+// Toolbar actions and key-reference entries share Lucide icons in the web UI.
+// The TUI keeps its compact textual row layout.
+const HELP_ICONS = {
+	"nav.up": "arrow-up",
+	"nav.down": "arrow-down",
+	"nav.jumpUp": "arrow-up",
+	"nav.jumpDown": "arrow-down",
+	"nav.pageUp": "arrow-up",
+	"nav.pageDown": "arrow-down",
+	"nav.home": "arrow-up",
+	"nav.end": "arrow-down",
+	"pane.enter": "arrow-right",
+	"pane.up": "arrow-up",
+	"pane.back": "arrow-left",
+	"pane.forward": "arrow-right",
+	"pane.toggle": "columns-2",
+	"pane.reload": "refresh-cw",
+	"list.mark": "check",
+	"bookmark.open": "bookmark",
+	"view.togglePreview": "panel-right",
+	"view.maximize": "maximize",
+	"view.toggleMode": "columns-2",
+	"file.mkdir": "folder-plus",
+	"file.open": "file",
+	"file.edit": "file-text",
+	"history.open": "refresh-cw",
+	"history.undo": "arrow-left",
+	"history.redo": "arrow-right",
+	"trash.open": "trash",
+	"panel.open": "terminal",
+	"panel.shell": "terminal",
+	"filter.start": "search",
+	"app.quit": "power",
+	"app.help": "circle-question-mark",
+}
+
+// Function: helpGroups
+// The categorized key reference as `{ title, rows }` groups in display order.
+// One row per command, with every distinct chord from the live keymap. The
+// registry provides the action title.
+function helpGroups() {
+	const byId = new Map(getCommands().map((command) => [command.id, command]))
+	const groups = new Map()
+	for (const binding of DEFAULT_KEYMAP) {
+		const command = byId.get(binding.command)
+		if (!command) continue
+		const group = binding.command.split(".")[0]
+		if (!groups.has(group)) groups.set(group, new Map())
+		const rows = groups.get(group)
+		if (!rows.has(binding.command)) rows.set(binding.command, { keys: [], id: binding.command, title: command.title })
+		const row = rows.get(binding.command)
+		const glyph = keyGlyph(binding)
+		if (!row.keys.includes(glyph)) row.keys.push(glyph)
+	}
+	const out = []
+	for (const group of GROUP_ORDER) {
+		const rows = groups.get(group)
+		if (!rows) continue
+		const list = []
+		for (const row of rows.values()) {
+			list.push({ id: row.id, title: row.title, keys: row.keys.map(keyLabelGlyph).join("/") })
+		}
+		out.push({ title: GROUP_TITLES[group] ?? group, rows: list })
+	}
+	return out
+}
+
+// Function: helpLines
+// The flat reference: group headings and rows, one per line, blank line
+// between groups (the single-column fallback).
+function helpLines() {
+	const lines = []
+	for (const group of helpGroups()) {
+		lines.push(group.title)
+		for (const row of group.rows) lines.push(commandLabel(row).trim())
+		lines.push("")
+	}
+	return lines
+}
+
+// Function: helpBlocks
+// The reference split into two columns balanced by line count, as flat lists of
+// renderable blocks: `{ type: "section", label }` headings,
+// `{ type: "entry", open, head, keys, close }` rows and `{ type: "spacer" }`
+// blank lines between groups. Every entry title and key is padded to the widest
+// one across both columns, so all brackets share one width and the keys align
+// down each column (keys right-aligned against the closing bracket).
+function helpBlocks() {
+	const groups = helpGroups()
+	const commands = new Map(getCommands().map((command) => [command.id, command]))
+	let titleWidth = 0
+	let keyWidth = 0
+	for (const group of groups) {
+		for (const row of group.rows) {
+			titleWidth = Math.max(titleWidth, row.title.length)
+			keyWidth = Math.max(keyWidth, keyLabelGlyph(row.keys).length)
+		}
+	}
+	const columns = [[], []]
+	const loads = [0, 0]
+	for (const group of groups) {
+		const at = loads[0] <= loads[1] ? 0 : 1
+		columns[at].push({ type: "section", key: `section:${group.title}`, label: group.title.toUpperCase() })
+		for (const row of group.rows) {
+			const command = commands.get(row.id)
+			// The compact web badge shows the command's canonical key when the
+			// registry has one (lowercase `b`, `Spc`, `⇥`); otherwise fall back
+			// to the keymap chords, which may list several alternatives.
+			const shortcut = command?.keys ? keyLabelGlyph(command.keys) : keyLabelGlyph(row.keys)
+			columns[at].push({
+				type: "entry",
+				key: `entry:${row.id}`,
+				icon: HELP_ICONS[row.id] ?? "chevron-right",
+				title: row.title,
+				shortcut,
+				open: OPEN,
+				head: `${row.title.padEnd(titleWidth)} `,
+				keys: keyLabelGlyph(row.keys).padStart(keyWidth),
+				close: CLOSE,
+			})
+		}
+		// A blank row separates the groups (and costs one line, like the
+		// heading).
+		columns[at].push({ type: "spacer", key: `spacer:${group.title}` })
+		// A group costs its rows plus its heading and the blank after it.
+		loads[at] += group.rows.length + 2
+	}
+	// The blank line separates groups, so the bottom of each column ends on its
+	// last entry instead.
+	for (const column of columns) {
+		if (column[column.length - 1]?.type === "spacer") column.pop()
+	}
+	return { left: columns[0], right: columns[1] }
+}
+
+// Function: createBehaviors
+// Builds the Help behavior map for the given renderer environment.
+function createBehaviors(env) {
+	return {
+		bg: () => env.theme.surfaceBg,
+		borderFg: () => env.theme.borderPrimaryActiveFg,
+		dimFg: () => env.theme.textSecondaryFg,
+		leftRows: (self, data) => env.rows?.(self, data, "left") ?? [],
+		rightRows: (self, data) => env.rows?.(self, data, "right") ?? [],
+		// The reference has no cursor for the scrollbox to follow, so its
+		// vertical bar is driven here: visible only while the two columns
+		// actually overflow the viewport. The viewport height is derived from
+		// the injected `size` (so the bar tracks a resize) and the dialog's own
+		// geometry (`Help.xml`: 82% tall, minus padding, borders, rule and
+		// footer).
+		scrollbar: (self, data) => {
+			const scroll = self?.ref?.scroll
+			const bar = scroll?.verticalScrollBar
+			if (!bar) return ""
+			const height = unwrap(data?.size)?.height ?? self?.ctx?.height ?? 0
+			const viewport = height > 0 ? Math.floor(height * 0.82) - 6 : 0
+			const columns = helpBlocks()
+			const rows = Math.max(columns.left.length, columns.right.length)
+			const want = viewport > 0 && rows > viewport
+			if (bar.visible !== want) bar.visible = want
+			return ""
+		},
+		open: (_self, data) => Boolean(unwrap(data.open)),
+		// The footer shorthand reads like the bar: dim brackets, bright title,
+		// accent key.
+		hintOpen: () => OPEN,
+		hintHead: () => `${CLOSE_HINT.title} `,
+		hintKeys: () => CLOSE_HINT.keys,
+		hintClose: () => CLOSE,
+		bracketFg: () => env.theme.textSecondaryFg,
+		headFg: () => env.theme.textFg,
+		keyFg: () => env.theme.accentFg,
+		// Separator rule above the footer (a top border on a one-row box).
+		rule: () => ["top"],
+		ruleFg: () => env.theme.textSecondaryFg,
+		textFg: () => env.theme.textFg,
+		title: () => " Keys ",
+		titleFg: () => env.theme.textHeadingFg,
+	}
+}
+
+// Function: createRowBehaviors
+// Builds the HelpRow behavior map (one section heading or one key entry).
+function createRowBehaviors(env) {
+	return {
+		isSection: (_self, data) => data.item?.type === "section",
+		isEntry: (_self, data) => data.item?.type === "entry",
+		section: (_self, data) => data.item?.label ?? "",
+		// Sections are bright; the TUI adds bold via OpenTUI's attribute bit
+		// (the web bolds through CSS instead).
+		sectionFg: () => env.theme.textHeadingFg,
+		sectionAttrs: () => BOLD,
+		open: (_self, data) => data.item?.open ?? "",
+		head: (_self, data) => data.item?.head ?? "",
+		keys: (_self, data) => data.item?.keys ?? "",
+		close: (_self, data) => data.item?.close ?? "",
+		hasIcon: (_self, data) => Boolean(env.theme.lucideIcons && data.item?.icon),
+		iconHref: (_self, data) =>
+			env.theme.lucideIcons && data.item?.icon ? `#lucide-${data.item.icon}` : "",
+		actionTitle: (_self, data) => data.item?.title ?? `${data.item?.head ?? ""}`.trim(),
+		shortcut: (_self, data) => data.item?.shortcut ?? `${data.item?.keys ?? ""}`.trim(),
+		bracketFg: () => env.theme.textSecondaryFg,
+		headFg: () => env.theme.textFg,
+		keyFg: () => env.theme.accentFg,
+	}
+}
+
+export { createBehaviors, createRowBehaviors, helpBlocks, helpGroups, helpLines, keyGlyph }
+
+// EOF

package/src/js/tcmd/components/Help.xml

@@ -3,9 +3,18 @@
 	     out:title="title" out:titleColor="titleFg" out:borderColor="borderFg"
 	     out:backgroundColor="bg" flexDirection="column"
 	     paddingLeft="2" paddingRight="2" paddingTop="1" paddingBottom="1">
-		<scrollbox flexGrow="1">
-			<text out="text" out:fg="textFg"></text>
-		</scrollbox>
-		<text out="hint" out:fg="dimFg"></text>
+		<helpscroll out="scrollbar" ref="scroll" flexGrow="1" overflow="hidden">
+			<box flexDirection="row" overflow="hidden">
+				<box out="leftRows" flexDirection="column" flexGrow="1" flexBasis="0" overflow="hidden"></box>
+				<box out="rightRows" flexDirection="column" flexGrow="1" flexBasis="0" overflow="hidden" paddingLeft="2"></box>
+			</box>
+		</helpscroll>
+		<box height="1" flexShrink="0" out:border="rule" out:borderColor="ruleFg"></box>
+		<box height="1" flexShrink="0" flexDirection="row" overflow="hidden">
+			<text out="hintOpen" out:fg="bracketFg" wrapMode="none"></text>
+			<text out="hintHead" out:fg="headFg" wrapMode="none"></text>
+			<text out="hintKeys" out:fg="keyFg" wrapMode="none"></text>
+			<text out="hintClose" out:fg="bracketFg" wrapMode="none"></text>
+		</box>
 	</box>
 </box>

package/src/js/tcmd/components/HelpRow.html

@@ -0,0 +1,8 @@
+<div class="help-block">
+	<span class="help-section" when="isSection" out="section"></span>
+	<span class="help-entry" when="isEntry" role="group">
+		<svg class="help-icon ui-icon" when="hasIcon" aria-hidden="true" focusable="false" viewBox="0 0 24 24"><use out:href="iconHref"></use></svg>
+		<span class="help-title" out="actionTitle"></span>
+		<kbd class="help-key" out="shortcut"></kbd>
+	</span>
+</div>

package/src/js/tcmd/components/HelpRow.xml

@@ -0,0 +1,7 @@
+<box height="1" flexDirection="row" flexShrink="0" overflow="hidden">
+	<text when="isSection" out="section" out:fg="sectionFg" out:attributes="sectionAttrs" wrapMode="none"></text>
+	<text when="isEntry" out="open" out:fg="bracketFg" wrapMode="none"></text>
+	<text when="isEntry" out="head" out:fg="headFg" wrapMode="none"></text>
+	<text when="isEntry" out="keys" out:fg="keyFg" wrapMode="none"></text>
+	<text when="isEntry" out="close" out:fg="bracketFg" wrapMode="none"></text>
+</box>

package/src/js/tcmd/components/OverlayList.html

@@ -0,0 +1,8 @@
+<div class="overlay-list" when="open" role="dialog" aria-modal="true" aria-label="History and trash" on:click="!dialog:overlay-cancel">
+	<div class="overlay-dialog" on:click="dialogStop">
+		<h2 out="title"></h2>
+		<p class="overlay-empty" when="emptyVisible" out="empty"></p>
+		<ul class="overlay-rows" out="rows"></ul>
+		<footer out="footer"></footer>
+	</div>
+</div>