@ssebastien/tcmd 0.1.3 → 0.1.7

package/README.md

@@ -10,18 +10,78 @@
 
 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
+- Browse files in the three-column explorer (the opening view) — the parent
+  directory, the current directory (slightly wider) and the preview — or in
+  the two-pane commander (the left is the source, the right the destination),
+  with `t` toggling between the two views. Clicking any column, preview
+  included, gives it the focus.
+- Named bookmarks: `b` opens one bookmarks panel. Type to filter the stored
+  bookmarks by name or path; when the filter is empty and the cursor entry (or
+  the pane directory) is not bookmarked yet, a first row adds it under a
+  basename-derived name. `Enter` opens the selected bookmark, `⌫`/`Delete`
+  removes it. A directory bookmark opens to show its contents, a file bookmark
+  is selected and previewed in its directory.
+- Undo/redo (`⌃Z` / `⌃⇧Z` or `⌃Y`) over recorded filesystem changes (mkdir,
+  copies to new destinations, move, rename, trashed delete), with a history list
+  (`u`); a delete reports the trash directory it used and can be undone or
+  restored from the trash browser
+  (`⇧T`), which lists trashed entries by their original path. A double click on
+  a row opens it like `Enter`.
+- Operations over the current panes: copy, move, mkdir/new, hardlink/symlink,
+  chmod/chown, delete/erase/unlink, stat, du/df, touch, selection buffers,
+  edit/view/open and shell commands; `abspath` and `realpath` show
+  copy-pasteable absolute paths and copy them to the clipboard, with the latter
+  following symlinks. `unlink` removes links only, never their targets.
+- Command panel (`:`), the one entry point, a two-pane palette: the left pane
+  filters (`:xxx`) over CLI operations grouped by purpose: **Command**,
+  **File**, **Info**, **Create**, **Edit** (amber), and **Delete** (red). The
+  Command group also has the workspace-view toggle and Quit; File's `view`
+  previews the selected path; Info holds `stat`, `du` and `df`; amber Edit also
+  holds `copy` and the metadata changes. Bold section
+  titles head indented command names, alphabetized within each category. The right
+  pane lists the selected command's arguments under its name — editable values
+  use filled fields, while read-only values are plain and muted; `new`/`mkdir`
+  show the current `PATH` above a `NAME`, and `chmod`/`chown` list `PATH`
+  first. Selections use
+  a checkbox (multiple) / radio (single)
+  list of the selected paths wrapped in its own border, with a lone path shown
+  read-only. `chmod`'s `MODE` is a compact u/g/o grid of clickable R/W/X cells
+  (arrow keys move between cells, Space toggles), seeded from the selected
+  file's current mode. Labels and values sit one space in from the pane border
+  (` PATH`, ` [value]`), and `[Run]` follows the last field after a
+  blank line, aligned left in the command category's color. Amber (Edit) and
+  red (Delete) actions take two steps: the first Run turns the action into
+  `[Confirm]` and prints the command below it in the risk colour, the second
+  executes. A failed run shows `[Retry]` with a framed error block below it,
+  while a
+  successful result briefly replaces the command bar at the bottom. A selection
+  argument draws from the *focused* column, so in the explorer focusing the parent mirror
+  selects the directory under its cursor. `Tab` cycles the filter, arguments and
+  Run button; `Enter` runs a complete command or jumps to the next missing
+  argument, and a `[Close Esc]` close button sits in the dialog's top border,
+  upper right. `!` lands straight on the shell
+  command. A destination/path argument browses the filesystem in a file picker
+  (`⌃O`): its path is editable as a string, the matching entries sit below and
+  render like a file panel (icons, aligned sizes, scrollbar), with `..` pinned
+  at the top. Explorer mode has no destination pane, so a move or copy there
+  asks where to. A `replace` operation replaces a literal `FIND` with `REPLACE`
+  across the selection — one file replaces its whole name — previewing each
+  `old → new` mapping before it runs. Exact `rename FROM TO PATH` renames one named
+  child inside `PATH`.
+- Keyboard and mouse navigation, inline file previews — a previewed directory
+  renders as a pane (its breadcrumbs over its own listing), in both views, a
+  source file highlights with tree-sitter (JavaScript, TypeScript, Markdown and
+  Zig today) through the same `code` renderable, and an image draws in place
+  through the terminal's graphics protocol (Kitty/sixel, half-block fallback),
+  the metadata card staying for formats with no decoder. `.gz` and `.bz2`
+  entries preview their decompressed contents: the inner name drives the kind
+  and highlighter (`notes.txt.gz` heads as `<GZ · TXT>`), and a body that
+  decompresses to binary stays a card
+- Symlinks are shown *and* followed: a link row prints `name -> target`
+  (`notes.md -> notes.txt`, `docs/ -> ../shared`), a link to a directory is a
+  directory (it sorts, opens and previews as one), and the preview reads
+  through it — the header reads `notes.md -> notes.txt  <TXT>` and the kind
+  comes from the target's extension, not the link's name
 - Bookmarks and quick find (later milestones)
 
 References: [Marta.sh](https://marta.sh) for the UI, [fman.io](https://fman.io)
@@ -46,39 +106,88 @@ 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
+Keys: `↑/↓` move (`^↑/^↓` jump a few lines), `Enter/→` open (a directory
+re-opens with the cursor it was left with, a text file opens in `$EDITOR`, and
+anything that cannot be edited — an image, media, a binary, or any file on a
+host with no editor — opens the fullscreen viewer), `←/Bksp` parent (the cursor
+lands on the directory you left), `Esc`/`⇧Esc` history back/forward, `Tab`/`⇧Tab` switch panes
+(`⇧Tab` goes back), `t` toggle the commander/explorer view, `Space` mark, `b`
+open the bookmarks panel (filter, add the current path, `Enter` open,
+`⌫`/`Del` remove), `:` open the
+command panel (the one entry point for CLI operations, grouped by risk with
+editable arguments, an explicit Run button and the inline file picker on `⌃O`),
+`v` preview (fullscreen viewer when
+the terminal is narrow), `⇧V` maximize the preview over the columns and back
+again (in either full view, `↑`/`↓` scroll a file preview and `←`/`→` step to
+the previous/next entry), `O`/`E` open/edit the previewed file, `/` fuzzy-filter
+the active pane (`Enter` keeps it, `Esc` clears), `!` open the panel on the
+shell command, `F5`/`r`/`^R` reload, `?` key reference, `q` quit.
+
+Listings refresh themselves when the filesystem changes: the TUI and desktop
+views watch the displayed directories natively, while the web view polls them
+every few seconds. Hidden columns pause their watcher and re-read when shown.
+A refresh keeps the selected entry selected, so files written by other
+programs appear without moving the cursor. The keys above (and the web toolbar
+button) remain for a forced re-read.
+
+The workspace opens in explorer mode with a slim identity bar (`TinyCmd -
+HOST`) — the view mode and version trailing at its right, the mode word drawn
+letter by letter along the logo's own gradients (`explorer` in the Tiny blues,
+`commander` in the Cmd oranges, clicking it toggles the view) and the version
+dim after it — over an
+unframed tiling of pane boxes (the two middle edges sit side by side) labelled
+**SRC** (left, source) / **DST** (right, destination) in commander, 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
+rule from the listing, and an entry-detail line for the selected entry. 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
+bright, and the size/rights dropping out when the pane is too narrow. The active
+pane's border and header rule take the view mode's colour — the Tiny blue in
+explorer, the gold accent in commander — and its cursor row uses the strong
+cursor colour, while
+the inactive pane stays dim with a muted cursor. TUI 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
+`Dockerfile` and dotfiles included), on unless `TCMD_ICONS=0`; it needs a
+Nerd-Font-patched terminal font. The web and desktop views use local Lucide SVG
+icons for toolbar actions, file kinds, bookmarks, and Help key badges; command
+panel entries show a chevron to indicate their argument pane. 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
+fullscreen viewer below that; `⇧V` expands it over the whole pane row —
+parent and current included — and brings the previous layout back on the next
+press. The status bar keeps its fixed bracket shorthands on one line
+(`[Commands :]`, `[Mark Spc]`, `[Filter /]`, `[Switch ⇥]`, `[Bookmarks b]`,
+`[Toggle Mode t]`, `[Help ?]`) and elides entries behind `…` when the width
+runs out — 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.
 
+### View modes
+
+`t` flips the workspace between two modes:
+
+- **explorer** (the default) leads with the parent of the current directory,
+  so the three columns read parent · current · preview — a Miller chain with
+  the current column slightly wider than its neighbours;
+- **commander** tiles source and destination.
+
+The parent and preview columns are mirrors: they own their cursor, filter and
+marks, but opening an entry, stepping up, following one of their breadcrumbs or
+clicking one of their rows moves the pane they follow, which is what keeps the
+mirror in step (in the explorer the previewed directory *is* the current
+column's own child, so the chain never drifts). A click on the parent column
+makes the clicked directory the current one — or, for a file, opens its
+directory with the file selected and previewed — while a click inside the
+previewed directory promotes that directory to current with the clicked entry
+selected (focus stays on the column that was clicked). The parent mirror's
+cursor also follows the current
+directory: it lands on the entry the current pane shows, so the chain always
+highlights where it is. `Tab` cycles through the columns the current mode shows,
+and clicking any column — the preview included — gives it the focus. A
+previewed directory always renders as a pane, in both modes: its breadcrumbs
+over its own listing, instead of a directory card.
+
 ### Web version
 
 The web view runs the same core on select.js and offers two filesystem
@@ -89,28 +198,104 @@ backends:
 - **HTTP API** (automatic fallback, or `?fs=http`): the server exposes the
   real filesystem over `/api/*`, using the same Node adapter as the TUI.
 
+It uses the same command panel (`:`), selection/filter and history keys as the
+TUI, plus `?` for the key reference. Pane focus, marks,
+entry details and command risk colours follow the terminal presentation. The
+inspector sits beside the panes when wide and opens with `v` as a fullscreen
+viewer when narrow (`Esc` closes it); `⇧V` maximizes it over the pane row and
+restores the layout. Bookmarks persist in browser storage,
+separately for each filesystem backend and HTTP root; they are not shared with
+the TUI's bookmark file. Storage denial leaves bookmarks usable for the session.
+
 ```sh
+tcmd --server        # installed command: serve the web UI without the TUI
 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/*
 ```
 
+From a checkout, `./bin/tcmd --server` (or `bun run tcmd --server`) does the
+same thing, building the browser bundle if it is missing. Installed packages
+include the bundle. Open http://localhost:8787/?fs=http for your actual files,
+or http://localhost:8787/?fs=opfs for the browser-storage demo. Stop with Ctrl-C.
+Use `HOST=0.0.0.0 PORT=9000 tcmd --server` to change the address and port
+(default `127.0.0.1:8787`), or
+`TCMD_WEB_ROOT=/some/dir tcmd --server` to confine the filesystem API. `HOST`
+takes an IP address (`0.0.0.0` or `::` for every interface); a machine name
+resolves to several addresses and the server binds only one of them.
+
 `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
+only supports OPFS); the server binds to loopback by default (`HOST`
+overrides it) 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
+don't expose the port. Symlinks that resolve outside the root are rejected;
+root and destination checks are not race-proof against another local process
+changing the filesystem during a request. With OPFS, deleting moves entries to `/.trash`;
+the API uses the desktop trash. OPFS coordination across tabs uses Web Locks
+when available; without them, writes are coordinated per adapter only.
+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.
 
+### Desktop app (tinyjs)
+
+The native desktop target reuses the web presentation and shared session, but
+uses a tinyjs backend for real filesystem access. It runs without Bun/Node in
+the shipped app and does not start an HTTP server or open a port.
+
+Install [tinyjs](https://tinyjs.app/) and the project dependencies, then run:
+
+```sh
+bun install
+bun run desktop:dev       # bundle the webview UI, then open the native window
+bun run desktop:build     # tinyjs build; emits a platform-native app/package
+```
+
+`tinyjs.json` configures the app. `tinyjs build` bundles the desktop frontend
+through `desktop:bundle`; the source page is `desktop/frontend/index.html`.
+For frontend changes during development, rerun `bun run desktop:bundle` before
+reloading the window. The desktop uses the system webview and requires tinyjs
+0.57.0 or newer.
+
+The desktop window keeps the native title bar, hides the native menu, and uses
+an in-app toolbar for folder navigation, refresh, view/preview toggles, commands
+and help. Its toolbar replaces the TinyCmd identity header; the browser UI keeps
+that header. Press F6 to move focus between the workspace and toolbar; toolbar
+buttons use native Tab/Enter/Space keys, and Escape returns to the workspace.
+
+The web UI uses the system sans-serif font for controls and chrome, with the
+M+1Code Nerd Font Mono bundled for filenames, paths, and file content. The
+font is from Nerd Fonts v3.5.1 and is distributed under SIL OFL 1.1; its license
+is included in `public/fonts/OFL.txt`.
+The UI icons are from Lucide and distributed under ISC (with the listed Feather
+icons under MIT); the license is included in `public/licenses/LUCIDE.txt`.
+
+On Linux, the tinyjs launcher also needs the Ayatana AppIndicator runtime. On
+Fedora install it with `sudo dnf install libayatana-appindicator-gtk3`; on
+Debian/Ubuntu use `sudo apt install libayatana-appindicator3-1`. Install the
+WebKitGTK runtime required by tinyjs as well.
+
+Filesystem operations are performed by the backend using txiki.js APIs. Text
+files open in the operating system's default editor; `!` / shell commands run
+in a non-interactive shell and display captured output in a native dialog.
+Trash uses the Freedesktop trash under `$XDG_DATA_HOME` (or
+`~/.local/share/Trash`), including undo/restore. The current desktop adapter
+supports POSIX paths on Linux and macOS. Windows drive/UNC paths are not yet
+supported; the app reports this rather than attempting file operations.
+
+The desktop backend has full access to the current user's files, and the
+command panel intentionally exposes shell execution. Treat commands and
+filesystem prompts accordingly. Browser and TUI builds remain separate and
+continue to use their existing backends.
+
 ## Architecture
 
 MVC with a presentation-agnostic core, so a web UI can share the same model
@@ -125,26 +310,26 @@ src/js/tcmd/
     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
+    pane.js      one directory, proxying its cells + currentPane resolution
     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
+    panel.js     grouped CLI command panel, with arguments bound from context
+    session.js   two panes + parent/preview mirrors, view mode, active pane, preview, 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
+    operations.js CLI operations (copy/move/delete/erase/stat/sel/…)
+    script.js    scripting line parser and runner
   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
+    Frame.js          workspace chrome, breakpoints and command-bar geometry
+    Help.js           key-reference overlay behaviors + the two-column key text
     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)
@@ -152,6 +337,8 @@ src/js/tcmd/
     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)
+    effects.js   instance-owned focus, key trapping, resize and scroll effects
+    bookmarks.js localStorage bookmark store, scoped by backend and API root
     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`)
@@ -177,9 +364,13 @@ 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
+`components/Frame.js` holds the renderer-free workspace chrome (brand bar,
+responsive breakpoints, pane borders, command-bar geometry) and
+`components/Help.js` holds the key reference — behaviours and the two-column
+key text, with every distinct keymap chord shown in the command bar's bracket
+style — used by both views. Web-only components live under `web/` (`header.js` +
+`header.html`, plus the DOM effects in `effects.js` and the bookmark store in
+`bookmarks.js`). 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.
 
@@ -206,8 +397,8 @@ Decoupling rules:
   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.
+`deps/` symlinks to sibling checkouts; run `scripts/link-deps.sh` after
+`bun install` to re-link `node_modules` so upstream edits propagate.
 
 ## Tests
 
@@ -222,14 +413,17 @@ 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)
+      bar, command panel, text preview
+- [x] File operations (copy/move/delete/erase/stat/touch/sel), with the
+      `$A`/`$B` pane filesets and `$FILE` still resolving in any argument
+- [x] Grouped command panel (`:`): white / amber / red risk sections, editable
+      arguments, an explicit Run action and an inline picker; `!` lands on shell
 - [x] Pane fuzzy filtering (`/` to filter, `Enter` to keep, `Esc` to clear)
-- [x] Named bookmarks (`b` records, `g` jumps, persisted to a JSON file)
+- [x] Named bookmarks (`b` opens the panel to add, filter, open or remove them,
+      persisted to a JSON file)
 - [ ] Quick find, grep
-- [ ] Image/PDF/audio/video previews
+- [x] Image previews (terminal graphics protocol) and tree-sitter source
+      highlighting in the inspector
+- [ ] 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

@@ -5,13 +5,21 @@ if ! command -v bun >/dev/null 2>&1; then
 	exit 1
 fi
 script=$0
+case "$script" in
+	*/*) ;;
+	*) script=$(command -v "$script") ;;
+esac
+case "$script" in
+	/*) ;;
+	*) script=$PWD/$script ;;
+esac
 while [ -L "$script" ]; do
-	dir=$(CDPATH= cd -- "$(dirname -- "$script")" && pwd)
+	dir=$(CDPATH= cd -P -- "$(dirname -- "$script")" && pwd)
 	link=$(readlink "$script")
 	case "$link" in
 		/*) script=$link ;;
 		*) script=$dir/$link ;;
 	esac
 done
-dir=$(CDPATH= cd -- "$(dirname -- "$script")" && pwd)
+dir=$(CDPATH= cd -P -- "$(dirname -- "$script")" && pwd)
 exec bun "$dir/tcmd.js" "$@"

package/bin/tcmd.js

@@ -1,4 +1,15 @@
 #!/usr/bin/env bun
 // TinyCommand `tcmd` entry point.
-const paths = process.argv.slice(2).filter((arg) => arg !== "-")
-await import("../src/js/tcmd/tui/index.js").then((tui) => tui.main(paths))
+const raw = process.argv.slice(2).filter((arg) => arg !== "-")
+// `--server` is a mode flag, not a path: accept it in any position.
+const server = raw.includes("--server")
+const paths = raw.filter((arg) => arg !== "--server")
+if (server) {
+	if (paths.length > 0) {
+		console.error("Usage: tcmd --server (configure with HOST, PORT and TCMD_WEB_ROOT)")
+		process.exit(1)
+	}
+	await import("../scripts/serve-web.js").then((web) => web.main())
+} else {
+	await import("../src/js/tcmd/tui/index.js").then((tui) => tui.main(paths))
+}

package/desktop/dist/index.html

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en">
+	<head>
+		<meta charset="utf-8" />
+		<meta name="viewport" content="width=device-width, initial-scale=1" />
+		<title>TinyCommand</title>
+		<link rel="stylesheet" href="./style.css" />
+	</head>
+	<body>
+		<div id="app"></div>
+		<script type="module" src="./main.js"></script>
+	</body>
+</html>