@liberation-data/desk 0.1.0 → 0.3.0

package/dist/react/infoTip.d.ts

@@ -0,0 +1,11 @@
+import type { ReactNode } from 'react';
+export interface InfoTipProps {
+    /** What it explains, e.g. "About these logs" — the button's name and the popover's. */
+    readonly label: string;
+    readonly children: ReactNode;
+    readonly placement?: 'below' | 'above';
+    readonly align?: 'start' | 'end';
+    readonly className?: string;
+}
+export declare function InfoTip({ label, children, placement, align, className }: InfoTipProps): import("react").JSX.Element;
+//# sourceMappingURL=infoTip.d.ts.map

package/dist/react/infoTip.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"infoTip.d.ts","sourceRoot":"","sources":["../../src/react/infoTip.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAYtC,MAAM,WAAW,YAAY;IAC3B,uFAAuF;IACvF,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,QAAQ,EAAE,SAAS,CAAA;IAC5B,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,GAAG,OAAO,CAAA;IACtC,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,GAAG,KAAK,CAAA;IAChC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAC5B;AAED,wBAAgB,OAAO,CAAC,EAAE,KAAK,EAAE,QAAQ,EAAE,SAAmB,EAAE,KAAe,EAAE,SAAS,EAAE,EAAE,YAAY,+BAyBzG"}

package/dist/react/infoTip.js

@@ -0,0 +1,8 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useState } from 'react';
+import { Popover } from './overlays.js';
+export function InfoTip({ label, children, placement = 'below', align = 'start', className }) {
+    const [open, setOpen] = useState(false);
+    return (_jsx(Popover, { open: open, onOpenChange: setOpen, label: label, placement: placement, align: align, trigger: props => (_jsx("button", { ...props, ref: props.ref, type: "button", className: ['desk-infotip', className].filter(Boolean).join(' '), "aria-label": label, "data-open": open || undefined, children: _jsx("span", { "aria-hidden": "true", children: "i" }) })), children: _jsx("div", { className: "desk-infotip-body", children: children }) }));
+}
+//# sourceMappingURL=infoTip.js.map

package/dist/react/infoTip.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"infoTip.js","sourceRoot":"","sources":["../../src/react/infoTip.tsx"],"names":[],"mappings":";AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAA;AAEhC,OAAO,EAAE,OAAO,EAAE,MAAM,eAAe,CAAA;AAoBvC,MAAM,UAAU,OAAO,CAAC,EAAE,KAAK,EAAE,QAAQ,EAAE,SAAS,GAAG,OAAO,EAAE,KAAK,GAAG,OAAO,EAAE,SAAS,EAAgB;IACxG,MAAM,CAAC,IAAI,EAAE,OAAO,CAAC,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAA;IACvC,OAAO,CACL,KAAC,OAAO,IACN,IAAI,EAAE,IAAI,EACV,YAAY,EAAE,OAAO,EACrB,KAAK,EAAE,KAAK,EACZ,SAAS,EAAE,SAAS,EACpB,KAAK,EAAE,KAAK,EACZ,OAAO,EAAE,KAAK,CAAC,EAAE,CAAC,CAChB,oBACM,KAAK,EACT,GAAG,EAAE,KAAK,CAAC,GAAG,EACd,IAAI,EAAC,QAAQ,EACb,SAAS,EAAE,CAAC,cAAc,EAAE,SAAS,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,gBACpD,KAAK,eACN,IAAI,IAAI,SAAS,YAE5B,8BAAkB,MAAM,kBAAS,GAC1B,CACV,YAED,cAAK,SAAS,EAAC,mBAAmB,YAAE,QAAQ,GAAO,GAC3C,CACX,CAAA;AACH,CAAC"}

package/dist/react/pane.d.ts

@@ -0,0 +1,28 @@
+import type { Ref, UIEvent, ReactNode } from 'react';
+export interface ToolbarProps {
+    /** Controls, in reading order. Anything given `className="desk-grow"` takes the spare room. */
+    readonly children: ReactNode;
+    /** Pushed to the trailing end: what acts on everything here, or the state of it. */
+    readonly trailing?: ReactNode;
+    /** Names the row for assistive technology when it holds more than one thing: "Log controls". */
+    readonly label?: string;
+    readonly className?: string;
+}
+/** One aligned row of controls. Every item sits on the same centre line, whatever its height. */
+export declare function Toolbar({ children, trailing, label, className }: ToolbarProps): import("react").JSX.Element;
+export interface PaneProps {
+    /** Stays put at the top: a Toolbar, usually. */
+    readonly header?: ReactNode;
+    /** Stays put at the bottom: a count, a status line, the buttons of a form. */
+    readonly footer?: ReactNode;
+    /** Fills what is left and scrolls, on its own. */
+    readonly children: ReactNode;
+    /** The scrolling part is the thing being read, so it can be named and reached by the keyboard. */
+    readonly label?: string;
+    /** The scrolling element itself: for reading where it sits, or sending it to the bottom. */
+    readonly bodyRef?: Ref<HTMLDivElement>;
+    readonly onScroll?: (event: UIEvent<HTMLDivElement>) => void;
+    readonly className?: string;
+}
+export declare function Pane({ header, footer, children, label, bodyRef, onScroll, className }: PaneProps): import("react").JSX.Element;
+//# sourceMappingURL=pane.d.ts.map

package/dist/react/pane.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pane.d.ts","sourceRoot":"","sources":["../../src/react/pane.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,GAAG,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAWpD,MAAM,WAAW,YAAY;IAC3B,+FAA+F;IAC/F,QAAQ,CAAC,QAAQ,EAAE,SAAS,CAAA;IAC5B,oFAAoF;IACpF,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,CAAA;IAC7B,gGAAgG;IAChG,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAC5B;AAED,iGAAiG;AACjG,wBAAgB,OAAO,CAAC,EAAE,QAAQ,EAAE,QAAQ,EAAE,KAAK,EAAE,SAAS,EAAE,EAAE,YAAY,+BAU7E;AAED,MAAM,WAAW,SAAS;IACxB,gDAAgD;IAChD,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,CAAA;IAC3B,8EAA8E;IAC9E,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,CAAA;IAC3B,kDAAkD;IAClD,QAAQ,CAAC,QAAQ,EAAE,SAAS,CAAA;IAC5B,kGAAkG;IAClG,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;IACvB,4FAA4F;IAC5F,QAAQ,CAAC,OAAO,CAAC,EAAE,GAAG,CAAC,cAAc,CAAC,CAAA;IACtC,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,CAAC,cAAc,CAAC,KAAK,IAAI,CAAA;IAC5D,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAC5B;AAED,wBAAgB,IAAI,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,EAAE,SAAS,+BAehG"}

package/dist/react/pane.js

@@ -0,0 +1,9 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/** One aligned row of controls. Every item sits on the same centre line, whatever its height. */
+export function Toolbar({ children, trailing, label, className }) {
+    return (_jsxs("div", { ...(label ? { role: 'group', 'aria-label': label } : {}), className: ['desk-toolbar', className].filter(Boolean).join(' '), children: [children, trailing != null && _jsx("div", { className: "desk-toolbar-trailing", children: trailing })] }));
+}
+export function Pane({ header, footer, children, label, bodyRef, onScroll, className }) {
+    return (_jsxs("div", { className: ['desk-pane', className].filter(Boolean).join(' '), children: [header != null && _jsx("div", { className: "desk-pane-header", children: header }), _jsx("div", { ref: bodyRef, className: "desk-pane-body", onScroll: onScroll, ...(label ? { role: 'region', 'aria-label': label, tabIndex: 0 } : {}), children: children }), footer != null && _jsx("div", { className: "desk-pane-footer", children: footer })] }));
+}
+//# sourceMappingURL=pane.js.map

package/dist/react/pane.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pane.js","sourceRoot":"","sources":["../../src/react/pane.tsx"],"names":[],"mappings":";AAqBA,iGAAiG;AACjG,MAAM,UAAU,OAAO,CAAC,EAAE,QAAQ,EAAE,QAAQ,EAAE,KAAK,EAAE,SAAS,EAAgB;IAC5E,OAAO,CACL,kBACM,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,YAAY,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EACzD,SAAS,EAAE,CAAC,cAAc,EAAE,SAAS,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,aAE/D,QAAQ,EACR,QAAQ,IAAI,IAAI,IAAI,cAAK,SAAS,EAAC,uBAAuB,YAAE,QAAQ,GAAO,IACxE,CACP,CAAA;AACH,CAAC;AAiBD,MAAM,UAAU,IAAI,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAa;IAC/F,OAAO,CACL,eAAK,SAAS,EAAE,CAAC,WAAW,EAAE,SAAS,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,aAC/D,MAAM,IAAI,IAAI,IAAI,cAAK,SAAS,EAAC,kBAAkB,YAAE,MAAM,GAAO,EACnE,cACE,GAAG,EAAE,OAAO,EACZ,SAAS,EAAC,gBAAgB,EAC1B,QAAQ,EAAE,QAAQ,KACd,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,YAAY,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,YAEtE,QAAQ,GACL,EACL,MAAM,IAAI,IAAI,IAAI,cAAK,SAAS,EAAC,kBAAkB,YAAE,MAAM,GAAO,IAC/D,CACP,CAAA;AACH,CAAC"}

package/llms.txt

@@ -46,7 +46,12 @@ Rules that are easy to get wrong:
 
 ```ts
 createDesk(options?: DeskOptions): Desk
-interface DeskOptions { cascade?: Partial<CascadeOptions>; stage?: () => Size; initial?: DeskState }
+interface DeskOptions { cascade?: Partial<CascadeOptions>; stage?: () => Size; initial?: DeskState; layouts?: LayoutStore }
+// layouts: remembers each window type's last mode/frame (saved by float/fill/zoom, not placeAll or open frames);
+// open() without mode/frame restores it, fitted to the stage (fills if too small); more instances step +x,+y.
+localLayoutStore(key): LayoutStore   // localStorage 'desk.layouts.<key>'
+interface LayoutStore { load(type): SavedLayout | undefined; save(type, layout: SavedLayout): void }
+fitFrame(frame, stage, min?): Frame | null; stepFrom(frame, open: Frame[], stage, step, margin): Frame
 
 interface Desk {
   getState(): DeskState
@@ -177,6 +182,7 @@ useWindowId(): string | null                        // inside a window's content
 <Desktop
   renderWindow={(id) => ReactNode}                  // memoised: chrome re-renders, content does not
   title={(id) => ReactNode}
+  note?={(id) => ReactNode}                         // quiet text in the title bar: what this window is looking at
   actions?={(id) => ReactNode}                      // window-wide controls in the title bar
   loading?={(id) => ReactNode}                      // inside a window while its code loads
   failed?={(id, error, reload) => ReactNode}        // inside a window that could not open
@@ -196,17 +202,32 @@ Every window has its own Suspense and error boundary: one window loading or thro
 the menu bar or the dock. A failure is logged with `console.error` and shows Reload, which remounts the
 window; `lazyWindow` retries its import on reload, unlike `React.lazy`, which caches a failed import.
 
+### Inside a window
+
+```tsx
+<Pane label?={string} header?={ReactNode} footer?={ReactNode} bodyRef?={Ref} onScroll?={fn}>{scrolling content}</Pane>
+<Toolbar label?={string} trailing?={ReactNode}>{controls}</Toolbar>   // className="desk-grow" takes spare room
+<InfoTip label={string} placement?={'below'|'above'} align?={'start'|'end'}>{explanation}</InfoTip>
+```
+
+A pane fills its window and scrolls only its middle, so the window never scrolls and the toolbar stays put.
+A named pane is a focusable region, so it scrolls from the keyboard. InfoTip is an (i) popover for
+explanation only — never a warning, which belongs in front of people.
+
 ### Dock
 
 ```tsx
-<Dock entries={DockEntry[]} label?="Dock" placement?={'overlay' | 'inline'} />
-dockItem({ id, label, icon, window?, description?, badge?, onSelect?, disabled? })
+<Dock entries={DockEntry[]} label?="Dock" placement?={'overlay' | 'inline'}
+  pins?={{ accepts, onPin: (drag, before: id | null) => void, onMove?: (id, before: id | null) => void }} />
+dockItem({ id, label, icon, window?, description?, badge?, onSelect?, disabled?, contextMenu?: () => MenuItem[], movable? })
 dockStack({ id, label, items: DockItem[], icon? })
 dockSeparator(id)
 ```
 
 An item opens `window ?? id` and shows a dot while that window is open, accent when it is key. A stack fans
 out above the dock. One tab stop; arrow keys along it; Escape folds a stack away.
+Pins: the app stores kept items and passes them back as entries. A drop on the dock keeps at the end; on a
+`movable` item, in front of it. Movable items drag along the dock (type DOCK_ITEM, payload id).
 
 ### Menu bar
 
@@ -218,6 +239,15 @@ menuCommand(label, command, { shortcut?, checked?, detail?, args? })
 menuAction(label, onSelect, { disabled?, shortcut?, checked?, detail? })
 menuSeparator(); menuHeader(label)
 windowMenuItems(state, focus, title): MenuItem[]
+
+const { target, menu, open } = useContextMenu({ label, items: () => MenuItem[], disabled? })
+// spread `target` (onContextMenu, onKeyDown) on the element; render `menu` anywhere (portal).
+// Right-click opens at the pointer; Menu key / Shift+F10 at the element. Commands run from that element.
+
+<IconView label items={{id, label, icon, subtitle?, badge?, disabled?}[]} onOpen={item => …}
+  openOn?="double"|"single" selected? onSelectionChange? contextMenu?={item => MenuItem[]}
+  drag?={{ type, payload: item => unknown }} empty? className? />
+// click selects, double-click / Return opens (single: click opens); arrows, Home/End, type-ahead. Needs a DeskProvider.
 ```
 
 Command items are enabled via `canPerform` as the menu opens, and menus bind their own shortcuts. Opening a
@@ -406,5 +436,5 @@ in the accessibility tree.
 - A `DeskProvider` already carries an event bus; `BusProvider` is only for supplying or sharing one.
 - `renderWindow` must be stable (module scope or `useCallback`) for the memoisation to hold.
 - `parse`/`syncWithLocation` warn once when no `isKnown` is given: unknown ids from a URL are then trusted.
-- `npm run size` enforces a gzipped budget: core 10 KiB, react 46 KiB, css 10 KiB.
+- `npm run size` enforces a gzipped budget: core 11 KiB, react 46 KiB, css 10 KiB.
 - The package is ESM only, with `"sideEffects": ["**/*.css"]`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@liberation-data/desk",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "A desktop for the web, for React: windows, a dock, menus and commands, controls, tours and setup assistants.",
   "license": "Apache-2.0",
   "author": "Jasper Blues",

package/src/core/desk.ts

@@ -8,6 +8,7 @@ import type {
   Size,
   WindowId,
 } from './types.js'
+import { fitFrame, stepFrom } from './layouts.js'
 
 export interface Desk {
   getState(): DeskState
@@ -106,6 +107,7 @@ export function createDesk(options: DeskOptions = {}): Desk {
   let stage = options.stage ?? (() => DEFAULT_STAGE)
   let state = normalise(options.initial ?? EMPTY)
   const listeners = new Set<(state: DeskState) => void>()
+  const layouts = options.layouts
 
   const commit = (next: DeskState) => {
     if (next === state) return
@@ -142,6 +144,7 @@ export function createDesk(options: DeskOptions = {}): Desk {
     if (window.mode === 'floating' && !frame) return
     const next = frame ?? fits(remembered.get(id)) ?? nextFrame(state)
     if (frame) remembered.set(id, frame)
+    layouts?.save(windowType(id), { mode: 'floating', frame: next })
     commit(toFront(replace(state, { id, mode: 'floating', frame: next }), id))
   }
 
@@ -149,6 +152,7 @@ export function createDesk(options: DeskOptions = {}): Desk {
     const window = find(id)
     if (!window || window.mode === 'filled') return
     remembered.set(id, window.frame)
+    layouts?.save(windowType(id), { mode: 'filled' })
     commit(toFront(replace(state, { id, mode: 'filled' }), id))
   }
 
@@ -167,8 +171,19 @@ export function createDesk(options: DeskOptions = {}): Desk {
         commit(toFront(state, id))
         return
       }
-      const mode = opts.mode ?? (opts.frame ? 'floating' : 'filled')
-      const window: DeskWindow = mode === 'filled' ? { id, mode } : { id, mode, frame: opts.frame ?? nextFrame(state) }
+      const saved = opts.mode || opts.frame ? undefined : layouts?.load(windowType(id))
+      const kept = saved?.mode === 'floating' ? fitFrame(saved.frame, stage()) : null
+      const mode = opts.mode ?? (opts.frame || kept ? 'floating' : 'filled')
+      const frame = () => {
+        if (opts.frame) return opts.frame
+        if (!kept) return nextFrame(state)
+        const siblings = state.stack.flatMap(other => {
+          const w = find(other)
+          return w?.mode === 'floating' && windowType(w.id) === windowType(id) ? [w.frame] : []
+        })
+        return stepFrom(kept, siblings, stage(), cascade.step, cascade.margin)
+      }
+      const window: DeskWindow = mode === 'filled' ? { id, mode } : { id, mode, frame: frame() }
       commit({ windows: [...state.windows, window], stack: [...state.stack, id] })
     },
 

package/src/core/index.ts

@@ -29,6 +29,8 @@ export { bindShortcuts, formatShortcut, isApplePlatform, isInstalledApp, matches
 export type { Keymap, Shortcut, ShortcutOptions } from './shortcuts.js'
 export { parse, serialize, syncWithLocation } from './location.js'
 export { isTitleCase, titleCase } from './titles.js'
+export { fitFrame, localLayoutStore, stepFrom } from './layouts.js'
+export type { LayoutStore, SavedLayout } from './layouts.js'
 export type { LocationEnv, LocationOptions } from './location.js'
 export type {
   CascadeOptions,

package/src/core/layouts.ts

@@ -0,0 +1,88 @@
+import type { Frame, Size } from './types.js'
+
+/*
+ * Windows that come back the way they were left. Close a window you had made small and put in a
+ * corner, open it tomorrow, and it is small and in the corner again; one you zoomed to fill the desk
+ * fills it again.
+ *
+ * What is remembered is per kind of window, not per id: `query#2` opens where `query` was last left.
+ * A remembered frame is a promise about a screen that may have changed, so it is fitted to the
+ * current one: moved in until it is on the desk, made smaller if the desk is now smaller, and given
+ * up for filling if it would be too small to use. A second window of a kind already open steps down
+ * and to the right of it, as a cascade does, rather than opening exactly on top and hiding it.
+ */
+
+export type SavedLayout = { readonly mode: 'filled' } | { readonly mode: 'floating'; readonly frame: Frame }
+
+/** Where layouts are kept. Synchronous: a window opens now, not after a round trip. */
+export interface LayoutStore {
+  load(type: string): SavedLayout | undefined
+  save(type: string, layout: SavedLayout): void
+}
+
+const MIN: Size = { width: 240, height: 160 }
+
+/** Keeps layouts in this browser, under `desk.layouts.<key>`. */
+export function localLayoutStore(key: string): LayoutStore {
+  const name = `desk.layouts.${key}`
+  const read = (): Record<string, SavedLayout> => {
+    try {
+      const raw = globalThis.localStorage?.getItem(name)
+      const parsed: unknown = raw ? JSON.parse(raw) : {}
+      return parsed && typeof parsed === 'object' ? (parsed as Record<string, SavedLayout>) : {}
+    } catch {
+      return {}
+    }
+  }
+  return {
+    load: type => valid(read()[type]),
+    save(type, layout) {
+      try {
+        globalThis.localStorage?.setItem(name, JSON.stringify({ ...read(), [type]: layout }))
+      } catch {
+        // Private windows and full storage: windows still open, just not where they were.
+      }
+    },
+  }
+}
+
+const finite = (...values: unknown[]) => values.every(v => typeof v === 'number' && Number.isFinite(v))
+
+/** Storage is outside the program: anything that is not a layout is treated as none. */
+function valid(layout: unknown): SavedLayout | undefined {
+  const l = layout as SavedLayout | undefined
+  if (l?.mode === 'filled') return l
+  if (l?.mode === 'floating' && l.frame && finite(l.frame.x, l.frame.y, l.frame.width, l.frame.height)) return l
+  return undefined
+}
+
+/** A remembered frame on today's desk: on screen, no bigger than the desk, or null if too small to use. */
+export function fitFrame(frame: Frame, stage: Size, min: Size = MIN): Frame | null {
+  const width = Math.min(frame.width, stage.width)
+  const height = Math.min(frame.height, stage.height)
+  if (width < min.width || height < min.height) return null
+  return {
+    x: Math.max(0, Math.min(frame.x, stage.width - width)),
+    y: Math.max(0, Math.min(frame.y, stage.height - height)),
+    width,
+    height,
+  }
+}
+
+/**
+ * Where another window of a kind goes when some are already free on the desk: a step down and right
+ * of the one in front, back to the top-left when that would run off the desk, and never exactly on
+ * top of one already there.
+ */
+export function stepFrom(frame: Frame, open: readonly Frame[], stage: Size, step: { x: number; y: number }, margin: number): Frame {
+  const front = open.at(-1)
+  if (!front) return frame
+  const taken = (f: Frame) => open.some(o => o.x === f.x && o.y === f.y)
+  let next = { ...frame, x: front.x + step.x, y: front.y + step.y }
+  for (let tries = 0; tries <= open.length; tries++) {
+    if (next.x + next.width > stage.width || next.y + next.height > stage.height) next = { ...next, x: margin, y: margin }
+    if (!taken(next)) return next
+    next = { ...next, x: next.x + step.x, y: next.y + step.y }
+  }
+  return next
+}

package/src/core/types.ts

@@ -1,3 +1,5 @@
+import type { LayoutStore } from './layouts.js'
+
 export type WindowId = string
 
 export interface Frame {
@@ -40,6 +42,8 @@ export interface DeskOptions {
   /** Reports the stage's size, so floating windows open inside it. */
   readonly stage?: () => Size
   readonly initial?: DeskState
+  /** Remembers how each kind of window was left, and opens it that way again. */
+  readonly layouts?: LayoutStore
 }
 
 export interface OpenOptions {

package/src/desk.css

@@ -216,6 +216,23 @@
   color: var(--desk-muted);
 }
 
+.desk-window-note {
+  margin: 0 0 0 auto;
+  min-width: 0;
+  /* The title is what the window IS; the note is what it is looking at. In a narrow window the note
+     gives up its room first, and is cut before the title is. */
+  flex: 0 999 auto;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  font-size: 11.5px;
+  color: var(--desk-muted);
+}
+
+.desk-window-note + .desk-window-actions {
+  margin-left: var(--desk-space-1);
+}
+
 .desk-window-actions {
   margin-left: auto;
   display: flex;
@@ -372,7 +389,8 @@
   transition: transform .18s var(--desk-ease), margin .18s var(--desk-ease);
 }
 
-.desk-dock-item:disabled {
+.desk-dock-item:disabled,
+.desk-dock-item[aria-disabled="true"] {
   opacity: .45;
   cursor: not-allowed;
 }
@@ -658,6 +676,13 @@
   height: 15px;
 }
 
+/* A context menu is the same menu, opened where the pointer is rather than under a title. */
+.desk-context-menu {
+  position: fixed;
+  z-index: 1300;
+  outline: none;
+}
+
 .desk-menubar-slot[data-align="end"] .desk-menu {
   left: auto;
   right: 0;
@@ -2548,3 +2573,229 @@
   border: 0;
   background: var(--desk-surface);
 }
+
+/* Icon view: a Finder's icons, in rows that follow the window's width. */
+.desk-icon-view {
+  list-style: none;
+  margin: 0;
+  padding: 12px;
+  display: grid;
+  grid-template-columns: repeat(auto-fill, minmax(104px, 1fr));
+  align-content: start;
+  gap: 8px;
+}
+
+.desk-icon-cell {
+  display: grid;
+  justify-items: center;
+  align-content: start;
+  gap: 4px;
+  padding: 10px 6px;
+  border-radius: 10px;
+  text-align: center;
+  cursor: default;
+  user-select: none;
+  outline: none;
+}
+
+.desk-icon-cell[aria-disabled="true"] {
+  opacity: .45;
+}
+
+.desk-icon-cell:focus-visible {
+  box-shadow: 0 0 0 2px var(--desk-accent);
+}
+
+.desk-icon-glyph {
+  position: relative;
+  display: grid;
+  place-items: center;
+  width: 56px;
+  height: 56px;
+  border-radius: 14px;
+  border: 1px solid var(--desk-rule);
+  background: var(--desk-dock-icon);
+  color: var(--desk-ink);
+}
+
+.desk-icon-glyph > svg,
+.desk-icon-glyph > img {
+  width: 55%;
+  height: 55%;
+  object-fit: contain;
+}
+
+.desk-icon-badge {
+  position: absolute;
+  top: -5px;
+  right: -5px;
+  min-width: 18px;
+  padding: 0 5px;
+  border-radius: 9px;
+  background: var(--desk-accent);
+  color: #fff;
+  font-size: 11px;
+  line-height: 18px;
+}
+
+.desk-icon-label {
+  max-width: 100%;
+  padding: 1px 6px;
+  border-radius: 5px;
+  font-size: 12.5px;
+  line-height: 1.3;
+  overflow-wrap: anywhere;
+  display: -webkit-box;
+  -webkit-line-clamp: 2;
+  -webkit-box-orient: vertical;
+  overflow: hidden;
+}
+
+.desk-icon-subtitle {
+  max-width: 100%;
+  font-size: 11px;
+  color: var(--desk-muted);
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.desk-icon-cell[aria-selected="true"] .desk-icon-glyph {
+  background: color-mix(in srgb, var(--desk-accent) 16%, transparent);
+}
+
+.desk-icon-cell[aria-selected="true"] .desk-icon-label {
+  background: var(--desk-accent);
+  color: #fff;
+}
+
+.desk-icon-view-empty {
+  display: grid;
+  place-items: center;
+  padding: 32px 16px;
+  color: var(--desk-muted);
+  text-align: center;
+}
+
+.desk-icon-drag {
+  display: grid;
+  place-items: center;
+  width: 40px;
+  height: 40px;
+}
+
+/* Something carried to the dock: the dock lights up, and a kept item shows where it would go in front. */
+.desk-dock-item[data-desk-drop][data-ready] {
+  outline: none;
+  background: var(--desk-dock-icon);
+}
+
+.desk-dock-item[data-desk-drop][data-over] {
+  box-shadow: -6px 0 0 -2px var(--desk-accent);
+}
+
+/* ── The inside of a window: controls that stay, content that scrolls ── */
+
+.desk-pane {
+  display: flex;
+  flex-direction: column;
+  height: 100%;
+  min-height: 0;
+}
+
+.desk-pane-header,
+.desk-pane-footer {
+  flex: none;
+}
+
+/* The only part that scrolls, so the toolbar never leaves with the content. */
+.desk-pane-body {
+  flex: 1;
+  min-height: 0;
+  overflow: auto;
+}
+
+.desk-pane-body:focus-visible {
+  outline: 2px solid var(--desk-accent);
+  outline-offset: -2px;
+}
+
+/* A window whose whole content is a pane does not scroll itself: the pane's middle does. */
+.desk-body:has(> .desk-pane) {
+  overflow: hidden;
+}
+
+.desk-toolbar {
+  display: flex;
+  align-items: center;
+  flex-wrap: wrap;
+  gap: var(--desk-space-2);
+  /* One centre line for everything in the row, whatever each control's own height is. */
+  min-height: calc(var(--desk-control-height) + var(--desk-space-2) * 2);
+  padding: var(--desk-space-2) var(--desk-space-3);
+  border-bottom: 1px solid var(--desk-rule);
+}
+
+.desk-toolbar > *,
+.desk-toolbar-trailing > * {
+  flex: none;
+}
+
+.desk-toolbar .desk-grow {
+  flex: 1 1 140px;
+  min-width: 0;
+}
+
+.desk-toolbar-trailing {
+  margin-left: auto;
+  display: flex;
+  align-items: center;
+  gap: var(--desk-space-2);
+}
+
+/* ── An (i): what a view would explain if asked ── */
+
+.desk-infotip {
+  flex: none;
+  display: inline-grid;
+  place-items: center;
+  width: 18px;
+  height: 18px;
+  padding: 0;
+  border: 1px solid var(--desk-rule);
+  border-radius: 50%;
+  background: none;
+  color: var(--desk-muted);
+  font-family: var(--desk-font);
+  font-size: 11px;
+  font-style: italic;
+  font-weight: 700;
+  line-height: 1;
+  cursor: pointer;
+}
+
+.desk-infotip:hover,
+.desk-infotip[data-open] {
+  border-color: var(--desk-accent);
+  color: var(--desk-accent);
+}
+
+.desk-infotip:focus-visible {
+  outline: 2px solid var(--desk-accent);
+  outline-offset: 2px;
+}
+
+.desk-infotip-body {
+  max-width: 34ch;
+  font-size: 12.5px;
+  line-height: 1.45;
+  color: var(--desk-muted);
+}
+
+.desk-infotip-body > :first-child {
+  margin-top: 0;
+}
+
+.desk-infotip-body > :last-child {
+  margin-bottom: 0;
+}

package/src/react/Desktop.tsx

@@ -13,6 +13,12 @@ export type DeskLayout = 'desktop' | 'fullscreen'
 export interface DesktopProps {
   readonly renderWindow: (id: WindowId) => ReactNode
   readonly title: (id: WindowId) => ReactNode
+  /**
+   * A quiet line on the trailing side of the title bar, saying what this window is looking at: the
+   * request behind it, the file it is editing, how many rows it found. Text, not a control — it
+   * gives way to the actions and disappears before the title does when the window is narrow.
+   */
+  readonly note?: (id: WindowId) => ReactNode
   /** Window-wide controls on the trailing side of the title bar. One or two; more belongs in a toolbar. */
   readonly actions?: (id: WindowId) => ReactNode
   /** Shown when no window is open. */
@@ -70,7 +76,7 @@ const halfFrame = (stage: HTMLElement, side: 'start' | 'end'): Frame => {
   return { x: side === 'start' ? area.x : area.x + width + area.gap, y: area.y, width, height: area.height }
 }
 
-export function Desktop({ renderWindow, title, actions, empty, loading, failed, layout = 'auto', className }: DesktopProps) {
+export function Desktop({ renderWindow, title, note, actions, empty, loading, failed, layout = 'auto', className }: DesktopProps) {
   const desk = useDesk()
   const state = useDeskState()
   const stage = useRef<HTMLDivElement>(null)
@@ -150,6 +156,7 @@ export function Desktop({ renderWindow, title, actions, empty, loading, failed,
           // One window at a time: the rest stay mounted, keeping their state, and simply wait offstage.
           hidden={mode === 'fullscreen' && window.id !== focused}
           title={title(window.id)}
+          note={note?.(window.id)}
           actions={actions?.(window.id)}
         >
           {/* Memoised on the id and the render function: moving or focusing a window
@@ -184,6 +191,7 @@ interface WindowViewProps {
   readonly depth: number
   readonly focused: boolean
   readonly title: ReactNode
+  readonly note?: ReactNode
   readonly actions?: ReactNode
   readonly children: ReactNode
 }
@@ -210,7 +218,7 @@ function reshape(gesture: Gesture, origin: Frame, dx: number, dy: number): Frame
   }
 }
 
-function WindowView({ window, layout, hidden, depth, focused, title, actions, children }: WindowViewProps) {
+function WindowView({ window, layout, hidden, depth, focused, title, note, actions, children }: WindowViewProps) {
   const desk = useDesk()
   // While dragging, the frame lives here and commits once on release, so a drag
   // re-renders one window rather than notifying every subscriber per pixel.
@@ -331,6 +339,7 @@ function WindowView({ window, layout, hidden, depth, focused, title, actions, ch
           <h2 id={titleId} className="desk-title">
             {title}
           </h2>
+          {note != null && note !== false && <p className="desk-window-note">{note}</p>}
           {actions && <div className="desk-window-actions">{actions}</div>}
         </header>
         <div className="desk-body">{children}</div>