@kabmo-labs/kabmo 0.7.0 → 0.8.0

package/src/client/hooks/ui/updates/shell-download.test.ts

@@ -6,8 +6,10 @@
 import { describe, expect, test } from 'bun:test';
 
 import {
+  desktopShellFromIdentity,
   parseShellRelease,
   shellDownloadLabel,
+  shellDownloadShortLabel,
   shellFromBootstrap,
   shellReleasePath,
   shouldOfferShellDownload,
@@ -155,3 +157,74 @@ describe('shellReleasePath', () => {
     expect(shellReleasePath('ios')).toBe('/api/updates/ios');
   });
 });
+
+describe('the desktop shells', () => {
+  test('each desktop shell reads its own route, with an explicit kind', () => {
+    // ONE route with a required `kind`, so no absence can silently mean a
+    // platform — the reason the mobile pair has two routes.
+    expect(shellReleasePath('macos')).toBe('/api/updates/desktop?kind=macos');
+    expect(shellReleasePath('windows')).toBe('/api/updates/desktop?kind=windows');
+    expect(shellReleasePath('linux')).toBe('/api/updates/desktop?kind=linux');
+  });
+
+  test('a desktop shell offers an update when it is behind', () => {
+    // The reported gap: an installed desktop app that is behind had no way to
+    // learn it, because nothing in the console read its version.
+    expect(shouldOfferShellDownload('macos', '0.1.0', null, RELEASE)).toEqual({
+      ...RELEASE,
+      kind: 'update',
+      platform: 'macos',
+    });
+    expect(shouldOfferShellDownload('windows', '0.1.0', null, RELEASE)?.platform).toBe('windows');
+    expect(shouldOfferShellDownload('linux', '0.1.0', null, RELEASE)?.platform).toBe('linux');
+  });
+
+  test('a desktop shell that is current, or ahead, offers nothing', () => {
+    expect(shouldOfferShellDownload('macos', '1.2.3', null, RELEASE)).toBeNull();
+    expect(shouldOfferShellDownload('macos', '1.3.0', null, RELEASE)).toBeNull();
+  });
+
+  test('a desktop BROWSER is offered nothing', () => {
+    // A desktop app is installed by hand from the release page; a tab that
+    // advertised one would be a button for a product the reader did not ask for.
+    expect(shouldOfferShellDownload('macos', null, false, RELEASE)).toBeNull();
+    expect(shouldOfferShellDownload('windows', undefined, undefined, RELEASE)).toBeNull();
+  });
+
+  test('the label names the desktop platform', () => {
+    const update: ShellDownload = { ...RELEASE, kind: 'update', platform: 'linux' };
+    expect(shellDownloadLabel(update)).toBe('Update Kabmo 1.2.3 for Linux');
+    expect(shellDownloadShortLabel(update)).toBe('Update Linux');
+  });
+
+  test('the short label keeps the mobile spellings', () => {
+    expect(shellDownloadShortLabel(UPDATE)).toBe('Update APK');
+    expect(shellDownloadShortLabel(INSTALL)).toBe('Get APK');
+    expect(shellDownloadShortLabel({ ...UPDATE, platform: 'ios' })).toBe('Update app');
+  });
+});
+
+describe('desktopShellFromIdentity', () => {
+  test('reads the bridge identity the shell injects', () => {
+    expect(desktopShellFromIdentity({ platform: 'macos', shellVersion: '0.2.0' })).toEqual({
+      platform: 'macos',
+      version: '0.2.0',
+    });
+    expect(desktopShellFromIdentity({ platform: 'windows', shellVersion: '0.2.0' })?.platform).toBe('windows');
+    expect(desktopShellFromIdentity({ platform: 'linux', shellVersion: '0.2.0' })?.platform).toBe('linux');
+  });
+
+  test('is null in a browser, and for an identity with no version', () => {
+    expect(desktopShellFromIdentity(null)).toBeNull();
+    expect(desktopShellFromIdentity(undefined)).toBeNull();
+    expect(desktopShellFromIdentity({ platform: 'macos' })).toBeNull();
+    expect(desktopShellFromIdentity({ shellVersion: '0.2.0' })).toBeNull();
+  });
+
+  test('an unknown platform is not compared against a published artifact', () => {
+    // A newer shell reporting a fourth platform must not be matched to a file
+    // nobody publishes.
+    expect(desktopShellFromIdentity({ platform: 'beos', shellVersion: '1.0.0' })).toBeNull();
+    expect(desktopShellFromIdentity({ platform: 'android', shellVersion: '1.0.0' })).toBeNull();
+  });
+});

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

@@ -1,12 +1,11 @@
 /**
- * What the sidebar should offer for a native shell, and why.
+ * What the console should offer for a native shell, and why.
  *
  * TWO DIFFERENT OFFERS, from two different facts:
  *
- * - **`update`** — this page is running inside the shell (`shellVersion` from
- *   the bootstrap) and a newer build is published. An up-to-date shell offers
- *   nothing: a button that downloads the build already installed is worse than
- *   no button.
+ * - **`update`** — this page is running inside the shell and a newer build is
+ *   published. An up-to-date shell offers nothing: a button that downloads the
+ *   build already installed is worse than no button.
  * - **`install`** — this page is an Android BROWSER (Chrome, Brave, Firefox) and
  *   an APK is published. The reader may not know a native shell exists, and
  *   telling them is the whole point of the offer; there is no installed version
@@ -16,18 +15,25 @@
  * an APK can — iOS has no sideload-by-URL path — so a browser on an iPhone is
  * offered nothing, and only an installed iOS shell ever sees this control.
  *
- * A desktop browser gets neither: an APK cannot be installed there, and the
- * app's own update badge already covers the server.
+ * There is NO desktop BROWSER offer either, but there IS a desktop SHELL one: a
+ * desktop app is installed by hand from the release page, so nothing in a tab
+ * should advertise it — while an installed app that is behind has exactly the
+ * same problem the mobile pair had, and used to have no way to learn it.
  *
- * The probe is lazy: it runs only when a shell token or an Android device is
- * present, so a console that can never show the button makes no request for it.
- * ONE hook for both shells, because the decision table is identical and only the
- * artifact, the endpoint and the platform word differ.
+ * The probe is lazy: it runs only when an installed shell (a bootstrap token, or
+ * a bridge identity) or an Android device is present, so a console that can
+ * never show the button makes no request for it. ONE hook for every shell,
+ * because the decision table is identical and only the artifact, the endpoint
+ * and the platform word differ.
  */
 
 import { useEffect, useState } from 'preact/hooks';
 import { isNewer } from '@/shared/lib/updates/semver';
-import type { ShellKind } from '@/shared/lib/updates/shell-ua';
+import {
+  isDesktopShellKind,
+  type DesktopShellKind,
+  type ShellKind,
+} from '@/shared/lib/updates/shell-ua';
 
 /** Which shell the offer is for. */
 export type ShellPlatform = ShellKind;
@@ -36,7 +42,13 @@ export type ShellPlatform = ShellKind;
 export type ShellOfferKind = 'update' | 'install';
 
 export interface ShellDownload {
-  /** The artifact to download. */
+  /**
+   * What the control links to.
+   *
+   * The artifact itself for the mobile pair (an APK the shell installs, an IPA
+   * the release page explains), and the RELEASE PAGE for a desktop shell: every
+   * desktop build is per-architecture, so the console cannot name one file.
+   */
   url: string;
   /** The version that artifact ships. */
   latest: string;
@@ -58,6 +70,9 @@ interface ReleasePayload {
 const PLATFORM_NAMES: Record<ShellPlatform, string> = {
   android: 'Android',
   ios: 'iOS',
+  macos: 'macOS',
+  windows: 'Windows',
+  linux: 'Linux',
 };
 
 /**
@@ -126,8 +141,14 @@ export function shellDownloadLabel(download: ShellDownload): string {
   return `${verb} Kabmo ${download.latest} for ${PLATFORM_NAMES[download.platform]}`;
 }
 
-/** The endpoint that answers for one shell. */
+/**
+ * The endpoint that answers for one shell.
+ *
+ * The desktop trio shares ONE route with an explicit `kind`, so no absence can
+ * silently mean a platform — the reason the mobile pair has two.
+ */
 export function shellReleasePath(platform: ShellPlatform): string {
+  if (isDesktopShellKind(platform)) return `/api/updates/desktop?kind=${platform}`;
   return `/api/updates/${platform}`;
 }
 
@@ -146,6 +167,27 @@ export function shellFromBootstrap(bootstrap: {
   return null;
 }
 
+/**
+ * Which DESKTOP shell this page is running inside, from the bridge identity.
+ *
+ * The desktop trio reports itself over `window.__kabmoDesktop` rather than the
+ * User-Agent, because a desktop app is not downloaded from the console and the
+ * server has nothing to parse per request. The identity is injected at document
+ * start, before the page's own scripts, so this answers on the FIRST paint.
+ *
+ * An identity whose `platform` is not one of the three is not a desktop shell
+ * this build knows how to update — a newer shell reporting a fourth platform
+ * must not be compared against an artifact nobody publishes.
+ */
+export function desktopShellFromIdentity(identity: {
+  platform?: string;
+  shellVersion?: string;
+} | null | undefined): { platform: DesktopShellKind; version: string } | null {
+  if (!identity?.platform || !identity.shellVersion) return null;
+  if (!isDesktopShellKind(identity.platform)) return null;
+  return { platform: identity.platform, version: identity.shellVersion };
+}
+
 /**
  * Fetch the published artifact and decide what to offer.
  *
@@ -159,7 +201,18 @@ export function useShellDownload(
   onAndroid: boolean | null | undefined,
   fetchImpl: typeof fetch = fetch,
 ): ShellDownload | null {
-  const [release, setRelease] = useState<Omit<ShellDownload, 'kind' | 'platform'> | null>(null);
+  /**
+   * The answer, TAGGED with the platform it was read for.
+   *
+   * A bare payload is not enough: this hook is called with a different platform
+   * when a page's shell changes (a desktop identity arriving, a spawn adoption),
+   * and an untagged answer would be compared against the new platform's version
+   * — offering an Android APK to a Mac for one render.
+   */
+  const [answer, setAnswer] = useState<{
+    platform: ShellPlatform;
+    release: Omit<ShellDownload, 'kind' | 'platform'> | null;
+  } | null>(null);
   const wanted = Boolean(version) || (platform === 'android' && Boolean(onAndroid));
 
   useEffect(() => {
@@ -171,7 +224,7 @@ export function useShellDownload(
         const response = await fetchImpl(shellReleasePath(platform));
         if (!response.ok) return;
         const payload: unknown = await response.json();
-        if (!cancelled) setRelease(parseShellRelease(payload));
+        if (!cancelled) setAnswer({ platform, release: parseShellRelease(payload) });
       } catch {
         // A probe that cannot answer is a button that must not appear.
       }
@@ -182,28 +235,57 @@ export function useShellDownload(
     };
   }, [wanted, platform, fetchImpl]);
 
+  // A stale answer belongs to the platform it was read for, not this one.
+  const release = answer?.platform === platform ? answer.release : null;
   return shouldOfferShellDownload(platform, version, onAndroid, release);
 }
 
+/** The bridge identity a desktop shell injects before the page's first script. */
+export interface DesktopIdentity {
+  platform?: string;
+  shellVersion?: string;
+}
+
+function readDesktopIdentity(): DesktopIdentity | null {
+  if (typeof window === 'undefined') return null;
+  // `window.__kabmoDesktop` is declared by `lib/desktop/bridge` — the same
+  // object the shell injects, so this reads the shell's own contract rather
+  // than re-declaring its shape here.
+  return window.__kabmoDesktop ?? null;
+}
+
 /**
  * The offer for whichever shell this page is running inside — or the Android
  * install offer for a browser on that platform.
  *
  * The single entry point both sidebar layouts call, so the two cannot disagree
  * about which shell they are in or which endpoint they read. It reads the
- * bootstrap the SERVER wrote for this request rather than sniffing the UA
- * client-side, because the server already parsed it for the very response that
- * carried the page.
+ * bootstrap the SERVER wrote for this request (and, for a desktop shell, the
+ * identity the shell injected) rather than sniffing the UA client-side, because
+ * the server already parsed it for the very response that carried the page.
+ *
+ * `desktop` is a parameter so the tests can drive the bridge identity without a
+ * real shell; production reads it from `window.__kabmoDesktop`.
  */
-export function useShellOffer(fetchImpl: typeof fetch = fetch): ShellDownload | null {
+export function useShellOffer(
+  fetchImpl: typeof fetch = fetch,
+  desktop: DesktopIdentity | null = readDesktopIdentity(),
+): ShellDownload | null {
   const bootstrap = typeof window === 'undefined' ? undefined : window.__OMP_BOOTSTRAP__;
-  const shell = shellFromBootstrap(bootstrap);
-  return useShellDownload(
-    shell?.platform ?? 'android',
-    shell?.version ?? null,
-    bootstrap?.isAndroid,
-    fetchImpl,
-  );
+  const mobile = shellFromBootstrap(bootstrap);
+  const fromBridge = desktopShellFromIdentity(desktop);
+
+  // The desktop identity is checked FIRST and is authoritative when present: a
+  // desktop shell never carries a mobile UA token, and a page that somehow had
+  // both is in the desktop app, whose version is the one being compared.
+  //
+  // ONE call, with the resolved platform — never two conditional calls. A hook
+  // behind an `if` changes the hook order between renders, which React/Preact
+  // treats as a different component.
+  const platform = fromBridge?.platform ?? mobile?.platform ?? 'android';
+  const version = fromBridge?.version ?? mobile?.version ?? null;
+
+  return useShellDownload(platform, version, fromBridge ? null : bootstrap?.isAndroid, fetchImpl);
 }
 
 /**
@@ -212,9 +294,11 @@ export function useShellOffer(fetchImpl: typeof fetch = fetch): ShellDownload |
  * It names the OFFER, and for Android it names the file type because that is
  * what a reader recognises (`APK` is the thing they will see in Downloads). An
  * iOS update is an IPA, which nobody installs by hand — the shell finishes the
- * install itself — so the platform word is the honest one there.
+ * install itself — so the platform word is the honest one there. A desktop
+ * update opens the release page, so it names the platform too.
  */
 export function shellDownloadShortLabel(download: ShellDownload): string {
   if (download.platform === 'ios') return 'Update app';
+  if (isDesktopShellKind(download.platform)) return `Update ${PLATFORM_NAMES[download.platform]}`;
   return download.kind === 'update' ? 'Update APK' : 'Get APK';
 }

package/src/client/hooks/ui/updates/shell-offer.test.ts

@@ -0,0 +1,187 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * `useShellOffer` — the one hook both sidebars call.
+ *
+ * The pure decision table is pinned next door; what this file covers is the
+ * WIRING, which is where the reported bug lived: an APK two versions behind a
+ * running server drew no button, and no unit test of `shouldOfferShellDownload`
+ * could have seen it, because the hook never asked the server at all.
+ *
+ * Three facts it reads, and each has been wrong at some point:
+ *
+ * 1. the MOBILE shell's version, from the bootstrap the server wrote for this
+ *    request (the `KabmoAndroid/<v>` token);
+ * 2. the DESKTOP shell's version, from the bridge identity injected before the
+ *    first script — a desktop app carries no UA token;
+ * 3. the release itself, fetched from the shell's own route, with the desktop
+ *    trio sharing one endpoint and an explicit `kind`.
+ */
+
+import { afterAll, afterEach, beforeAll, describe, expect, test } from 'bun:test';
+import { Window } from 'happy-dom';
+import { h, render } from 'preact';
+import { act } from 'preact/test-utils';
+import { useShellOffer } from '@/client/hooks/ui/updates/shell-download';
+import { installDomGlobals, restoreDomGlobals } from '@/test-support/pristine-globals';
+
+let container: HTMLElement;
+
+/** The payload every route answers in these cases. */
+const RELEASE = {
+  url: 'https://github.com/kabmo-labs/kabmo/releases/download/v0.7.0/Kabmo-0.6.0-android.apk',
+  latest: '0.6.0',
+  releaseUrl: 'https://github.com/kabmo-labs/kabmo/releases/tag/v0.7.0',
+};
+
+function Harness({ fetchImpl }: { fetchImpl: typeof fetch }) {
+  const offer = useShellOffer(fetchImpl);
+  return h('span', { id: 'offer' }, offer ? `${offer.kind}:${offer.platform}:${offer.latest}` : 'none');
+}
+
+/** A fetch double that answers the release payload and records the URLs asked. */
+function stubFetch(asked: string[]) {
+  return (async (input: string | URL | Request) => {
+    asked.push(String(input));
+    return { ok: true, json: async () => RELEASE } as Response;
+  }) as unknown as typeof fetch;
+}
+
+async function mount(fetchImpl: typeof fetch): Promise<string> {
+  await act(async () => {
+    render(h(Harness, { fetchImpl }), container);
+  });
+  // The probe is an effect: let its promise settle and re-render.
+  for (let i = 0; i < 20; i += 1) await act(async () => {});
+  return container.querySelector('#offer')?.textContent ?? '';
+}
+
+/** Install a bootstrap and (optionally) a bridge identity on the page. */
+function shell(options: { bootstrap?: Record<string, unknown>; desktop?: Record<string, unknown> }): void {
+  const page = globalThis as unknown as {
+    window: {
+      __OMP_BOOTSTRAP__?: Record<string, unknown>;
+      __kabmoDesktop?: Record<string, unknown>;
+    };
+  };
+  delete page.window.__OMP_BOOTSTRAP__;
+  delete page.window.__kabmoDesktop;
+  if (options.bootstrap) page.window.__OMP_BOOTSTRAP__ = options.bootstrap;
+  if (options.desktop) page.window.__kabmoDesktop = options.desktop;
+}
+
+beforeAll(() => {
+  installDomGlobals(new Window({ url: 'http://localhost' }));
+  container = document.createElement('div');
+  document.body.appendChild(container);
+});
+
+afterEach(() => {
+  act(() => render(null, container));
+  shell({});
+});
+
+afterAll(() => {
+  container.remove();
+  restoreDomGlobals();
+});
+
+describe('the Android shell', () => {
+  test('offers an update when the APK is behind the published asset', async () => {
+    // The reported incident: server v0.7.0, APK v0.5.0, published 0.6.0, and
+    // the sidebar drew nothing because the probe answered `null`.
+    shell({ bootstrap: { shellVersion: '0.5.0', isAndroid: true } });
+    const asked: string[] = [];
+
+    expect(await mount(stubFetch(asked))).toBe('update:android:0.6.0');
+    expect(asked, 'the Android route').toEqual(['/api/updates/android']);
+  });
+
+  test('offers nothing when the APK is the published build', async () => {
+    shell({ bootstrap: { shellVersion: '0.6.0', isAndroid: true } });
+    expect(await mount(stubFetch([]))).toBe('none');
+  });
+
+  test('offers an INSTALL to a browser on Android, and nothing on a desktop browser', async () => {
+    shell({ bootstrap: { isAndroid: true } });
+    expect(await mount(stubFetch([]))).toBe('install:android:0.6.0');
+
+    shell({ bootstrap: { isAndroid: false } });
+    expect(await mount(stubFetch([]))).toBe('none');
+  });
+});
+
+describe('the iOS shell', () => {
+  test('reads its own token and its own route', async () => {
+    shell({ bootstrap: { iosShellVersion: '0.1.0' } });
+    const asked: string[] = [];
+
+    expect(await mount(stubFetch(asked))).toBe('update:ios:0.6.0');
+    expect(asked).toEqual(['/api/updates/ios']);
+  });
+
+  test('an iOS browser is offered nothing, because an IPA cannot be installed from a page', async () => {
+    shell({ bootstrap: {} });
+    expect(await mount(stubFetch([]))).toBe('none');
+  });
+});
+
+describe('the desktop shells', () => {
+  test('reads the version from the bridge and the route from the kind', async () => {
+    // No bootstrap token at all: a desktop app reports itself over the bridge,
+    // and the console had no way to read it before this.
+    shell({ desktop: { platform: 'macos', shellVersion: '0.1.0', overlayTitlebar: true } });
+    const asked: string[] = [];
+
+    expect(await mount(stubFetch(asked))).toBe('update:macos:0.6.0');
+    expect(asked).toEqual(['/api/updates/desktop?kind=macos']);
+  });
+
+  test('each desktop shell asks for its own kind', async () => {
+    for (const platform of ['windows', 'linux'] as const) {
+      shell({ desktop: { platform, shellVersion: '0.1.0' } });
+      const asked: string[] = [];
+      await mount(stubFetch(asked));
+      expect(asked, platform).toEqual([`/api/updates/desktop?kind=${platform}`]);
+    }
+  });
+
+  test('a current desktop build offers nothing', async () => {
+    shell({ desktop: { platform: 'windows', shellVersion: '0.6.0' } });
+    expect(await mount(stubFetch([]))).toBe('none');
+  });
+
+  test('a browser on a desktop is offered nothing', async () => {
+    shell({ bootstrap: { isAndroid: false } });
+    expect(await mount(stubFetch([]))).toBe('none');
+  });
+
+  test('the desktop identity wins over a mobile token, because that is the shell asking', async () => {
+    // A page cannot carry both in practice, and if it somehow did the desktop
+    // app is the process whose version is being compared.
+    shell({
+      bootstrap: { shellVersion: '0.1.0', isAndroid: true },
+      desktop: { platform: 'linux', shellVersion: '0.1.0' },
+    });
+    expect(await mount(stubFetch([]))).toBe('update:linux:0.6.0');
+  });
+
+  test('a refused probe draws no button', async () => {
+    shell({ desktop: { platform: 'macos', shellVersion: '0.1.0' } });
+    const refusing = (async () => ({ ok: false, json: async () => ({}) }) as Response) as unknown as typeof fetch;
+    expect(await mount(refusing)).toBe('none');
+  });
+
+  test('a payload with no artifact draws no button', async () => {
+    shell({ desktop: { platform: 'macos', shellVersion: '0.1.0' } });
+    const empty = (async () =>
+      ({
+        ok: true,
+        json: async () => ({ url: null, latest: null, releaseUrl: null }),
+      }) as Response) as unknown as typeof fetch;
+    expect(await mount(empty)).toBe('none');
+  });
+});

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' });