@dopame/acde-linux-x64 0.0.0-stage → 0.0.10

package/lib/acde/skills/acde/references/guide/tools.md

@@ -0,0 +1,291 @@
+# Debugging
+
+A set of commands connects to a running `acde dev` session and lets you look at pages, run code, take screenshots, and click buttons. After 0.0.9, `acde devtools` also opens the DevTools of Chrome or Edge on a page; see [DevTools](#devtools). Run them in another terminal:
+
+```sh
+acde webs
+```
+
+```text
+NAME           KIND     APP    WINDOW   TITLE
+desktop        desktop  -      0        My Desktop
+notes#1048576  app      notes  1048576  Notes
+```
+
+## Sessions
+
+These commands find an `acde dev` session in this order: `--session <pid>`; otherwise the session whose project directory contains the current directory; otherwise, outside any project, the only session, if there is just one (the command then names it on stderr: `acde: using acde dev <pid> (...), the only one running`); otherwise they fail and list all sessions. After 0.0.9, sessions that `acde test` started for its tests are left out of this choice (they are listed with `acde test` after what they run); only `--session <pid>` reaches them.
+
+## Commands
+
+| Command | What it does |
+| --- | --- |
+| `acde webs` | Lists the running pages (one per window) |
+| `acde eval <web> <code>` | Runs code in a page and prints the result as JSON; Promises are awaited. With `-` as the code, reads it from stdin |
+| `acde shot <web> [-o FILE]` | Screenshot of one window (PNG) |
+| `acde screen [-o FILE]` | Screenshot of the whole screen, all windows together |
+| `acde pointer <x> <y>` | Moves the pointer to a point on the screen, as a real move: hover effects and screen edge events (a desktop showing its Dock at an edge) follow. In a host window the screen is its content area |
+| `acde inspect [--window W] [--find TEXT] [--all] [--offscreen]` | Turns the screen into text: the window list and the element tree of the focused window (`--all`: every window that is not marked `[minimized]`, and elements hidden by `opacity: 0` or `visibility`) |
+| `acde query <selector> [--window W] [--ref REF] [--limit N]` | Finds elements by CSS selector, including ones `inspect` leaves out, and prints a ref for each |
+| `acde act <ref> <action> [arg]` | Clicks, types, presses keys, and more on a ref from `inspect` or `query` |
+| `acde console [--web W] [--level L] [--since S] [--follow]` | The pages' `console.*` output and uncaught errors |
+| `acde network [--web W] [--failed] [--since S] [--follow]` | The pages' fetch / XHR / WebSocket / EventSource requests and their image, stylesheet and font loads; the kind column says which |
+| `acde permissions` | Lists the camera and microphone prompts that wait and the decisions made; see [Camera and microphone](#camera-and-microphone) |
+| `acde allow` / `acde deny` `[<prompt id> \| <app> <capability>] [--all]` | Answers a waiting camera or microphone prompt |
+| `acde revoke <app> <capability>` | Takes back a decision |
+| `acde stop` | Ends the session; see [Stopping](dev.md#stopping) |
+| `acde devtools [web]` | Opens the DevTools of Chrome or Edge on a page; see [DevTools](#devtools) (after 0.0.9) |
+
+A **web** is one page: the desktop page, or the page in one app window (each window has one). `<web>` is a web name from `acde webs` (`notes#1048576`), an app id (that app's first window), or `desktop`.
+
+### eval
+
+```sh
+acde eval notes 'document.title'
+acde eval notes 'import("acde:fs").then(m => m.fs.roots())'
+echo 'localStorage.length' | acde eval notes -
+```
+
+On Windows, `acde` is `acde.cmd`, so what reaches the CLI is what cmd makes of the arguments. What a shell passes differs:
+
+- PowerShell (5.1 and 7) drops double quotes inside arguments it passes to a `.cmd`; write them as `\"` (the first line below).
+- cmd has no single-quoted strings: put the argument in double quotes and write the double quotes inside it as `\"` (the second line below).
+
+```powershell
+acde eval notes 'document.querySelector(\"#x\").textContent'
+```
+
+```bat
+acde eval notes "document.querySelector(\"#x\").textContent"
+```
+
+Code that has only single quotes inside it is written the same way in all three, and passing the code on stdin avoids the question (shown for PowerShell):
+
+```powershell
+acde eval notes "document.querySelector('#x').textContent"
+'document.querySelector("#x").textContent' | acde eval notes -
+```
+
+The same applies to any argument with double quotes, such as `act ... type`.
+
+### inspect and act
+
+`inspect` gives every element a **ref**, such as `w1.18` (element 18 in window `w1`); pass it to `act`.
+
+```sh
+$ acde inspect
+- window "Notes" [app=notes] [focused] [fullscreen] [w1]
+  - heading "Notes" [level=1] [w1.16]
+  - form [w1.6]
+    - text "Title" [w1.17]
+    - textbox "Title": "" [w1.18]
+    - text "Email" [w1.19]
+    - textbox "Email": "" [w1.20]
+    - button "Save" [w1.21]
+  - list "Saved notes" [w1.7]
+    - listitem [w1.22]
+      - text "Buy milk" [w1.22]
+  - text "1 note" [w1.8]
+  (1 more outside the visible area; scroll, or add offscreen)
+
+$ acde act w1.18 type "Weekly report"
+typed, the value is now "Weekly report"
+
+(windows unchanged)
+- window "Notes" [app=notes] [focused] [fullscreen] [w1]
+  ~ - textbox "Title": "Weekly report" [focused] [w1.18]
+  (1 more outside the visible area; scroll, or add offscreen)
+
+$ acde act w1.21 click
+clicked 55,202
+
+(windows unchanged)
+- window "Notes" [app=notes] [focused] [fullscreen] [w1]
+  ~ - textbox "Title": "" [w1.18]
+  ~ - button "Save" [focused] [w1.21]
+  + - listitem [w1.23]
+  + - text "Weekly report" [w1.23]
+  ~ - text "2 notes" [w1.8]
+  (1 more outside the visible area; scroll, or add offscreen)
+```
+
+Without `--find`, the text is always in this English format: one line per window, top first (`- window "Notes" [app=notes] [focused] [w1]`, the desktop is `- desktop`), and under a listed window its elements, indented two spaces per level, as `- role "name": "value" [states] [ref]` (the value only where the element has one). Notes in parentheses say what is left out or unchanged, such as `(empty)`, `(no changes)` and `(windows unchanged)`.
+
+`act` prints what it did on the first line (`clicked 55,202` is the point it clicked, in window coordinates), waits for the page to settle, and then prints the windows and the content of the window again. Where it has listed that window before, it prints only what changed since: `~` for a changed line, `+` for a new one, `-` for one that is gone; `(windows unchanged)` stands for an unchanged window list. So the output of `act` is usually all you need to read before the next step. An element that is scrolled out of view is scrolled into view first, so a ref from `inspect --offscreen` or `query` works wherever the element is on the page.
+
+`act` exits with code 0 when the action was done. When it was not, it prints one line on stderr, `acde: act <ref>: <reason>`, and exits with code 1. The reasons: `the element is not displayed` (it is `display: none` or hidden by `visibility`), `covered by another element: <div> (27)`, `cannot type into this element`, `there is no such element (any more); acde inspect --find TEXT gives the current refs` (the element is gone, see below), `w1 is minimized; act restore on it first` (a click or another pointer action on a minimized window or on an element in it).
+
+A ref stays the same as long as its element lives: moving it, changing its text or attributes, or reordering a list keeps it. When the page replaces the element with a new one (for example by setting `innerHTML`), the new element gets a new ref, and acting on the old one fails (`acde: act w1.23: there is no such element (any more); …`); take a new `inspect` then.
+
+After 0.0.9, an app run on its own shows its window menus on the title bar (see [Windows](window.md#menus)), and `inspect` lists them first: `menubar [w1.m]`, one `menuitem "File" [collapsed] [w1.m1]` per menu, and under the open one its items with their shortcuts, `menuitem "New": "ctrl+n" [w1.m1.1]` (a separator takes a number too). `acde act w1.m1 click` opens a menu, `acde act w1.m1.1 click` opens it if needed and chooses the item (`chose File › New`), and `acde act w1 key escape` closes it. A disabled item is not chosen (`acde: act w1.m1.4: w1.m1.4 (Print) is disabled`).
+
+By default the tree leaves out elements that can't be seen: `display: none`, `aria-hidden`, `inert`, `opacity: 0` and hidden `visibility`. `--all` lists every window that is not marked `[minimized]` in the window list and also keeps the elements hidden by `opacity: 0` (marked `transparent`; they can still be clicked) or by `visibility` (marked `invisible`; they can't); `display: none`, `aria-hidden` and `inert` are always left out.
+
+A window that is off the screen is marked `[minimized]` in the window list: one whose state is `minimized` (after `act w1 minimize`, the app's own `minimize()`, or the desktop's `windows.requestState(id, 'minimized')`), and one the desktop hid with `windows.hide(id)`. Its elements are not listed: `--all` and `--find` skip it, and `--window w1` prints `(empty)` and `(minimized; act restore on it to see its elements)` under its line. Pointer actions on it (`click`, `double`, `right`, `hover`, `scroll`, and `drag` from or onto it) are refused, and `act w1 restore` brings it back. In a desktop session:
+
+```sh
+$ acde act w1 minimize
+w1 is minimized (the windows changed)
+
+- window "Tools" [app=tools] [minimized] [w1]
+- desktop [focused] [fullscreen] [w0]
+  - navigation "Apps" [w0.6]
+    - button "Tools" [w0.10]
+
+$ acde act w1.10 click
+acde: act w1.10: w1 is minimized; act restore on it first
+
+$ acde act w1 restore
+w1 is in front (the windows changed)
+
+- window "Tools" [app=tools] [focused] [w1]
+  + - heading "Tools" [level=1] [w1.10]
+- desktop [fullscreen] [w0]
+```
+
+`--find TEXT` looks in every window that is not marked `[minimized]` (or in `--window W`) and prints only the elements whose name or value contains the text (case does not matter). Its output has a format of its own: a line `<window ref> <app id> "<title>":` for each window that has a match (`w0 desktop:` for the desktop), and under it one line per element. An element inside an ancestor that has a name is followed by `in` and the nearest such ancestor; one that has none is followed by nothing:
+
+```sh
+$ acde inspect --find milk
+w1 notes "Notes":
+- text "Buy milk" [w1.22]  in list "Saved notes" [w1.7]
+
+$ acde inspect --find save
+w1 notes "Notes":
+- button "Save" [w1.21]
+- list "Saved notes" [w1.7]
+```
+
+When nothing matches it says so on stderr (`acde: no element's name or value contains "milk"; elements scrolled out of view need --offscreen`) and exits with code 2. Elements scrolled out of view are found only with `--offscreen`; without it, a note under the tree says how many were left out (`(1 more outside the visible area; scroll, or add offscreen)`).
+
+Actions: `click` `double` `right` `hover` `scroll` `type` `settext` `select` `key` `drag` `focus`; a window ref (`w1`) also accepts `close` `minimize` `restore` `fill` `fullscreen`. `fill` fills the desktop's work area with the window and `fullscreen` covers the whole host window with it; `restore` sets either back to normal. Both refuse the desktop (`the desktop cannot be made filled`, `... fullscreen`) and a window that already fills the host window (`w1 already fills the host window`), and need an acdert from 0.0.9 on. `minimize` on a window that cannot be minimized changes nothing, says why and exits with code 1; in a session that runs a single app, on macOS and headless, that is the app's own window: `w1 cannot be minimized: it fills the host window, which only the host window's own controls minimize here`. The argument to `key` looks like `"ctrl+a backspace"`; the argument to `drag` is the target ref. When closing a window ends acdert (the app's window when `acde dev` runs one app), `acde dev` ends with it; `act w1 close` then says so and exits with code 0.
+
+#### Key names
+
+The argument to `key` (and `press()` in tests) is one or more chords separated by spaces; a chord is keys joined by `+`, pressed in order and released in reverse. Keys are physical keys on a US layout. Case does not matter, except that a single capital letter (`A`) adds `shift`:
+
+- modifiers: `ctrl` (`control`), `shift`, `alt`, `super` (`meta`, `win`)
+- letters `a` … `z`, digits `0` … `9`, `f1` … `f12`
+- `enter` (`return`), `escape` (`esc`), `tab`, `space`, `backspace`, `delete` (`del`), `insert`, `home`, `end`, `pageup`, `pagedown`, `up`, `down`, `left`, `right`, `menu`
+- printable characters as they are: `-` `=` `[` `]` `;` `'` `` ` `` `\` `,` `.` `/`, and the shifted ones `!` `@` `#` `$` `%` `^` `&` `*` `(` `)` `_` `+` `{` `}` `|` `:` `"` `<` `>` `?` `~`, which add `shift` themselves (`*` is `shift+8`). `+` alone, or last in a chord (`ctrl++`), is the `+` key
+- names for some characters: `plus` (`+`), `multiply`, `asterisk`, `star` (`*`), `minus` (`-`), `divide` (`/`), `period` (`.`), `comma` (`,`); these are the main keyboard keys, not the keypad
+- the keypad: `Numpad0` … `Numpad9`, `NumpadAdd`, `NumpadSubtract`, `NumpadMultiply`, `NumpadDivide`, `NumpadDecimal`, `NumpadEnter`
+- the DOM `KeyboardEvent.code` names of the other keys, e.g. `KeyA`, `Digit8`, `Minus`, `ArrowUp`, `CapsLock`, `ShiftRight`
+
+The whole argument is checked before anything is pressed: an unknown key fails with `unknown key: …` and presses nothing. The space character is `space` (spaces separate chords). To enter text, use `type` instead.
+
+### query
+
+`inspect` lists what a user can see and use. `query` finds elements by CSS selector whether they are shown or not, and gives each a ref, so it reaches what `inspect` leaves out: an element that is `display: none`, one that is scrolled out of view, and one that has no role, name or value of its own (a plain `<div>`; `inspect` lists what is inside it in its place).
+
+```sh
+$ acde query 'form input[type=email]'
+1 in w1:
+- textbox "Email": "" [w1.20] <input>
+
+$ acde query '[data-testid="menu"] li'
+2 in w1:
+- generic "Rename" [w1.25] <li> [hidden]
+- generic "Delete" [w1.26] <li> [hidden]
+
+$ acde query button
+4 in w1:
+- button "Save" [focused] [w1.21] <button>
+- button "Undo" [transparent] [w1.10] <button> [hidden]
+- button [invisible] [w1.24] <button> [hidden]
+- button "Load more" [w1.11] <button>
+
+$ acde query nav
+acde: nothing in w1 matches "nav"
+```
+
+Each line is the element's role, name, value, a heading's level, states and ref, exactly as `inspect` prints them (`- heading "Notes" [level=1] [w1.16] <h1>`), then its tag. `[hidden]` after the tag marks an element that is not visible: it has no size, or is `display: none`, hidden by `visibility`, or transparent, or its window is minimized. The `transparent` and `invisible` marks are the ones `inspect --all` gives: a transparent element still takes clicks, as it does for a user; for an `invisible` or `display: none` one, `act` answers `the element is not displayed` until the page shows it. An element whose role cannot be told is listed as `generic`; the tag says what it is.
+
+The refs work with `act`, like the ones from `inspect`: `acde act w1.20 type "me@example.com"`. `query` searches the focused window; `--window w2` picks another, `--ref w1.6` searches only under that element, and `--limit N` lists at most N elements (1 to 3000, default 600; the first line still counts them all). When nothing matches, it says so on stderr (`acde: nothing in w1 matches "nav"`; in 0.0.9 on stdout, without `acde: `) and the exit code is 2; otherwise it is 0.
+
+### Styles and layout
+
+To look at styles and boxes, ask the page with `eval` (after 0.0.9, also the Elements panel of [DevTools](#devtools)). `getComputedStyle` gives the values the page uses after the CSS cascade, and `getBoundingClientRect` gives an element's box in CSS pixels of the page:
+
+```sh
+acde eval notes "getComputedStyle(document.querySelector('h1')).color"
+acde eval notes "(({ display, fontSize, margin }) => ({ display, fontSize, margin }))(getComputedStyle(document.querySelector('.card')))"
+acde eval notes "(({ x, y, width, height }) => ({ x, y, width, height }))(document.querySelector('.card').getBoundingClientRect())"
+```
+
+Copy the properties you want into a plain object, as above, so the JSON result has them. The code has only single quotes inside, so it is written the same way in sh, PowerShell and cmd (see [eval](#eval)). To see whether something is drawn where you expect, take a screenshot with `acde shot`; to find an element that `inspect` leaves out (no size, `display: none`), use `acde query`.
+
+### console and network
+
+```sh
+acde console --level errors --follow
+acde network --failed
+```
+
+`--level` is `log`, `info`, `warn`, `error`, `debug`, or `errors` (`console.error` plus uncaught errors). `--follow` keeps printing new entries.
+
+When a `fetch` in the page rejects with `TypeError: Failed to fetch`, the line of that request in `acde network --failed` says why (a CORS rule, a name that does not resolve, a refused connection):
+
+```sh
+$ acde network --failed
+   1 GET    ERR https://nonexistent.invalid/  (fetch 158 ms; Failed to connect to host: Failed resolving hostname: failed to lookup address information: nodename nor servname provided, or not known) notes#1048576
+```
+
+Entries stay after a page reloads, so errors from before a change are still listed. The first column is the entry's number. `--since reload` lists only what came after `acde dev` last rebuilt and reloaded (everything, if it has not reloaded yet); `--since N` lists entry `N` and later. A reload the page does by itself (`location.reload()`) does not count.
+
+```sh
+acde console --level errors --since reload
+```
+
+The most recent 5000 entries of each kind are kept.
+
+## DevTools
+
+After 0.0.9, `acde devtools [web]` opens the DevTools of Chrome or Edge (or Chromium on Linux) on a page of the session: Elements, Console, Network, and Sources with breakpoints.
+
+```sh
+acde devtools            # the focused page
+acde devtools notes      # a web name, an app id, desktop, or a window title
+acde devtools services   # the desktop's services (or one service, by its name)
+```
+
+It prints the DevTools address on stdout, and on stderr `acde: opened DevTools for <page> in <browser>`. Asked again for a page whose DevTools are open, it brings them to the front instead (`acde: brought DevTools for <page> to the front in <browser>`). F12 in the host window of `acde dev` does the same for the page in that window; see [acde dev](dev.md#devtools).
+
+The browser runs with a profile of acde's own, not your everyday one. `ACDE_BROWSER` names another browser (a path to it). Without Chrome or Edge, or with `ACDE_BROWSER=none`, nothing opens: paste the printed address into the address bar of Chrome or Edge on this machine.
+
+Elements shows the element tree, the computed styles and the box model, read only. It does not list the CSS rules that matched an element (only its inline style); change styles from the page code or the Console.
+
+## Without a display
+
+On a machine without a display, such as a server over ssh, start the session with `acde dev --headless`. On Linux, `acde dev` without it stops at once when neither `WAYLAND_DISPLAY` nor `DISPLAY` is set and says to add `--headless`; see [acde dev](dev.md). Every command on this page works the same in a headless session:
+
+```sh
+acde dev --headless &
+acde inspect          # the windows and the focused window's elements, as text
+acde shot notes       # ./notes.png
+acde screen           # ./screen.png, every window together
+```
+
+A headless session has no picker dialogs: a folder, file or save picker the page opens fails unless it was answered beforehand, and the page sees it as cancelled. Answer it from a test with `chooseFolder`, `chooseFiles` or `chooseSaveFile` ([Testing](testing.md#network-file-pickers-clipboard)), from an agent with the MCP tools `choose_folder`, `choose_files` and `choose_save_file` ([MCP](mcp.md)), or (after 0.0.9) from the shell with `acde choose folder ~/Notes`, `acde choose open a.md b.md` or `acde choose save out.md` (`--cancel` to cancel). `acde drop <web> <file...>` (after 0.0.9) drops files onto a page, as a drag from the file manager would. The session output names the missing answer: `no folder chooser without a host window (ACDE_HEADLESS): answer it beforehand with the MCP tool choose_folder or acde.chooseFolder() in a test`. A headless session also has its own clipboard and no camera or microphone dialog (see below).
+
+## Camera and microphone
+
+A capability an app declares is granted without asking, except the camera and the microphone. In 0.0.9, an app that declares one is asked when it starts, and its window opens once the prompt is answered; after 0.0.9, the user is asked the first time a page asks for one (`getUserMedia`), and the call waits for the answer. In a session that runs a single app, the host window asks in a dialog on Windows, and after 0.0.9 also on macOS (a sheet with `Don't Allow` and `Allow`) and on Linux (a notification with the same two buttons, where the desktop's notification service shows buttons). Elsewhere, and in a headless session, there is no dialog, so answer from the command line:
+
+```sh
+$ acde permissions
+pending:
+  1  recorder  microphone  (request)
+decisions: none
+
+$ acde allow
+allowed recorder microphone (prompt 1)
+```
+
+Without arguments, `acde allow` and `acde deny` answer the only waiting prompt. When several wait, they answer none and list them; name one by its id (`acde allow 2`) or by app and capability (`acde allow recorder microphone`), or answer them all with `--all`.
+
+Decisions persist per app (in `$XDG_CONFIG_HOME/acde/permissions.json`), so the user is not asked again. Answering is the user's decision: when you run these commands for someone, allow only what they asked for or agreed to, and tell them what you allowed. `acde revoke <app> <capability>` removes a decision, so the app is asked again the next time it asks. A denied or revoked capability makes `getUserMedia` reject with `NotAllowedError`, as in a browser.
+
+## Errors
+
+When a command fails, it prints `acde: <reason>` and exits with code 1. If the session has already exited, it says `acde dev <pid> is gone`. `inspect --find` and `query` that find nothing are not failures; they exit with code 2.

package/lib/acde/skills/acde/references/guide/window.md

@@ -0,0 +1,167 @@
+# Windows
+
+Each app window is a separate web page with its own DOM and JS heap; one window crashing does not affect the others. All windows of the same app share storage such as `localStorage`, IndexedDB, and cookies.
+
+## Size and title bar
+
+- In a desktop, a new window's content area is the configured `size` (800 × 600 by default) and opens centered; next time it opens where it was last closed.
+- In an `acde dev` session that runs a single app (an app project without `--desktop`), the app **fills the host window**, and `size` sets how large that window opens: with `"size": [400, 300]` the host window's content area is 400 × 300. The title bar is drawn inside it, so the page is 400 × 268. Without `size` the host window takes most of the screen (90% of its width and 85% of its height, at most 1440 × 900).
+- `acde dev --headless` has no host window, and `size` is not applied: the screen is 1440 × 900 (1280 × 800 in `acde test`) and the app fills it, so the page is 1440 × 868. To see the app in a window of its own `size`, run it in a desktop: `acde dev --desktop ./my-desktop`, or `--desktop dopame` once that desktop is installed (see [acde dev](dev.md#what-runs)).
+- The title bar drawn by the system is **not part of the page's document**: `innerHeight`, `100vh`, and `resize` events only cover the content area. To drop the title bar, set `"frame": false` in the config, draw your own, and use `setGrabHint` to tell the system where the window can be dragged.
+- The title comes from `document.title` or `window.setTitle()`, whichever was set last (a `<title>` in the page replaces a title set before the document loaded); if neither is set, `label` is used.
+- Declare the colour schemes your page supports, as in a browser: `color-scheme: light dark` on the root (`:root { color-scheme: light dark }`) or `<meta name="color-scheme" content="light dark">` when it follows the system with `prefers-color-scheme`, `dark` when it is always dark. The system draws a dark title bar only for pages that name `dark`; a page that declares nothing is taken as light only and gets a light title bar even in a dark theme. The `html` template follows the system and declares `light dark`. In 0.0.9, an app run on its own (an `acde dev` of the app, `acde test`) always gets a light title bar, because only a desktop sets the title bar's colours. After 0.0.9, there the title bar is dark while the page is: a page that names only `dark` always, a page that names `light dark` while `prefers-color-scheme` is `dark` (the system's scheme, or `emulate({ colorScheme })` in a test). As in browsers, the root's `color-scheme` counts before the meta: an app with its own light / dark switch sets `color-scheme: dark` or `light` on the root, and the title bar follows it.
+
+## acde:window
+
+```js
+import { window as self } from 'acde:window'
+
+self.setTitle('Untitled — Notes')
+
+self.on('beforeclose', async () => {
+  if (!dirty) return true
+  return confirmDiscard() // return false to keep the window open
+})
+```
+
+> The module is named `window`, the same as the global `window`, so renaming it on import keeps things clear.
+
+| Member | Does |
+| --- | --- |
+| `id` | This window's id (a number) |
+| `setTitle(title)` | Sets the title |
+| `setMenus(menus)` | App menus (shown in the desktop's menu bar) |
+| `close()` | Closes the window at once; `beforeclose` is not asked |
+| `minimize()` | Minimizes the window, as `requestState('minimized')` does; the promise rejects with `status: 409`, `code: 'unavailable'` when the window cannot be minimized |
+| `state` / `requestState(state)` | The window's state: `normal`, `minimized`, `filled` (fills the work area), `fullscreen`; see [Window state](#window-state) |
+| `requestMode(mode)` | Whether the user can move and resize the window: `free` (both), `fixed` (move only), `pinned` (neither) |
+| `output` | The screen the window is on: `{width, height, scale, workArea: {x, y, width, height}}` in logical pixels; `workArea` leaves out what the desktop's panels reserve. In a session that runs a single app the screen is the host window: with `"size": [400, 300]`, `output` and its `workArea` are both 400 × 300 |
+| `requestAttention()` | Requests attention (for example a bouncing Dock icon; up to the desktop) |
+| `requestActivate()` | Brings the window to the front and requests focus; the system may turn this into a request for attention |
+| `setGrabHint(rect, edges?)` | Pressing in this area makes the system move the window (no `edges`) or resize it (with edges) |
+| `setBackdrop(rect, effect?)` | Frosted glass over whatever is behind this area: `{radius, blur, saturate, brightness}`; `null` removes it |
+| `requestGrab(kind)` / `releaseGrab(kind)` | Takes exclusive pointer or keyboard input (`'pointer'` / `'keyboard'`) |
+| `shortcut(combo)` / `unshortcut(combo)` | Registers an app-level global shortcut, such as `'ctrl+shift+k'` |
+| `hostControls` | `true` when the host system draws the window's minimize / maximize / close buttons, so a frameless app should hide its own |
+| `minimizable` | `false` when this window cannot be minimized. In a session that runs a single app, on macOS and headless, the app's window is such a window: it fills the host window |
+
+### Window state
+
+Full screen is a **state** of the window, not a mode: `requestMode('fullscreen')` throws a `TypeError` (`requestMode: full screen is a window state, use requestState('fullscreen')`).
+
+```js
+self.on('state', ({ state, previous }) => {
+  document.body.dataset.windowState = state
+})
+
+self.requestState('fullscreen') // 'normal' | 'minimized' | 'filled' | 'fullscreen'
+```
+
+- `requestState()` returns nothing. The system decides: when it refuses, nothing changes and no event arrives. A `fixed` window can only be minimized, and a `pinned` one cannot change state. A window whose `minimizable` is `false` cannot be minimized: `requestState('minimized')` changes nothing, and `minimize()` rejects.
+- The state also changes without the page asking: the title bar's buttons, the desktop minimizing the window, the user bringing a minimized window back. Keep the UI in step with the `state` event (or `self.state`), not with what the page last requested.
+- A minimized window that gets the focus again returns to the state it had before (`fullscreen`, for example).
+- In a single-app `acde dev` session the app already fills the host window, and state requests may change nothing (headless on macOS, `minimized`, `filled` and `fullscreen` all leave the state `normal`, and no event arrives). Try states in a desktop session.
+- The standard Fullscreen API (`element.requestFullscreen()`) is not supported; it rejects with `NotSupportedError`.
+
+### Events
+
+Subscribe with `on(name, handler)`, which returns an unsubscribe function. A name the module does not have throws a `TypeError` (`acde:window has no nosuch event (activate, deactivate, beforeclose, request, suspend, resume, grab, grablost, state, output, hostcontrols, minimizable, shortcut)`). Events are not dispatched on the global `window`.
+
+| Event | When |
+| --- | --- |
+| `activate` / `deactivate` | The window gains / loses focus |
+| `state` | The window's state changed, `{state, previous}` |
+| `output` | The screen or its work area changed; the handler gets the new `output` |
+| `beforeclose` | The user or the desktop wants to close the window. Return `false` (or resolve to `false`) to keep it; if there is no answer within 3 seconds, it closes |
+| `request` | Another app or the system asks this window to open something (see [Opening apps](open.md)) |
+| `shortcut` | A registered shortcut was pressed, `{key}` |
+| `grab` / `grablost` | Exclusive input was answered, `{kind, granted}` / taken back, `{kind: 'lost', reason}` |
+| `hostcontrols` / `minimizable` | `hostControls` / `minimizable` changed; the handler gets the new value |
+
+### Menus
+
+```js
+self.setMenus([
+  {
+    id: 'file',
+    label: 'File',
+    items: [
+      { id: 'new', label: 'New', shortcut: 'ctrl+n', onSelect: () => newDoc() },
+      { type: 'separator' },
+      { id: 'close', label: 'Close', onSelect: () => self.close() },
+    ],
+  },
+])
+```
+
+Call `setMenus` again with the whole list to change anything (a `checked` mark, a `disabled` item). Where the menus show:
+
+- In a desktop, in its menu bar (the Dopame desktop shows the focused window's menus).
+- In 0.0.9, an app run on its own (an `acde dev` of the app, `acde test`) shows them nowhere. After 0.0.9, it shows them on the title bar the system draws: the menu names after the window buttons, the window's title moved past them. A name opens its menu on a press; the arrow keys, Return and Escape work the open menu, and choosing an item runs its `onSelect`. An item without `onSelect` is shown disabled. `acde inspect` lists the menus first (`menuitem "File" [collapsed] [w1.m1]`, and the items of the open one, `w1.m1.2`), `acde act w1.m1.2 click` opens the menu and chooses the item, and in a test `getByRole('menuitem', { name: 'New' })` finds them. With `"frame": false` there is no title bar, so no menus either.
+
+An item's `shortcut` (`'ctrl+n'`, the same names as `shortcut()`; after 0.0.9 also `mod`, which is ⌘ on macOS and Ctrl elsewhere) is shown next to it. In a desktop, and in 0.0.9 everywhere, it is only shown: to have the key work, register the combo with `self.shortcut()` as well and handle the `shortcut` event. After 0.0.9, an app run on its own has it bound too, while its window is focused: pressing it runs the item's `onSelect`, as long as the item has one and is not `disabled`. The page then gets no `keydown` for that combo (an `Edit` item with `ctrl+c` takes copy from text fields as well), and if the app also registered it with `self.shortcut()`, the item runs and no `shortcut` event comes, so it does not run twice.
+
+## A second window of your app
+
+An app opens another window of itself with `open` from `acde:open`, like any other app. It needs two things in its config: `multiple`, so that a second window is allowed, and its own id in the `open` capability:
+
+```jsonc
+{
+  "id": "notes",
+  "multiple": true,
+  "requests": ["edit-note"],
+  "capabilities": { "open": ["notes"] }
+}
+```
+
+```js
+import { open } from 'acde:open'
+import { window as self } from 'acde:window'
+
+const { window } = await open('notes', { kind: 'edit-note', note: 'todo' })
+
+self.on('request', (request) => {
+  if (request.kind === 'edit-note') load(request.note)
+})
+```
+
+- The new window runs the same `entry`; a request tells it what to show. Like any request it needs a `kind` that the app lists in its own `requests`; `open('notes')` with no request opens a plain window.
+- Without `multiple`, `open('notes', …)` opens nothing new: it resolves with the window that already runs, and that window gets the request.
+- Without `notes` in `open`, the call is rejected with 403 `forbidden` (`Notes may not use open notes (not in its manifest's capabilities)`), even though it is the app's own id.
+- Pass `{ parent: self.id }` as the third argument to make the new window a child of this one (see [Opening apps](open.md#apps)).
+- The windows share storage (`localStorage`, IndexedDB, cookies) but not memory: each is its own page.
+
+## Browser APIs
+
+| API | In acde |
+| --- | --- |
+| `window.close()` | Closes this window |
+| `location.reload()` | Reloads this window |
+| `alert()` | Drawn inside the window; `confirm()` / `prompt()` return `false` / `null` |
+| External links | Handed to the browser app |
+| Downloads | Saved to the Downloads folder |
+| `Notification` | Shown by the desktop (a system notification when there is no desktop, except on Windows, where a single app shows none; `acde:capabilities` reports `notifications` `unsupported` there) |
+| `visibilitychange` | The window is hidden / shown |
+| `screen.*` | The screen's logical size |
+
+## Module entry
+
+`entry` can also be a module whose default export is a `WindowApp`:
+
+```ts
+import type { WindowApp } from '@dopame/acde-api'
+
+const app: WindowApp = {
+  mount(element, host) {
+    host.setTitle('Hello')
+    element.textContent = 'Hello from a module'
+    return () => { element.textContent = '' } // unmount
+  },
+}
+export default app
+```
+
+## Memory and hangs
+
+- Each window's JS heap has a limit (`heapMb`, 256 MB by default). Exceeding it ends only that window.
+- When a single task runs longer than 5 seconds, the desktop is told the window is "not responding" and can end it.