@ssebastien/tcmd 0.1.2 → 0.1.4

package/src/js/tcmd/components/FilePreview.js

@@ -8,10 +8,20 @@
 // their leading content; other kinds show a metadata card. Renderer-agnostic
 // logic; `FilePreview.xml` / `FilePreview.html` are the presentations.
 //
-// Environment: `textFg`, `textSecondaryFg`, `textHeadingFg`.
+// A directory is the exception: it renders the *directory column* — its own
+// breadcrumbs over a cursorable listing — so a previewed directory looks and
+// behaves like a pane in every view mode (click a row to focus it, Enter to
+// descend). The listing is the inspector pane's (`session.panes.preview`),
+// threaded down as the `dir*` inputs; `paneId` is what rows, crumbs and the
+// column body publish back to the App.
+//
+// Environment: `textFg`, `textSecondaryFg`, `textHeadingFg`, and the optional
+// `actions` footer text (default: the TUI's `[Open O] [Edit E]` hints; the web
+// substitutes a note that those keys do not exist in a browser).
 
 import { unwrap } from "select/state/cells"
 import { formatSize } from "./format.js"
+import { previewSource } from "../core/session.js"
 
 const KIND_LABELS = {
 	directory: "directory",
@@ -57,7 +67,9 @@ function previewTitle(preview) {
 
 // Function: entryCard
 // Metadata card for the entry the session did not preview: a directory, or a
-// file whose kind has no inline preview.
+// file whose kind has no inline preview. Directories normally take the
+// directory column instead (see `isDirectoryPane`); the branch stays for a
+// `stat` payload and for hosts that render no listing.
 function entryCard(entry) {
 	if (!entry) return ""
 	const lines = []
@@ -69,42 +81,93 @@ function entryCard(entry) {
 	return lines.join("\n")
 }
 
+// Function: isDirectoryPane
+// True when the inspector previews a plain directory: no `stat` card was
+// pinned on it, so the directory column takes the body.
+function isDirectoryPane(preview, entry) {
+	return Boolean(entry?.isDir) && !preview
+}
+
 // Function: headerTitle
-// The inspector title: the preview's own title, else the cursor entry.
+// The inspector title: the preview's own title, else the cursor entry — whose
+// symlink target and resolved extension `previewSource` supplies, so the
+// header names the traversal before the async read lands.
 function headerTitle(preview, entry) {
 	if (preview) return previewTitle(preview)
 	if (entry) {
-		const badge = entry.isDir ? "DIR" : (entry.ext || "file").toUpperCase()
-		return `${entry.name}${entry.isDir ? "/" : ""}  <${badge}>`
+		const source = previewSource(entry)
+		const badge = entry.isDir ? "DIR" : (source.ext || "file").toUpperCase()
+		const name = entry.isDir ? `${entry.name}/` : entry.name
+		const target = entry.isSymlink && entry.target ? ` -> ${entry.target}` : ""
+		return `${name}${target}  <${badge}>`
 	}
 	return "inspector"
 }
 
 // Function: createBehaviors
 // Builds the FilePreview behavior map for the given renderer environment.
+// `env.actions` overrides the footer line so a presentation can carry its own
+// copy (the browser has no Open/Edit); the default advertises the TUI keys.
 function createBehaviors(env) {
+	const actions = env.actions ?? (() => " [Open O] [Edit E]")
+	const directory = (_self, data) =>
+		isDirectoryPane(unwrap(data.preview), unwrap(data.entry))
+	const body = (_self, data) => !directory(_self, data)
 	return {
-		actions: () => " [Open O] [Edit E]",
+		actions,
 		actionsFg: () => env.textSecondaryFg,
 		cardText: (_self, data) => cardText(unwrap(data.preview)),
+		// The directory column: breadcrumbs over the inspector pane's listing,
+		// shaped like a pane header (a rule separates it from the body).
+		dirCrumbsView: (_self, data) => ({ segments: data.dirSegments, paneId: data.paneId }),
+		dirListView: (_self, data) => ({
+			entries: data.dirEntries,
+			cursor: data.dirCursor,
+			marked: data.dirMarked,
+			active: data.dirActive,
+			loading: data.dirLoading,
+			paneId: data.paneId,
+		}),
 		dimFg: () => env.textSecondaryFg,
 		emptyText: () => "  No file selected\n  Move the cursor or press v",
 		entryText: (_self, data) => entryCard(unwrap(data.entry)),
+		// The rule between the contents and the shortcut footer.
+		footRule: () => ["top"],
+		footRuleFg: () => env.textSecondaryFg,
+		headRule: () => ["top"],
+		headRuleFg: () => env.textSecondaryFg,
 		hasCard: (_self, data) => hasCard(unwrap(data.preview)),
-		// The metadata card fills in whenever there is a cursor entry but no
-		// preview payload (a directory, or a non-text file).
-		hasEntryCard: (_self, data) => !unwrap(data.preview) && Boolean(unwrap(data.entry)),
 		hasText: (_self, data) => hasText(unwrap(data.preview)),
 		headerTitle: (_self, data) => headerTitle(unwrap(data.preview), unwrap(data.entry)),
 		isEmpty: (_self, data) => !unwrap(data.preview) && !unwrap(data.entry),
+		isDirPane: directory,
 		previewText: (_self, data) => unwrap(data.preview)?.text ?? "",
 		previewTitle: (_self, data) => previewTitle(unwrap(data.preview)),
 		previewTitleColor: () => env.textHeadingFg,
 		show: (_self, data) => Boolean(unwrap(data.show)),
+		// One body at a time: the directory column, else the card/text/empty
+		// states, with the title row yielding to the breadcrumb header.
+		// `showEntryCard` fills in whenever there is a cursor entry but no
+		// preview payload — except a directory, which gets the listing.
+		showBody: body,
+		showCard: (_self, data) => body(_self, data) && hasCard(unwrap(data.preview)),
+		showEmpty: (_self, data) => body(_self, data) && !unwrap(data.preview) && !unwrap(data.entry),
+		showEntryCard: (_self, data) =>
+			body(_self, data) && !unwrap(data.preview) && Boolean(unwrap(data.entry)),
+		showText: (_self, data) => body(_self, data) && hasText(unwrap(data.preview)),
 		textFg: () => env.textFg,
 	}
 }
 
-export { cardText, createBehaviors, entryCard, hasCard, hasText, headerTitle, previewTitle }
+export {
+	cardText,
+	createBehaviors,
+	entryCard,
+	hasCard,
+	hasText,
+	headerTitle,
+	isDirectoryPane,
+	previewTitle,
+}
 
 // EOF

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

@@ -1,10 +1,23 @@
+<!-- The inspector: a card/text body for a file, and a directory column
+     (breadcrumbs + cursorable listing) for a directory, so a previewed
+     directory reads as a pane. The body and the column share the border and
+     the footer, and the whole column is clickable to take focus. -->
 <box when="show" out:title="headerTitle" out:titleColor="previewTitleColor" border borderStyle="rounded"
-     flexDirection="column" flexGrow="1" overflow="hidden">
-	<scrollbox flexGrow="1">
-		<text when="hasText" out="previewText" out:fg="textFg"></text>
-		<text when="hasCard" out="cardText" out:fg="dimFg"></text>
-		<text when="hasEntryCard" out="entryText" out:fg="dimFg"></text>
-		<text when="isEmpty" out="emptyText" out:fg="dimFg"></text>
+     flexDirection="column" flexGrow="1" overflow="hidden" on:click="paneId!pane:activate">
+	<box when="isDirPane" flexDirection="row" height="1" paddingLeft="1" overflow="hidden">
+		<box flexGrow="1" flexShrink="1" minWidth="0" overflow="hidden">
+			<breadcrumbs in:segments="dirSegments" in:paneId="paneId" height="1"></breadcrumbs>
+		</box>
+	</box>
+	<box when="isDirPane" height="1" out:border="headRule" out:borderColor="headRuleFg"></box>
+	<filelist when="isDirPane" in:entries="dirEntries" in:cursor="dirCursor" in:marked="dirMarked"
+	          in:active="dirActive" in:paneId="paneId" in:loading="dirLoading"></filelist>
+	<scrollbox when="showBody" flexGrow="1">
+		<text when="showText" out="previewText" out:fg="textFg"></text>
+		<text when="showCard" out="cardText" out:fg="dimFg"></text>
+		<text when="showEntryCard" out="entryText" out:fg="dimFg"></text>
+		<text when="showEmpty" out="emptyText" out:fg="dimFg"></text>
 	</scrollbox>
+	<box height="1" out:border="footRule" out:borderColor="footRuleFg"></box>
 	<box height="1"><text out="actions" out:fg="actionsFg"></text></box>
 </box>

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

@@ -1,4 +1,4 @@
-<li class="file-row" out:class="rowClass" on:click="paneId:paneId,index:index!list:select">
+<li class="file-row" out:class="rowClass" out:data-marked="rowMarked" out:data-active="rowActive" out:data-kind="rowKind" on:click="paneId:paneId,index:index!list:select">
 	<span class="marker" out="rowMarker"></span>
 	<span class="name" out:class="rowNameClass" out="rowName"></span>
 	<span class="size" out="rowSize"></span>

package/src/js/tcmd/components/FileRow.js

@@ -8,7 +8,8 @@
 // markedRow, active, paneId }`, the same bag shape in both engines.
 // `currentRow`/`markedRow` are plain per-row booleans snapshotted by the
 // `fileRows` builder (see `rows.js`); `active` is the pane-focus cell, read
-// with `unwrap` at the point of use.
+// with `unwrap` at the point of use. A symlink row carries its target in the
+// name (`notes -> ../real/notes`, see `rowName`).
 //
 // Environment: `cursorBg`, `cursorInactiveBg`, `currentClass`,
 // `accentSecondaryFg`, `accentFg`, `linkFg`, `dirFg`, `devFg`, `fileFg`,
@@ -20,10 +21,13 @@ import { iconFor } from "./icons.js"
 
 // Function: rowName
 // The entry name with the directory slash (the icon is its own slot, so it
-// can be dimmer than the name — see `rowIcon`).
+// can be dimmer than the name — see `rowIcon`), and, for a symlink, the
+// `-> target` tail `ls -l` prints. The name cell truncates, so a narrow pane
+// drops the target before the name itself.
 function rowName(entry) {
 	if (!entry) return ""
-	return entry.isDir ? `${entry.name}/` : entry.name
+	const name = entry.isDir ? `${entry.name}/` : entry.name
+	return entry.target ? `${name} -> ${entry.target}` : name
 }
 
 // Function: rowIcon
@@ -115,6 +119,9 @@ function createBehaviors(env) {
 			return undefined
 		},
 		rowClass: (_self, data) => (rowCurrent(data) ? env.currentClass : null),
+		rowMarked: (_self, data) => `${rowIsMarked(data)}`,
+		rowActive: (_self, data) => `${unwrap(data.active) !== false}`,
+		rowKind: (_self, data) => data.item?.isSymlink ? "link" : data.item?.isDir ? "dir" : data.item?.isDevice ? "dev" : "file",
 		// The icon is its own slot so it can sit dimmer than the name; it
 		// collapses when the environment keeps rows icon-free.
 		hasIcon: () => Boolean(env.icons),

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

@@ -1,6 +1,6 @@
 <div class="filter-bar" when="visible">
 	<span class="filter-prompt" out="prompt"></span>
-	<input when="editing" ref="query" inout="query" class="filter-input" />
+	<input when="editing" ref="query" inout="query" on:input="onFilter" class="filter-input" />
 	<span when="applied" class="filter-label" out="label"></span>
 	<span class="filter-alert" out="alert"></span>
 </div>

package/src/js/tcmd/components/FilterBar.js

@@ -7,10 +7,12 @@
 // FilterBar: the fuzzy filter indicator, folded into the pane header so it
 // never shifts the listing. While the pane owns the filter input
 // (`filtering === paneId`) it shows a compact focused input bound to the pane's
-// `query`; once accepted it degrades to the same `/ query` indication, so the
-// pane is navigable again and the filter can still be cleared with Esc. When
-// the query matches no entry it shows a `no match` alert. The key hints live in
-// the command bar, not here.
+// `query`; each change also routes through the pane's `setFilter` (passed as
+// `setFilter`), so the cursor re-anchors with no directory watcher. Once
+// accepted it degrades to the same `/ query` indication, so the pane is
+// navigable again and the filter can still be cleared with Esc. When the query
+// matches no entry it shows a `no match` alert. The key hints live in the
+// command bar, not here.
 //
 // Environment: `accentFg` (the applied label), `textSecondaryFg` (the `/`
 // prompt), `warningFg` (the no-match alert).
@@ -33,6 +35,14 @@ function createBehaviors(env) {
 		applied: (self, data) => !editing(self, data) && activeQuery(self, data).length > 0,
 		editing,
 		focused: editing,
+		// The input both displays and captures through `inout`; `on:input`
+		// additionally routes the change through the pane's `setFilter` so the
+		// cursor re-anchors on the first match. The TUI delivers the input
+		// value directly, the DOM an event carrying it.
+		onFilter: (_self, data, event) => {
+			const value = typeof event === "string" ? event : `${event?.target?.value ?? ""}`
+			data.setFilter?.(value)
+		},
 		// The bare query (shared with the web presentation).
 		label: (self, data) => queryText(self, data),
 		labelFg: () => env.accentFg,

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

@@ -1,6 +1,6 @@
 <box when="visible" flexDirection="row" height="1" flexShrink="0">
 	<text out="prompt" out:fg="promptFg"></text>
-	<input when="editing" ref="query" inout="query" out:focused="focused" width="14" height="1"></input>
+	<input when="editing" ref="query" inout="query" on:input="onFilter" out:focused="focused" width="14" height="1"></input>
 	<text when="applied" out="labelText" out:fg="labelFg" wrapMode="none" truncate="true"></text>
 	<text out="alert" out:fg="alertFg" wrapMode="none"></text>
 </box>

package/src/js/tcmd/{tui/frame.js → components/Frame.js}

@@ -3,17 +3,52 @@
 // License: BSD
 // Created: 2026-10-02
 
-// Module: tcmd/tui/frame
-// TUI-only presentation behaviors for the workspace chrome: the responsive
-// breakpoints driven by the `uiSize` cell, the pane borders, header rules,
-// the command-bar geometry and the help overlay state. Everything here is
-// injected into the App binding; none of it lives in the shared
-// `components/` logic.
+// 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 { DEFAULT_KEYMAP } from "../core/keymap.js"
-import { getCommands } from "../core/commands.js"
-import { commandBarMarksItem, commandBarRowCount, commandBarStatus } from "../components/CommandBar.js"
+import { commandBarMarksItem, commandBarRowCount, 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
@@ -42,6 +77,21 @@ function isNarrow(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"}`
+}
+
 // Function: commandBarRowsFor
 // The entries the bar currently shows: the context hints or the `bar`
 // commands, plus the active pane's marked count as a trailing entry.
@@ -106,6 +156,31 @@ function shineOf(letters, from, to) {
 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
@@ -130,6 +205,12 @@ function createFrameBehaviors(env) {
 			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.
@@ -160,14 +241,32 @@ function createFrameBehaviors(env) {
 		// 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; otherwise `v` opens the fullscreen viewer.
+		// wide enough; otherwise `v` opens the fullscreen viewer. Maximizing
+		// (`⇧V`) replaces the column with `showPreviewFull` below.
 		inspectorNarrow: (self, data) => isNarrow(data, self),
-		showInspectorInline: (self, data) => Boolean(unwrap(data.showPreview)) && !isNarrow(data, self),
+		showInspectorInline: (self, data) =>
+			Boolean(unwrap(data.showPreview)) && !isNarrow(data, self) && !unwrap(data?.previewFull),
 		showViewer: (self, data) => Boolean(unwrap(data.viewerOpen)) && isNarrow(data, self),
+		// 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 `tui/Help.js` so the
+		// 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)),
 
@@ -180,90 +279,20 @@ function createFrameBehaviors(env) {
 	}
 }
 
-// Function: keyGlyph
-// Human-readable glyph for a keymap chord ("↑", "⇧Tab", "^W", "PgUp").
-function keyGlyph(chord) {
-	const name = chord.key
-	const named = {
-		up: "↑",
-		down: "↓",
-		left: "←",
-		right: "→",
-		return: "↵",
-		enter: "↵",
-		space: "Space",
-		tab: "Tab",
-		pageup: "PgUp",
-		pagedown: "PgDn",
-		escape: "Esc",
-		backspace: "Bksp",
-		home: "Home",
-		end: "End",
-	}
-	let base = named[name] ?? (name.length === 1 ? name.toUpperCase() : `${name}`)
-	if (chord.ctrl) base = `^${base}`
-	if (chord.meta) base = `⌘${base}`
-	if (chord.shift && name !== "tab") base = `⇧${base}`
-	return base
-}
-
-// Constant: GROUP_ORDER / GROUP_TITLES
-// Help sections, in display order.
-const GROUP_ORDER = ["nav", "pane", "list", "bookmark", "view", "file", "panel", "palette", "filter", "app"]
-const GROUP_TITLES = {
-	app: "Session",
-	bookmark: "Bookmarks",
-	file: "Files",
-	filter: "Filter",
-	list: "Selection",
-	nav: "Navigation",
-	palette: "Commands",
-	panel: "Command panel",
-	pane: "Panes",
-	view: "View",
-}
-
-// Function: helpLines
-// Builds the categorized key reference from the keymap and the command
-// registry, so it can never drift from the actual bindings.
-function helpLines() {
-	const byId = new Map(getCommands().map((command) => [command.id, command]))
-	const groups = new Map()
-	const seen = new Set()
-	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: [], title: command.title })
-		const row = rows.get(binding.command)
-		const glyph = keyGlyph(binding)
-		if (!row.keys.includes(glyph) && !seen.has(`${binding.command}:${glyph}`)) {
-			row.keys.push(glyph)
-			seen.add(`${binding.command}:${glyph}`)
-		}
-	}
-	const lines = []
-	for (const group of GROUP_ORDER) {
-		const rows = groups.get(group)
-		if (!rows) continue
-		lines.push(GROUP_TITLES[group] ?? group)
-		for (const row of rows.values()) {
-			lines.push(`  ${row.keys.join("/").padEnd(9)} ${row.title}`)
-		}
-		lines.push("")
-	}
-	return lines
-}
-
 export {
 	commandBarLines,
 	createFrameBehaviors,
-	helpLines,
+	currentColumnId,
 	INSPECTOR_INLINE_WIDTH,
+	isExplorer,
 	isNarrow,
-	keyGlyph,
+	MIN_HEIGHT,
+	MIN_WIDTH,
+	MODE_SLOTS,
+	modeGradient,
+	modeWord,
 	sizeOf,
+	versionTrail,
+	VERSION,
 }
 // EOF

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

@@ -0,0 +1,7 @@
+<section class="help" when="open" role="dialog" aria-modal="true" aria-label="Key reference" tabindex="-1">
+	<div class="help-dialog">
+		<header out="title"></header>
+		<pre out="text"></pre>
+		<footer out="hint"></footer>
+	</div>
+</section>

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

@@ -0,0 +1,109 @@
+// 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 text
+// itself (`helpLines`). The content is built from the live keymap and command
+// registry, so it cannot drift from the actual bindings. Both presentations
+// (`Help.xml` / `Help.html`) render the same lines.
+
+import { unwrap } from "select/state/cells"
+import { DEFAULT_KEYMAP } from "../core/keymap.js"
+import { getCommands } from "../core/commands.js"
+
+// Function: keyGlyph
+// Human-readable glyph for a keymap chord ("↑", "⇧Tab", "^W", "PgUp").
+function keyGlyph(chord) {
+	const name = chord.key
+	const named = {
+		up: "↑",
+		down: "↓",
+		left: "←",
+		right: "→",
+		return: "↵",
+		enter: "↵",
+		space: "Space",
+		tab: "Tab",
+		pageup: "PgUp",
+		pagedown: "PgDn",
+		escape: "Esc",
+		backspace: "Bksp",
+		home: "Home",
+		end: "End",
+	}
+	let base = named[name] ?? (name.length === 1 ? name.toUpperCase() : `${name}`)
+	if (chord.ctrl) base = `^${base}`
+	if (chord.meta) base = `⌘${base}`
+	if (chord.shift && name !== "tab") base = `⇧${base}`
+	return base
+}
+
+// Constant: GROUP_ORDER / GROUP_TITLES
+// Help sections, in display order.
+const GROUP_ORDER = ["nav", "pane", "list", "bookmark", "view", "file", "panel", "filter", "app"]
+const GROUP_TITLES = {
+	app: "Session",
+	bookmark: "Bookmarks",
+	file: "Files",
+	filter: "Filter",
+	list: "Selection",
+	nav: "Navigation",
+	panel: "Commands",
+	pane: "Panes",
+	view: "View",
+}
+
+// Function: helpLines
+// The categorized key reference, one line per heading or binding.
+function helpLines() {
+	const byId = new Map(getCommands().map((command) => [command.id, command]))
+	const groups = new Map()
+	const seen = new Set()
+	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: [], title: command.title })
+		const row = rows.get(binding.command)
+		const glyph = keyGlyph(binding)
+		if (!row.keys.includes(glyph) && !seen.has(`${binding.command}:${glyph}`)) {
+			row.keys.push(glyph)
+			seen.add(`${binding.command}:${glyph}`)
+		}
+	}
+	const lines = []
+	for (const group of GROUP_ORDER) {
+		const rows = groups.get(group)
+		if (!rows) continue
+		lines.push(GROUP_TITLES[group] ?? group)
+		for (const row of rows.values()) {
+			lines.push(`  ${row.keys.join("/").padEnd(9)} ${row.title}`)
+		}
+		lines.push("")
+	}
+	return lines
+}
+
+// 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,
+		hint: () => " Esc / ? close ",
+		open: (_self, data) => Boolean(unwrap(data.open)),
+		text: () => helpLines().join("\n"),
+		textFg: () => env.theme.textFg,
+		title: () => " Keys ",
+		titleFg: () => env.theme.textHeadingFg,
+	}
+}
+
+export { createBehaviors, helpLines, keyGlyph }
+
+// EOF

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

@@ -1,3 +1,3 @@
 <div class="summary" ref="box">
-	<span out="line" class="summary-line"></span>
+	<span out="priorityLine" class="summary-line"></span>
 </div>