@ssebastien/tcmd 0.0.0-stage → 0.1.1

package/README.md

@@ -1,3 +1,235 @@
-# Temporary Holding Version
+# TinyCommand
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+```
+ ██▓                                 ██▓
+ ███▄▄  ███▀▀█▓▄  ███▀▀███▀▀█▓▄  ▄██▀▀███
+ ███    ███ ▀▀▀▀  ███  ███  ███  ███  ███
+ ███    ███  ███  ███  ███  ███  ███  ███
+ ▀██▄▄  ███▄▄███  ███  ███  ███  ███▄▄███
+```
+
+TinyCommand `tcmd` is a midnight-commander-like CLI and desktop tool:
+
+- Browse files in two panes (the left is the source, the right the
+  destination)
+- Named bookmarks: `b` records the cursor entry (or the pane directory) under
+  a name defaulting to its basename, remembering whether it is a file or a
+  directory; `g` opens a fzf-style picker over bookmark names and paths. A
+  directory bookmark opens to show its contents, a file bookmark is selected
+  and previewed in its directory.
+- Operations over the current panes: copy, move, delete/erase, stat, touch,
+  selection buffers, edit/view/open and shell commands
+- Command palette with UI actions, plus a scripting mode (`:`) that completes
+  operations and the available filesets ($A, $B, …, $FILE)
+- Keyboard and mouse navigation, inline file previews
+- Bookmarks and quick find (later milestones)
+
+References: [Marta.sh](https://marta.sh) for the UI, [fman.io](https://fman.io)
+for the minimalist take.
+
+## Running
+
+Install [Bun](https://bun.sh), then run without installing tcmd globally:
+
+```sh
+npm x @ssebastien/tcmd
+npm x @ssebastien/tcmd -- /tmp ~
+```
+
+Or install it globally with `npm install -g @ssebastien/tcmd` and run `tcmd`.
+
+For development:
+
+```sh
+bun install          # installs @ssebastien/select and @ssebastien/select-tui
+bun run tcmd         # open cwd (left) and ~ (right)
+bun run tcmd /tmp ~  # open specific directories
+```
+
+Keys: `↑/↓` move (`^↑/^↓` jump a few lines), `Enter/→` open, `←/Bksp` parent,
+`Esc`/`⇧Esc` history back/forward, `Tab`/`⇧Tab` switch panes
+(`⇧Tab` goes back), `Space` mark, `b` bookmark the cursor entry (or the pane
+directory) under a basename-defaulted name, `g` jump to a bookmark, `:` or `m`
+open the command panel (Commando: operations, their arguments, and the live
+resolved command), `v` preview (fullscreen viewer when the terminal is narrow),
+`O`/`E` open/edit the previewed file, `/` fuzzy-filter the active pane (`Enter`
+keeps it, `Esc` clears), `^P` command palette, `!` run a shell command, `^R`
+reload, `?` key reference, `q` quit.
+
+The workspace opens with a slim identity bar (`TinyCmd - HOST`) over an
+unframed tiling of pane boxes (the two middle edges sit side by
+side) labelled **SRC** (left, source) / **DST** (right, destination), with a
+header row (label + clickable breadcrumbs — collapsed to first letters like
+`/h/s/W/Perso/tcmd` when the width demands — + the inline filter) separated by a
+rule from the listing, an entry-detail line for the selected entry, and one
+summary row, so the two panes stay aligned. The detail line shows
+`date · type · size · rights` with the rights right-aligned, the date and size
+bright, and the size/rights dropping out when the pane is too narrow; the
+summary row is indented to match. The active pane's border and header
+rule are highlighted and its cursor row uses the strong cursor colour, while
+the inactive pane stays dim with a muted cursor. Rows lead with a yazi-style
+Nerd Font icon (folder/link kind icons plus a per-extension icon, `Makefile`,
+`Dockerfile` and dotfiles included), on unless `TCMD_ICONS=0` — it needs a
+Nerd-Font-patched terminal font, and the web view never shows icons. A
+context-aware inspector sits
+on the right when the terminal is at least 100 columns wide, and becomes a
+fullscreen viewer below that. The status bar lists every binding as a bracket
+shorthand (`[Open ⏎]`) wrapping over as many rows as the width demands — the
+marked count trails the list, and a notice or error swaps the keys for a
+one-line status. Below 64×16
+the app shows a resize hint instead of the workspace.
+
+### Web version
+
+The web view runs the same core on select.js and offers two filesystem
+backends:
+
+- **OPFS** (preferred): private browser storage, seeded with a demo tree on
+  first load. Needs a secure context (`localhost` or https).
+- **HTTP API** (automatic fallback, or `?fs=http`): the server exposes the
+  real filesystem over `/api/*`, using the same Node adapter as the TUI.
+
+```sh
+make run-local       # build and serve both backends (alias to `bun run web`)
+bun run web          # build and serve both backends on http://localhost:8787
+bun run web:build    # bundle only, into public/main.js
+bun run web:serve    # serve the existing bundle plus /api/*
+```
+
+`make run-local` is the local dev entry point (it wraps `bun run web` and
+honours `TCMD_WEB_PORT`, default 8787). The Makefile bootstraps the LittleSDK
+into `deps/sdk` for the standard `make` targets.
+
+Appending `?fs=opfs` or `?fs=http` to the URL forces one backend. The HTTP
+backend needs the page served by `bun run web:serve` (a plain static server
+only supports OPFS); the server binds to loopback and requires a per-process
+token injected into `index.html`. `TCMD_WEB_ROOT=/some/dir` confines the API
+(default `/`, the same access as `bun run tcmd`), but it is not a sandbox:
+don't expose the port. With OPFS, deleting moves entries to `/.trash`; the API
+uses the desktop trash. Open/edit/run are unavailable in the browser either
+way (the null host adapter reports it in the command bar); everything else —
+navigation, marks, scripting, copy/move/erase — works on either
+backend. `public/index.html` is the host page; `public/main.js` is generated.
+
+## Architecture
+
+MVC with a presentation-agnostic core, so a web UI can share the same model
+and controller:
+
+```
+src/js/tcmd/
+  core/     Model + Controller. No rendering dependencies.
+    fs.js        filesystem adapter interface (Node impl; web swaps in OPFS/HTTP)
+    os.js        host adapter (open/edit/run; null impl for the web)
+    path.js      pure string path ops
+    entries.js   filter/sort over file entries (dirs first)
+    selection.js cursor/mark arithmetic
+    directory.js one pane's directory: path, entries, view, cursor, marks
+    pane.js      one directory, proxying its cells
+    bookmarks.js named bookmarks (path + file/dir kind) + the memory/file stores
+    panel.js     command panel: operation args bound from the live context
+    session.js   two panes + active pane, preview, palette, panel, dispatch
+    keymap.js    key chords -> command ids
+    commands.js  command registry; commands are `run(session, payload)`
+    operations.js scripting operations (copy/move/delete/erase/stat/sel/…)
+    script.js    scripting line parser, runner and palette completions
+  components/  Shared, renderer-agnostic component logic
+    App.js            root controller: key + event -> dispatch
+    bind.js           `ui.component(name).does(behaviors).using(source)` binding
+    rows.js           keyed row-bag builders shared by both catalogues
+    FileList.js …     one `.js` per component (behaviors + pure helpers)
+    FileRow.js …      row behaviors shared by both engines
+    format.js         presentation helpers (sizes/counts)
+  tui/      View (select.tui templates on OpenTUI)
+    app.js       binds App.js + App.xml + TUI environment; size/help cells
+    catalogue.js binds each `components/*.js` to its `.xml` and registers tags
+    frame.js     TUI-only chrome: frame title, breakpoints
+    help.js      TUI-only `?` key-reference overlay behaviors
+    index.js     TUI entry point; feeds `size` from renderer resize events
+    theme.js     TUI palette resolver (dark/light/mono, NO_COLOR)
+  web/      Browser view (select.js templates on the DOM, same core)
+    app.js       binds App.js + App.html + web environment
+    catalogue.js binds each `components/*.js` to its `.html`
+    index.js     web entry point: `main(session, selector)`
+    main.js      browser bootstrap: backend choice + session (bundled)
+    opfs.js      OPFS filesystem adapter (browser storage)
+    http.js      filesystem adapter over the `/api` JSON endpoints
+    server.js    dev server: `public/` + `/api/*` (used by `bun run web:serve`)
+    seed.js      demo tree written to OPFS on first load
+    header.js    web-only title bar behaviors (+ `header.html`)
+    theme.js     web state classes
+  vendor/   Vendored third-party code kept close to upstream
+    fzy.js       fzy fuzzy scoring algorithm (MIT)
+```
+
+Each component is a triple: `ComponentName.js` (shared logic),
+`ComponentName.xml` (TUI presentation) and `ComponentName.html` (web
+presentation). Components that share a presentation bind the same source (e.g.
+`Breadcrumbs` uses `RowList.xml` for the TUI and
+`RowList.html` for the web). The `.js` imports neither renderer and reads
+reactive cells with `unwrap` from `select/state/cells`; each catalogue injects
+the renderer's runtime and theme through the `components/index.js` manifest,
+binding via the shared `components/bind.js` helper
+(`ui.component(name).does(behaviors).using(source)`, the contract both engines
+implement). Published events are registered with `.sub(...)` (the select.js
+contract) in both. List rows use the same keyed `Component.map` primitive over
+reactive collections, sharing row behaviors over a `{ item, index, … }` bag
+built by `components/rows.js`; cells stay in the bag and are read at the point
+of use.
+
+TUI-only components live under `tui/` (`frame.js`, `help.js`) and their `.xml`
+templates under `components/`; they are registered only by `tui/catalogue.js`.
+Web-only components live under `web/` (`header.js` + `header.html`). Shared
+behaviors only ever grow additively (a new key for a new presentation),
+so the other engine's presentation and the parity tests keep working unchanged.
+
+Decoupling rules:
+
+- `core/` state is reactive cells (`select/state/cells`) and commands mutate it
+  through `session.dispatch(id, payload)`; views only subscribe and publish.
+- The filesystem and host are injected adapters (`core/fs`, `core/os`), so tests
+  run on an in-memory fs and the web view swaps the backend without touching
+  the model.
+- Views receive data as cells (`in:` slots and mapped row bags keep cells
+  reactive) and read them with `unwrap`; they report intent via `pub()`ed
+  events (`list:select`, `crumbs:go`, …) that the app handles with `.sub(...)`
+  and maps to commands.
+- `components/` stays free of renderer imports; each `tui/` / `web/` catalogue
+  injects the renderer's runtime and theme, so the same controller serves both.
+
+## Dependencies
+
+- [select.js](../select.js) — reactive cells and the template binding language
+- [select.tui](../select.tui) — Select.js templates rendered on OpenTUI
+- [@opentui/core](https://github.com/anomalyco/opentui) — terminal renderer
+- [fzy.js](https://github.com/jhawthorn/fzy.js) — vendored fuzzy scoring (MIT,
+  see `src/js/tcmd/vendor/`)
+- Bun as the runtime
+
+`deps/` symlinks to sibling checkouts; `scripts/link-deps.sh` (run as
+postinstall) re-links `node_modules` so upstream edits propagate.
+
+## Tests
+
+```sh
+bun test            # core, components, TUI and web tests
+```
+
+Core tests use an in-memory filesystem; TUI tests drive the real component
+tree with OpenTUI's test renderer (frame capture, mock keys and mouse). Web
+tests run the shared logic through select.js on a happy-dom document.
+
+## Roadmap
+
+- [x] Walking skeleton: two panes, navigation, breadcrumbs, summary, command
+      bar, command palette, text preview
+- [x] File operations (copy/move/delete/erase/stat/touch/sel), scripting mode
+      with the `$A`/`$B` pane filesets
+- [x] Scripting completion (operations, filesets, active-directory and nested
+      paths)
+- [x] Pane fuzzy filtering (`/` to filter, `Enter` to keep, `Esc` to clear)
+- [x] Named bookmarks (`b` records, `g` jumps, persisted to a JSON file)
+- [ ] Quick find, grep
+- [ ] Image/PDF/audio/video previews
+- [x] Web view on the same core (shared components rendered by select.js)
+- [x] Pane navigation history (`Esc`/`⇧Esc` back/forward)

package/bin/tcmd

@@ -0,0 +1,17 @@
+#!/bin/sh
+# TinyCommand `tcmd` entry point.
+if ! command -v bun >/dev/null 2>&1; then
+	printf '%s\n' 'tcmd requires Bun (https://bun.sh). Install Bun, then run `bun x @ssebastien/tcmd` again.' >&2
+	exit 1
+fi
+script=$0
+while [ -L "$script" ]; do
+	dir=$(CDPATH= cd -- "$(dirname -- "$script")" && pwd)
+	link=$(readlink "$script")
+	case "$link" in
+		/*) script=$link ;;
+		*) script=$dir/$link ;;
+	esac
+done
+dir=$(CDPATH= cd -- "$(dirname -- "$script")" && pwd)
+exec bun "$dir/../src/js/tcmd/tui/index.js" "$@"

package/package.json

@@ -1,6 +1,38 @@
 {
-  "name": "@ssebastien/tcmd",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+	"name": "@ssebastien/tcmd",
+	"version": "0.1.1",
+	"description": "TinyCommand: a midnight-commander-like CLI and desktop tool",
+	"type": "module",
+	"main": "./src/js/tcmd/index.js",
+	"files": ["bin/", "src/js/tcmd/", "README.md"],
+	"bin": {
+		"tcmd": "./bin/tcmd"
+	},
+	"scripts": {
+		"test": "bun test tests",
+		"tcmd": "bun src/js/tcmd/tui/index.js",
+		"web": "bun run web:build && bun run web:serve",
+		"web:build": "bun build src/js/tcmd/web/main.js --outdir public --target browser",
+		"web:serve": "bun scripts/serve-web.js"
+	},
+	"dependencies": {
+		"@opentui/core": "0.5.9",
+		"@ssebastien/select": "^1.2.1",
+		"@ssebastien/select-tui": "^0.1.0"
+	},
+	"devDependencies": {
+		"happy-dom": "^20.10.6"
+	},
+	"author": "Sébastien Pierre",
+	"license": "BSD",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/sebastien/tcmd.git"
+	},
+	"engines": {
+		"bun": ">=1.1.0"
+	},
+	"publishConfig": {
+		"access": "public"
+	}
+}

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

@@ -0,0 +1,28 @@
+<div class="app" tabindex="0" on:keydown="keys">
+	<header out="headerView|Header"></header>
+	<main class="panes">
+		<section class="pane pane-left" out:class="leftPaneClass" on:click="leftId!pane:activate">
+			<div class="pane-header">
+				<div out="leftCrumbsView|Breadcrumbs"></div>
+				<div out="leftFilterView|FilterBar"></div>
+			</div>
+			<div out="leftListView|FileList"></div>
+			<div out="leftDetailView|EntryDetail"></div>
+			<div out="leftSummaryView|Summary"></div>
+		</section>
+		<section class="pane pane-right" out:class="rightPaneClass" on:click="rightId!pane:activate">
+			<div class="pane-header">
+				<div out="rightCrumbsView|Breadcrumbs"></div>
+				<div out="rightFilterView|FilterBar"></div>
+			</div>
+			<div out="rightListView|FileList"></div>
+			<div out="rightDetailView|EntryDetail"></div>
+			<div out="rightSummaryView|Summary"></div>
+		</section>
+		<div when="showPreview" out="previewView|FilePreview"></div>
+	</main>
+	<footer out="commandBarView|CommandBar"></footer>
+	<div when="paletteOpen" out="paletteView|CommandPalette"></div>
+	<div when="bookmarkOpen" out="bookmarkView|BookmarkList"></div>
+	<div out="confirmView|Confirm"></div>
+</div>

package/src/js/tcmd/components/App.js

@@ -0,0 +1,355 @@
+// Project: TinyCommand
+// Author:  Sebastien Pierre
+// License: BSD
+// Created: 2026-09-26
+
+// Module: tcmd/components/App
+// Root component: a header, two panes (breadcrumbs + FileList + summary each),
+// an optional preview column, the command bar and the command palette overlay.
+// App is the controller seam: component events (published bubbles) and key
+// chords are translated into `session.dispatch(commandId, payload)` calls; it
+// never mutates model state directly.
+//
+// Environment: `normalizeKey(event)` (optional; identity when omitted) and
+// `quit(self)`. Renderer-specific bindings (pane borders, status color) live in
+// the per-renderer app binding.
+
+import { derived, unwrap } from "select/state/cells"
+import { DEFAULT_KEYMAP, matchKeymap } from "../core/keymap.js"
+import { PANEL_FOCUS } from "../core/panel.js"
+
+// Function: createInit
+// State initializer binding the root component to a `session`.
+function createInit(session) {
+	const left = session.panes.left
+	const right = session.panes.right
+	// Pane-focus flags so the listing can render the cursor differently in the
+	// inactive pane. Shared by both engines.
+	const leftActive = derived([session.active], ([active]) => active === "left")
+	const rightActive = derived([session.active], ([active]) => active === "right")
+	return () => ({
+		active: session.active,
+		// The preview target entry, so the inspector can show a directory card
+		// even when there is no text/card preview.
+		appEntry: session.previewEntry,
+		appHost: session.host,
+		appPath: session.activePath,
+		bookmarkIndex: session.bookmarkIndex,
+		bookmarkItems: session.bookmarkItems,
+		bookmarkMode: session.bookmarkMode,
+		bookmarkOpen: session.bookmarkOpen,
+		bookmarkQuery: session.bookmarkQuery,
+		bookmarkTarget: session.bookmarkTarget,
+		commandBarItems: session.commandBarItems,
+		confirm: session.confirm,
+		dispatch: session.dispatch,
+		filtering: session.filtering,
+		leftActive,
+		leftCursor: left.cursor,
+		leftDisk: left.disk,
+		leftEntries: left.entries,
+		leftEntry: session.leftCursorEntry,
+		leftError: left.error,
+		leftFilter: left.filter,
+		leftId: "left",
+		leftLoading: left.loading,
+		leftMarked: left.marked,
+		leftSegments: left.segments,
+		notice: session.notice,
+		paletteIndex: session.paletteIndex,
+		paletteItems: session.paletteItems,
+		paletteMode: session.paletteMode,
+		paletteOpen: session.paletteOpen,
+		paletteQuery: session.paletteQuery,
+		panelCommand: session.panelCommand,
+		panelDraft: session.panelDraft,
+		panelCursorRow: session.panelCursorRow,
+		panelFiltered: session.panelFiltered,
+		panelFocus: session.panelFocus,
+		panelOpIndex: session.panelOpIndex,
+		panelItems: session.panelItems,
+		panelOpen: session.panelOpen,
+		panelOperation: session.panelOperation,
+		panelQuery: session.panelQuery,
+		panelRowIndex: session.panelRowIndex,
+		panelRows: session.panelRows,
+		panelRunnable: session.panelRunnable,
+		panelTextual: session.panelTextual,
+		panelValue: session.panelValue,
+		preview: session.preview,
+		rightActive,
+		rightCursor: right.cursor,
+		rightDisk: right.disk,
+		rightEntries: right.entries,
+		rightEntry: session.rightCursorEntry,
+		rightError: right.error,
+		rightFilter: right.filter,
+		rightId: "right",
+		rightLoading: right.loading,
+		rightMarked: right.marked,
+		rightSegments: right.segments,
+		showPreview: session.showPreview,
+	})
+}
+
+// Function: createBehaviors
+// Builds the App data/key behavior map for the given renderer environment.
+// Published events are registered separately via `createEvents()` (`.sub`).
+function createBehaviors(env) {
+	return {
+		// Global key handling: confirm dialogs first, palette mode, then the
+		// keymap.
+		keys: (self, data, event) => {
+			const key = env.normalizeKey ? env.normalizeKey(event) : event
+			if (unwrap(data.confirm)) {
+				const name = key?.name
+				if (name === "y" || name === "return" || name === "enter") data.dispatch("confirm.yes")
+				else if (name === "n" || name === "escape") data.dispatch("confirm.no")
+				return
+			}
+			if (unwrap(data.paletteOpen)) {
+				if (key?.name === "escape") {
+					data.dispatch("palette.toggle")
+					return
+				}
+				if (key?.name === "up") {
+					data.dispatch("palette.up")
+					return
+				}
+				if (key?.name === "down") {
+					data.dispatch("palette.down")
+					return
+				}
+				if (key?.name === "tab") {
+					// Shift-Tab walks the palette list backwards.
+					data.dispatch(key.shift ? "palette.up" : "palette.complete")
+					return
+				}
+				if (key?.name === "return" || key?.name === "enter") {
+					self.pub("palette:confirm", `${unwrap(data.paletteQuery) ?? ""}`)
+					return
+				}
+				// Let the focused input handle typing.
+				return
+			}
+			if (unwrap(data.panelOpen)) {
+				const focus = unwrap(data.panelFocus)
+				// Escape closes; Tab cycles the focus ring (command ⇄ args);
+				// arrows move within the focused column; Enter runs the command.
+				if (key?.name === "escape") {
+					data.dispatch("panel.cancel")
+					return
+				}
+				if (key?.name === "tab") {
+					data.dispatch("panel.tab", { delta: key.shift ? -1 : 1 })
+					return
+				}
+				if (key?.name === "up") {
+					data.dispatch(focus === PANEL_FOCUS.ARGS ? "panel.prevArg" : "panel.up")
+					return
+				}
+				if (key?.name === "down") {
+					data.dispatch(focus === PANEL_FOCUS.ARGS ? "panel.nextArg" : "panel.down")
+					return
+				}
+				if (key?.name === "return" || key?.name === "enter") {
+					// A focused textual-argument field owns Enter (its `on:enter`
+					// publishes `panel:confirm`), so the command is not run twice.
+					if (focus === PANEL_FOCUS.ARGS && unwrap(data.panelTextual)) return
+					// Enter runs the highlighted command with the current draft.
+					data.dispatch("panel.run")
+					return
+				}
+				// Space toggles a selection item in the argument column.
+				if (key?.name === "space" && focus === PANEL_FOCUS.ARGS && !unwrap(data.panelTextual)) {
+					data.dispatch("panel.toggleItem")
+					return
+				}
+				if (key?.name === "backspace" && focus === PANEL_FOCUS.ARGS) {
+					// Editing the command filter from the argument column.
+					data.dispatch("panel.type", { backspace: true })
+					return
+				}
+				// While the command column is focused, or a textual argument
+				// owns the cursor, the focused input handles typing.
+				if (focus !== PANEL_FOCUS.ARGS || unwrap(data.panelTextual)) return
+				// Typing on a non-textual argument jumps back to the command
+				// filter and appends the character.
+				if (key?.name && key.name.length === 1 && !key.ctrl && !key.meta) {
+					data.dispatch("panel.type", { char: key.name })
+					return
+				}
+				return
+			}
+			if (unwrap(data.bookmarkOpen)) {
+				const mode = unwrap(data.bookmarkMode)
+				if (key?.name === "escape") {
+					data.dispatch("bookmark.cancel")
+					return
+				}
+				if (mode === "name") {
+					// The input owns typing; Enter saves.
+					if (key?.name === "return" || key?.name === "enter") {
+						self.pub("bookmark:confirm")
+						return
+					}
+					return
+				}
+				// List mode: arrows move, Enter jumps.
+				if (key?.name === "up") {
+					data.dispatch("bookmark.up")
+					return
+				}
+				if (key?.name === "down") {
+					data.dispatch("bookmark.down")
+					return
+				}
+				if (key?.name === "return" || key?.name === "enter") {
+					self.pub("bookmark:confirm")
+					return
+				}
+				// Let the focused input handle typing the fuzzy query.
+				return
+			}
+			const active = unwrap(data.active)
+			if (unwrap(data.filtering) === active) {
+				// The filter input owns the keyboard: Esc clears, Enter keeps
+				// the filter and returns to the list, arrows move the cursor.
+				if (key?.name === "escape") {
+					data.dispatch("filter.clear")
+					return
+				}
+				if (key?.name === "return" || key?.name === "enter") {
+					data.dispatch("filter.accept")
+					return
+				}
+				if (key?.name === "tab") {
+					// Tab keeps the filter and returns to the list; Shift-Tab
+					// switches back to the other pane.
+					data.dispatch(key.shift ? "pane.toggle" : "filter.accept")
+					return
+				}
+				if (key?.name === "up") {
+					data.dispatch("nav.up")
+					return
+				}
+				if (key?.name === "down") {
+					data.dispatch("nav.down")
+					return
+				}
+				// Let the focused filter input handle typing.
+				return
+			}
+			// Esc clears an accepted filter on the active pane; without a
+			// filter (or on Shift-Esc) the keymap decides — Esc steps back
+			// through the pane's directory history.
+			if (key?.name === "escape" && !key.shift) {
+				const filter = active === "left" ? unwrap(data.leftFilter) : unwrap(data.rightFilter)
+				if (filter) {
+					data.dispatch("filter.clear")
+					return
+				}
+			}
+			const id = matchKeymap(DEFAULT_KEYMAP, key)
+			if (!id) return
+			if (id === "app.quit") {
+				env.quit(self)
+				return
+			}
+			// The command panel is a TUI-only view; the web renderer omits the
+			// capability so `m` never opens an invisible modal there.
+			if (id === "panel.toggle" && !env.panel) return
+			data.dispatch(id, { paneId: unwrap(data.active) })
+		},
+	}
+}
+
+// Function: createEvents
+// App event subscriptions, registered with `.sub(...)`. Handlers receive
+// `(self, data, event)` with the published payload in `event.data`. The
+// environment carries the renderer's `quit` hook, so the command bar's Quit
+// entry takes the same path as the `q` key.
+function createEvents(env = {}) {
+	return {
+		"commandbar:run": (_self, data, event) => {
+			if (event.data === "app.quit") {
+				env.quit?.(_self)
+				return
+			}
+			if (event.data) data.dispatch(event.data)
+		},
+		"panel:select": (_self, data, event) => {
+			// Clicking an operation row moves the cursor to it; clicking an
+			// argument/item row focuses the argument column (toggling an item).
+			const items = unwrap(data.panelItems) ?? []
+			const index = items.findIndex((row) => row.id === event.data)
+			if (index >= 0) {
+				data.dispatch("panel.setOp", { index })
+				return
+			}
+			const rows = unwrap(data.panelRows) ?? []
+			const rowIndex = rows.findIndex((row) => row.key === event.data)
+			if (rowIndex < 0) return
+			data.dispatch("panel.focusArg")
+			data.dispatch("panel.setRow", { index: rowIndex })
+			const row = rows[rowIndex]
+			if (row?.type === "item") data.dispatch("panel.toggleItem")
+		},
+		"panel:confirm": (_self, data) => {
+			if (!unwrap(data.panelOpen)) return
+			data.dispatch("panel.run")
+		},
+		"crumbs:go": (_self, data, event) => {
+			// The "…" truncation marker carries no path.
+			if (!event.data?.path) return
+			data.dispatch("pane.setPath", event.data)
+		},
+		"list:select": (_self, data, event) => data.dispatch("list.cursor", event.data),
+		"pane:activate": (_self, data, event) => data.dispatch("pane.activate", { paneId: event.data }),
+		"bookmark:select": (_self, data, event) => {
+			// Clicking a bookmark row selects and jumps to it.
+			if (!unwrap(data.bookmarkOpen)) return
+			const items = unwrap(data.bookmarkItems) ?? []
+			const index = items.findIndex((row) => row.name === event.data)
+			if (index < 0) return
+			data.dispatch("bookmark.setIndex", { index })
+			data.dispatch("bookmark.select")
+		},
+		"bookmark:confirm": (_self, data) => {
+			if (!unwrap(data.bookmarkOpen)) return
+			if (unwrap(data.bookmarkMode) === "name") data.dispatch("bookmark.save")
+			else data.dispatch("bookmark.select")
+		},
+		"palette:confirm": (_self, data, event) => {
+			// The global key handler and the input's on:enter can both fire;
+			// only the first one (while the palette is open) acts.
+			if (!unwrap(data.paletteOpen)) return
+			if (unwrap(data.paletteMode) === "script") {
+				// Submit the typed line: run it, or complete the highlighted row
+				// when the input is empty.
+				data.dispatch("palette.submit")
+				return
+			}
+			const items = unwrap(data.paletteItems) ?? []
+			const index = Math.max(0, Math.min(unwrap(data.paletteIndex) ?? 0, items.length - 1))
+			const match = items[index] ?? items[0]
+			if (match?.id) data.dispatch(match.id)
+			data.dispatch("palette.toggle")
+		},
+		"palette:run": (_self, data, event) => {
+			if (!event.data) return
+			if (unwrap(data.paletteMode) === "script") {
+				// Clicking a script row completes it; running stays on Enter.
+				const item = (unwrap(data.paletteItems) ?? []).find((row) => row.id === event.data)
+				if (item?.completion) data.dispatch("palette.setQuery", { query: item.completion })
+				return
+			}
+			data.dispatch(event.data)
+			data.dispatch("palette.toggle")
+		},
+	}
+}
+
+export { createBehaviors, createEvents, createInit }
+
+// EOF