@ssebastien/tcmd 0.1.4 → 0.1.7

package/src/js/tcmd/web/effects.js

@@ -8,10 +8,14 @@
 // default-key trapping and keeping the keyboard cursor visible. select.js
 // renders without any of this, so the web binding owns it explicitly.
 
-import { INSPECTOR_INLINE_WIDTH } from "../components/Frame.js"
+import { effect } from "select/state/cells"
 
 const canvases = new WeakMap()
 
+function isToolbarTarget(target) {
+	return Boolean(target?.closest?.(".desktop-toolbar"))
+}
+
 // Function: columnWidth
 // Available monospace columns, or zero in a DOM without layout (happy-dom).
 function columnWidth(el) {
@@ -42,6 +46,33 @@ function keepVisible(list, row) {
 	else if (rowRect.bottom > listRect.bottom) list.scrollTop += rowRect.bottom - listRect.bottom
 }
 
+// Function: previewBodies
+// The scrollable preview bodies in `root`: the inspector, the maximized
+// preview and the viewer each reuse one text/card body.
+function previewBodies(root) {
+	return root?.querySelectorAll?.(".preview-text, .preview-card") ?? []
+}
+
+// Function: resetPreviewScroll
+// Send the preview body back to the top. The inspector, the maximized preview
+// and the viewer each reuse one scrollable body, so a scroll offset would
+// otherwise carry over to the next file.
+function resetPreviewScroll(root) {
+	for (const body of previewBodies(root)) {
+		body.scrollTop = 0
+	}
+}
+
+// Function: applyPreviewScroll
+// Apply a full-preview scroll request from the App's arrow routing. The DOM
+// clamps `scrollTop` against the visible body, so the edges need no guard.
+function applyPreviewScroll(root, delta) {
+	if (!delta) return
+	for (const body of previewBodies(root)) {
+		body.scrollTop = Math.max(0, body.scrollTop + delta)
+	}
+}
+
 // Function: connectEffects
 // Returns a frame scheduler and teardown; the App registers teardown with
 // instance.effect(), so remounting leaves no listeners or observers behind.
@@ -53,14 +84,20 @@ function connectEffects(session, root, { size, help, viewer }) {
 	let frame = null
 	let retries = 0
 	let disposed = false
-	const viewerOpen = () => viewer.value && size.value.width > 0 && size.value.width < INSPECTOR_INLINE_WIDTH
+	// The viewer overlay is a modal at any width (Enter opens it on a file
+	// that cannot be edited); it owns focus while open.
+	const viewerOpen = () => Boolean(viewer.value)
 	const modalOpen = () => Boolean(session.confirm.value || help.value || viewerOpen() || session.panelOpen.value || session.bookmarkOpen.value)
 	const focusTarget = () => {
 		if (session.confirm.value) return root.querySelector(".confirm")
 		if (help.value) return root.querySelector(".help")
 		if (viewerOpen()) return root.querySelector(".viewer")
 		if (session.panelOpen.value) {
-			if (session.panelPicking.value) return root.querySelector(".panel-picker-query")
+			if (session.pickerOpen.value) {
+				return session.pickerFocus.value === "path"
+					? root.querySelector(".panel-picker-path")
+					: root.querySelector(".command-panel")
+			}
 			if (session.panelFocus.value === "ops") return root.querySelector(".panel-query")
 			return root.querySelector(session.panelTextual.value ? ".panel-value" : ".command-panel")
 		}
@@ -75,12 +112,6 @@ function connectEffects(session, root, { size, help, viewer }) {
 		const lineHeight = Number.parseFloat(view.getComputedStyle(root).lineHeight)
 		const height = lineHeight ? Math.floor(root.clientHeight / lineHeight) : 0
 		if (width && height && (size.value.width !== width || size.value.height !== height)) size.set({ width, height })
-		// A fullscreen viewer only exists while the viewport is narrow;
-		// widening back to the inline inspector drops the stale state so a
-		// later narrow resize does not resurrect it. Reads the cell (not just
-		// the fresh measurement) so a host that drives `size` directly is
-		// honoured too.
-		if (viewer.value && size.value.width >= INSPECTOR_INLINE_WIDTH) viewer.set(false)
 		// A modal's field mounts on a later frame than the flag that opens it;
 		// retry a few frames before giving up so focus lands on the overlay
 		// instead of the root.
@@ -91,7 +122,10 @@ function connectEffects(session, root, { size, help, viewer }) {
 			return
 		}
 		retries = 0
-		const focusable = target ?? root
+		// Do not steal focus as Tab moves between native toolbar buttons.
+		const toolbarFocused = !modalOpen() && !session.filtering.value &&
+			root.contains(doc.activeElement) && isToolbarTarget(doc.activeElement)
+		const focusable = toolbarFocused ? doc.activeElement : target ?? root
 		if (focusable !== doc.activeElement) focusable.focus({ preventScroll: true })
 		for (const list of root.querySelectorAll(".file-list, .bookmark-rows, .panel-ops, .panel-args")) {
 			keepVisible(list, list.querySelector(".is-current, .is-selected, .is-focused"))
@@ -105,12 +139,23 @@ function connectEffects(session, root, { size, help, viewer }) {
 		})
 	}
 	const trapKeys = (event) => {
+		// Reload remains disabled even when native controls own the other keys.
+		// F5 now refreshes the listing too, so it must not reload the page.
+		if ((event.ctrlKey && event.key.toLowerCase() === "r") || event.key === "F5") {
+			event.preventDefault()
+			return
+		}
+		if (isToolbarTarget(event.target)) return
 		const input = event.target?.tagName === "INPUT" || event.target?.tagName === "TEXTAREA"
 		// Editing keeps native text/caret keys except the ones the shared
 		// controller explicitly owns (vertical arrows, Enter and Tab).
-		if (input && [" ", "Backspace", "ArrowLeft", "ArrowRight", "Home", "End", "PageUp", "PageDown"].includes(event.key)) return
-		if ([" ", "Backspace", "Enter", "Tab", "ArrowUp", "ArrowDown", "ArrowLeft", "ArrowRight", "Home", "End", "PageUp", "PageDown", "Escape"].includes(event.key) ||
-			(event.ctrlKey && event.key.toLowerCase() === "r")) event.preventDefault()
+		if (input && [" ", "ArrowLeft", "ArrowRight", "Home", "End", "PageUp", "PageDown"].includes(event.key)) return
+		// The bookmark filter edits its query like any input; once it is empty,
+		// Backspace removes the selected bookmark instead. Delete always does.
+		const bookmarkFilterEmpty = session.bookmarkOpen.value && !`${session.bookmarkQuery?.value ?? ""}`.trim()
+		if (input && event.key === "Backspace" && !bookmarkFilterEmpty) return
+		if (session.bookmarkOpen.value && event.key === "Delete") event.preventDefault()
+		if ([" ", "Backspace", "Enter", "Tab", "ArrowUp", "ArrowDown", "ArrowLeft", "ArrowRight", "Home", "End", "PageUp", "PageDown", "Escape"].includes(event.key)) event.preventDefault()
 	}
 	const focusIn = (event) => {
 		if (modalOpen() && event.target !== focusTarget()) schedule()
@@ -123,11 +168,46 @@ function connectEffects(session, root, { size, help, viewer }) {
 	observer?.observe(root)
 	// Pane proportions also change when the inspector is toggled.
 	for (const pane of root.querySelectorAll(".pane")) observer?.observe(pane)
+	// Modal state can change before the initial focus frame runs (for example,
+	// the user opens the panel immediately after mount). Watch the focus-driving
+	// cells directly so that initial layout work cannot swallow that handoff.
+	const stopFocusWatch = effect(
+		[
+			session.panelOpen,
+			session.panelFocus,
+			session.panelOpIndex,
+			session.panelRowIndex,
+			session.panelTextual,
+			session.pickerOpen,
+			session.bookmarkOpen,
+			session.filtering,
+			session.confirm,
+			session.overlay,
+			help,
+			viewer,
+		],
+		schedule,
+	)
+	// The preview target and its payload both change as the cursor moves:
+	// reset on either so a new file starts at the top even when its text
+	// arrives asynchronously.
+	const previewInputs = [session.previewEntry, session.preview].filter((value) => value?.isReactive)
+	const stopPreviewWatch = previewInputs.length
+		? effect(previewInputs, () => resetPreviewScroll(root))
+		: null
+	// Full-preview arrow scrolling: the shared controller publishes a delta,
+	// the DOM body applies it to its own measured viewport.
+	const stopScrollWatch = session.previewScroll?.isReactive
+		? effect([session.previewScroll], ([request]) => applyPreviewScroll(root, request?.delta ?? 0))
+		: null
 	schedule()
 	return {
 		schedule,
 		dispose() {
 			disposed = true
+			stopFocusWatch?.()
+			stopPreviewWatch?.()
+			stopScrollWatch?.()
 			if (frame !== null) view.cancelAnimationFrame(frame)
 			observer?.disconnect()
 			root.removeEventListener("keydown", trapKeys)
@@ -138,6 +218,6 @@ function connectEffects(session, root, { size, help, viewer }) {
 	}
 }
 
-export { columnWidth, connectEffects, keepVisible }
+export { applyPreviewScroll, columnWidth, connectEffects, isToolbarTarget, keepVisible, resetPreviewScroll }
 
 // EOF

package/src/js/tcmd/web/header.html

@@ -1 +1 @@
-<header class="app-header" ref="box"><span class="brand-tiny">Tiny</span><span class="brand-cmd">Cmd</span><span out="title"></span><span class="app-header-status"><span class="app-header-mode" out:class="modeClass" out="mode"></span><span out="statusSuffix"></span></span></header>
+<header class="app-header" ref="box"><span class="brand-tiny">Tiny</span><span class="brand-cmd">Cmd</span><span out="title"></span><span class="app-header-status"><span class="app-header-mode" out:class="modeClass" on:click="!view:toggleMode"><svg class="header-mode-icon ui-icon" aria-hidden="true" focusable="false" viewBox="0 0 24 24"><use href="#lucide-columns-2"></use></svg><span out="mode"></span></span><span out="statusSuffix"></span></span></header>

package/src/js/tcmd/web/http.js

@@ -14,6 +14,8 @@
 // into `index.html`; when the page is not served by `bun run web:serve`, the
 // API is unreachable and the factory fails with a hint.
 
+import { decodeBase64 } from "../core/base64.js"
+
 // Function: apiToken
 // Token injected into the host page, or null when absent/placeholder.
 function apiToken(doc = globalThis.document) {
@@ -59,13 +61,24 @@ async function createHttpFs({ base = "/api", token, fetch: doFetch = globalThis.
 	return {
 		readDir: (path) => request("GET", "readDir", { params: { path } }),
 		stat: (path) => request("GET", "stat", { params: { path } }),
+		realpath: (path) => request("GET", "realpath", { params: { path } }),
 		isDir: async (path) => Boolean((await request("GET", "stat", { params: { path } }))?.isDir),
 		readTextHead: (path, maxBytes) => request("GET", "readTextHead", { params: { path, maxBytes } }),
+		readBytes: async (path, maxBytes) =>
+			decodeBase64((await request("GET", "readBytes", { params: { path, maxBytes } })).base64),
 		du: (path) => request("GET", "du", { params: { path } }),
 		disk: (path) => request("GET", "disk", { params: { path } }),
 		copy: (from, to) => request("POST", "copy", { body: { from, to } }),
 		move: (from, to) => request("POST", "move", { body: { from, to } }),
+		hardlink: (from, to) => request("POST", "hardlink", { body: { from, to } }),
+		symlink: (target, link) => request("POST", "symlink", { body: { target, link } }),
+		chmod: (path, mode) => request("POST", "chmod", { body: { path, mode } }),
+		chown: (path, owner) => request("POST", "chown", { body: { path, owner } }),
+		unlink: (path) => request("POST", "unlink", { body: { path } }),
+		mkdir: (path) => request("POST", "mkdir", { body: { path } }),
 		trash: (paths) => request("POST", "trash", { body: { paths } }),
+		trashList: () => request("GET", "trashList"),
+		restore: (paths) => request("POST", "restore", { body: { paths } }),
 		erase: (paths) => request("POST", "erase", { body: { paths } }),
 		touch: (path) => request("POST", "touch", { body: { path } }),
 		home: () => info.home,

package/src/js/tcmd/web/index.js

@@ -12,8 +12,8 @@ import { createWebApp } from "./app.js"
 
 // Function: main
 // Mounts the web UI for `session` into `selector` (default "#app").
-function main(session, selector = "#app") {
-	const App = createWebApp(session)
+function main(session, selector = "#app", options = {}) {
+	const App = createWebApp(session, options)
 	return App.new().mount(selector)
 }
 

package/src/js/tcmd/web/opfs.js

@@ -15,9 +15,17 @@
 // creating parents) backs the demo seeding in `web/main.js`.
 //
 // Trash: OPFS has no system trash, so `trash(paths)` moves entries into a
-// `/.trash` directory at the storage root, where they stay browsable.
+// `/.trash` directory at the storage root, recording original paths in
+// `/.trash/index.json` so `trashList()`/`restore()` can browse and undelete
+// them across reloads.
 
+import { mapLimit } from "../core/concurrency.js"
 import { basename, extname, join, normalize, parent, split } from "../core/path.js"
+import { PREVIEW_BYTES } from "../core/preview.js"
+
+// Constant: OPFS_READDIR_CONCURRENCY
+// Bounded window for the per-entry `getFile` metadata calls of a listing.
+const OPFS_READDIR_CONCURRENCY = 64
 
 // Function: createOpfsFs
 // Builds the filesystem adapter. `root` overrides the OPFS root handle (tests);
@@ -129,23 +137,36 @@ function createOpfsFs({ root, home = "/home/tester" } = {}) {
 	}
 
 	// Function: readDir
-	// Lists `path` as FileEntry-like rows.
+	// Lists `path` as FileEntry-like rows. Directory handles arrive through an
+	// async iterator, but each file's metadata (`getFile`) is an independent
+	// async call, so the entries are mapped with a bounded window instead of
+	// one await at a time.
 	async function readDir(path) {
 		const directory = await resolveDir(normalize(path))
-		const entries = []
-		for await (const handle of directory.values()) entries.push(await toEntry(path, handle))
-		return entries
+		const handles = []
+		for await (const handle of directory.values()) handles.push(handle)
+		return mapLimit(handles, OPFS_READDIR_CONCURRENCY, (handle) => toEntry(path, handle))
 	}
 
 	// Function: readTextHead
 	// Leading `maxBytes` of a text file, decoded as UTF-8.
-	async function readTextHead(path, maxBytes = 65536) {
+	async function readTextHead(path, maxBytes = PREVIEW_BYTES) {
 		const handle = await resolveFile(normalize(path))
 		if (!handle) throw notFound(path)
 		const file = await handle.getFile()
 		return file.slice(0, maxBytes).text()
 	}
 
+	// Function: readBytes
+	// Leading `maxBytes` of a file as raw bytes, for the compressed previews
+	// `core/session` decompresses.
+	async function readBytes(path, maxBytes = PREVIEW_BYTES) {
+		const handle = await resolveFile(normalize(path))
+		if (!handle) throw notFound(path)
+		const file = await handle.getFile()
+		return new Uint8Array(await file.slice(0, maxBytes).arrayBuffer())
+	}
+
 	// Function: du
 	// Recursive size in bytes; unreadable entries contribute 0.
 	async function du(path) {
@@ -176,14 +197,19 @@ function createOpfsFs({ root, home = "/home/tester" } = {}) {
 	// Function: copy
 	// Recursive copy of a file or directory; an existing directory target is
 	// merged into (the operations layer already appends the basename when the
-	// user copies "into" a directory).
+	// user copies "into" a directory), but colliding entries are never replaced.
 	async function copy(from, to) {
+		assertOutsideTrash(to)
+		return withPathLock(to, () => copyEntry(from, to))
+	}
+
+	async function copyEntry(from, to) {
+		await assertCopySafe(from, to)
 		const stats = await stat(from)
-		if (!stats) throw notFound(from)
 		if (stats.isDir) {
 			if (!(await stat(to))?.isDir) await ensureDir(to)
 			for await (const handle of (await resolveDir(from)).values()) {
-				await copy(join(from, handle.name), join(to, handle.name))
+				await copyEntry(join(from, handle.name), join(to, handle.name))
 			}
 			return
 		}
@@ -195,6 +221,25 @@ function createOpfsFs({ root, home = "/home/tester" } = {}) {
 		await writable.close()
 	}
 
+	async function assertCopySafe(from, to) {
+		const sourcePath = normalize(from)
+		const targetPath = normalize(to)
+		const source = await stat(sourcePath)
+		if (!source) throw notFound(from)
+		if (
+			sourcePath === targetPath ||
+			(source.isDir && targetPath.startsWith(sourcePath === "/" ? "/" : `${sourcePath}/`))
+		) {
+			throw new Error(`cannot copy a path into itself: ${to}`)
+		}
+		const destination = await stat(targetPath)
+		if (!destination) return
+		if (!source.isDir || !destination.isDir) throw pathExistsError(to)
+		for (const entry of await readDir(sourcePath)) {
+			await assertCopySafe(entry.path, join(targetPath, entry.name))
+		}
+	}
+
 	// Function: eraseOne
 	// Removes one entry (recursively for directories); the root is a no-op.
 	async function eraseOne(path) {
@@ -204,19 +249,174 @@ function createOpfsFs({ root, home = "/home/tester" } = {}) {
 		await directory.removeEntry(basename(normalized), { recursive: true })
 	}
 
+	// Function: mkdir
+	// Creates `path` (and its parents) as a directory.
+	async function mkdir(path) {
+		const normalized = normalize(path)
+		assertOutsideTrash(normalized)
+		if (normalized === "/") return
+		return withPathLock(normalized, () => ensureDir(normalized))
+	}
+
+	// Constant: TRASH_DIR / TRASH_INDEX
+	// Trashed entries live under `/.trash/<name>` and the original paths are
+	// recorded in `/.trash/index.json`, so a restore survives a reload.
+	const TRASH_DIR = "/.trash"
+	const TRASH_INDEX = `${TRASH_DIR}/index.json`
+
+	// Function: readTrashIndex
+	// The trash index rows, or [] when the index is missing.
+	async function readTrashIndex() {
+		try {
+			const handle = await resolveFile(TRASH_INDEX)
+			if (!handle) return []
+			const parsed = JSON.parse(await (await handle.getFile()).text())
+			if (!Array.isArray(parsed)) throw new Error("invalid OPFS trash index")
+			return parsed
+		} catch (error) {
+			if (error?.code === "ENOENT" || error?.name === "NotFoundError") return []
+			throw error
+		}
+	}
+
+	async function writeTrashIndex(rows) {
+		await writeTextFile(TRASH_INDEX, JSON.stringify(rows))
+	}
+
 	// Function: trash
-	// Moves entries into `/.trash` under a timestamped name, keeping them
-	// available for inspection instead of deleting them.
+	// Moves entries into `/.trash` under a timestamped name, recording each
+	// original path in the index so it can be listed and restored.
 	let trashSeq = 0
+	let trashQueue = Promise.resolve()
+	const pathQueues = new Map()
+	function withPathLocks(paths, action) {
+		const keys = [
+			...new Set(
+				paths.flatMap((path) => {
+					const chain = []
+					let current = normalize(path)
+					while (current !== "/") {
+						chain.push(current)
+						current = parent(current) ?? "/"
+					}
+					if (!chain.length) chain.push("/")
+					return chain
+				}),
+			),
+		].sort()
+		const locks = globalThis.navigator?.locks
+		const run = (index) => {
+			if (index === keys.length) return action()
+			const key = keys[index]
+			if (locks?.request) return locks.request(`tcmd-opfs-path:${key}`, { mode: "exclusive" }, () => run(index + 1))
+			const previous = pathQueues.get(key) ?? Promise.resolve()
+			let release
+			const gate = new Promise((resolve) => (release = resolve))
+			const tail = previous.then(() => gate)
+			pathQueues.set(key, tail)
+			return previous.then(() => run(index + 1)).finally(() => {
+				release()
+				if (pathQueues.get(key) === tail) pathQueues.delete(key)
+			})
+		}
+		return run(0)
+	}
+	const withPathLock = (path, action) => withPathLocks([path], action)
+
+	function withTrashLock(action) {
+		const locks = globalThis.navigator?.locks
+		if (locks?.request) return locks.request("tcmd-opfs-trash-index", { mode: "exclusive" }, action)
+		// ponytail: fallback serialization is adapter-local; Web Locks handles tabs where available.
+		const pending = trashQueue.then(action, action)
+		trashQueue = pending.catch(() => {})
+		return pending
+	}
+
 	async function trash(paths) {
-		await ensureDir("/.trash")
-		for (const path of paths) {
-			const normalized = normalize(path)
-			if (normalized === "/") continue
-			const name = `${Date.now()}-${++trashSeq}-${basename(normalized)}`
-			await copy(normalized, join("/.trash", name))
-			await eraseOne(normalized)
+		return withTrashLock(async () => {
+			await ensureDir(TRASH_DIR)
+			const index = await readTrashIndex()
+			const trashed = []
+			for (const path of paths) {
+				const normalized = normalize(path)
+				if (normalized === "/") continue
+				assertOutsideTrash(normalized)
+				await withPathLocks([normalized, TRASH_DIR], async () => {
+					let name
+					let to
+					do {
+						name = `${Date.now()}-${++trashSeq}-${basename(normalized)}`
+						to = join(TRASH_DIR, name)
+					} while (await stat(to))
+					await copyEntry(normalized, to)
+					const row = { name, originalPath: normalized, deletedAt: new Date().toISOString() }
+					index.push(row)
+					try {
+						await writeTrashIndex(index)
+					} catch (error) {
+						index.pop()
+						await eraseOne(to)
+						throw error
+					}
+					trashed.push({ from: normalized, to, name })
+					// Persist the restore record before removing the source. If removing
+					// it fails, both copies remain discoverable rather than losing the
+					// only restore metadata.
+					await eraseOne(normalized)
+				})
+			}
+			return trashed
+		})
+	}
+
+	// Function: trashList
+	// The trash rows, newest first. Entries whose copy is gone are skipped.
+	async function trashList() {
+		const index = await readTrashIndex()
+		const rows = []
+		for (const row of index) {
+			const trashPath = join(TRASH_DIR, row.name)
+			const stats = await stat(trashPath)
+			if (!stats) continue
+			rows.push({
+				name: row.name,
+				originalPath: row.originalPath ?? null,
+				deletedAt: row.deletedAt ?? null,
+				trashPath,
+				isDir: Boolean(stats.isDir),
+			})
 		}
+		return rows.sort((a, b) => `${b.deletedAt ?? ""}`.localeCompare(`${a.deletedAt ?? ""}`))
+	}
+
+	// Function: restore
+	// Moves trashed entries back to their recorded original paths.
+	async function restore(trashPaths) {
+		return withTrashLock(async () => {
+			const wanted = new Set((trashPaths ?? []).map((path) => normalize(path)))
+			const index = await readTrashIndex()
+			const rows = index.filter((row) => wanted.has(normalize(join(TRASH_DIR, row.name))) && row.originalPath)
+			if (rows.length !== wanted.size) throw new Error("unknown trash entry")
+			const destinations = rows.map((row) => normalize(row.originalPath))
+			if (new Set(destinations).size !== destinations.length) throw pathExistsError(destinations[0])
+			for (const destination of destinations) assertOutsideTrash(destination)
+			assertNoNestedDestinations(destinations)
+			for (const row of rows) {
+				if (await stat(row.originalPath)) throw pathExistsError(row.originalPath)
+			}
+			let remaining = index.slice()
+			for (const row of rows) {
+				const trashPath = join(TRASH_DIR, row.name)
+				await withPathLocks([trashPath, row.originalPath], async () => {
+					await ensureDir(parent(row.originalPath) ?? "/")
+					if (await stat(row.originalPath)) throw pathExistsError(row.originalPath)
+					await copyEntry(trashPath, row.originalPath)
+					remaining = remaining.filter((candidate) => candidate !== row)
+					await writeTrashIndex(remaining)
+					await eraseOne(trashPath)
+				})
+			}
+		})
 	}
 
 	// Function: touch
@@ -224,21 +424,29 @@ function createOpfsFs({ root, home = "/home/tester" } = {}) {
 	// (OPFS exposes no utimes).
 	async function touch(path) {
 		const normalized = normalize(path)
-		const stats = await stat(normalized)
-		if (stats?.isDir) return
-		const directory = await resolveDir(parent(normalized) ?? "/")
-		const handle = await directory.getFileHandle(basename(normalized), { create: true })
-		if (!stats) return
-		const bytes = await (await handle.getFile()).arrayBuffer()
-		const writable = await handle.createWritable()
-		await writable.write(bytes)
-		await writable.close()
+		assertOutsideTrash(normalized)
+		return withPathLock(normalized, async () => {
+			const stats = await stat(normalized)
+			if (stats?.isDir) return
+			const directory = await resolveDir(parent(normalized) ?? "/")
+			const handle = await directory.getFileHandle(basename(normalized), { create: true })
+			if (!stats) return
+			const bytes = await (await handle.getFile()).arrayBuffer()
+			const writable = await handle.createWritable()
+			await writable.write(bytes)
+			await writable.close()
+		})
 	}
 
 	// Function: writeText
 	// Creates (or replaces) a UTF-8 text file, creating parent directories.
 	async function writeText(path, text) {
 		const normalized = normalize(path)
+		assertOutsideTrash(normalized)
+		return withPathLock(normalized, () => writeTextFile(normalized, text))
+	}
+
+	async function writeTextFile(normalized, text) {
 		const directory = await resolveDir(parent(normalized) ?? "/", { create: true })
 		const handle = await directory.getFileHandle(basename(normalized), { create: true })
 		const writable = await handle.createWritable()
@@ -246,21 +454,64 @@ function createOpfsFs({ root, home = "/home/tester" } = {}) {
 		await writable.close()
 	}
 
+	function assertOutsideTrash(path) {
+		const normalized = normalize(path)
+		if (normalized === TRASH_DIR || normalized.startsWith(`${TRASH_DIR}/`)) {
+			const error = new Error(`reserved OPFS trash path: ${normalized}`)
+			error.code = "EPERM"
+			throw error
+		}
+	}
+
 	return {
 		readDir,
 		stat,
+		async realpath(path) {
+			const normalized = normalize(path)
+			if (!(await stat(normalized))) throw notFound(path)
+			return normalized
+		},
 		isDir: async (path) => Boolean((await stat(path))?.isDir),
 		readTextHead,
+		readBytes,
 		du,
 		disk,
 		copy,
 		move: async (from, to) => {
-			await copy(from, to)
-			await eraseOne(from)
+			assertOutsideTrash(from)
+			assertOutsideTrash(to)
+			return withPathLocks([from, to], async () => {
+				if (await stat(to)) throw pathExistsError(to)
+				await copyEntry(from, to)
+				await eraseOne(from)
+			})
+		},
+		// OPFS has no links, ownership or permission modes. The operations
+		// report a clear error instead of silently doing nothing.
+		hardlink: async () => {
+			throw new Error("hard links are not available in the browser filesystem")
+		},
+		symlink: async () => {
+			throw new Error("symbolic links are not available in the browser filesystem")
 		},
+		chmod: async () => {
+			throw new Error("permission modes are not available in the browser filesystem")
+		},
+		chown: async () => {
+			throw new Error("ownership is not available in the browser filesystem")
+		},
+		unlink: async (path) => {
+			throw new Error(`not a symbolic link: ${path}`)
+		},
+		mkdir,
 		trash,
+		trashList,
+		restore,
 		erase: async (paths) => {
-			for (const path of paths) await eraseOne(path)
+			for (const path of paths) {
+				assertOutsideTrash(path)
+				await withPathLock(path, () => eraseOne(path))
+			}
 		},
 		touch,
 		writeText,
@@ -277,6 +528,22 @@ function notFound(path) {
 	return error
 }
 
+function pathExistsError(path) {
+	const error = new Error(`destination already exists: ${path}`)
+	error.code = "EEXIST"
+	return error
+}
+
+function assertNoNestedDestinations(paths) {
+	for (let i = 0; i < paths.length; i++) {
+		for (let j = i + 1; j < paths.length; j++) {
+			if (paths[j].startsWith(`${paths[i]}/`) || paths[i].startsWith(`${paths[j]}/`)) {
+				throw pathExistsError(paths[j])
+			}
+		}
+	}
+}
+
 export { createOpfsFs }
 
 // EOF

package/src/js/tcmd/web/seed.js

@@ -23,7 +23,7 @@ const DEMO_TREE = {
 		"- Left/Backspace  go to the parent directory",
 		"- Tab  switch pane",
 		"- Space  mark the current entry",
-		"- b / g  record / jump to a bookmark",
+		"- b  bookmarks (filter, add current path, Enter open, Del remove)",
 		"- :  command panel (operations and app actions)",
 		"- !  shell command",
 		"- q  quit (unmounts the UI; reload to start over)",