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

package/lib/acde/skills/acde/references/reference/testing.md

@@ -0,0 +1,265 @@
+# Testing API
+
+`acde/test` exports `test`, `expect`, `describe`, `beforeAll`, `beforeEach`, `afterAll`, `afterEach`, and everything from `acde/driver`, including the types (`Fixtures`, `AppWindow`, `Locator`, `Acde`, `E2eSettings` and the option and result types below; `import { type AppWindow } from 'acde/test'`). `acde/driver` depends only on `node:` modules, so you can use it on its own in Node.js / Bun scripts.
+
+## test
+
+```ts
+test(name: string, body: (fixtures: Fixtures) => unknown, options?: TestOptions): void
+test(name: string, options: TestOptions, body: (fixtures: Fixtures) => unknown): void
+test.only / test.skip / test.todo(name) / test.if(condition)
+
+type TestOptions = number | {
+  timeout?: number
+  size?: [width: number, height: number]
+  localStorage?: Record<string, string>
+}
+
+interface Fixtures {
+  acde: Acde
+  app: AppWindow | null
+  home: string
+  settings: E2eSettings
+}
+```
+
+A number is the timeout in milliseconds. `localStorage` is written before the page loads (`app.seedLocalStorage`), then `size` sets the page's size (`app.resize`); both need the `app` fixture.
+
+## expect
+
+```ts
+expect(locator: Locator): LocatorAssertions
+expect(window: AppWindow): WindowAssertions
+expect(value): bun:test Matchers
+expect.poll(read: () => T | Promise<T>, options?: { timeout?: number; message?: string }): bun:test Matchers, each returning a Promise
+expect.soft(locator | window | value): the same assertions; a failure is recorded and the test fails at its end
+```
+
+**LocatorAssertions** (all support `.not` and accept `{timeout}`):
+
+`toBeVisible()` `toBeHidden()` `toHaveCount(n)` `toHaveText(text, {exact?})` `toContainText(text)` `toHaveValue(text)` `toHaveState(state)` `toBeChecked()` `toBeDisabled()` `toBeEnabled()` `toBeFocused()` `toHaveAttribute(name, value?)` `toHaveClass(text)` `toHaveCSS(property, text)` (the computed style) `toHaveJSProperty(name, value)` `toBeEmpty()` `toBeEditable()` `toBeInViewport({ratio?})` `toHaveScreenshot(name?, options?)`
+
+**WindowAssertions**: `toBeOpen()` `toHaveTitle(text)` `toHaveScreenshot(name?, options?)`
+
+`text` is a string or a RegExp. `toHaveText` and `toContainText` both compare the element's text content, not its accessible name. Screenshot options: `{maxDiffPixels, maxDiffPixelRatio, threshold, mask: Locator[], timeout}`.
+
+## Acde
+
+```ts
+class Acde {
+  static launch(options?: {
+    dirs?: string[]; desktop?: string; app?: string; out?: string
+    cwd?: string; env?: Record<string, string>; headless?: boolean
+    timeout?: number; startTimeout?: number; force?: boolean
+  }): Promise<Acde>
+  static attach(options?: { session?: number; cwd?: string; env?: Record<string, string>; timeout?: number }): Promise<Acde>
+
+  readonly desktop: AppWindow
+  readonly trace: Trace
+  window(match: string | { ref?: string; id?: number; app?: string; title?: string | RegExp }): AppWindow
+  open(name: string, options?: { timeout?: number }): Promise<AppWindow>
+  webs(): Promise<Web[]>
+  windows(): Promise<InspectWindow[]>
+
+  evaluate<T>(web: string, code: string): Promise<T>
+  snapshot(options?): Promise<{ text; windows; trees }>
+  query(options: { selector: string; window?: string; ref?: string; limit?: number; attributes?: string[] }): Promise<QueryResult>
+  act(ref: string, action: InspectAction, arg?): Promise<ActResult>
+  run(steps): Promise<ActResult>
+
+  screenshot(web: string, options?: { path?: string }): Promise<Shot>
+  screen(options?: { path?: string }): Promise<Shot>
+  console(options?: { web?; since?; limit?; level? }): Promise<{ entries; next; dropped }>
+  network(options?: { web?; since?; limit?; failed? }): Promise<{ entries; next; dropped }>
+  waitForRequest(url: string | RegExp, options?: { method?; web?; timeout? }): Promise<RequestEntry>
+  waitForConsole(text: string | RegExp, options?: { level?; web?; timeout? }): Promise<ConsoleEntry>
+
+  emulate(options: { colorScheme?: 'light' | 'dark' | null }): Promise<...>
+  chooseFolder(folder: string | null): Promise<void>
+  chooseFiles(files: string | string[] | null): Promise<void>
+  chooseSaveFile(file: string | null): Promise<void>
+  route(url: string | RegExp, response: RouteResponse, options?: { method?; web?; times? }): Promise<number>
+  unroute(id?: number): Promise<{ removed: number; left: number }>
+  pointer(x: number, y: number): Promise<{ x: number; y: number }>  // a real pointer move to screen coordinates
+  clipboard(): Promise<string>
+  setClipboard(text: string): Promise<void>
+
+  addInitScript(code: string, options?: { web?: string; once?: boolean }): Promise<number>
+  removeInitScript(id?: number): Promise<{ removed: number; left: number }>
+  reload(web: string): Promise<void>
+  resize(web: string, width: number, height: number): Promise<{ width: number; height: number }>
+  answerDialog(web: string, answer?: { accept?: boolean; text?: string }): Promise<void>
+  dialogs(options?: { web?: string }): Promise<Dialog[]>
+  waitForDialog(options?: { web?: string; type?: 'alert' | 'confirm' | 'prompt'; timeout?: number }): Promise<Dialog>
+  input(web: string, events: InputEvent[]): Promise<ActResult>
+
+  permissions(): Promise<{ pending: PermissionPrompt[]; decisions: PermissionDecision[] }>
+  waitForPrompt(match?: { app?: string; capability?: string; timeout?: number }): Promise<PermissionPrompt>
+  allow(match?: { app?: string; capability?: string; timeout?: number }): Promise<PermissionPrompt>
+  deny(match?: { app?: string; capability?: string; timeout?: number }): Promise<PermissionPrompt>
+  answer(prompt: PermissionPrompt | number, allow: boolean): Promise<void>
+  revoke(app: string, capability: string): Promise<boolean>
+  drop(files: string | string[], options?: { web?: string; x?: number; y?: number }): Promise<{ web; window; files }>
+
+  ready(): Promise<boolean>
+  readonly closed: boolean
+  close(): Promise<void>
+}
+
+interface ActResult {
+  ok: boolean
+  text: string
+  ended?: true
+}
+```
+
+- `launch` starts an `acde dev` session on the project's own runtime (Bun or Node.js) and waits until the windows of all pages have appeared, or an approval prompt waits (`startTimeout`, 120 seconds by default). With `force` (after 0.0.9), it starts even when another `acde dev` runs the project (`acde dev --force`); without it, that case is an error. When the session does not start, it ends that `acde dev` and throws a `LaunchError` (an `Error`, exported by `acde/driver`). Its message says how far the start got and ends with the last 40 lines of the output of `acde dev`; `logs` holds the whole output (`error.logs.tail(5000).text`), and `phase` is:
+  - `'exited'`: `acde dev exited (1) before it was ready:`; `code` is the exit code (`null` in the other phases).
+  - `'session'`: `acde dev (pid 4242) did not register a session within 120 s in <dir>`, then the line `no session yet: its build did not finish, or acdert did not start listening; last output:`.
+  - `'window'`: `acde dev did not start within 120 s:`, then the line `acdert runs and answers, but no window appeared (pages: 0, windows: 0) and no approval prompt waits; last output:`.
+  - `'failed'`: anything else that went wrong while it waited (the message is that error's, which is also the `cause`).
+- `close()` ends the session that `launch` started: it asks acdert to quit, so acdert and `acde dev` end on their own. On macOS and Linux it also sends SIGTERM to `acde dev`, then SIGKILL after 10 seconds. On Windows it waits up to 10 seconds for them to exit, then ends `acde dev` and acdert together (the whole process tree). On a session from `attach` it only disconnects; requests still waiting fail at once.
+- `act` answers `ok: false` when the action was not done. In a session that runs a single app, closing the app's only window ends the session, by design: the `close` that did it resolves with `ok: true`, `ended: true` and the text `closed w1; acdert exited with it, so acde dev <pid> ended`; `closed` becomes true, and every later request rejects with `acde dev <pid> is no longer connected`. Any other request during which the runtime goes away rejects with `acdert closed the connection` (also a `close` in a desktop session, and a `run` whose steps close the window).
+- `choose*` answers, in advance, the **next** picker of that kind the page opens; `null` means the user cancelled; relative paths resolve against the current directory. A headless session has no picker dialog, so a picker opened without an answer fails and the page sees it as cancelled.
+- Call `waitFor*` before the action that triggers it.
+- `addInitScript` registers code that runs before a page's own scripts on every load (`once`: on the next load only); `web` is a page name or an app id, and without it every page runs the code. It returns an id for `removeInitScript`, which removes every script when no id is given.
+- `answerDialog` answers the page's next `alert` / `confirm` / `prompt` in advance: `accept: false` cancels, `text` is what a `prompt` answers. Without an answer `confirm` gives false and `prompt` null. `Dialog` is `{ type, message, defaultValue, answered, accept, text }`.
+- `input` sends raw events at page coordinates: `{ type: 'move' | 'down' | 'up' | 'wheel', x, y, button?, dx?, dy? }`, `{ type: 'keydown' | 'keyup', key }` and `{ type: 'text', text }`. `app.mouse` and `app.keyboard` are built on it.
+- Camera and microphone prompts (`PermissionPrompt` is `{ id, app, label, capability, reason }`, `PermissionDecision` is `{ app, label, capability, decision: 'granted' | 'denied' }`): `allow` and `deny` wait for a prompt that matches (any prompt when nothing is given), answer it and return it; `waitForPrompt` only waits; `answer` answers a prompt you already have. Nothing answers a prompt by itself: after 0.0.9, `getUserMedia()` waits until the test answers; in 0.0.9, the prompt comes when an app that declares the capability starts, and its window waits. `revoke` takes a decision back and returns whether there was one. See [Approvals in tests](../guide/testing.md#approvals).
+- `drop` drops files from the system onto a page (default: the middle of the desktop page; `web` picks a page, `x` and `y` a point in it). The page gets a standard `drop` event a moment after the call returns, so wait for what the page does with it.
+
+### route
+
+```ts
+type RouteResponse =
+  | { status?: number; statusText?: string; headers?: Record<string, string>; contentType?: string; body?: string | Uint8Array; json?: unknown }
+  | { abort: true | string }
+```
+
+`url` is a glob (`**` matches anything, `*` matches anything except `/`; a glob starting with `/` is matched against the path plus query, otherwise against the whole URL) or a RegExp. Rules added later match first; a rule is removed automatically once its `times` are used up. Only fetch / XHR are affected, not WebSocket / EventSource.
+
+## AppWindow
+
+```ts
+class AppWindow {
+  getByRole(role: string, options?: RoleOptions): Locator
+  getByText(text: string | RegExp, options?: { exact?: boolean }): Locator
+  getByLabel / getByPlaceholder / getByTitle / getByAltText (text, options?): Locator
+  getByTestId(id: string): Locator
+  locator(selector: string): Locator
+
+  info(options?): Promise<InspectWindow>
+  isOpen(): Promise<boolean>
+  waitFor(options?: { state?: 'open' | 'closed'; timeout?: number }): Promise<void>
+  web(): Promise<string>
+  evaluate<T>(code: string): Promise<T>
+  snapshot(options?: { find?: string; diff?: boolean }): Promise<string>
+  screenshot(options?: { path?: string; mask?: Locator[] }): Promise<Shot>
+
+  press(keys: string): Promise<ActResult>
+  focus() / minimize() / restore() / fill() / fullscreen() / close(): Promise<ActResult>
+
+  readonly mouse: Mouse
+  readonly keyboard: Keyboard
+  readonly clock: Clock
+
+  addInitScript(code: string, options?: { once?: boolean }): Promise<number>
+  reload(options?: { timeout?: number }): Promise<void>
+  resize(width: number, height: number, options?: { timeout?: number }): Promise<{ width: number; height: number }>
+  seedLocalStorage(entries: Record<string, string>, options?: { timeout?: number }): Promise<void>
+  answerDialog(answer?: { accept?: boolean; text?: string }): Promise<void>
+  dialogs(): Promise<Dialog[]>
+  waitForDialog(options?: { type?: 'alert' | 'confirm' | 'prompt'; timeout?: number }): Promise<Dialog>
+
+  route / waitForRequest / waitForConsole / console / network / drop  // as on Acde, scoped to this window
+}
+
+interface RoleOptions {
+  name?: string | RegExp; exact?: boolean
+  checked?: boolean; disabled?: boolean; selected?: boolean
+  expanded?: boolean; pressed?: boolean; focused?: boolean; level?: number
+}
+```
+
+`AppWindow` looks itself up in the window table again on every use, so it keeps working if the window is closed and reopened.
+
+`info()` is the window's row in that table: `ref`, `id`, `app`, `title`, `state` (`normal`, `minimized`, `filled`, `fullscreen`), `focus`, `hidden` and more. While a window is minimized, `state` is `minimized`, `hidden` is `true`, and locators find no element in it: `toBeHidden()` passes, and an action waits until its timeout (`no element matches`). `restore()` brings the window and its elements back. `fill()` fills the desktop's work area with the window and `fullscreen()` covers the whole host window with it (state `filled` / `fullscreen`); `restore()` sets either back to `normal`. Both are refused for the desktop and for a window that already fills the host window (a single-app session).
+
+`reload()` waits until the new page has loaded; `resize()` sets the size of the page without the title bar and waits until `innerWidth` and `innerHeight` have it (a window that fills the screen resizes the host window, which Windows cannot do yet); `seedLocalStorage()` writes the entries before the page's scripts run, by reloading the page once.
+
+```ts
+class Mouse {
+  move(x: number, y: number, options?: { steps?: number }): Promise<ActResult>
+  down(options?: { button?: 'left' | 'right' | 'middle' }): Promise<ActResult>
+  up(options?: { button?: 'left' | 'right' | 'middle' }): Promise<ActResult>
+  click(x: number, y: number, options?: { button?; clickCount?: number; modifiers?: Modifier[] }): Promise<ActResult>
+  dblclick(x: number, y: number, options?: { button?; modifiers?: Modifier[] }): Promise<ActResult>
+  wheel(deltaX: number, deltaY: number): Promise<ActResult>
+}
+
+class Keyboard {
+  down(key: string) / up(key: string): Promise<ActResult>
+  press(keys: string): Promise<ActResult>       // "Enter", "Control+a"
+  type(text: string): Promise<ActResult>        // key presses; characters without a key are inserted as text
+  insertText(text: string): Promise<ActResult>  // as the input method commits it, no key events
+}
+
+class Clock {
+  install(options?: { time?: number | string | Date }): Promise<ClockState>
+  fastForward(duration: number | string) / runFor(duration: number | string): Promise<ClockState>
+  pauseAt(time) / setFixedTime(time) / setSystemTime(time): Promise<ClockState>
+  resume() / state(): Promise<ClockState>
+}
+
+type Modifier = 'Shift' | 'Control' | 'Alt' | 'Meta' | 'ControlOrMeta'
+```
+
+Coordinates are CSS pixels of the page, as `getBoundingClientRect()` gives them. `ControlOrMeta` is `Control` on every system. A time is milliseconds since 1970, a `Date` or a date string; a duration is milliseconds, `"mm:ss"` or `"hh:mm:ss"`. `ClockState` is `{ installed, paused, now, performanceNow, fixed, timers }`. `fastForward` fires each timer that is due once, `runFor` fires every timer at its own time; `setFixedTime` makes `Date` stand still while timers go on, `setSystemTime` moves `Date` only.
+
+`close()` waits until the window is gone. Closing the only window of a session that runs a single app ends the session: the call resolves with `ended: true` and a text that says so (see `act` under [Acde](#acde)), and the session takes no more requests. A test has no need to close that window, since its session ends with the test.
+
+## Locator
+
+```ts
+class Locator {
+  getByRole / getByText / getByLabel / … / locator(...)   // search within this element
+  filter(options: { hasText?: string | RegExp; hasNotText?: string | RegExp; has?: Locator; hasNot?: Locator }): Locator
+  or(other: Locator) / and(other: Locator): Locator
+  nth(index: number) / first() / last(): Locator
+
+  count(): Promise<number>
+  all(): Promise<Locator[]>
+  isVisible(): Promise<boolean>
+  textContent(): Promise<string>  // the text inside the element (what toHaveText compares)
+  text() / name() / value() / states() / ref() / node(): Promise<...>
+  waitFor(options?: { state?: 'visible' | 'hidden'; timeout?: number }): Promise<void>
+
+  click(options?: { button?: 'left' | 'right'; clickCount?: 1 | 2; modifiers?: Modifier[]; timeout?: number }): Promise<ActResult>
+  dblclick(options?: { modifiers?: Modifier[] }) / hover(options?: { modifiers?: Modifier[] }): Promise<ActResult>
+  focus() / clear(): Promise<ActResult>
+  evaluate<T>(fn: string | ((element, arg) => T), arg?: unknown): Promise<T>
+  fill(text: string) / type(text: string) / press(keys: string): Promise<ActResult>
+  scroll(dy?: number): Promise<ActResult>
+  selectOption(values: string | string[]): Promise<ActResult>
+  check() / uncheck() / setChecked(checked: boolean): Promise<void>
+  dragTo(target: Locator): Promise<ActResult>
+  screenshot(options?: { path?: string; mask?: Locator[] }): Promise<Shot>
+}
+```
+
+When an action fails (`ok: false`), it is retried until the timeout, then `ActError` is thrown.
+
+`evaluate` calls the function in the page with the element and `arg` (JSON), and returns its JSON result; `fn` may also be the source of such a function.
+
+### Semantic tree limitations
+
+`getByRole`, `getByText` and `getByLabel` search the runtime's semantic tree, not the DOM:
+
+- Elements with `opacity: 0` are not in it, so these locators do not find them.
+- `getByText` compares accessible names.
+
+CSS locators (`locator`, `getByTestId`, `getByPlaceholder`, `getByTitle`, `getByAltText`) search the DOM and also match elements that are not rendered; `toBeVisible`, `toBeHidden`, `isVisible()` and `waitFor({ state })` tell the two apart, and actions wait until the element is rendered.
+
+## Png
+
+`Png.decode(bytes)`, `Png.encode(image)`, `Png.diff(actual, expected, {threshold})`: PNG encoding/decoding using only `node:zlib`, plus a pixelmatch-style comparison. The screenshot assertions are built on it. `Png.animate(frames)` joins PNGs of one size (`{ png, ms }` each) into an animated PNG; `Video.start(acde)` records the screen with it (`stop()`, then `write(path)`), which is what `acde test --video` keeps.

package/lib/acde/skills/acde/references/reference/web.md

@@ -0,0 +1,94 @@
+# Web compatibility
+
+acdert has its own renderer (it is not Chromium), and page JS runs in its embedded V8. The rule is that **standard APIs are fully browser-compatible**: behavior, signatures, events, and errors all follow the spec. Anything that can't be done that way is a gap; it is not filled with a look-alike proprietary version. Below are the things worth knowing.
+
+## Origin
+
+Every app page has the origin `http://acde.local`. Each app's storage is a separate partition, invisible to other apps.
+
+## Storage
+
+| API | Notes |
+| --- | --- |
+| `localStorage` | Shared by all windows of the same app; 5 MiB quota; other windows get a `storage` event on changes |
+| `sessionStorage` | Per window, in memory only; **not** kept across `location.reload()` (unlike browsers) |
+| IndexedDB | Fully implemented, stored in SQLite; promise-wrapper libraries (idb and others) behave as in browsers |
+| Cache API | `caches` is supported |
+| cookie | Stored and sent as usual for same-origin requests (your own backend); cross-origin requests neither send nor store cookies |
+| `navigator.storage` | `estimate()`; `persist()` is always `true`; `getDirectory()` is the origin private file system (OPFS) |
+
+Data lives in `$XDG_DATA_HOME/acde/storage/app-<id>/`.
+
+## Network
+
+- `fetch`, `XMLHttpRequest`, `WebSocket`, and `EventSource` are all supported.
+- Same-origin paths and `localhost` go to the app's own backend; see [Backend](../guide/backend.md).
+- Requests to other hosts use the system's DNS and network, with normal certificate validation, and go through a proxy the way the system says: with `http_proxy`, `https_proxy` or `all_proxy` set in the session, only those variables (and `no_proxy`) count; otherwise the system's proxy settings (Windows: the user's Internet settings, including a configuration script and automatic detection; macOS: the network settings; Linux has no other source). `localhost`, loopback addresses and the app's own backend are always reached directly. Proxy authentication and `https://` proxies are not supported. Responses are not decompressed automatically (no `Accept-Encoding` is sent).
+- Cross-origin requests follow browser rules: `Origin` header, CORS preflight, response header filtering, opaque responses for `no-cors`.
+- Forbidden request headers (`Host`, `Cookie`, `Origin`, `Referer`, `Sec-*`, ...) are not sent even if you set them.
+- Synchronous XHR can only read the app's own files.
+
+## External resources
+
+Images (`<img>` and images in CSS), stylesheets (`<link rel="stylesheet">`) and fonts load from other hosts as they do in a browser: images and stylesheets without CORS, fonts only with an `Access-Control-Allow-Origin` that allows the page, a stylesheet only from a 2xx `text/css` response. They show up in `acde network` with the kinds `image`, `stylesheet` and `font`, and a failed one is a console error `Failed to load resource: <url>: <reason>`. A `<link rel="stylesheet">` fires `load` once its sheet is fetched and applied and `error` when it cannot be had (also when a sheet it `@import`s cannot); `link.sheet` and `document.styleSheets` have the sheet from then on. The rules of a sheet from another host (`sheet.cssRules`) throw `SecurityError` unless the link has `crossorigin` and the host allows the page with `Access-Control-Allow-Origin`; after 0.0.9, its `@font-face` faces are still in `document.fonts`. **ES modules can't be `import`ed from other hosts** (`module … is not a local file`): bundle the code you depend on into the app. After 0.0.9, `blob:` and `data:` modules can be imported when their type is a JavaScript MIME type (`text/javascript`). (Classic `<script src>` can load from other hosts.) An app that should work without a network bundles its images, styles and fonts too.
+
+## Scripts
+
+Classic `<script>`, `type="module"`, and `type="importmap"` are supported.
+
+## File pickers
+
+`showOpenFilePicker`, `showSaveFilePicker`, `showDirectoryPicker`, and `<input type="file">` open the system dialog; see [Files and folders](../guide/files.md).
+
+Files and folders dropped into a window arrive the standard way: `dataTransfer.files`, and a read-only handle from `dataTransfer.items[i].getAsFileSystemHandle()`. Folders and files over 64 MiB are not in `files`; use the handle. See [Dropped files](../guide/files.md#dropped-files).
+
+## Media
+
+`Audio` / `AudioContext` are supported. WebGPU is currently available only on Linux.
+
+`<video>` plays what the system's own decoders can open, so formats differ by platform: on macOS, MP4 / QuickTime plays and WebM does not. Ask `canPlayType()` before choosing a source.
+
+`navigator.mediaDevices.getUserMedia()` needs the `camera` / `microphone` capability in the config and the user's answer the first time (see [Capabilities](../guide/capabilities.md#camera-and-microphone)). Not available on Windows.
+
+- In 0.0.9, a required capability is asked for when the app starts, and a denial keeps the app from starting; after 0.0.9, a required one is asked for on first use too, and a denial only fails the calls. An [optional](../guide/capabilities.md#optional-capabilities) one that was not asked for yet is asked for by `getUserMedia()` itself, with the prompt `request('camera')` raises; a call that wants both asks for the microphone first, then the camera. The call resolves once the user allows and rejects with `NotAllowedError` (`Permission denied`) when the user denies; later calls do not ask again.
+- `navigator.permissions.query({ name: 'camera' })` (or `'microphone'`) answers `prompt` until the user has answered and `denied` after a denial or after the approval was taken back; its `change` event fires on the answer. Once the user has allowed it, the answer is the host system's own permission for the device (`granted` when the system allows it too).
+- In an app that does not declare the capability, the query answers `denied` and `getUserMedia()` rejects with `NotAllowedError`, without a prompt.
+- Constraints are judged first: a request that no device can meet rejects with `OverconstrainedError` and asks nobody.
+- `enumerateDevices()` lists one entry without a label for a kind that is not allowed yet.
+- To try a page without a real camera or microphone, start the session with `ACDE_CAPTURE=fake`: the devices are then `Fake camera` and `Fake microphone`.
+
+## Rendering and canvas
+
+Styles are computed by Stylo, the style engine of Firefox; layout and painting are acdert's own. What does not work yet:
+
+- Canvas 2D: `drawImage()` draws only an `<img>` or a `<canvas>`; any other source (a `<video>`, an `ImageBitmap`) draws nothing and throws nothing. `createConicGradient()` does not draw a conic gradient. In 0.0.9, `ctx.filter` is accepted but not applied, and `drawImage()` of an `<img>` showing an SVG draws nothing; after 0.0.9, `ctx.filter` applies `blur()`, `brightness()`, `contrast()`, `grayscale()`, `hue-rotate()`, `invert()`, `opacity()`, `saturate()`, `sepia()` and `drop-shadow()` (not `url()`), and SVG images are drawn.
+- SVG geometry: `getTotalLength()` and `getPointAtLength()` are estimates from the element's box, not its path; `isPointInFill()` and `isPointInStroke()` are always `false`.
+- In 0.0.9, elements inside an inline `<svg>` have empty boxes: `getBBox()` and `getBoundingClientRect()` give zeros. After 0.0.9, shapes, text and groups have their boxes, and `getComputedTextLength()` measures text.
+- In 0.0.9, `<use href="#id">` and `url(#id)` that point into another `<svg>` of the page (a sprite sheet, a shared gradient) draw nothing. After 0.0.9 they work.
+- In 0.0.9 on macOS, `font-family: monospace` is Courier; after 0.0.9 it is Menlo, as in Safari and Chrome. In 0.0.9, symbols that no font in the stack has (`✕` `✔` `❤`) draw as a box, and `font-weight: 700` of a font with only a regular face draws regular; after 0.0.9, the system supplies a font for such symbols, and the bold is synthesized.
+
+Added after 0.0.9:
+
+- `:has()` selectors (Tailwind's `has-*` variants).
+- `animationstart`, `animationiteration`, `animationend`, `animationcancel`, `transitionrun`, `transitionstart`, `transitionend` and `transitioncancel` (dialogs and menus that wait for `animationend` before they unmount).
+- A `<textarea>`'s `scrollHeight` covers its text, and `field-sizing: content` grows the box with it.
+- `new Image()` with a `src` loads (and fires `load` / `error`) without being in the document.
+- Inline SVG colors given as `oklch()`, `lab()` or `color-mix()` (Tailwind 4's palette) are painted.
+- In SVG images and inline SVG, a `<mask>` made of one filled path clips to it (other masks clip to their region), and a group `filter` made of blurs, drop shadows and color matrices is applied (the glow of icons exported from Figma).
+- An element with an `id` is reachable as a global (`window.wave`).
+- `pointer-events: all` and the other SVG values (`visible`, `painted`, `fill`, `stroke` …) are understood and act as `auto`. In 0.0.9 they are dropped, so the element inherits `none`: every button in a Mantine `Modal` or `Drawer` cannot be clicked.
+- An SVG image used as a `background-image` or `mask-image` is drawn. In 0.0.9 a simple one (shapes in plain colours: icons, the select arrows of `@tailwindcss/forms` and Bootstrap, CSS mask icons) draws nothing.
+- An inline `<svg>` without a `viewBox` draws its content in CSS pixels from its top left, and clips it to its box, as browsers do. In 0.0.9 it is stretched to the size of the box, so an `<svg>` sized only by CSS draws too large and off centre (Mantine's `RingProgress`).
+- `<input>` and `<textarea>` have undo and redo: `Ctrl+Z`, and `Ctrl+Shift+Z` or `Ctrl+Y`.
+
+## Not yet supported
+
+`<datalist>`, `appearance: base-select` on `<select>`, Web Workers, `crypto.subtle`, WebGL (`getContext('webgl')` and `getContext('webgl2')` return `null`; use 2D canvas, or WebGPU on Linux), OffscreenCanvas / `createImageBitmap`, the Fullscreen API (`requestFullscreen()` rejects with `NotSupportedError`; an app window goes full screen with `requestState('fullscreen')` from [`acde:window`](../guide/window.md#window-state)) and pointer lock, `:target`, Storage Buckets, and Service Workers.
+
+## Differences from browsers
+
+- `alert()` is drawn inside the window; `confirm()` returns `false` and `prompt()` returns `null`.
+- There is no top layer: after 0.0.9, an open popover and a modal `<dialog>` get the highest `z-index` instead, so an ancestor's `transform`, `filter` or `contain` still clips them, and they have no `::backdrop`.
+- `navigator.userAgent` and `navigator.platform` say Linux on every system (`Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) acdert/<version>` and `Linux x86_64`), and editing shortcuts use Ctrl everywhere, so an app behaves the same on every host. To know the real system, read `platform` from [`acde:capabilities`](../guide/capabilities.md#acdecapabilities).
+- In 0.0.9 there are no developer tools: use the [debugging tools](../guide/tools.md) and [MCP](../guide/mcp.md). After 0.0.9, `acde dev` opens the DevTools of Chrome or Edge on a page (F12 in the window, or `acde devtools`); see [acde dev](../guide/dev.md#devtools).
+- Pages have no security sandbox (there is no syscall-level isolation yet): don't run code you don't trust.

package/lib/acde/skills/acde/references/start/first-app.md

@@ -0,0 +1,87 @@
+# First app
+
+## Create
+
+```sh
+acde new my-app
+```
+
+In a terminal, `acde new` asks for whatever is missing: the directory, app or desktop, template, display name, whether to add a backend, Bun or Node.js (when both are installed), whether to install dependencies, and whether to run `git init`. Press Enter at each prompt to accept the defaults.
+
+To skip the prompts, pass everything as options and add `--yes` (it still installs the dependencies; add `--no-install` to skip that):
+
+```sh
+acde new my-app --template html --label "My App" --yes
+```
+
+Available templates:
+
+| Template | What it is |
+| --- | --- |
+| `html` | A plain web page (default); add `--backend` to include a backend |
+| `desktop` | A desktop (see [Desktops](../guide/desktop.md)) |
+| `react` `vue` `svelte` `solid` `preact` `vanilla` | create-vite templates. In 0.0.9 they ignore `--backend`; after 0.0.9, `--backend` adds `server.ts` |
+| `next` `nuxt` `sveltekit` `astro` | Each framework's official scaffolding tool |
+
+Framework templates run the latest version of the framework's scaffolding tool through your package manager, then add `acde.config.jsonc`.
+
+## Run
+
+`acde dev` runs your app in the runtime, acdert, which the installer set up next to acde (inside the Dopame virtual machine it is already on PATH). `acde doctor` checks that it is there and works on this machine; see [The runtime](install.md#the-runtime).
+
+```sh
+cd my-app
+acde dev
+```
+
+`acde dev` builds the project, starts acdert, and opens a window on your computer with your app inside. Leave it running, then edit and save `index.html` or `src/main.js`; the window reloads automatically.
+
+Press Ctrl+C or close the window to stop, or run `acde stop` from another terminal in the project directory.
+
+> In the built-in templates, `package.json` has three scripts, `dev`, `build`, and `check`, which run `acde dev` / `acde build` / `acde check`. Framework templates leave the framework's own scripts alone and add `acde:dev`, `acde:build`, and `acde:check` instead.
+
+## Add a capability
+
+Let's have the app keep a file of its own. This example uses the `html` template; in a framework template, add only the `capabilities` line to its `acde.config.jsonc` (it has no `entry`, and should not get one) and put the code in one of the framework's source files.
+
+First, request the `fs` capability in `acde.config.jsonc`:
+
+```jsonc
+{
+  "type": "app",
+  "id": "my-app",
+  "label": "My App",
+  "icon": "files",
+  "entry": "index.html",
+  "capabilities": { "fs": true }
+}
+```
+
+Then in `src/main.js`:
+
+```js
+import { fs } from 'acde:fs'
+
+const status = document.querySelector('#status')
+await fs.writeFile('private', 'hello.txt', 'Hello from my app')
+const { text } = await fs.readText('private', 'hello.txt')
+const roots = await fs.roots()
+status.textContent = `${text} (roots: ${roots.map((r) => r.id).join(', ')})`
+```
+
+Save, and after the window reloads you'll see `Hello from my app (roots: private)`. With `"fs": true` an app gets a private folder of its own (the root `private`) and whatever folder the user picks for it. The user's shared folders, such as Desktop and Downloads, are named in the config and approved by the user before the app gets them; see [Files and folders](../guide/files.md). Importing a capability you haven't requested fails outright.
+
+## Build and check
+
+```sh
+acde check   # check the config and entry
+acde build   # build into .acde/
+```
+
+`.acde/` is the **package** the runtime understands: a directory with a `package.json` whose `acde` field is the **manifest** (what the package contains), plus the build output for the web pages and backend. To install the app into the Dopame desktop on your machine, use `acde install`; see [Local install](../guide/install.md).
+
+## Next steps
+
+- [Project layout](project.md)
+- [Configuration](../guide/config.md)
+- [Backend](../guide/backend.md)