@liberation-data/desk 0.1.0

package/src/react/MenuBar.tsx

@@ -0,0 +1,350 @@
+import { useEffect, useId, useMemo, useRef, useState } from 'react'
+import type { KeyboardEvent as ReactKeyboardEvent, ReactNode } from 'react'
+import { canPerform, perform } from '../core/commands.js'
+import type { CommandId } from '../core/commands.js'
+import { focusedId } from '../core/desk.js'
+import { bindShortcuts, formatShortcut, isApplePlatform } from '../core/shortcuts.js'
+import type { DeskState, WindowId } from '../core/types.js'
+import { useDesk } from './context.js'
+
+/*
+ * A menu bar in the AppKit manner. Menus never take keyboard focus from the
+ * window you were working in — they are driven by a document key listener while
+ * open — so a command chosen from a menu reaches the same responder a shortcut
+ * would. Items ask the responder chain whether they are enabled as the menu opens.
+ */
+
+type Flag = boolean | (() => boolean)
+
+interface ItemCommon {
+  readonly label: string
+  /** Shown after the label, muted. */
+  readonly detail?: string
+  readonly shortcut?: string
+  readonly checked?: Flag
+}
+
+export type MenuItem =
+  | ({ readonly type: 'command'; readonly command: CommandId; readonly args?: unknown } & ItemCommon)
+  | ({ readonly type: 'action'; readonly onSelect: () => void; readonly disabled?: Flag } & ItemCommon)
+  | { readonly type: 'separator' }
+  | { readonly type: 'header'; readonly label: string }
+
+export interface Menu {
+  readonly id: string
+  /** The accessible name, and the title when `title` is not given. */
+  readonly label: string
+  /** A richer title: an icon, a badge. */
+  readonly title?: ReactNode
+  /** The app's own menu: its name, set in bold. Conventionally the first one. */
+  readonly emphasis?: boolean
+  /** Items, or a function called each time the menu opens — for lists that change, like open windows. */
+  readonly items: readonly MenuItem[] | (() => readonly MenuItem[])
+}
+
+type Options<T> = Omit<T, 'type' | 'label'>
+export const menuCommand = (label: string, command: CommandId, options: Omit<Options<Extract<MenuItem, { type: 'command' }>>, 'command'> = {}): MenuItem => ({
+  type: 'command',
+  label,
+  command,
+  ...options,
+})
+export const menuAction = (label: string, onSelect: () => void, options: Omit<Options<Extract<MenuItem, { type: 'action' }>>, 'onSelect'> = {}): MenuItem => ({
+  type: 'action',
+  label,
+  onSelect,
+  ...options,
+})
+export const menuSeparator = (): MenuItem => ({ type: 'separator' })
+export const menuHeader = (label: string): MenuItem => ({ type: 'header', label })
+
+/** One item per open window, the key window checked — what a Window menu lists at its foot. */
+export function windowMenuItems(state: DeskState, focus: (id: WindowId) => void, title: (id: WindowId) => string): MenuItem[] {
+  const key = focusedId(state)
+  return state.windows.map(w => menuAction(title(w.id), () => focus(w.id), { checked: w.id === key }))
+}
+
+export interface MenuBarProps {
+  /** Menus on the leading side, in order. The first is conventionally the app's own. */
+  readonly menus: readonly Menu[]
+  /** Status menus on the trailing side. */
+  readonly status?: readonly Menu[]
+  /** Leading content before the menus, e.g. the app's mark. */
+  readonly leading?: ReactNode
+  /** Trailing content after the status menus, e.g. a clock. */
+  readonly trailing?: ReactNode
+  readonly label?: string
+  /** Bind the shortcuts of command items, in every menu. Default true. */
+  readonly shortcuts?: boolean
+  readonly className?: string
+}
+
+interface Resolved {
+  readonly item: MenuItem
+  readonly enabled: boolean
+  readonly checked: boolean | undefined
+}
+
+interface OpenMenu {
+  readonly id: string
+  readonly items: readonly Resolved[]
+  readonly active: number
+  readonly via: 'pointer' | 'keyboard'
+}
+
+const read = (flag: Flag | undefined) => (typeof flag === 'function' ? flag() : flag)
+const selectable = (r: Resolved) => r.enabled && (r.item.type === 'command' || r.item.type === 'action')
+
+export function MenuBar({ menus, status = [], leading, trailing, label = 'Menu bar', shortcuts = true, className }: MenuBarProps) {
+  const desk = useDesk()
+  const all = useMemo(() => [...menus, ...status], [menus, status])
+  const [open, setOpen] = useState<OpenMenu | null>(null)
+  const [roving, setRoving] = useState(0)
+  const bar = useRef<HTMLDivElement>(null)
+  const titles = useRef(new Map<string, HTMLButtonElement>())
+  // Where focus was before the keyboard reached the menu bar, so a chosen command starts from there.
+  const returnTo = useRef<HTMLElement | null>(null)
+  const baseId = useId()
+  const apple = useMemo(isApplePlatform, [])
+
+  const resolve = (menu: Menu): Resolved[] =>
+    (typeof menu.items === 'function' ? menu.items() : menu.items).map(item => ({
+      item,
+      enabled:
+        item.type === 'command' ? canPerform(desk, item.command)
+        : item.type === 'action' ? !read(item.disabled)
+        : false,
+      checked: item.type === 'command' || item.type === 'action' ? read(item.checked) : undefined,
+    }))
+
+  const step = (items: readonly Resolved[], from: number, delta: 1 | -1) => {
+    for (let i = 1; i <= items.length; i++) {
+      const index = (from + delta * i + items.length * 2) % items.length
+      if (items[index] && selectable(items[index])) return index
+    }
+    return -1
+  }
+
+  const openMenu = (index: number, via: OpenMenu['via'], active: 'first' | 'last' | 'none' = 'first') => {
+    const menu = all[(index + all.length) % all.length]
+    if (!menu) return
+    const items = resolve(menu)
+    setRoving(all.indexOf(menu))
+    setOpen({
+      id: menu.id,
+      items,
+      via,
+      active: active === 'none' ? -1 : active === 'first' ? step(items, -1, 1) : step(items, items.length, -1),
+    })
+    if (via === 'keyboard') titles.current.get(menu.id)?.focus()
+  }
+
+  const close = (returnFocus: boolean) => {
+    const was = open
+    setOpen(null)
+    if (returnFocus && was) titles.current.get(was.id)?.focus()
+  }
+
+  const activate = (resolved: Resolved | undefined) => {
+    if (!resolved || !selectable(resolved)) return
+    const wasKeyboard = open?.via === 'keyboard'
+    setOpen(null)
+    // Keyboard use put focus on the menu bar; send it back so the command starts where the person was working.
+    if (wasKeyboard && bar.current?.contains(document.activeElement)) {
+      if (returnTo.current?.isConnected) returnTo.current.focus()
+      else (document.activeElement as HTMLElement).blur()
+    }
+    const { item } = resolved
+    if (item.type === 'command') perform(desk, item.command, item.args)
+    else if (item.type === 'action') item.onSelect()
+  }
+
+  // While a menu is open, the keyboard drives it without it ever holding focus.
+  useEffect(() => {
+    if (!open) return
+    const menuIndex = all.findIndex(m => m.id === open.id)
+    const onKey = (event: KeyboardEvent) => {
+      const handled = (() => {
+        switch (event.key) {
+          case 'ArrowDown': setOpen({ ...open, active: step(open.items, open.active, 1) }); return true
+          case 'ArrowUp': setOpen({ ...open, active: step(open.items, open.active < 0 ? open.items.length : open.active, -1) }); return true
+          case 'Home': setOpen({ ...open, active: step(open.items, -1, 1) }); return true
+          case 'End': setOpen({ ...open, active: step(open.items, open.items.length, -1) }); return true
+          case 'ArrowRight': openMenu(menuIndex + 1, open.via); return true
+          case 'ArrowLeft': openMenu(menuIndex - 1, open.via); return true
+          case 'Enter':
+          case ' ': activate(open.items[open.active]); return true
+          case 'Escape': close(open.via === 'keyboard'); return true
+          case 'Tab': close(false); return false
+          default: {
+            if (event.key.length !== 1 || event.metaKey || event.ctrlKey || event.altKey) return false
+            const letter = event.key.toLowerCase()
+            const start = open.active
+            for (let i = 1; i <= open.items.length; i++) {
+              const index = (start + i) % open.items.length
+              const r = open.items[index]
+              if (r && selectable(r) && 'label' in r.item && r.item.label.toLowerCase().startsWith(letter)) {
+                setOpen({ ...open, active: index })
+                return true
+              }
+            }
+            return false
+          }
+        }
+      })()
+      if (handled) {
+        event.preventDefault()
+        event.stopPropagation()
+      }
+    }
+    const onPointerDown = (event: PointerEvent) => {
+      if (!bar.current?.contains(event.target as Node)) setOpen(null)
+    }
+    document.addEventListener('keydown', onKey, true)
+    document.addEventListener('pointerdown', onPointerDown, true)
+    return () => {
+      document.removeEventListener('keydown', onKey, true)
+      document.removeEventListener('pointerdown', onPointerDown, true)
+    }
+  })
+
+  // Menus own their key equivalents, as in AppKit. Menus that build their items when opened are
+  // read when a key is pressed, so their shortcuts work before the menu has ever been opened.
+  const menusNow = useRef(all)
+  menusNow.current = all
+  useEffect(
+    () =>
+      shortcuts
+        ? bindShortcuts(
+            desk,
+            () =>
+              Object.fromEntries(
+                menusNow.current
+                  .flatMap(m => (typeof m.items === 'function' ? m.items() : m.items))
+                  .flatMap(i => (i.type === 'command' && i.shortcut ? [[i.shortcut, i.command] as const] : [])),
+              ),
+            { apple },
+          )
+        : undefined,
+    [desk, shortcuts, apple],
+  )
+
+  const onBarKeyDown = (event: ReactKeyboardEvent<HTMLDivElement>) => {
+    if (open) return
+    const index = all.findIndex(m => titles.current.get(m.id) === document.activeElement)
+    if (index < 0) return
+    const move = (to: number) => {
+      const next = all[(to + all.length) % all.length]
+      if (next) {
+        setRoving(all.indexOf(next))
+        titles.current.get(next.id)?.focus()
+      }
+    }
+    switch (event.key) {
+      case 'ArrowRight': move(index + 1); break
+      case 'ArrowLeft': move(index - 1); break
+      case 'Home': move(0); break
+      case 'End': move(all.length - 1); break
+      case 'ArrowDown':
+      case 'Enter':
+      case ' ': openMenu(index, 'keyboard', 'first'); break
+      case 'ArrowUp': openMenu(index, 'keyboard', 'last'); break
+      default: return
+    }
+    event.preventDefault()
+  }
+
+  const renderMenu = (menu: Menu, index: number) => {
+    const isOpen = open?.id === menu.id
+    const titleId = `${baseId}-title-${menu.id}`
+    const menuId = `${baseId}-menu-${menu.id}`
+    return (
+      <div className="desk-menubar-slot" key={menu.id} data-align={index >= menus.length ? 'end' : undefined}>
+        <button
+          ref={el => {
+            if (el) titles.current.set(menu.id, el)
+            else titles.current.delete(menu.id)
+          }}
+          id={titleId}
+          type="button"
+          role="menuitem"
+          className="desk-menubar-title"
+          aria-haspopup="menu"
+          aria-expanded={isOpen}
+          aria-controls={isOpen ? menuId : undefined}
+          aria-label={menu.title ? menu.label : undefined}
+          data-emphasis={menu.emphasis || undefined}
+          tabIndex={index === roving ? 0 : -1}
+          // Opening a menu with the pointer must not move focus out of the window being worked in.
+          onMouseDown={event => event.preventDefault()}
+          onClick={() => (isOpen ? close(false) : openMenu(index, 'pointer', 'none'))}
+          onPointerEnter={() => {
+            if (open && !isOpen) openMenu(index, open.via, open.via === 'keyboard' ? 'first' : 'none')
+          }}
+        >
+          {menu.title ?? menu.label}
+        </button>
+        {isOpen && open && (
+          <div
+            id={menuId}
+            role="menu"
+            aria-labelledby={titleId}
+            className="desk-menu"
+            aria-activedescendant={open.active >= 0 ? `${menuId}-${open.active}` : undefined}
+          >
+            {open.items.map((resolved, i) => {
+              const { item } = resolved
+              if (item.type === 'separator') return <div key={i} role="separator" className="desk-menu-separator" />
+              if (item.type === 'header') return <div key={i} role="presentation" className="desk-menu-header">{item.label}</div>
+              const checkable = resolved.checked !== undefined
+              return (
+                <div
+                  key={i}
+                  id={`${menuId}-${i}`}
+                  role={checkable ? 'menuitemcheckbox' : 'menuitem'}
+                  aria-checked={checkable ? resolved.checked : undefined}
+                  aria-disabled={!resolved.enabled || undefined}
+                  className="desk-menu-item"
+                  data-active={i === open.active || undefined}
+                  onMouseDown={event => event.preventDefault()}
+                  onPointerMove={() => {
+                    if (open.active !== i && selectable(resolved)) setOpen({ ...open, active: i })
+                  }}
+                  onPointerLeave={() => {
+                    if (open.via === 'pointer' && open.active === i) setOpen({ ...open, active: -1 })
+                  }}
+                  onClick={() => activate(resolved)}
+                >
+                  <span className="desk-menu-check" aria-hidden="true">{resolved.checked ? '✓' : ''}</span>
+                  <span className="desk-menu-label">{item.label}</span>
+                  {item.detail && <span className="desk-menu-detail">{item.detail}</span>}
+                  {item.shortcut && <kbd className="desk-menu-shortcut">{formatShortcut(item.shortcut, apple)}</kbd>}
+                </div>
+              )
+            })}
+          </div>
+        )}
+      </div>
+    )
+  }
+
+  return (
+    <div
+      ref={bar}
+      role="menubar"
+      aria-label={label}
+      className={['desk-menubar', className].filter(Boolean).join(' ')}
+      onKeyDown={onBarKeyDown}
+      onFocus={event => {
+        const from = event.relatedTarget
+        if (from instanceof HTMLElement && !bar.current?.contains(from)) returnTo.current = from
+      }}
+    >
+      {leading && <div className="desk-menubar-leading">{leading}</div>}
+      {menus.map((menu, i) => renderMenu(menu, i))}
+      <span className="desk-menubar-spacer" />
+      {status.map((menu, i) => renderMenu(menu, menus.length + i))}
+      {trailing && <div className="desk-menubar-trailing">{trailing}</div>}
+    </div>
+  )
+}

package/src/react/appFrame.tsx

@@ -0,0 +1,183 @@
+import { useEffect, useRef } from 'react'
+import type { CSSProperties } from 'react'
+import { topicMatches } from '../core/events.js'
+import type { DeskEvent } from '../core/events.js'
+import { useDragging, useDropTarget } from './dnd.js'
+import type { Accepts } from './dnd.js'
+import { useDesk, useWindowId } from './context.js'
+import { useBus } from './events.js'
+
+/*
+ * A generated app — a self-contained page — running inside a window, and taking
+ * part in the desk as a native window does: hearing events, saying things, and
+ * taking what is dropped on it.
+ *
+ * It runs in a sandboxed frame with no access to the host's origin, and talks
+ * only through messages. The host decides, per app, which topics it may hear,
+ * which it may say, and what may be dropped on it. Nothing else crosses.
+ */
+
+/** The protocol version. Every message carries it, so a mismatch is ignored rather than misread. */
+const PROTOCOL = 1
+
+type HostMessage =
+  | { readonly desk: 1; readonly kind: 'hello'; readonly window: string | null; readonly listens: readonly string[]; readonly says: readonly string[] }
+  | { readonly desk: 1; readonly kind: 'event'; readonly topic: string; readonly payload: unknown; readonly from: string | null }
+  | { readonly desk: 1; readonly kind: 'drop'; readonly type: string; readonly payload: unknown; readonly from: string | null }
+
+type AppMessage =
+  | { readonly desk: 1; readonly kind: 'ready' }
+  | { readonly desk: 1; readonly kind: 'publish'; readonly topic: string; readonly payload: unknown }
+  | { readonly desk: 1; readonly kind: 'open'; readonly window: string }
+
+const isAppMessage = (data: unknown): data is AppMessage =>
+  typeof data === 'object' && data !== null && (data as { desk?: unknown }).desk === PROTOCOL && typeof (data as { kind?: unknown }).kind === 'string'
+
+export interface AppFrameProps {
+  /** The accessible name of the frame: what the app is. */
+  readonly title: string
+  /** The app's page, as a URL or as the HTML itself. Give one. */
+  readonly src?: string
+  readonly srcDoc?: string
+  /** Topics the app may hear, e.g. `['ride.selected']` or `['ride.*']`. Default: none. */
+  readonly listens?: readonly string[]
+  /** Topics the app may say. Anything else it publishes is dropped. Default: none. */
+  readonly says?: readonly string[]
+  /** What may be dropped on it. Default: nothing. */
+  readonly accepts?: Accepts
+  /** Windows the app may ask to open. Default: none. */
+  readonly opens?: readonly string[]
+  /**
+   * The frame's sandbox. The default lets the app run its own scripts and forms, and
+   * nothing more: no same-origin access, no top-level navigation, no pop-ups.
+   */
+  readonly sandbox?: string
+  readonly className?: string
+}
+
+export function AppFrame({
+  title,
+  src,
+  srcDoc,
+  listens = [],
+  says = [],
+  accepts,
+  opens = [],
+  sandbox = 'allow-scripts allow-forms',
+  className,
+}: AppFrameProps) {
+  const desk = useDesk()
+  const bus = useBus()
+  const windowId = useWindowId()
+  const frame = useRef<HTMLIFrameElement>(null)
+  const dragging = useDragging()
+
+  const post = (message: HostMessage) => {
+    // A sandboxed frame without same-origin has an opaque origin, so '*' is the only
+    // target that reaches it. It is safe here: the message goes to this frame's
+    // window and no other.
+    frame.current?.contentWindow?.postMessage(message, '*')
+  }
+
+  const latest = useRef({ listens, says, opens, windowId })
+  latest.current = { listens, says, opens, windowId }
+
+  // What the app says: only from this frame, only on topics it was granted.
+  useEffect(() => {
+    const onMessage = (event: MessageEvent) => {
+      if (!frame.current || event.source !== frame.current.contentWindow || !isAppMessage(event.data)) return
+      const message = event.data
+      const granted = latest.current
+      if (message.kind === 'ready') {
+        post({ desk: PROTOCOL, kind: 'hello', window: granted.windowId, listens: granted.listens, says: granted.says })
+      } else if (message.kind === 'publish') {
+        if (typeof message.topic === 'string' && granted.says.some(pattern => topicMatches(pattern, message.topic))) {
+          bus.publish(message.topic, message.payload, { from: granted.windowId })
+        }
+      } else if (message.kind === 'open') {
+        if (typeof message.window === 'string' && granted.opens.includes(message.window)) desk.open(message.window)
+      }
+    }
+    window.addEventListener('message', onMessage)
+    return () => window.removeEventListener('message', onMessage)
+  }, [bus, desk])
+
+  // What the app hears: only the topics it was granted, and never its own words back.
+  const listenKey = listens.join('|')
+  useEffect(() => {
+    if (!listens.length) return
+    const stops = listens.map(pattern =>
+      bus.subscribe(pattern, (event: DeskEvent) => {
+        if (event.from !== null && event.from === latest.current.windowId) return
+        post({ desk: PROTOCOL, kind: 'event', topic: event.topic, payload: event.payload, from: event.from })
+      }),
+    )
+    return () => stops.forEach(stop => stop())
+    // listenKey stands for the list's contents; the array itself changes identity every render.
+  }, [bus, listenKey])
+
+  const { dropProps } = useDropTarget({
+    accepts: accepts ?? (() => false),
+    disabled: accepts === undefined,
+    onDrop: drag => post({ desk: PROTOCOL, kind: 'drop', type: drag.type, payload: drag.payload, from: drag.from }),
+  })
+
+  // While something is being carried, the frame must not swallow the pointer, or the
+  // desk can never see that it is over this app.
+  const frameStyle: CSSProperties = { pointerEvents: dragging ? 'none' : 'auto' }
+
+  return (
+    <div className={['desk-app-frame', className].filter(Boolean).join(' ')} {...dropProps}>
+      <iframe
+        ref={frame}
+        title={title}
+        className="desk-app-frame-page"
+        sandbox={sandbox}
+        {...(srcDoc !== undefined ? { srcDoc } : src !== undefined ? { src } : {})}
+        style={frameStyle}
+      />
+    </div>
+  )
+}
+
+/**
+ * The app's half of the bridge, as a script to put in its page. It gives the page a
+ * small `desk` object:
+ *
+ *   desk.on('ride.selected', event => …)     hear a granted topic
+ *   desk.onDrop(drop => …)                   take what is dropped on the window
+ *   desk.publish('ride.selected', ride)      say something, if it was granted
+ *   desk.open('map')                         ask for a window, if it was granted
+ *   desk.window                              which window this is, once connected
+ */
+export const APP_BRIDGE_SCRIPT = `(() => {
+  const handlers = new Map();
+  const drops = [];
+  const send = message => parent.postMessage(Object.assign({ desk: ${PROTOCOL} }, message), '*');
+  const desk = {
+    window: null,
+    listens: [],
+    says: [],
+    on(topic, handler) { (handlers.get(topic) || handlers.set(topic, []).get(topic)).push(handler); },
+    onDrop(handler) { drops.push(handler); },
+    publish(topic, payload) { send({ kind: 'publish', topic, payload }); },
+    open(window) { send({ kind: 'open', window }); },
+  };
+  const matches = (pattern, topic) =>
+    pattern === '*' || pattern === topic || (pattern.endsWith('.*') && (topic === pattern.slice(0, -2) || topic.startsWith(pattern.slice(0, -1))));
+  addEventListener('message', event => {
+    if (event.source !== parent || !event.data || event.data.desk !== ${PROTOCOL}) return;
+    const message = event.data;
+    if (message.kind === 'hello') { desk.window = message.window; desk.listens = message.listens; desk.says = message.says; }
+    if (message.kind === 'event') for (const [pattern, list] of handlers) if (matches(pattern, message.topic)) list.forEach(h => h(message));
+    if (message.kind === 'drop') drops.forEach(h => h(message));
+  });
+  window.desk = desk;
+  send({ kind: 'ready' });
+})();`
+
+/** Puts the bridge into a page of HTML, so a generated app needs nothing added by hand. */
+export function withAppBridge(html: string): string {
+  const script = `<script>${APP_BRIDGE_SCRIPT}</script>`
+  return /<head[^>]*>/i.test(html) ? html.replace(/<head[^>]*>/i, match => `${match}${script}`) : `${script}${html}`
+}

package/src/react/arrange.ts

@@ -0,0 +1,82 @@
+import type { Frame, WindowId } from '../core/types.js'
+
+/** The part of the stage windows are laid out in, and the gap between them. */
+export interface Area extends Frame {
+  readonly gap: number
+}
+
+export interface ArrangeLimits {
+  readonly minWidth: number
+  readonly minHeight: number
+}
+
+/**
+ * Where Arrange puts each window. The same windows always land in the same places:
+ * the focused window takes the first and largest place, the rest follow in the order
+ * they were opened. Nothing here looks at where windows are now, so a small drag
+ * never swaps two windows the next time.
+ *
+ *   1 fills the area · 2 side by side · 3 one tall on the left, two stacked on the right
+ *   4 a 2 × 2 grid · more a grid, while every cell stays usable
+ *
+ * When a grid cell would be too small to use, the focused window and the one used
+ * before it share the area and the rest cascade over the second half, so the focused
+ * window, which stays in front, covers none of them.
+ */
+export function arrangement(
+  ids: readonly WindowId[],
+  focused: WindowId | null,
+  previous: WindowId | null,
+  area: Area,
+  limits: ArrangeLimits,
+): Record<WindowId, Frame> {
+  const first = focused && ids.includes(focused) ? focused : ids[0]
+  if (first === undefined) return {}
+  const order = [first, ...ids.filter(id => id !== first)]
+  const { x, y, width, height, gap } = area
+  const half = (width - gap) / 2
+  const place = (frames: readonly Frame[]) => Object.fromEntries(order.map((id, i) => [id, frames[i] as Frame]))
+
+  if (order.length === 1) return place([{ x, y, width, height }])
+  if (order.length === 2) return place([{ x, y, width: half, height }, { x: x + half + gap, y, width: half, height }])
+  if (order.length === 3) {
+    const stacked = (height - gap) / 2
+    return place([
+      { x, y, width: half, height },
+      { x: x + half + gap, y, width: half, height: stacked },
+      { x: x + half + gap, y: y + stacked + gap, width: half, height: stacked },
+    ])
+  }
+
+  const columns = Math.ceil(Math.sqrt(order.length))
+  const rows = Math.ceil(order.length / columns)
+  const cellWidth = (width - gap * (columns - 1)) / columns
+  const cellHeight = (height - gap * (rows - 1)) / rows
+  if (cellWidth >= limits.minWidth && cellHeight >= limits.minHeight) {
+    return place(
+      order.map((_, i) => ({
+        x: x + (i % columns) * (cellWidth + gap),
+        y: y + Math.floor(i / columns) * (cellHeight + gap),
+        width: cellWidth,
+        height: cellHeight,
+      })),
+    )
+  }
+
+  // Too many to grid: the two most recent share the area, the rest cascade over the second half.
+  const second = previous && previous !== first && ids.includes(previous) ? previous : (order[1] as WindowId)
+  const rest = order.filter(id => id !== first && id !== second)
+  const step = 28
+  const floatWidth = Math.max(limits.minWidth, Math.min(720, half - step * 2))
+  const floatHeight = Math.max(limits.minHeight, Math.min(520, height - step * 2))
+  return {
+    [first]: { x, y, width: half, height },
+    [second]: { x: x + half + gap, y, width: half, height },
+    ...Object.fromEntries(
+      rest.map((id, i) => {
+        const n = i % 6
+        return [id, { x: x + half + gap + step + n * 32, y: y + step + n * step, width: floatWidth, height: floatHeight }]
+      }),
+    ),
+  }
+}

package/src/react/commands.ts

@@ -0,0 +1,60 @@
+import { useCallback, useContext, useEffect, useRef } from 'react'
+import type { RefObject } from 'react'
+import { addCommandHandler, canPerform, perform } from '../core/commands.js'
+import type { CommandHandler, CommandId } from '../core/commands.js'
+import { bindShortcuts } from '../core/shortcuts.js'
+import type { Keymap, ShortcutOptions } from '../core/shortcuts.js'
+import { useDesk, WindowContext } from './context.js'
+
+export interface UseCommandOptions {
+  /** Whether the handler can act right now. Read when the command arrives and when a menu opens. */
+  readonly enabled?: boolean | (() => boolean)
+  /**
+   * Where in the chain this responder sits.
+   * - `'window'` (the default inside a window): the window this component is rendered in.
+   * - `'app'` (the default outside windows): the top of the chain.
+   * - a ref: that element, e.g. an editor that answers Copy only while it has focus.
+   */
+  readonly at?: 'window' | 'app' | RefObject<Element | null>
+}
+
+/** Answers a command when it reaches this component's place in the responder chain. */
+export function useCommand<Args = unknown>(command: CommandId, handler: CommandHandler<Args>, options: UseCommandOptions = {}): void {
+  const window = useContext(WindowContext)
+  // Latest handler and enablement without re-registering on every render.
+  const latest = useRef({ handler, enabled: options.enabled })
+  latest.current = { handler, enabled: options.enabled }
+
+  const at = options.at ?? (window ? 'window' : 'app')
+  const ref = typeof at === 'object' ? at : at === 'window' ? window?.element : null
+
+  useEffect(() => {
+    const target: EventTarget | null | undefined = at === 'app' ? document : ref?.current
+    if (!target) return
+    return addCommandHandler<Args>(target, command, args => latest.current.handler(args), {
+      enabled: () => {
+        const enabled = latest.current.enabled
+        return typeof enabled === 'function' ? enabled() : (enabled ?? true)
+      },
+    })
+  }, [command, at, ref])
+}
+
+/** Returns a function that sends a command along the chain, and reports whether anything handled it. */
+export function usePerform(): <Args = unknown>(command: CommandId, args?: Args) => boolean {
+  const desk = useDesk()
+  return useCallback((command, args) => perform(desk, command, args), [desk])
+}
+
+/** Returns a function that asks whether a command would be handled right now — what a menu calls as it opens. */
+export function useCanPerform(): (command: CommandId) => boolean {
+  const desk = useDesk()
+  return useCallback(command => canPerform(desk, command), [desk])
+}
+
+/** Performs commands from keyboard shortcuts while mounted. Pass a stable keymap. */
+export function useShortcuts(keymap: Keymap, options: ShortcutOptions = {}): void {
+  const desk = useDesk()
+  const { target, apple } = options
+  useEffect(() => bindShortcuts(desk, keymap, { ...(target ? { target } : {}), ...(apple === undefined ? {} : { apple }) }), [desk, keymap, target, apple])
+}