@kabmo-labs/kabmo 0.7.0 → 0.9.0

package/src/client/hooks/ui/updates/shell-update.ts

@@ -0,0 +1,119 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Installing a desktop shell's own update, from the console.
+ *
+ * ## Why the shell does the work
+ *
+ * A page cannot replace the executable it runs inside, and a browser download
+ * leaves a file in a folder the user has to find and open. So the button asks
+ * the SHELL (`update_apply` over the bridge), and the shell downloads, verifies,
+ * replaces and relaunches. What this hook owns is only the part a page can own:
+ * the run's state, and reporting the outcome where the user clicked.
+ *
+ * ## Why it is a hook rather than a function at the call site
+ *
+ * Both sidebars draw this control and each one unmounts at a different moment (a
+ * phone closes the drawer, a desktop swaps sessions). The state has to live with
+ * the control that shows it, and the two must report the SAME vocabulary — so the
+ * phases and their sentences are here, not in either footer.
+ *
+ * ## A failure is always a sentence
+ *
+ * The shell sends its own reason ("the downloaded file is not a signed Kabmo
+ * build", "the installer refused with code 5"), which is the only thing that can
+ * tell a user what to do next. Nothing here replaces it with a generic failure,
+ * and nothing reports success before the shell said so.
+ */
+
+import { useCallback, useRef, useState } from 'preact/hooks';
+import {
+  applyShellUpdate,
+  bridgeError,
+  isDesktopShell,
+  type ShellUpdateOutcome,
+} from '@/client/lib/desktop/bridge';
+import type { ShellDownload } from '@/client/hooks/ui/updates/shell-download';
+
+/** What the control is doing right now. */
+export type ShellUpdatePhase = 'idle' | 'working' | 'done' | 'error';
+
+export interface ShellUpdateState {
+  phase: ShellUpdatePhase;
+  /** The shell's own sentence, for `done` and `error`. */
+  message: string | null;
+}
+
+export interface UseShellUpdateResult extends ShellUpdateState {
+  /** Run the update this offer names. */
+  apply: (download: ShellDownload) => Promise<void>;
+  /**
+   * Forget the last run, back to `idle`.
+   *
+   * The dialog calls this when it OPENS: a run that failed last time must not greet
+   * the user with its old refusal the next time they press the control.
+   */
+  reset: () => void;
+  /** True while a run is in flight, so the control can disable itself. */
+  working: boolean;
+}
+
+/**
+ * Whether this offer is something the shell can install by itself.
+ *
+ * Two facts, and both are required. The artifact must be a FILE (`direct`), and
+ * the page must be inside the desktop shell that can install it — an Android
+ * shell installs through `PackageInstaller` and iOS cannot install at all, so
+ * neither belongs to this path. A browser on a desktop gets neither, because
+ * there is no shell to ask.
+ */
+export function canSelfUpdate(download: ShellDownload | null | undefined): boolean {
+  if (!download) return false;
+  if (!download.direct) return false;
+  if (download.platform === 'android' || download.platform === 'ios') return false;
+  return isDesktopShell();
+}
+
+export function useShellUpdate(): UseShellUpdateResult {
+  const [state, setState] = useState<ShellUpdateState>({ phase: 'idle', message: null });
+  // A second click while the shell is replacing itself would be a second
+  // installer beside the first, so the run is claimed by a ref rather than by
+  // the render state — a fast double click lands before the state is read.
+  const running = useRef(false);
+
+  const apply = useCallback(async (download: ShellDownload) => {
+    if (running.current) return;
+    running.current = true;
+    setState({ phase: 'working', message: null });
+
+    try {
+      const outcome: ShellUpdateOutcome = await applyShellUpdate(download.url, download.latest);
+      setState({
+        phase: outcome.success ? 'done' : 'error',
+        // The shell's sentence is the report. `?? null` rather than a fallback
+        // string: a shell that answered nothing has said nothing, and inventing
+        // "Update failed" over it would hide that.
+        message: outcome.message ?? null,
+      });
+    } catch (cause) {
+      // A refused command (an older shell with no `update_apply`) lands here,
+      // and its own message says so.
+      setState({ phase: 'error', message: bridgeError(cause) });
+    } finally {
+      running.current = false;
+    }
+  }, []);
+
+  const reset = useCallback(() => {
+    // A run in flight is NOT resettable: the shell is already replacing itself, and
+    // reporting `idle` over it would re-arm a control whose second press would start
+    // a second installer.
+    if (running.current) return;
+    setState({ phase: 'idle', message: null });
+  }, []);
+
+  return { ...state, apply, reset, working: state.phase === 'working' };
+}

package/src/client/hooks/workspace/diff-file.ts

@@ -1,5 +1,4 @@
 import { useCallback, useEffect, useRef, useState } from 'preact/hooks';
-import type { DiffContentMode } from '@/client/components/workspace/diff-panel/Toolbar';
 
 interface UseFileDiffOptions {
   filePath: string;
@@ -7,11 +6,14 @@ interface UseFileDiffOptions {
   isStaged: boolean;
   repo: string;
   root?: string;
-  contentMode: DiffContentMode;
 }
 
 export interface FileDiffState {
   rawDiff: string;
+  /** The document before the change (HEAD, or the index for an unstaged read). */
+  oldContent: string;
+  /** The document after it (the working file). */
+  newContent: string;
   currentStatus: string;
   currentStaged: boolean;
   isLoading: boolean;
@@ -31,8 +33,10 @@ export interface FileDiffState {
  * earlier read overwriting a newer one, and a dependency on the staged/status
  * copies re-keying the callback and firing a fetch per render.
  */
-export function useFileDiff({ filePath, status, isStaged, repo, root, contentMode }: UseFileDiffOptions): FileDiffState {
+export function useFileDiff({ filePath, status, isStaged, repo, root }: UseFileDiffOptions): FileDiffState {
   const [rawDiff, setRawDiff] = useState<string>('');
+  const [oldContent, setOldContent] = useState<string>('');
+  const [newContent, setNewContent] = useState<string>('');
   const [currentStatus, setCurrentStatus] = useState<string>(status);
   const [currentStaged, setCurrentStaged] = useState<boolean>(isStaged);
   const [isLoading, setIsLoading] = useState<boolean>(true);
@@ -62,11 +66,9 @@ export function useFileDiff({ filePath, status, isStaged, repo, root, contentMod
         staged: staged ? '1' : '0',
         repo: repo || '.',
       });
-      // `fullContext=1` makes git emit the whole file rather than the hunks.
-      // Only the user's own toggle changes it, so it is safe as a callback
-      // dependency (unlike the staged/status copies above, which the action
-      // path updates while a fetch of its own is already in flight).
-      if (contentMode === 'full') params.set('fullContext', '1');
+      // No `fullContext`: the panel renders both SIDES of the file now, and
+      // how much of them is shown is a client-side collapse. Asking the server
+      // for the whole file as a patch would be a second answer to that question.
       if (statusForFetch) params.set('status', statusForFetch);
       if (root) params.set('root', root);
 
@@ -74,6 +76,8 @@ export function useFileDiff({ filePath, status, isStaged, repo, root, contentMod
       const data = (await res.json().catch(() => null)) as {
         success?: boolean;
         diff?: string;
+        oldContent?: string;
+        newContent?: string;
         status?: string;
         staged?: boolean;
         error?: string;
@@ -83,6 +87,11 @@ export function useFileDiff({ filePath, status, isStaged, repo, root, contentMod
       if (seq !== fetchSeqRef.current) return;
       if (data?.success) {
         setRawDiff(data.diff || '');
+        // Both sides travel on every read: the merge view compares documents,
+        // and a whitespace fold has to be applied to the ORIGINAL, not to the
+        // patch (see `foldWhitespaceOnly`).
+        setOldContent(data.oldContent ?? '');
+        setNewContent(data.newContent ?? '');
         if (data.status) {
           statusRef.current = data.status;
           setCurrentStatus(data.status);
@@ -100,7 +109,7 @@ export function useFileDiff({ filePath, status, isStaged, repo, root, contentMod
     } finally {
       if (seq === fetchSeqRef.current) setIsLoading(false);
     }
-  }, [filePath, repo, root, contentMode]);
+  }, [filePath, repo, root]);
 
   useEffect(() => {
     setCurrentStatus(status);
@@ -124,5 +133,15 @@ export function useFileDiff({ filePath, status, isStaged, repo, root, contentMod
     }
   }, []);
 
-  return { rawDiff, currentStatus, currentStaged, isLoading, errorMessage, fetchDiff, adoptState };
+  return {
+    rawDiff,
+    oldContent,
+    newContent,
+    currentStatus,
+    currentStaged,
+    isLoading,
+    errorMessage,
+    fetchDiff,
+    adoptState,
+  };
 }

package/src/client/hooks/workspace/diff-git-actions.ts

@@ -0,0 +1,147 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The diff panel's git writes, and the conflict-marker read behind its banner.
+ *
+ * Split out of the panel because these are the only parts of it that talk to
+ * the server: the panel used to fire and forget (`fetcher.submit` + an
+ * optimistic flip + a 300ms timer), which made a rejected action
+ * indistinguishable from a successful one — the badge flipped and the diff
+ * silently stayed put. Every write here AWAITS its answer and reports the
+ * server's own reason.
+ *
+ * `revert` is the server's name for "restore this file from the index", and it
+ * is the one that handles the untracked case (there the file is removed).
+ * Sending `discard`, which no handler matched, returned `{success: true}` for
+ * doing nothing at all.
+ */
+
+import { useCallback, useEffect, useState } from 'preact/hooks';
+import type { ConflictMarkers } from '@/shared/lib/fs/git-unmerged';
+
+export interface DiffGitActions {
+  /** A write is in flight; the toolbar locks its actions. */
+  isBusy: boolean;
+  /** The server's refusal, or a transport failure, as a sentence. */
+  error: string | null;
+  /** The conflict sides' labels from the file's own markers (`{}` when none). */
+  markers: ConflictMarkers;
+  dismissError: () => void;
+  /** Stage or unstage this path, then re-read the diff at the new side. */
+  stageUnstage: () => Promise<void>;
+  /** Take one side of a conflict (or only stage a resolved file with `''`). */
+  resolve: (side: 'ours' | 'theirs' | '') => Promise<void>;
+  /** Restore this file from the index — the untracked case removes it. */
+  revert: () => Promise<void>;
+}
+
+export interface DiffGitActionsArgs {
+  filePath: string;
+  repo: string;
+  root?: string;
+  /** The status the panel currently believes (`UU`, `M`, …). */
+  status: string;
+  staged: boolean;
+  /** The panel is showing a conflicted file, so its marker labels are read. */
+  conflicted: boolean;
+  /** Adopt a state change the server confirmed. */
+  adoptState: (patch: { staged: boolean }) => void;
+  /** Re-read the diff, optionally at the other side of the index. */
+  fetchDiff: (options?: { staged: boolean }) => Promise<void>;
+  /** Something on disk changed, so the workspace panels should refresh. */
+  onFileSaved?: () => void;
+}
+
+export function useDiffGitActions(args: DiffGitActionsArgs): DiffGitActions {
+  const { filePath, repo, root, staged, conflicted, adoptState, fetchDiff, onFileSaved } = args;
+  const [isBusy, setIsBusy] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const [markers, setMarkers] = useState<ConflictMarkers>({});
+
+  const run = useCallback(
+    async (fields: Record<string, string>): Promise<boolean> => {
+      const fd = new FormData();
+      for (const [key, value] of Object.entries(fields)) fd.set(key, value);
+      fd.set('repo', repo || '.');
+      if (root) fd.set('root', root);
+      try {
+        const res = await fetch('/api/fs/git', { method: 'POST', body: fd });
+        const data = (await res.json().catch(() => null)) as { success?: boolean; error?: string } | null;
+        if (!res.ok || !data?.success) {
+          setError(data?.error || `Request failed (HTTP ${res.status})`);
+          return false;
+        }
+        setError(null);
+        return true;
+      } catch (err: unknown) {
+        setError(err instanceof Error ? err.message : 'Request failed');
+        return false;
+      }
+    },
+    [repo, root],
+  );
+
+  /** One write, its busy flag, and the refresh every action ends with. */
+  const write = useCallback(
+    async (fields: Record<string, string>, after: () => Promise<void>): Promise<void> => {
+      setIsBusy(true);
+      try {
+        if (!(await run(fields))) return;
+        await after();
+      } finally {
+        setIsBusy(false);
+      }
+    },
+    [run],
+  );
+
+  // The marker labels are fetched when the file turns out to be conflicted, and
+  // re-fetched when the path changes. Keyed on the path and the status so a
+  // resolve (which changes the status away from `UU`) clears the banner.
+  useEffect(() => {
+    if (!conflicted) {
+      setMarkers({});
+      return;
+    }
+    let cancelled = false;
+    const params = new URLSearchParams({ conflictMarkers: '1', file: filePath, repo: repo || '.' });
+    if (root) params.set('root', root);
+    void fetch(`/api/fs/git?${params.toString()}`)
+      .then((res) => res.json() as Promise<{ markers?: ConflictMarkers }>)
+      .then((body) => {
+        if (!cancelled) setMarkers(body.markers ?? {});
+      })
+      .catch(() => {
+        if (!cancelled) setMarkers({});
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, [conflicted, filePath, repo, root]);
+
+  return {
+    isBusy,
+    error,
+    markers,
+    dismissError: () => setError(null),
+    stageUnstage: () =>
+      write({ actionType: staged ? 'unstage' : 'stage', file: filePath }, async () => {
+        adoptState({ staged: !staged });
+        onFileSaved?.();
+        await fetchDiff({ staged: !staged });
+      }),
+    resolve: (side) =>
+      write({ actionType: 'resolve_conflict', file: filePath, ...(side ? { side } : {}) }, async () => {
+        onFileSaved?.();
+        await fetchDiff();
+      }),
+    revert: () =>
+      write({ actionType: 'revert', file: filePath }, async () => {
+        onFileSaved?.();
+        await fetchDiff();
+      }),
+  };
+}

package/src/client/hooks/workspace/editor-view.ts

@@ -0,0 +1,61 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The desktop editor column's WIDTH mode, read and written through the session
+ * slot every surface follows.
+ *
+ * Two surfaces read it — the layout (which collapses the columns) and both
+ * toolbars (which draw the mode buttons) — so it goes through
+ * `useSharedSessionState`: `useSessionState` hands each caller a private copy,
+ * and a copy would leave the diff toolbar showing `normal` after the editor
+ * toolbar entered compact view. A private copy is right for state one component
+ * owns; this one is a decision two toolbars and the layout share.
+ *
+ * The stored mode only means anything while the editor column is OPEN. With it
+ * closed the chat is the only thing on screen, and honouring the mode would
+ * leave a blank workspace; the effective mode is therefore DERIVED rather than
+ * written back, so closing and reopening the column returns the user to the
+ * width they chose.
+ */
+
+import { useSharedSessionState } from '@/client/hooks/workspace/session-state';
+import {
+  DEFAULT_EDITOR_VIEW_MODE,
+  EDITOR_VIEW_MODE_KEY,
+  editorViewHides,
+  isEditorViewMode,
+  type EditorViewMode,
+} from '@/shared/lib/workspace/editor-view-mode';
+
+export interface EditorViewLayout {
+  /** The mode in force, after the editor-open guard. */
+  mode: EditorViewMode;
+  /** The chat column is collapsed and the editor takes its width. */
+  chatHidden: boolean;
+  /** The session sidebar is collapsed as well (full view only). */
+  sidebarHidden: boolean;
+  /** Enter a mode, or return to `normal` — see `toggledEditorViewMode`. */
+  setMode: (next: EditorViewMode) => void;
+  /** Leave `full` for `compact`: the chat stays hidden, the sidebar returns. */
+  revealSidebar: () => void;
+}
+
+export function useEditorViewLayout(editorOpen: boolean): EditorViewLayout {
+  const [stored, setMode] = useSharedSessionState<EditorViewMode>(EDITOR_VIEW_MODE_KEY, DEFAULT_EDITOR_VIEW_MODE);
+  const mode: EditorViewMode = editorOpen && isEditorViewMode(stored) ? stored : DEFAULT_EDITOR_VIEW_MODE;
+
+  return {
+    mode,
+    chatHidden: editorViewHides(mode, 'chat'),
+    sidebarHidden: editorViewHides(mode, 'sidebar'),
+    setMode,
+    // Only `full` hides the sidebar, so only `full` has anything to step back
+    // from. A caller that asks for the sidebar (the navbar's own toggle) must be
+    // able to call this unconditionally: turning `normal` into `compact` would
+    // hide the chat for a user who only wanted their sidebar back.
+    revealSidebar: () => setMode((previous) => (previous === 'full' ? 'compact' : previous)),
+  };
+}

package/src/client/hooks/workspace/file-create.ts

@@ -4,7 +4,8 @@
  */
 
 /**
- * Creating one empty file in a named folder of the Files panel, and opening it.
+ * Creating one entry in a named folder of the Files panel, and opening it when
+ * it is a file.
  *
  * Extracted from `useFileActions` because the Files panel needs the SAME flow
  * from two places that share no target: a row's context menu (create beside the
@@ -12,6 +13,12 @@
  * root). A second copy would drift on the two things that matter — a refusal
  * keeps the dialog open with the server's reason beside the field, and a success
  * OPENS the file, because the user asked for something to work on.
+ *
+ * The name may carry SEGMENTS (`lib/parse.ts`), so one dialog creates a nested
+ * path and every directory that leads to it. The grammar that keeps the result
+ * inside the named folder is the server's (`normalizeRelativePath`); this side
+ * only reports its refusal, because a second copy of that rule is how the field
+ * accepts something the route then rejects.
  */
 
 import { useEffect, useRef, useState } from 'preact/hooks';
@@ -21,30 +28,46 @@ import { useFetcher } from '@/client/lib/router/fetcher';
 /** The shape `/api/fs/action` answers a create with. */
 interface CreateResponse {
   success?: boolean;
-  /** Relative path of the file that was created. */
+  /** `file` or `folder` — what the request asked for. */
+  kind?: 'file' | 'folder';
+  /** Relative path of the entry that was created. */
   path?: string;
   error?: string;
 }
 
+/** What a create produced, for the caller to place in its tree. */
+export interface CreatedEntry {
+  path: string;
+  name: string;
+  kind: 'file' | 'folder';
+}
+
 export interface FileCreateDeps {
-  /** Folder the file goes in, relative to the listed root (`.` for the root). */
+  /** Folder the entry goes in, relative to the listed root (`.` for the root). */
   folderPath: string;
   rootPath?: string;
   repo?: string;
-  /** Fired after the file exists, so the tree re-reads. */
-  onCreated: () => void;
-  /** Fired with the new file's relative path, so the panel can open its tab. */
+  /**
+   * Fired after the entry exists. The tree inserts it directly rather than
+   * re-reading: a create answers with the whole result, and a reload would cost
+   * one request per open folder to learn what this call already knows.
+   */
+  onCreated: (entry: CreatedEntry) => void;
+  /** Fired with a created FILE's relative path, so the panel can open its tab. */
   onOpenCreated?: (file: { path: string; name: string }) => void;
 }
 
 export interface FileCreate {
   open: boolean;
+  /** Whether the open dialog makes a folder; a row's menu offers both. */
+  kind: 'file' | 'folder';
   name: string;
   setName: (value: string) => void;
   /** The server's refusal, rendered inside the dialog. */
   error: string | null;
   busy: boolean;
-  openDialog: () => void;
+  /** Open the dialog; `kind` defaults to a file. */
+  openDialog: (kind?: 'file' | 'folder') => void;
   closeDialog: () => void;
   submit: (event: FormEvent) => void;
 }
@@ -52,6 +75,7 @@ export interface FileCreate {
 export function useFileCreate({ folderPath, rootPath, repo, onCreated, onOpenCreated }: FileCreateDeps): FileCreate {
   const fetcher = useFetcher<CreateResponse>();
   const [open, setOpen] = useState(false);
+  const [kind, setKind] = useState<'file' | 'folder'>('file');
   const [name, setName] = useState('');
   const [error, setError] = useState<string | null>(null);
 
@@ -71,24 +95,29 @@ export function useFileCreate({ folderPath, rootPath, repo, onCreated, onOpenCre
     // The fetcher parses the body whatever the status, so a refusal arrives as
     // `data.error` rather than as a throw — which is what keeps the dialog open.
     if (data.success && data.path) {
+      const createdKind = data.kind === 'folder' ? 'folder' : 'file';
       setOpen(false);
       setName('');
       setError(null);
-      onCreated();
-      onOpenCreated?.({ path: data.path, name: data.path.split('/').pop() || data.path });
+      const name = data.path.split('/').pop() || data.path;
+      onCreated({ path: data.path, name, kind: createdKind });
+      // A folder has nothing to open: the user is about to put something in it.
+      if (createdKind === 'file') onOpenCreated?.({ path: data.path, name });
     } else {
-      setError(data.error || 'Could not create the file');
+      setError(data.error || `Could not create the ${kind}`);
     }
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [fetcher.state, fetcher.data]);
 
   return {
     open,
+    kind,
     name,
     setName,
     error,
     busy: fetcher.state !== 'idle',
-    openDialog: () => {
+    openDialog: (nextKind: 'file' | 'folder' = 'file') => {
+      setKind(nextKind);
       setName('');
       setError(null);
       setOpen(true);
@@ -103,6 +132,7 @@ export function useFileCreate({ folderPath, rootPath, repo, onCreated, onOpenCre
       formData.append('actionType', 'create');
       formData.append('path', folderPath);
       formData.append('name', trimmed);
+      if (kind === 'folder') formData.append('kind', 'folder');
       if (repo && repo !== '.') formData.append('repo', repo);
       if (rootPath) formData.append('root', rootPath);
       void fetcher.submit(formData, { method: 'post', action: '/api/fs/action' });

package/src/client/hooks/workspace/file-listing.ts

@@ -25,7 +25,7 @@
 
 import { useRef, useState } from 'preact/hooks';
 import type { FsNode } from '@/shared/types';
-import { rehydrateTree, setChildrenAt } from '@/shared/lib/fs/file-tree';
+import { placeEntry, rehydrateTree, setChildrenAt, takeEntry, rekeyCache } from '@/shared/lib/fs/file-tree';
 import { isRecord } from '@/shared/lib/util/guards';
 
 /**
@@ -86,6 +86,20 @@ export interface FileListing {
   loadChildren: (path: string) => Promise<void>;
   /** Adopt a realtime root snapshot, then re-read the open folders. */
   adoptRoot: (payload: unknown) => void;
+  /**
+   * Insert a row the panel just created, without a reload.
+   *
+   * A create answers with the entry's path, so the tree already knows the whole
+   * result; re-reading the root plus every open folder to learn it back would
+   * be one request per open folder for an answer the caller holds.
+   */
+  insertEntry: (entry: { path: string; kind: 'file' | 'folder' }) => void;
+  /**
+   * Move a row the panel just renamed, without a reload. Returns the folders
+   * whose path moved, so the caller can rekey its expansion set — a renamed
+   * folder's open branches are still open, under their new names.
+   */
+  moveEntry: (fromPath: string, toPath: string) => void;
   /** Forget the root listing and every cached child (a repo switch). */
   reset: () => void;
 }
@@ -117,6 +131,8 @@ export function useFileListing({
   const scopeRef = useRef(scope);
   scopeRef.current = scope;
   const listedScopeRef = useRef('');
+  /** The absolute base dir the current listing was read for — what `commit` stamps. */
+  const listedRootRef = useRef('');
   const expandedPathsRef = useRef(expandedPaths);
   expandedPathsRef.current = expandedPaths;
 
@@ -132,6 +148,7 @@ export function useFileListing({
   /** Render the tree from the current root listing plus the children cache. */
   const commit = (requested: string, root: string) => {
     listedScopeRef.current = requested;
+    listedRootRef.current = root;
     setState({
       scope: requested,
       files: rehydrateTree(rootFilesRef.current, childrenCacheRef.current),
@@ -223,9 +240,45 @@ export function useFileListing({
     childrenCacheRef.current = {};
     rootFilesRef.current = [];
     listedScopeRef.current = '';
+    listedRootRef.current = '';
     setState({ scope: '', files: [], root: '' });
   };
 
+  /**
+   * The tree edits below patch the same two sources a read fills — the root
+   * list and the children cache — and then commit, so `rehydrateTree` remains
+   * the only thing that builds what is rendered. Editing the rendered tree
+   * directly would be undone by the next commit, which rebuilds from these.
+   */
+  const insertEntry = (entry: { path: string; kind: 'file' | 'folder' }): void => {
+    const requested = scopeRef.current;
+    if (listedScopeRef.current !== requested) return;
+    const node: FsNode = {
+      name: entry.path.slice(entry.path.lastIndexOf('/') + 1),
+      path: entry.path,
+      type: entry.kind,
+      ignored: false,
+    };
+    const placed = placeEntry(rootFilesRef.current, childrenCacheRef.current, node);
+    if (placed.nodes === rootFilesRef.current) return;
+    rootFilesRef.current = placed.nodes;
+    childrenCacheRef.current = placed.cache;
+    commit(requested, listedRootRef.current);
+  };
+
+  const moveEntry = (fromPath: string, toPath: string): void => {
+    const requested = scopeRef.current;
+    if (listedScopeRef.current !== requested) return;
+    const taken = takeEntry(rootFilesRef.current, childrenCacheRef.current, fromPath);
+    if (!taken.entry) return;
+    childrenCacheRef.current = rekeyCache(taken.cache, fromPath, toPath);
+    const moved: FsNode = { ...taken.entry, path: toPath, name: toPath.slice(toPath.lastIndexOf('/') + 1) };
+    const placed = placeEntry(taken.nodes, childrenCacheRef.current, moved);
+    rootFilesRef.current = placed.nodes;
+    childrenCacheRef.current = placed.cache;
+    commit(requested, listedRootRef.current);
+  };
+
   // A listing read for another scope is not this one's to render: the panel
   // shows an empty tree until the current scope's read lands.
   const current = state.scope === scope;
@@ -237,6 +290,8 @@ export function useFileListing({
     reload,
     loadChildren,
     adoptRoot,
+    insertEntry,
+    moveEntry,
     reset,
   };
 }