@kabmo-labs/kabmo 0.7.0 → 0.9.0

package/src/client/components/common/shell-update-button/index.tsx

@@ -0,0 +1,125 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The native shell's update/install control, shared by both sidebar layouts.
+ *
+ * ## Two controls, because there are two different jobs
+ *
+ * - **A link** when the console cannot name a file: a desktop shell that did not
+ *   report its architecture, or any offer whose artifact is not installable from
+ *   inside. Following it is the browser's (or the WebView's) job.
+ * - **A button** when the shell CAN install it: the click opens a CONFIRMATION, and
+ *   the confirmation asks the shell to download, verify and replace itself. That is
+ *   the desktop self-update, and it is the whole reason this component exists.
+ *
+ * The decision is `canSelfUpdate`, never a check on the platform at the call site:
+ * Android installs through `PackageInstaller` (its own path, unchanged), iOS cannot
+ * install at all, and a browser has no shell to ask.
+ *
+ * ## The control is ONLY a control
+ *
+ * Every word a run has to say — the confirmation, the progress, the shell's own
+ * refusal — is in `Modal.tsx`. The footer is a 24px row of glyphs, and a status
+ * sentence pushed into it moved the neighbouring controls and read as a status
+ * line for the SIDEBAR rather than for the update.
+ *
+ * ## The state lives here, not in either footer
+ *
+ * Both layouts draw this control and each unmounts at a different moment (a phone
+ * closes its drawer, a desktop swaps sessions). One hook, one vocabulary of
+ * phases, so the two cannot report the same run differently.
+ */
+
+import { useState } from 'preact/hooks';
+import { createPortal } from 'preact/compat';
+import { Download, Loader2 } from 'lucide-preact';
+import {
+  shellDownloadLabel,
+  shellDownloadShortLabel,
+  type ShellDownload,
+} from '@/client/hooks/ui/updates/shell-download';
+import { canSelfUpdate, useShellUpdate } from '@/client/hooks/ui/updates/shell-update';
+import { ShellUpdateModal } from '@/client/components/common/shell-update-button/Modal';
+
+interface ShellUpdateButtonProps {
+  download: ShellDownload;
+  /** `icon` for the desktop footer's glyph row, `label` for the phone's. */
+  variant: 'icon' | 'label';
+}
+
+const ICON_CLASS = 'p-1 rounded hover:text-ink hover:bg-ink/5 cursor-pointer transition-colors';
+
+export function ShellUpdateButton({ download, variant }: ShellUpdateButtonProps) {
+  const { phase, message, apply, reset, working } = useShellUpdate();
+  // The dialog is open from the CLICK until it is dismissed, and the run's phases
+  // are drawn inside it. A closed dialog whose run is still `working` is not a
+  // state this component can be in: `confirm` is what opens it.
+  const [open, setOpen] = useState(false);
+  const label = shellDownloadLabel(download);
+
+  if (!canSelfUpdate(download)) {
+    // A link, and `target="_blank"` hands it to the system browser so the console
+    // is not replaced by a file download.
+    return (
+      <a
+        href={download.url}
+        target="_blank"
+        rel="noopener noreferrer"
+        title={label}
+        aria-label={label}
+        className={ICON_CLASS}
+      >
+        {variant === 'icon' ? <Download size={16} /> : <span>{shellDownloadShortLabel(download)}</span>}
+      </a>
+    );
+  }
+
+  return (
+    <>
+      <button
+        type="button"
+        // A dismissed run is not a run: reopening starts from the confirmation, not
+        // from the previous attempt's refusal.
+        onClick={() => {
+          reset();
+          setOpen(true);
+        }}
+        disabled={working}
+        title={label}
+        aria-label={label}
+        className={`${ICON_CLASS} disabled:cursor-not-allowed disabled:opacity-60 inline-flex items-center gap-1`}
+      >
+        {working ? (
+          <Loader2 size={variant === 'icon' ? 16 : 13} className="animate-spin motion-reduce:animate-none" />
+        ) : (
+          <Download size={variant === 'icon' ? 16 : 13} />
+        )}
+        {variant === 'label' && <span>{shellDownloadShortLabel(download)}</span>}
+      </button>
+
+      {open &&
+        // A PORTAL, not a child of this row. The footer is a 24px flex row of
+        // glyphs, so a dialog rendered inside it is nested in a control strip: its
+        // text joins the row's own text content (measured in the browser — the row
+        // read as the dialog's body), and any `overflow`/`transform` added to that
+        // row later would clip a `fixed` overlay. The portal is what makes "the
+        // footer says nothing about a run" true rather than merely visually true.
+        createPortal(
+          <ShellUpdateModal
+            download={download}
+            phase={phase === 'idle' ? 'confirm' : phase}
+            message={message}
+            onConfirm={() => void apply(download)}
+            // Closing mid-run hides the dialog but does not cancel the shell: it is
+            // already replacing itself, and a Cancel that could not stop it would be
+            // a button that lies. The control stays disabled until the run answers.
+            onClose={() => setOpen(false)}
+          />,
+          document.body,
+        )}
+    </>
+  );
+}

package/src/client/components/common/toolbar-row/index.test.tsx

@@ -0,0 +1,166 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The toolbar stays ONE row, and what does not fit is one click away.
+ *
+ * The failure this pins is a row that becomes two: the editor panel is 320px
+ * wide on a 1440px screen, and the width-mode buttons pushed ten controls past
+ * it. Wrapping moved the document down by the toolbar's own height and read as
+ * a second toolbar; a horizontal scroll clipped the tail invisibly. Neither is
+ * visible to a state-only assertion, so the cases below are about what is
+ * RENDERED and what the `⋯` menu offers.
+ *
+ * happy-dom lays nothing out, so `getBoundingClientRect` and `clientWidth` are
+ * stubbed at the PROTOTYPE level — the rule reads exactly those two values, and
+ * stubbing them before the first render is what lets the component's own layout
+ * effect measure a real row instead of a row of zeros.
+ */
+
+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 { Save, Search, WrapText } from 'lucide-preact';
+import { ToolbarRow, type ToolbarCluster } from '@/client/components/common/toolbar-row';
+import { installDomGlobals, restoreDomGlobals } from '@/test-support/pristine-globals';
+
+let container: HTMLElement;
+/** What the stubbed layout reports for the row, and for each cluster in order. */
+let rowWidth = 0;
+let clusterWidths: number[] = [];
+
+/** Captured inside `beforeAll`: the DOM globals do not exist at module load. */
+let originalRect: typeof Element.prototype.getBoundingClientRect;
+let originalClientWidth: PropertyDescriptor | undefined;
+
+/** The row is the flex container the component renders; clusters carry a marker. */
+function isRow(el: HTMLElement): boolean {
+  return el.className.includes('flex-nowrap');
+}
+
+function rectOf(width: number): DOMRect {
+  return { width, height: 0, top: 0, left: 0, right: width, bottom: 0, x: 0, y: 0, toJSON: () => ({}) } as DOMRect;
+}
+
+beforeAll(() => {
+  installDomGlobals(new Window({ url: 'http://localhost' }));
+  originalRect = Element.prototype.getBoundingClientRect;
+  originalClientWidth = Object.getOwnPropertyDescriptor(HTMLElement.prototype, 'clientWidth');
+  Element.prototype.getBoundingClientRect = function (this: Element) {
+    const el = this as HTMLElement;
+    if (el.hasAttribute?.('data-toolbar-cluster')) {
+      const siblings = [...(el.parentElement?.querySelectorAll('[data-toolbar-cluster]') ?? [])];
+      return rectOf(clusterWidths[siblings.indexOf(el)] ?? 0);
+    }
+    if (isRow(el)) return rectOf(rowWidth);
+    return originalRect.call(this);
+  };
+  Object.defineProperty(HTMLElement.prototype, 'clientWidth', {
+    configurable: true,
+    get(this: HTMLElement) {
+      if (isRow(this)) return rowWidth;
+      return originalClientWidth?.get?.call(this) ?? 0;
+    },
+  });
+});
+
+afterEach(() => {
+  if (container) {
+    render(null, container);
+    container.remove();
+  }
+  rowWidth = 0;
+  clusterWidths = [];
+});
+
+afterAll(() => {
+  Element.prototype.getBoundingClientRect = originalRect;
+  if (originalClientWidth) Object.defineProperty(HTMLElement.prototype, 'clientWidth', originalClientWidth);
+  restoreDomGlobals();
+});
+
+/** Three clusters, the first pinned — the editor toolbar in miniature. */
+function clusters(onSelect: string[] = []): ToolbarCluster[] {
+  const make = (id: string, label: string, icon: typeof Save, pinned?: boolean): ToolbarCluster => ({
+    id,
+    pinned,
+    actions: [{ label, icon, onSelect: () => onSelect.push(label) }],
+    children: h('button', { type: 'button', 'aria-label': label }, label),
+  });
+  return [
+    make('save', 'Save file', Save, true),
+    make('find', 'Find and replace', Search),
+    make('wrap', 'Word wrap on', WrapText),
+  ];
+}
+
+async function mount(width: number, widths: number[], onSelect: string[] = []): Promise<void> {
+  rowWidth = width;
+  clusterWidths = widths;
+  container = document.createElement('div');
+  document.body.appendChild(container);
+  await act(async () => {
+    render(h(ToolbarRow, { clusters: clusters(onSelect) }), container);
+  });
+  // The layout effect commits its measurement in a second pass, the way the
+  // browser gives one before paint.
+  await act(async () => {});
+}
+
+function rowButtons(): HTMLButtonElement[] {
+  const host = container.firstElementChild as HTMLElement;
+  return [...host.querySelectorAll<HTMLButtonElement>(':scope > div > button')];
+}
+
+async function openMenu(): Promise<void> {
+  const trigger = rowButtons().find((button) => button.getAttribute('aria-label') === 'More actions');
+  if (!trigger) throw new Error('no overflow trigger rendered');
+  await act(async () => {
+    trigger.dispatchEvent(new window.MouseEvent('click', { bubbles: true }) as never);
+  });
+}
+
+describe('ToolbarRow overflow', () => {
+  test('a wide row draws every cluster and no trigger', async () => {
+    await mount(400, [60, 60, 60]);
+    expect(rowButtons().map((button) => button.getAttribute('aria-label'))).toEqual([
+      'Save file',
+      'Find and replace',
+      'Word wrap on',
+    ]);
+  });
+
+  test('a narrow row keeps the pinned cluster and moves the rest into `⋯`', async () => {
+    await mount(120, [60, 60, 60]);
+    const labels = rowButtons().map((button) => button.getAttribute('aria-label'));
+    expect(labels).toContain('Save file');
+    expect(labels).toContain('More actions');
+    expect(labels).not.toContain('Word wrap on');
+  });
+
+  test('the menu offers the hidden controls, named in words', async () => {
+    await mount(120, [60, 60, 60]);
+    await openMenu();
+    const items = [...container.querySelectorAll('[role="menuitem"]')].map((item) => item.textContent?.trim());
+    expect(items).toContain('Word wrap on');
+    // The pinned control is on the row, so it is NOT in the menu.
+    expect(items).not.toContain('Save file');
+  });
+
+  test('a menu row runs the same action the button would', async () => {
+    const ran: string[] = [];
+    await mount(120, [60, 60, 60], ran);
+    await openMenu();
+    const item = [...container.querySelectorAll<HTMLButtonElement>('[role="menuitem"]')].find(
+      (row) => row.textContent?.trim() === 'Word wrap on',
+    );
+    if (!item) throw new Error('the wrap row is missing from the menu');
+    await act(async () => {
+      item.dispatchEvent(new window.MouseEvent('click', { bubbles: true }) as never);
+    });
+    expect(ran).toEqual(['Word wrap on']);
+  });
+});

package/src/client/components/common/toolbar-row/index.tsx

@@ -0,0 +1,189 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * One toolbar row that never becomes two.
+ *
+ * The editor and diff toolbars carry ten-plus controls and the editor panel is
+ * 320px wide on a 1440px screen. WRAPPING was the previous answer and it is the
+ * wrong one: a second row moves the document down by the toolbar's own height
+ * and reads as a second toolbar. A horizontal scroll is worse — a clipped
+ * control is invisible. So the clusters that do not fit move into a `⋯` menu and
+ * every control stays one click away.
+ *
+ * Widths are MEASURED, never tabulated: the row lays every cluster out once and
+ * reads each one's rendered width, then hides what does not fit. A table of
+ * guessed pixel widths drifts the moment a label, an icon or a font changes, and
+ * a wrong guess here is a control that is either clipped or needlessly buried.
+ */
+
+import { useEffect, useLayoutEffect, useRef, useState } from 'preact/hooks';
+import type { ComponentChildren } from 'preact';
+import { Ellipsis, type LucideIcon } from 'lucide-preact';
+import { useOnClickOutside } from '@/client/hooks/ui/on-click-outside';
+import { toolbarHasOverflow, toolbarVisibleClusters } from '@/shared/lib/ui/toolbar-overflow';
+
+/** One row the `⋯` menu offers when its cluster is not on the row. */
+export interface ToolbarOverflowAction {
+  label: string;
+  icon: LucideIcon;
+  onSelect: () => void;
+  /** Rendered as a pressed row (word wrap on, a mode already active). */
+  active?: boolean;
+  disabled?: boolean;
+}
+
+/**
+ * A logical group of controls that hides as a unit.
+ *
+ * A group rather than a single button because the clusters are already grouped
+ * in the toolbars (zoom is two buttons, copy/download is a pair, the width modes
+ * are a pair) and splitting them would let half of a pair stay on the row.
+ */
+export interface ToolbarCluster {
+  id: string;
+  /**
+   * Never leave the row, whatever its width.
+   *
+   * The visual order is not the priority order: Save is drawn first because that
+   * is where a reader looks for it, while the width modes sit last and are the
+   * reason the panel exists. Pinning says which ones a menu row must not be the
+   * only way to reach.
+   */
+  pinned?: boolean;
+  /** What the `⋯` menu offers when this cluster is hidden. */
+  actions: ToolbarOverflowAction[];
+  children: ComponentChildren;
+}
+
+interface ToolbarRowProps {
+  clusters: ToolbarCluster[];
+  className?: string;
+}
+
+export function ToolbarRow({ clusters, className = '' }: ToolbarRowProps) {
+  const rowRef = useRef<HTMLDivElement>(null);
+  /** Measured widths, tagged with the cluster set they describe. */
+  const [metrics, setMetrics] = useState<{ signature: string; widths: number[] } | null>(null);
+  const [available, setAvailable] = useState(0);
+
+  // The set changes when a conditional cluster appears or disappears (a
+  // previewable file opened, a byte viewer took over), and stale widths would
+  // then hide the wrong cluster. Rendering every cluster until they are measured
+  // is what gives the ruler something to measure — and the layout effect runs
+  // BEFORE paint, so the unresolved frame is never seen.
+  const signature = clusters.map((cluster) => `${cluster.id}:${cluster.pinned ? 1 : 0}`).join('|');
+  const ready = metrics?.signature === signature;
+  const widths = ready ? metrics.widths : [];
+  const pinned = clusters.map((cluster) => cluster.pinned === true);
+  const visible = widths.length > 0
+    ? toolbarVisibleClusters({ widths, pinned, available })
+    : clusters.map(() => true);
+
+  useLayoutEffect(() => {
+    const row = rowRef.current;
+    if (!row) return;
+    if (!ready) {
+      const children = [...row.querySelectorAll<HTMLElement>('[data-toolbar-cluster]')];
+      if (children.length === clusters.length) {
+        setMetrics({ signature, widths: children.map((child) => child.getBoundingClientRect().width) });
+      }
+    }
+    setAvailable(row.clientWidth);
+  });
+
+  // The row's width changes on a window resize, a panel drag and a layout mode
+  // switch — none of which are `window` events.
+  useEffect(() => {
+    const row = rowRef.current;
+    if (!row || typeof ResizeObserver === 'undefined') return;
+    const observer = new ResizeObserver(() => setAvailable(row.clientWidth));
+    observer.observe(row);
+    return () => observer.disconnect();
+  }, []);
+
+  const hiddenActions = clusters.filter((_, index) => !visible[index]).flatMap((cluster) => cluster.actions);
+
+  return (
+    <div ref={rowRef} className={`flex flex-nowrap items-center justify-end gap-x-1 overflow-hidden ${className}`}>
+      {clusters.map((cluster, index) =>
+        visible[index] ? (
+          <div key={cluster.id} data-toolbar-cluster="" className="flex items-center flex-shrink-0">
+            {cluster.children}
+          </div>
+        ) : null,
+      )}
+      {toolbarHasOverflow(visible) && <OverflowMenu actions={hiddenActions} />}
+    </div>
+  );
+}
+
+/**
+ * The `⋯` trigger and its menu.
+ *
+ * A menu rather than a horizontal scroll: a clipped action is invisible, and the
+ * diff toolbar already learned that a scroll strip with no visible scrollbar
+ * reads as "there is nothing more here" (measured: 361px of content in a 296px
+ * box, with `Stage` entirely outside it).
+ */
+function OverflowMenu({ actions }: { actions: ToolbarOverflowAction[] }) {
+  const [open, setOpen] = useState(false);
+  const rootRef = useRef<HTMLDivElement>(null);
+  useOnClickOutside(rootRef, () => setOpen(false));
+
+  useEffect(() => {
+    if (!open) return;
+    const onKeyDown = (event: globalThis.KeyboardEvent) => {
+      if (event.key === 'Escape') setOpen(false);
+    };
+    document.addEventListener('keydown', onKeyDown);
+    return () => document.removeEventListener('keydown', onKeyDown);
+  }, [open]);
+
+  return (
+    <div className="relative flex-shrink-0" ref={rootRef}>
+      <button
+        type="button"
+        title="More actions"
+        aria-label="More actions"
+        aria-haspopup="menu"
+        aria-expanded={open}
+        onClick={() => setOpen(!open)}
+        className={`flex items-center justify-center p-1.5 rounded transition-colors cursor-pointer ${
+          open ? 'bg-ink/10 text-ink' : 'text-ink/50 hover:text-ink hover:bg-ink/5'
+        }`}
+      >
+        <Ellipsis size={14} />
+      </button>
+
+      {open && (
+        <div
+          role="menu"
+          className="absolute right-0 top-full mt-1 w-52 bg-paper border border-ink/15 rounded-lg shadow-lg z-50 py-1 text-xs"
+        >
+          {actions.map((action) => (
+            <button
+              key={action.label}
+              type="button"
+              role="menuitem"
+              disabled={action.disabled}
+              aria-pressed={action.active}
+              onClick={() => {
+                setOpen(false);
+                action.onSelect();
+              }}
+              className={`w-full text-left flex items-center gap-2 px-3 py-1.5 transition-colors disabled:cursor-default disabled:opacity-40 ${
+                action.active ? 'bg-ink/5 text-ink font-medium' : 'text-ink/75 hover:bg-ink/5 hover:text-ink'
+              }`}
+            >
+              <action.icon size={13} className="flex-shrink-0" />
+              <span className="truncate">{action.label}</span>
+            </button>
+          ))}
+        </div>
+      )}
+    </div>
+  );
+}

package/src/client/components/common/workspace-options-menu/index.tsx

@@ -13,7 +13,7 @@
  * source of truth.
  */
 
-import { FolderOpen, ListChecks, Pin, PinOff, Trash2 } from 'lucide-preact';
+import { FolderOpen, GitBranch, ListChecks, Pin, PinOff, Trash2 } from 'lucide-preact';
 
 interface WorkspaceOptionsMenuProps {
   variant: 'desktop' | 'mobile';
@@ -23,6 +23,12 @@ interface WorkspaceOptionsMenuProps {
   onOpenFolder?: () => void;
   /** Enter the session batch-selection mode scoped to this workspace. */
   onSelectSessions?: () => void;
+  /**
+   * Open the New worktree dialog for this workspace. Offered only for a folder
+   * bound to a repository: a worktree needs one, and a row that opens a dialog
+   * which can only refuse is a row that teaches the user nothing.
+   */
+  onNewWorktree?: () => void;
   confirmDelete: boolean;
   onPin: () => void;
   onDelete: () => void;
@@ -35,6 +41,7 @@ export function WorkspaceOptionsMenu({
   isPinned = false,
   onOpenFolder,
   onSelectSessions,
+  onNewWorktree,
   confirmDelete,
   onPin,
   onDelete,
@@ -71,6 +78,12 @@ export function WorkspaceOptionsMenu({
             <span>Select sessions</span>
           </button>
         )}
+        {onNewWorktree && (
+          <button type="button" onClick={onNewWorktree} className="w-full text-left px-3 py-2 hover:bg-ink/5 text-ink/80 flex items-center space-x-2">
+            <GitBranch size={13} />
+            <span>New worktree…</span>
+          </button>
+        )}
         <button type="button" onClick={onRequestDelete} className="w-full text-left px-3 py-2 hover:bg-error/10 text-error flex items-center space-x-2">
           <Trash2 size={13} />
           <span>Delete Workspace</span>
@@ -105,6 +118,11 @@ export function WorkspaceOptionsMenu({
           <ListChecks size={12} /><span>Select sessions</span>
         </button>
       )}
+      {onNewWorktree && (
+        <button type="button" onClick={onNewWorktree} className="w-full text-left px-3 py-1.5 hover:bg-ink/5 cursor-pointer flex items-center space-x-2 text-ink/80">
+          <GitBranch size={12} /><span>New worktree…</span>
+        </button>
+      )}
       <button type="button" onClick={onRequestDelete} className="w-full text-left px-3 py-1.5 hover:bg-ink/5 cursor-pointer flex items-center space-x-2 text-error">
         <Trash2 size={12} /><span>Delete Workspace</span>
       </button>

package/src/client/components/layout/desktop-layout/TopNavbar.tsx

@@ -12,8 +12,7 @@ import { titlebarPaddingLeft, titlebarPaddingRight } from '@/shared/lib/ui/title
 import { ServerSwitcher } from '@/client/components/common/server-switcher';
 import { useDesktopServers } from '@/client/hooks/desktop/servers';
 import { isDesktopShell } from '@/client/lib/desktop/bridge';
-import { dragRegionProps, drawsWindowControls, titlebarInsetLeft } from '@/client/lib/desktop/titlebar';
-import { WindowControls } from '@/client/components/common/window-controls';
+import { dragRegionProps, titlebarInsetLeft } from '@/client/lib/desktop/titlebar';
 import { useOnClickOutside } from '@/client/hooks/ui/on-click-outside';
 
 interface TopNavbarProps {
@@ -203,10 +202,10 @@ export function TopNavbar({
           onToggleEditor={onToggleEditor}
           onSwitchToMobile={onSwitchToMobile}
         />
-        {/* The Windows shell is borderless and its webview is an HWND, so the
-            system's caption buttons cannot be drawn over it — the page owns
-            them there. Absent on macOS, whose traffic lights are the system's. */}
-        {drawsWindowControls() && <WindowControls />}
+        {/* The Windows/Linux caption buttons come from `HeaderControls` itself:
+            a desktop shell window can be narrower than the mobile breakpoint,
+            so the phone header has to draw them too — and a control that only
+            one layout renders is a control the other layout's window loses. */}
       </div>
 
       {menu.anchor && sessionActions && (