react-x11 2.51.1 → 2.53.0

package/src/cli/templates/AGENTS.template.md

@@ -0,0 +1,195 @@
+<!-- BEGIN:react-x11-agent-rules -->
+
+# This is react-x11, not react-dom
+
+This app is React drawing native desktop windows with react-x11
+{{version}}. There is no DOM, no browser and no CSS. What you know about
+React carries over: components, hooks, state, context, Suspense, error
+boundaries. What you know about the DOM does not. Before writing UI, read the
+docs installed with the package. They match the version this app runs and
+are newer than your training data.
+
+## Where to look
+
+**Docs**, installed with the package (paths from this file's directory):
+`node_modules/react-x11/docs/`
+
+| page                                                | for                                                                          |
+| --------------------------------------------------- | ---------------------------------------------------------------------------- |
+| `react-features.md`                                 | **read first**: where a DOM habit breaks (refs, measuring, portals, effects) |
+| `elements.md`                                       | the host elements and their props                                            |
+| `styling.md`                                        | the `style` prop: layout, paint, `:hover` blocks, theme tokens               |
+| `components.md`                                     | `Button`, `Select`, `Dialog`, `MenuBar`, `Tabs`, `Table`, `SplitPane`, …     |
+| `events.md`                                         | events, focus, keys, shortcuts                                               |
+| `appearance.md`                                     | light and dark, the accent, reduced motion                                   |
+| `globalmenu.md`                                     | where `MenuBar` goes on each platform                                        |
+| `testing.md`                                        | `react-x11/test`: render headless, query, click, type, write a PNG           |
+| `accessibility.md`                                  | roles, names, what a screen reader hears                                     |
+| `filedialog.md`, `notifications.md`, `clipboard.md` | the desktop around the app                                                   |
+| `drag-and-drop.md`, `system.md`, `packaging.md`     | more of it, and shipping the app                                             |
+| `ecosystem/*.md`                                    | state, forms, routing, data fetching, i18n with libraries you know           |
+| `README.md`                                         | the map of every page                                                        |
+
+The same pages are online at
+`https://sidorares.github.io/react-x11/docs/reference/<page>`.
+
+**Types**: `node_modules/react-x11/src/index.d.ts` and
+`node_modules/react-x11/src/types/*.d.ts` hold every element, style key, event
+and widget with its props. Grep them for any prop you are not sure of.
+
+**Examples** are not in the package. These are pinned to this version:
+`https://github.com/sidorares/react-x11/tree/v{{version}}/examples`, raw files
+at `https://raw.githubusercontent.com/sidorares/react-x11/v{{version}}/examples/<file>`.
+`finder.jsx` and `settings.jsx` (sidebar and content), `tasks.jsx` (list and
+input), `widgets.jsx` (every control), `dashboard.jsx`, `menu.jsx`,
+`theming.jsx`. Read the closest one or two before writing a screen.
+
+## Rules you will trip on
+
+Most of these throw with a message that names the fix. Read the message
+before guessing.
+
+- **Host elements are lowercase and few**: `<window>`, `<popup>`, `<box>`,
+  `<text>`, `<textinput>`, `<textarea>`, `<image>`, `<svg>`, `<canvas>`,
+  `<video>`, `<glarea>`. No `<div>`, `<span>`, `<button>`, `<input>`.
+- **Everything drawn is inside a `<window>`.** `<window>` takes its geometry as
+  props, not style: `title`, `width`, `height`, `minWidth`, `minHeight`,
+  `resizable`.
+- **Raw strings and numbers go only inside `<text>`.** `<box>hi</box>` throws.
+  A `<text>` inside a `<text>` is a styled span.
+- **Style lives in `style`**, an object or an array (`[s.row, on && s.on]`,
+  falsy entries skipped). `<box padding={8}>` throws. There is no
+  `className`, no CSS file, no Tailwind, no styled-components.
+- **State blocks paint only.** `':hover'`, `':active'`, `':focus'`,
+  `':focus-visible'`, `':focus-within'` and `':disabled'` inside `style` may set
+  colours, `background`, `opacity`, `outline`, `borderRadius`. Not padding,
+  size or `border` (its width is layout).
+- **Flexbox is React Native's direction with CSS's shrink**: `flexDirection`
+  defaults to `'column'`, and children of a column stretch to its full width.
+  A `Button` in a column becomes a slab: give it `alignSelf: 'flex-start'`, or
+  put buttons in a `flexDirection: 'row'` box. `display: 'grid'` and `gap`
+  work as in CSS.
+- **A pane smaller than its content scrolls** only with
+  `overflow: 'scroll'` (or `'hidden'`, or `minHeight: 0`). For 1000+ rows use
+  `Table`, which is virtualized.
+- **Colours are theme tokens**: `'$background'`, `'$surface'`, `'$text'`,
+  `'$textMuted'`, `'$border'`, `'$accent'`, `'$accentText'`, `'$accentHover'`,
+  `'$accentActive'`, `'$surfaceHover'`, `'$surfaceActive'`,
+  `'$hoverBackground'`/`'$hoverText'` (a selected row), `'$danger'`,
+  `'$success'`, `'$warning'`, `'$info'`, `'$link'`. They follow the desktop's
+  light or dark scheme and its accent. A hard-coded grey is wrong in one of
+  the two. `useTheme()` gives the resolved values, for `<canvas>` drawing.
+- **Events**: `onClick`, `onMouseDown`/`Up`/`Move`/`Enter`/`Leave`, `onWheel`,
+  `onContextMenu`, and `onKeyDown`/`onKeyUp` on an element that is
+  `focusable`. `Button` takes **`onPress`**. Every input's `onChange` gets an
+  event: read `ev.value`. Keys: compare `ev.keysym` with `XK_RETURN`,
+  `XK_ESCAPE`, `XK_DOWN`, … from `'react-x11/keysyms'`.
+- **Shortcuts**: `[['Control', 'S']]` is ⌘S on macOS and Ctrl+S elsewhere. Put
+  them on `MenuBar` items (`shortcut`) or use `useAccelerator(chord, fn)`.
+  Never bind Copy, Paste, Cut, Select All or Undo in a menu while a text field
+  can have focus: the fields handle those already, and both would run.
+- **Web UI libraries do not work** (MUI, Radix, shadcn, recharts, react-dom
+  anything). Plain JavaScript libraries do: zustand, zod, date-fns, `fetch`.
+- **No `localStorage`.** Persist with
+  `createSettings({ appId, defaults })` from `react-x11`
+  (`const [value, setValue] = settings.use('key')`) or with `node:fs`.
+- **Paths are absolute**: `new URL('./data.json', import.meta.url)`. On macOS
+  the app's JavaScript runs on a worker thread, where `process.chdir()` throws.
+
+## Bigger components
+
+Charts, a data table, a tree, tabs, markdown, a code editor, a rich text
+editor, a calendar and date picker, a colour picker, a timeline, a reorderable
+list, flow graphs, maps, formulas and a 3D scene are in
+`@react-x11/components`. Install it, then import from its subpaths, not the
+package root: `@react-x11/components/charts`, `/table`, `/tree`, `/tabs`,
+`/markdown`, `/code-editor`, `/rich-text-editor`, `/calendar`,
+`/color-picker`, `/timeline`, `/reorder`, `/flow`, `/maps`, `/formula`,
+`/three`. Its `README.md` and `docs/components/<name>.md` are in
+`node_modules/@react-x11/components/`, and each subpath has its own `.d.ts`.
+
+## Commands
+
+- `{{run}} start` runs the app once.
+- `{{run}} dev` runs it with hot reload. It keeps running and is meant for a
+  person at the keyboard; do not wait for it to exit.
+- `npx react-x11 help` lists every `REACT_X11_*` variable.
+  `REACT_X11_DEBUG_LAYOUT=1` outlines every laid-out box, for a layout that
+  does not do what you expect.
+
+## Check your work: run it and look at it
+
+Passing tests are not the finish line. A clipped label, a stretched button or
+a colour that is wrong in dark mode passes every test and is obvious in a
+picture.
+
+1. Render the app headless and write a picture of each scheme.
+   `react-x11/test` runs a real X server inside the test process: no window
+   opens, nothing to install but `pngjs` (`npm install -D pngjs`).
+
+   ```jsx
+   // test/App.test.jsx — run with: node --import tsx --test test/*.test.jsx
+   import React from 'react';
+   import { mkdirSync } from 'node:fs';
+   import { afterEach, test } from 'node:test';
+   import {
+     cleanup,
+     renderX11,
+     screen,
+     toPNG,
+     userEvent,
+   } from 'react-x11/test';
+   import App from '../src/App.jsx';
+
+   afterEach(cleanup);
+   // a font file, so text measures the same every run; Linux finds one itself
+   const fonts = {
+     darwin: { 'sans-serif': '/System/Library/Fonts/Supplemental/Arial.ttf' },
+     win32: { 'sans-serif': 'C:\\Windows\\Fonts\\segoeui.ttf' },
+   }[process.platform];
+
+   for (const colorScheme of ['light', 'dark']) {
+     test(`renders in ${colorScheme}`, async () => {
+       const { ctx, window: win } = await renderX11(<App />, {
+         wrap: false, // App renders its own <window>
+         fonts,
+         colorScheme,
+       });
+       // drive it the way a person would, then assert on what shows
+       // await userEvent.click(screen.getByRole('button', { name: 'Add' }));
+       // screen.getByText('1 item');
+       mkdirSync('shots', { recursive: true });
+       const { width, height } = win; // the size the app's window came out
+       await toPNG(ctx, `shots/${colorScheme}.png`, { width, height });
+     });
+   }
+   ```
+
+   Queries are Testing Library's: `getByText`, `getByRole(role, { name })`,
+   `getByPlaceholder`, `findBy*`, `queryBy*`, and `userEvent.click`, `type`,
+   `key`, `hover`. A `getBy*` that matches twice throws: add
+   `{ exact: true }` or narrow with `within(node)`.
+
+2. **Open both PNGs and look at them.** Fix what looks wrong: clipped or
+   overlapping text, a cramped or empty window, rows that do not line up, a
+   colour that ignores dark mode, a control with no hover or pressed state.
+   Render again. Two or three passes is normal.
+3. The headless render is the X11 backend: native control bezels, the macOS
+   menu bar and SF Symbols do not appear in it, and bold may come out regular.
+   Judge layout, spacing, colour and text from it. Then run `{{run}} start`
+   for a few seconds to confirm the real app starts with nothing in its
+   output.
+
+## Design
+
+Read [DESIGN.md](DESIGN.md) before writing UI. It says how this app should
+look and how to get each piece out of react-x11.
+
+<!-- END:react-x11-agent-rules -->
+
+The block above comes from react-x11 {{version}}. Keep notes about this app
+below it, so the block can be replaced with a newer version's.
+
+## This app
+
+<!-- What it is, who it is for, and the decisions an agent should keep to. -->

package/src/cli/templates/DESIGN.template.md

@@ -0,0 +1,269 @@
+# Design
+
+How this app should look and behave. People and coding agents both read it
+before changing the UI.
+
+The first section is this app's brief: fill it in. The rest is the house
+style react-x11 {{version}} starts every app with: the conventions of the
+desktops the app runs on, and how to get each one out of react-x11. Change
+any of it that this app does differently. Then the agent follows your rules
+and not the defaults.
+
+## This app
+
+- **What it is**: _one line: what someone opens it to do._
+- **Who uses it, and how often**: _all day, or once a week?_
+- **Platforms**: macOS, Windows and Linux, each looking like itself. _Or
+  name the one that matters most._
+- **Layout**: _sidebar and content, three panes, content and inspector, or
+  one compact window (see "Window anatomy")._
+- **Density**: regular. _Compact for a data-heavy tool._
+- **Colour**: the desktop's own, with the user's accent. No brand palette.
+  _If there is a brand colour, name it and the one or two places it may
+  appear._
+- **Voice**: short and plain. Buttons are verbs ("Add Account", not "OK").
+
+## Look like the desktop it runs on
+
+A desktop app is quiet, dense, aligned and driven from the keyboard. It is
+light or dark because the desktop is. People notice in a second when an app is
+a web page in a window.
+
+react-x11 gives you most of this already:
+
+- The theme tokens are the desktop's palette, its light or dark scheme and its
+  accent.
+- The widgets wear AppKit's own bezels on macOS.
+- `MenuBar` goes where the platform keeps menus.
+
+Keep those defaults, and spend the effort on layout, copy and behaviour.
+
+## Window anatomy
+
+- **One main window** with a clear structure. Pick one of the standard
+  layouts:
+  - **Sidebar and content** (Mail, Files, Explorer): a list of places or
+    collections on the left, 200–260 px wide, then the content. This is the
+    default for anything with collections of things.
+  - **Sidebar, list and detail**: three columns, with the middle list
+    260–320 px wide.
+  - **Content and inspector**: a 240–300 px panel on the right with the
+    properties of the selection.
+  - **One compact window** for a single-purpose utility: a timer, a
+    converter. This needs no sidebar.
+- **A toolbar** under the title bar: a 40–48 px row with the few most-used
+  actions as icon buttons, and a search field at the trailing end.
+- **Dialogs for short tasks**: a modal dialog for a three-field "New item…"
+  form, and a popup anchored to what it edits for a small editor. Never take
+  over the whole window for a short form.
+- **Size**: 900×600 by default for a sidebar app, 720×480 for a simple one,
+  about 360×480 for a utility. **Always set a minimum size** (about 600×400
+  for a sidebar app), so the layout never collapses.
+
+## Menus and shortcuts
+
+People try a shortcut before they look for a button. Write shortcuts with
+`Control`: it is ⌘ on macOS and Ctrl elsewhere. The standard menus, in order:
+
+- **File**: New (Control+N), Open… (Control+O), Close Window (Control+W), Save
+  (Control+S), Save As… (Control+Shift+S), Export…, Print… (Control+P)
+- **Edit**: Undo, Redo, Cut, Copy, Paste, Delete, Select All, Find…
+  (Control+F)
+- **View**: Show or Hide Sidebar, view modes (Control+1, Control+2, …), Zoom
+  In and Zoom Out
+- _the app's own_: its own verbs (Item, Format, Playback, …), with shortcuts
+  for the frequent ones
+- **Help**: _App name_ Help
+
+And the rules around them:
+
+- **Where the menu shows**: on macOS `MenuBar` becomes the system menu bar.
+  On Linux it goes to the desktop's panel where one hosts menus (KDE
+  Plasma), and is drawn in the window everywhere else, Windows included.
+- **Settings and Quit**: on macOS, react-x11 adds the app menu itself, with
+  Quit (⌘Q) only. Put "Settings…" (Control+,) at the end of your first menu.
+  On Windows and Linux, put Settings… in Edit or File, and Quit (Control+Q) at
+  the end of File.
+- An item that opens a window or asks for more ends in "…". An item that does
+  not apply is disabled, not hidden. Every frequent action is in a menu, even
+  when it also has a button.
+- The text fields already handle Copy, Paste, Cut, Select All, Undo and Redo,
+  with a right-click menu of their own. Do not put those shortcuts on menu
+  items while a field can have focus: both would run.
+
+## Type
+
+- **Base size**: 13 on macOS, which is AppKit's body size, and 14 elsewhere,
+  which is react-x11's default. Set it once at the root (see the recipes
+  below). Never set `fontFamily`: the default is the system's UI face.
+- **Scale**: base for body, controls and lists; base −2 in `'$textMuted'` for
+  secondary text and captions; base +2 and +4, semibold (600), for titles; base
+  +9 for a rare large title. Use at most three sizes on one screen.
+  Hierarchy comes from weight and the muted colour, not from size jumps.
+- A number that changes while you watch (a timer, a price, a count) uses
+  `fontVariantNumeric: 'tabular-nums'`.
+- A one-line label that can overflow: `textWrap: 'nowrap'` and
+  `textOverflow: 'ellipsis'`.
+
+## Colour
+
+- **Semantic tokens only**: `'$background'` for the window, `'$surface'` for
+  lists, fields and raised areas, `'$text'`, `'$textMuted'`, `'$border'` for
+  separators, `'$accent'`, `'$hoverBackground'` and `'$hoverText'` for a
+  selected row, and `'$danger'`, `'$success'`, `'$warning'`, `'$info'` for
+  status. A hard-coded grey is wrong in light or in dark.
+- **The accent is the user's**, not yours. Use it for the primary button, the
+  selection, focus and toggles.
+- **Colour highlights; it is not the ground.** Most of a window is neutral.
+  Big saturated panels are a web look.
+- **Light and dark both look intended.** Shadows almost vanish in dark, so
+  separation comes from a slightly lighter surface instead.
+
+## Spacing and sizes
+
+- A 4 and 8 px grid: 20 px window margins (16 compact), 8 px between related
+  controls, 16–20 px between groups, 6–12 px of padding inside a row.
+- Let the widgets size themselves: they follow the platform. Rows you draw
+  yourself: 28 px on macOS, 32–36 px elsewhere.
+- Corners match the widgets'. `useTheme().radius` is their radius.
+- Separators are 1 px lines in `'$border'`, not borders around every box.
+- Align everything to a few vertical lines. Form labels are either
+  right-aligned against a column of fields or stacked above them in a narrow
+  pane.
+
+## Interaction
+
+- **Every input gets an answer on the event that started it**: a hover tint,
+  a distinct pressed state on mouse down, then the action on release.
+- **Keyboard**: Tab moves focus, Space and Return activate, arrows move
+  through lists and grids, Return confirms a dialog, Escape cancels it,
+  Control+F focuses search, Delete removes the selection. The focus ring
+  shows on keyboard focus.
+- **Selection**: one click selects (a filled row in `'$hoverBackground'`),
+  and a double click or Return opens.
+- **Right click** shows a context menu with the item's verbs.
+- **Dialog buttons** are named for what they do ("Delete 3 Items", not
+  "Yes"). On macOS and GNOME, Cancel comes first and the action is last, at
+  the trailing edge. On Windows and KDE the action comes first, then Cancel.
+- **Destructive actions** can be undone, or are confirmed in a dialog whose
+  button says what it deletes.
+- **Empty states**: a short centred line in `'$textMuted'` ("No Notes"), an
+  optional one-line explanation, and at most one button. Never a blank pane.
+- **Success is shown in place**, not in a "Saved!" dialog. Dialogs are for
+  decisions.
+
+## Icons
+
+- Icons label places and actions in sidebars and toolbars. They do not
+  decorate paragraphs. Never use emoji as UI icons.
+- Use the platform's own icons, which are monoline, sized like the text and
+  drawn in its colour: `<image src={{ symbol }} />` draws an SF Symbol on
+  macOS (`'folder'`) and an icon from the freedesktop theme on Linux
+  (`'folder-symbolic'`). A name the desktop lacks draws nothing, and Windows
+  has no icon theme to draw from. So an icon is never the only label, and an
+  app that needs icons everywhere ships its own.
+- Affordances (chevrons, check, close, plus, more) come from `<Icon name>`,
+  which is the same everywhere.
+
+## Motion and accessibility
+
+- Motion is subtle and fast: 120–200 ms for hover, selection and disclosure.
+  Nothing bounces, and nothing animates on a timer the user did not start.
+  With reduced motion on, cut or cross-fade instead.
+- Every control has a name a screen reader can say: an icon-only button needs
+  an `aria-label`. Text contrast is at least 4.5:1. Nothing is reachable by
+  mouse only. State is never shown by colour alone: add an icon or a word.
+
+## The same, in react-x11
+
+- **Window size and minimum**: `<window title="…" width={900} height={600}
+minWidth={600} minHeight={400}>`
+- **The app's name on macOS**: `createRoot({ cocoa: { appName: 'Notes' } })`:
+  what the menu bar and ⌘-Tab show. Without it they say "node".
+- **Base type size**: `<ThemeProvider value={{ fontSize: process.platform ===
+'darwin' ? 13 : 14 }}>` around the app.
+- **Menu bar**: `<MenuBar menus={[{ label: 'File', items: [...] }]} />` inside
+  the window. Item: `{ label, onSelect, shortcut: [['Control', 'N']], enabled,
+items }`, or `{ type: 'separator' }`. A check item: `toggleType:
+'checkmark', toggleState: 0 or 1`.
+- **A shortcut with no menu item**: `useAccelerator([['Control', 'K']],
+handler)`
+- **Sidebar**: a `<box>` with `width: 220`, `backgroundColor: '$surface'`,
+  `borderEndWidth: 1`, `borderColor: '$border'`, `padding: 8`, `gap: 2`. Rows:
+  `flexDirection: 'row'`, `alignItems: 'center'`, `gap: 8`, `paddingInline:
+8`, `borderRadius: 6`, `':hover': { backgroundColor: '$surfaceHover' }`, and
+  when selected `backgroundColor: '$hoverBackground'` with text in
+  `'$hoverText'`. Section headers: base −2, `fontWeight: 600`, `'$textMuted'`.
+  See `examples/finder.jsx` and `settings.jsx`.
+- **Resizable split**: `<SplitPane direction="row" defaultSize={240}
+min={180}>` with two children.
+- **Toolbar**: a row under the title bar: `flexDirection: 'row'`, `alignItems:
+'center'`, `gap: 8`, `height: 44`, `paddingInline: 12`, `borderBottomWidth:
+1`, `borderColor: '$border'`. Icon buttons in it, then `<textinput
+placeholder="Search" />` last.
+- **Buttons**: `<Button onPress={…}>`. `primary` is the default action, one
+  per view. `variant="outline"` for a secondary one, `variant="ghost"
+size="small"` for toolbar and inline icon buttons. Never size a `Button`
+  yourself: `style` sizes its slot.
+- **Other controls**: `Checkbox`, `Switch`, `RadioGroup` and `Radio`,
+  `Slider`, `Select` (`options`, `value`), `ProgressBar`, `Tooltip label="…"`,
+  `<textinput placeholder>`, `<textarea>`. Every `onChange(ev)` gives
+  `ev.value`.
+- **Tabs**: `<Tabs items={[{ id, label, content }]} />`
+- **Modal dialog**: `<Dialog open title="…" onClose={…}
+actions={<>…buttons…</>}>`: a real window that keeps focus. Escape and the
+  close button call `onClose`. `autoFocus` on its first field.
+- **Context menu and popover**: `<ContextMenu items={[…]}>` around the node it
+  belongs to. `<popup anchor={{ to: ref, placement: 'bottom' }}>` for a custom
+  popover.
+- **Lists, tables, trees**: `Table` (`columns: [{ id, label, width, value,
+align }]`, `rows`, `onActivate`) for sortable, virtualized data. `Tree` from
+  `@react-x11/components/tree`. Draw short lists yourself.
+- **Hover and press on your own box**: `cursor: 'pointer'`, `':hover': {
+backgroundColor: '$surfaceHover' }`, `':active': { backgroundColor:
+'$surfaceActive' }`, `transition: 120`.
+- **Focus and keys**: `focusable` (and `tabIndex`) on a custom control, and
+  the focus ring comes with it. `onKeyDown={(ev) => ev.keysym === XK_DOWN &&
+…}` with keysyms from `react-x11/keysyms`. `role` and `aria-label` so a
+  screen reader can name it.
+- **Light, dark, reduced motion**: tokens follow the desktop.
+  `useSystemAppearance()` gives `{ colorScheme, accent, reducedMotion, … }`,
+  and `transition: reducedMotion ? 0 : 150` respects it.
+- **A tinted alert**: `backgroundColor: tint(theme.danger, 0.12)` with `tint`
+  from `react-x11/style` and `theme` from `useTheme()`, and `'$danger'` for
+  its text.
+- **Files, notifications, settings**: `useFileDialog()` gives `openFile()` and
+  `saveFile()`, which resolve to paths or `null`. `useNotifier()` gives
+  `notify({ summary, body })`: check `available` first and never depend on it.
+  `createSettings({ appId, defaults })` remembers state.
+- **Charts**: `@react-x11/components/charts`, at least 200 px tall, with
+  series in `'$accent'`, `'$info'`, `'$success'`, and a tooltip.
+
+## What makes it look like a website (avoid)
+
+- **A hero header**: a big title and tagline at the top of the window. The
+  window's title is in the title bar, and content starts with content.
+- **Card soup**: every item in a rounded, shadowed, padded card on a grey
+  page. Use lists with separators and selection. Keep cards for things that
+  are visual: a gallery, a dashboard tile.
+- **A centred landing page**: content in a narrow column with empty sides.
+  Fill the window and align to the leading edge.
+- **Phone and web patterns**: hamburger menus, bottom tab bars, floating
+  action buttons. Use the menu bar, a sidebar, a toolbar.
+- **Wide buttons**: the column-stretch trap, and buttons styled as links.
+  Buttons are compact and sit in a row at the trailing edge or in a toolbar.
+- **Gradients, glows, neon, emoji icons, big shadows**, and everything
+  rounded to 16 px or more.
+- **A palette of your own that ignores dark mode**, or replaces the user's
+  accent.
+- **Sample data that looks fake**: "Lorem ipsum", "Item 1, Item 2". Seed 10–30
+  plausible, varied records. It is the cheapest polish there is.
+- **Buttons that do nothing.** Cut them, or disable them and say why.
+
+## Before calling it done
+
+Look at a picture of every screen, in light and in dark. Is there one
+obvious primary area? Do the leading edges line up, and are the row heights
+consistent? Is there one accent-coloured thing per region, and is nothing
+clipped? If it looks like part of the operating system rather than a
+landing page, it is done.

package/src/cocoa/app.js

@@ -5,7 +5,7 @@
 // that stands in for the X socket.
 //
 // Two run loops. By default Node's loop is master and a timer pumps AppKit
-// (docs/macos.md §"Input and the run loop", option 1): input waits for the
+// (design/macos.md §"Input and the run loop", option 1): input waits for the
 // pump, and AppKit's modal loops (live resize, menu tracking, a drag) stall
 // JS timers — but not the delegate callbacks, which is why live resize
 // still relayouts: the resize event flushes the frame synchronously on its
@@ -13,7 +13,7 @@
 // Under the launcher (`node --import react-x11/cocoa-main`, src/cocoa/
 // main.js) the app runs on a worker instead, AppKit keeps the main thread
 // in a real `[NSApp run]`, and this object is fed by the bridge's batches
-// (`_routeBatch`) with no pump at all (docs/macos.md §"JS on a worker").
+// (`_routeBatch`) with no pump at all (design/macos.md §"JS on a worker").
 import { isMainThread } from 'node:worker_threads';
 
 import { cssColorStraight } from 'ntk/color';
@@ -64,11 +64,11 @@ const PUMP_INTERVAL_MS = 8;
 // The edge moves when the delegate returns, so the budget is how long a
 // slow frame may hold the drag back. 50 covers what a large tree costs —
 // the Cocoa `resize` cell measures 28ms a tick at 3,662 nodes
-// (docs/macos.md) — with room, where the bridge's own test met every tick
+// (design/macos.md) — with room, where the bridge's own test met every tick
 // in 3.1ms against 3ms of layout. Past three 60Hz frames an edge that waits
 // reads as the drag stuttering, so a tree slower than that lets the edge
 // go first and its frame land after (Flutter's Windows embedder waits up
-// to 100, docs/windows.md §"Resize"). `createRoot({ cocoa: { resizeWait } })`
+// to 100, design/windows.md §"Resize: where the threads meet"). `createRoot({ cocoa: { resizeWait } })`
 // sets it; 0 is no handshake at all.
 const RESIZE_WAIT_MS = 50;
 // What `createRoot({ cocoa: { paneStretch } })` and
@@ -272,7 +272,7 @@ export class CocoaApp {
     }
 
     // 'surface' (the measured default) or 'layers' — the retained CALayer
-    // presenter, opt-in while docs/macos.md's measure-first gate is open.
+    // presenter, opt-in while design/macos.md's measure-first gate is open.
     this._presenterMode =
       options.cocoa?.presenter ??
       process.env.REACT_X11_COCOA_PRESENTER ??
@@ -391,7 +391,7 @@ export class CocoaApp {
 
     // the global-menu exports, newest active: the macOS menu bar is one per
     // app, so the most recent MenuBar owns it (per-focused-window switching
-    // is the follow-up — docs/macos.md §Menus)
+    // is the follow-up — design/macos.md §Menus)
     this._globalMenus = [];
     this._activeGlobalMenu = null;
 

package/src/cocoa/bezels.js

@@ -1,5 +1,5 @@
 // Native control bezels — AppKit's own pixels for the core controls, cached
-// as surfaces the ordinary 2d paint path can blit (docs/macos.md §Native
+// as surfaces the ordinary 2d paint path can blit (design/macos.md §Native
 // controls). The mechanism is offscreen NSCell/NSControl rendering, the
 // WebKit/Gecko form-control technique: interaction, focus and keyboard stay
 // the shared component implementation, and only the *bezel* — the pixels of

package/src/cocoa/fonts.js

@@ -1,6 +1,6 @@
 // The Cocoa text engine: CoreText behind the same `app.fonts` contract ntk's
 // FontManager answers on the X11 backend. The renderer touches exactly this
-// surface (docs/macos.md §"Text: the engine contract"):
+// surface (design/macos.md §"Text: the engine contract"):
 //
 //   fonts.layout(spans, base, { maxWidth, align, lineHeight, maxLines,
 //                               overflow, direction })

package/src/cocoa/globalmenu.js

@@ -1,4 +1,4 @@
-// The macOS menu bar as a global-menu export (docs/macos.md §Menus).
+// The macOS menu bar as a global-menu export (design/macos.md §Menus).
 //
 // The Linux global menu was built for exactly this moment: the item
 // vocabulary is data, and the pure snapshot/IdAllocator machinery in

package/src/cocoa/keymap.js

@@ -23,7 +23,7 @@
 //
 // There is no input method behind this. The bridge's view swallows
 // `keyDown:` without `interpretKeyEvents:` and is no `NSTextInputClient`
-// (docs/macos.md, "IME"), so these fields are all the text there is. Two
+// (design/macos.md, "IME"), so these fields are all the text there is. Two
 // consequences, both handled below:
 //
 // - **A dead key types nothing.** ⌥E on a US layout leaves `chars` empty, and

package/src/cocoa/panewindow.js

@@ -1,4 +1,4 @@
-// The pane process's "window" on the Cocoa backend — docs/frame.md's child
+// The pane process's "window" on the Cocoa backend — design/frame.md's child
 // half, with the X server replaced by shared memory.
 //
 // On X11 a pane renders into a real window of its own and the host embeds

package/src/cocoa/player.js

@@ -1,4 +1,4 @@
-// `<video src>` on macOS (docs/architecture/video.md §3.2, §9): a file or URL
+// `<video src>` on macOS (design/architecture/video.md §3.2, §9): a file or URL
 // played by AVFoundation through @windowkit/appkit's player verbs — the
 // platform's decoder, audio, seeking and HLS — with the picture on the
 // player's own AVPlayerLayer.

package/src/cocoa/presenter.js

@@ -1,4 +1,4 @@
-// The retained layer presenter — Tier L of docs/macos.md: one CALayer per
+// The retained layer presenter — Tier L of design/macos.md: one CALayer per
 // drawn node, React commits landing as property sets inside a single
 // disabled-actions CATransaction per frame, the WindowServer compositing.
 //
@@ -350,7 +350,7 @@ export function stylePaintsPlain(node, style = node.style ?? {}) {
 /**
  * Style property → the key path on a PropBox's own layer, for the
  * animations the presenter takes off the frame clock and hands to the
- * render server (docs/architecture/animation.md §4.2). Only what the layer
+ * render server (design/architecture/animation.md §4.2). Only what the layer
  * expresses as a property of itself qualifies: a colour on `<text>` is a
  * re-raster per frame, a layout property moves the siblings, and both stay
  * on the JS loop. `scaled` values go out in points, as `_syncPropBox`

package/src/cocoa/promotion.js

@@ -36,7 +36,7 @@
 // overlapped, hidden, clipped, faded or non-plain returns to the bitmap in
 // the frame that finds it, the animation handed back to the clock — and a
 // loop the clock runs is offered again once the scene would take it
-// (`wouldTake`), where it is in its cycle. docs/macos.md §"Layer
+// (`wouldTake`), where it is in its cycle. design/macos.md §"Layer
 // promotion" is the account.
 import { now } from '../nodes/animation.js';
 import { BoxNode } from '../nodes/box.js';

package/src/cocoa/relaunch.js

@@ -1,4 +1,4 @@
-// Threaded mode by default (docs/macos.md §"JS on a worker"). On macOS the
+// Threaded mode by default (design/macos.md §"JS on a worker"). On macOS the
 // process main thread is AppKit's — the only thread it lets own a window —
 // and while the app's JS runs there, every menu, drag, live resize and
 // modal panel stops it. So the first import of react-x11 on the main thread

package/src/cocoa/threaded.js

@@ -1,4 +1,4 @@
-// Threaded mode's worker half (docs/macos.md §"JS on a worker: a UI thread
+// Threaded mode's worker half (design/macos.md §"JS on a worker: a UI thread
 // of the bridge's own"): with the launcher (src/cocoa/main.js) holding the
 // process main thread in the bridge's `runMain()`, the app's JS runs on a
 // `worker_threads` Worker, and this module is what that worker needs to

package/src/cocoa/video.js

@@ -1,4 +1,4 @@
-// A video's frames on a layer of their own (docs/architecture/video.md §7):
+// A video's frames on a layer of their own (design/architecture/video.md §7):
 // what the surface presenter's sprites (src/cocoa/sprites.js) do with a part
 // whose `contents` is a `VideoFrames` sink instead of a `paint`.
 //

package/src/cocoa/window.js

@@ -39,7 +39,7 @@ const FENCE_TIMEOUT_MS = 100;
 // (`_takeBack`). Three, a `CAMetalLayer`'s depth, is what an animation
 // mostly needs; an input answered between two of its frames puts two flips
 // inside one refresh, and four kept every write of a clicked 120Hz animation
-// off a held buffer (docs/macos.md, "Measured: the swapchain and the
+// off a held buffer (design/macos.md, "Measured: the swapchain and the
 // WindowServer's hold").
 const MAX_BUFFERS = 4;
 // Past this many rects, what a buffer missed is copied whole: a buffer left
@@ -235,14 +235,14 @@ export class CocoaWindow {
     // change.
     this.damageRectCap = 16;
 
-    // The retained layer presenter (docs/macos.md Tier L), behind
+    // The retained layer presenter (design/macos.md Tier L), behind
     // REACT_X11_COCOA_PRESENTER=layers while the surface path is the
     // measured default. Its hooks exist only in this mode, so the feature
     // detection in src/nodes/ keeps the surface path byte-identical; the
     // scroll blit is shadowed off because a layer frame has no backing
     // bitmap to blit. The last two are the animation seam: a transition or
     // a loop the presenter takes runs in the render server and schedules no
-    // frames here (docs/architecture/animation.md §4).
+    // frames here (design/architecture/animation.md §4).
     if (app._presenterMode === 'layers') {
       this._presenter = new CocoaLayerPresenter(this);
       this.presentFrame = (windowNode) => this._presenter.frame(windowNode);
@@ -659,7 +659,7 @@ export class CocoaWindow {
    * A new size retires the chain, released on the spot (`_releaseBacking`):
    * left to the handles' finalizers, a forty-tick drag of the two-buffer
    * chain this used to be held 800MB until a collection happened to run —
-   * the `rss +80MB` docs/macos.md measured. The layer keeps its own
+   * the `rss +80MB` design/macos.md measured. The layer keeps its own
    * reference to whichever IOSurface it is still showing, so the free is
    * safe while that frame is on glass. A new chain starts with the one
    * buffer its first frame paints: a live-resize tick paints its size once,