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

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

@@ -0,0 +1,40 @@
+# Assets and icons
+
+## public/
+
+The project's `public/` directory (rename it with the `public` config field) is copied as is into the app's `web/`.
+
+References in your pages that start with `/` and point to a file in public:
+
+- In HTML: bundled as usual.
+- `url(/x)` in CSS: kept as is when the project is an app whose entry is HTML, because the runtime also serves the app's directory at `/`. Elsewhere (a desktop, or the apps it bundles) it is bundled as usual.
+- If the file can't be found anywhere, the build fails and tells you which URL in which file, and what's missing from public.
+
+## Files your scripts refer to
+
+A file that only your JavaScript names is bundled one of these ways:
+
+- `import logo from './logo.png'`: `logo` is its URL in the built app.
+- `new URL('./logo.png', import.meta.url)`: the file is copied and the URL points at it (with Node.js, Vite does this; with Bun, acde does it after 0.0.9). The path must be a literal that starts with `./` or `../` and names a file that exists; a module (`.js`, `.ts`, …) is left alone.
+- A path in a string (`img.src = 'img/logo.png'`) is not seen by any bundler: put the file in `public/` and refer to it as `/img/logo.png`.
+
+## URLs
+
+App pages have the origin `http://acde.local`. An app's files are served both under `/app/<id>/` and at `/`, so `/logo.png` and relative paths both work.
+
+## Icons
+
+Set `icon` to an icon name or to an image in the project:
+
+```jsonc
+{ "icon": "chart" }        // icon name
+{ "icon": "assets/logo.svg" } // image in the project
+```
+
+**Icon names** refer to Dopame's built-in icon set, which matches the desktop's visual style:
+
+`files` `browser` `editor` `office` `term` `projects` `dash` `team` `dopa` `settings` `store` `app` `timer` `cards` `list` `chart` `calc` `music` `video` `photo` `paint` `game` `chat` `mail` `calendar` `code` `book` `map` `weather`
+
+If omitted, it's `app`.
+
+**Images**: a value that contains `/` or `\`, or has an extension, is treated as a path relative to the project directory, and must be a `.svg` or `.png`. At build time it's copied to the app's `web/icon.<ext>`, and the manifest gets `/app/<id>/icon.<ext>`. `acde check` warns about any other value.

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

@@ -0,0 +1,94 @@
+# Backend
+
+An app can have a backend: a module that exports `fetch`, or any Node.js / Bun server that calls `listen()` (Express, Hono, Fastify, ...). Pages reach it with a plain `fetch('/api/…')`.
+
+App backends run on macOS, Linux and Windows. On Windows the runtime reaches the backend in another way; see [On Windows](#on-windows).
+
+## Write a backend
+
+The `server.ts` generated by `acde new my-app --backend`:
+
+```ts
+export default {
+  fetch(request: Request): Response {
+    const url = new URL(request.url)
+    if (url.pathname === '/api/hello') return Response.json({ hello: 'world', at: new Date().toISOString() })
+    return new Response('not found', { status: 404 })
+  },
+}
+```
+
+In the page:
+
+```js
+const answer = await (await fetch('/api/hello')).json()
+```
+
+`export default { fetch }` works on both Bun and Node.js. On Node.js, acde's preload runs it with `node:http`; requests and responses are WHATWG `Request` / `Response` objects with streaming bodies. (There's no WebSocket upgrade on Node.js.)
+
+You can also listen yourself:
+
+```ts
+import { createServer } from 'node:http'
+
+createServer((req, res) => res.end('hi')).listen(3000)
+```
+
+## Discovery
+
+Without a `backend` field, acde uses the first of these that exists:
+
+`server.ts` `server.js` `src/server.ts` `src/server.js` `server/index.ts` `server/index.js` `backend/index.ts` `backend/index.js`
+
+To set it explicitly, or turn it off:
+
+```jsonc
+{ "backend": { "entry": "api/main.ts", "port": 8080 } }
+{ "backend": false }
+```
+
+`port` defaults to 3000; it's the port the backend thinks it's listening on.
+
+## No TCP ports
+
+An app's backend doesn't open TCP ports on the host. At build time, acde puts a preload (`acde-listen.js`) next to the backend that replaces `listen(P)` in `Bun.serve`, `Bun.listen`, and `net` / `http` / `https` / `tls` / `http2` with a unix socket at `<app's socket directory>/P.sock`. If no port is given, it uses `PORT` / `BUN_PORT` / `NODE_PORT`, and otherwise 3000.
+
+As a result:
+
+- Two apps can both `listen(3000)` without conflict.
+- Requests from the page to same-origin paths (`/api/x`) or to `http://localhost:<port>/…` (and `127.0.0.1`, `[::1]`, `0.0.0.0`) all go to the app's own backend.
+- UDP `bind` to a specific port is rejected (`EACCES`); ports opened by native extensions on their own aren't covered.
+
+## On Windows
+
+The same build runs on Windows, and there too the backend opens no TCP port and no named pipe. How the runtime reaches it depends on what runs it:
+
+- **Bun**: as on macOS and Linux, `listen(P)` becomes a socket file `P.sock`. Its directory (`ACDE_APP_SOCKETS`) is made anew each time the backend starts, and only the current user and the system can open it.
+- **Node.js**: Node.js cannot listen on a socket file on Windows, so nothing listens at all. The preload keeps the server that called `listen(P)`, and the runtime hands it every connection (HTTP requests and WebSocket upgrades) through a private pipe to the backend process. The backend gets `ACDE_APP_CHANNEL=fd` and no `ACDE_APP_SOCKETS`. A backend built by an acde from before this is not started on Windows; the log says `not started: acde-listen.js does not support the Windows channel (built by an older acde: acde build it again)`.
+
+To stop a backend on Windows the runtime asks it to shut down: it takes no new connections, finishes the requests in progress and exits; after 3 seconds the runtime ends it together with the processes it started.
+
+## Bundling
+
+`acde build` bundles the backend into a single ES module, `backend/server.js` (target node): npm packages are bundled in, while Node built-in modules and `bun` / `bun:*` stay as imports. The same output runs on both Bun and Node.js.
+
+## Running
+
+- The backend starts **when the app's first window opens** and stops **when its last window closes** (on macOS and Linux with SIGTERM, then SIGKILL after 3 seconds; for Windows see [above](#on-windows)). After the 4th crash within a minute, it's no longer restarted automatically.
+- It runs on Bun if `bun` is on PATH, otherwise on Node.js (≥ 22.3). `acde dev` picks based on the project's JavaScript runtime.
+- The environment is built from scratch: `ACDE_APP_ID`, `ACDE_APP_DATA`, `ACDE_APP_SOCKETS`, `PORT`, `NODE_ENV=production`, plus the session's `HOME`, `PATH`, `LANG`, and so on, and the proxy variables below. Nothing else is inherited from your terminal.
+- Proxy settings are passed on. If the session sets any of `http_proxy`, `https_proxy` or `all_proxy`, the backend gets `http_proxy`, `https_proxy`, `all_proxy` and `no_proxy` as the session has them (on macOS and Linux under both the lower-case and the upper-case names, as set; on Windows, where variable names ignore case, under the upper-case names). If none is set, the backend gets the system's manual proxy, the same settings pages use. Only Windows and macOS have one: on Windows the HTTP proxy from the user's Internet settings (a `socks=` entry becomes `all_proxy=socks4a://host:port`), set under the upper-case names; on macOS the HTTP, HTTPS and SOCKS proxies from the network settings (SOCKS becomes `socks5h://host:port`), set under both the lower-case and the upper-case names. `no_proxy` then holds the session's `no_proxy`, the system's exceptions in `no_proxy` form (`*.example.com` becomes `.example.com`, `192.168.*` becomes `192.168.0.0/16`; other wildcards, Windows' `<local>` and macOS's "exclude simple hostnames" have no `no_proxy` form and are left out), and `localhost,127.0.0.1,::1`. A proxy auto-config script or automatic proxy discovery answers per URL and can't be expressed as variables, so with those the backend gets no system proxy (on Windows, "Automatically detect settings" alone still passes the manual proxy). The settings are read each time a backend starts. Linux has no system proxy setting to read: only the session's variables count there. Your HTTP client still has to honour these variables (Bun's `fetch` and many npm clients do; Node.js's built-in `fetch` does not by default).
+- The working directory is `$XDG_DATA_HOME/acde/apps/<id>/`; the app can keep its own data here.
+- On macOS and Linux the sockets are in a directory of the session's runtime (`ACDE_APP_SOCKETS`). In 0.0.9 it is one directory per app id, `<runtime dir>/acde/apps/<id>`, shared by every session: running `acde test` while `acde dev` runs the same app leaves the dev session's backend unreachable (`cannot connect to …/3000.sock: Connection refused`) until `acde dev` is restarted. After 0.0.9, each session has its own, `<runtime pid>/<id>` in acde's runtime directory, removed when the backend stops: `$TMPDIR/acde-<uid>` on macOS, and `acde/` in `XDG_RUNTIME_DIR` (`/run/user/<uid>` on Linux when it is not set). A socket path longer than the system allows (104 bytes on macOS, 108 on Linux) is not started; the log says so.
+- Backend output goes to the runtime's log, prefixed with `[<id>#backend]`. `acde dev` prints it in your terminal.
+
+## Running it directly
+
+To debug the built backend on its own, without the runtime, give it a socket directory and load the preload that `acde build` put next to it (the commands are for macOS and Linux):
+
+```sh
+acde build
+cd .acde/backend
+ACDE_APP_SOCKETS=/tmp/my-app-sockets bun --preload ./acde-listen.js server.js
+curl --unix-socket /tmp/my-app-sockets/3000.sock http://localhost/api/hello
+```

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

@@ -0,0 +1,157 @@
+# Capabilities
+
+Pages only get the standard Web APIs. There is exactly one way into system capabilities: the built-in `acde:` modules, imported the same way as `node:fs`:
+
+```js
+import { fs } from 'acde:fs'
+import { window } from 'acde:window'
+import fs2 from 'acde:fs' // the default export is the same object
+```
+
+There is no `acde` global, and the runtime never attaches anything non-standard to `window`.
+
+Talking to other hosts needs no capability: `fetch`, `WebSocket`, and the other standard APIs work as usual, through the system's proxy when one is set. See [Web compatibility](../reference/web.md#network).
+
+## Requesting capabilities
+
+The `capabilities` in your config decide which modules an app can import:
+
+```jsonc
+{
+  "capabilities": {
+    "fs": true,
+    "openFiles": true,
+    "open": ["notes", "viewer"]
+  }
+}
+```
+
+| Capability | Grants |
+| --- | --- |
+| `fs` | `acde:fs`. `true`: the app's private folder and the folders the user picks for it. `{ "roots": ["downloads", … ] }` adds shared places; see [Files and folders](files.md) |
+| `terminal` | `acde:terminal`: pseudo-terminals |
+| `network` | `acde:network`: network settings, Wi-Fi (Linux only, including Dopame OS) |
+| `office` | `acde:office`: office document service (Linux only) |
+| `open` | Opening other apps with `acde:open`. `true` for any app, or a list of app ids |
+| `openFiles` | `acde:openPath` / `acde:handlers`, and `open(request)` without a target app: a file or a link goes to its default app |
+| `launch` | `start` in `acde:launch`: start native programs |
+| `slots` | `embed` in `acde:launch`: native programs embedded in your own window (Dopame OS only) |
+| `camera` / `microphone` | `navigator.mediaDevices.getUserMedia()` video / audio (not on Windows); the user is asked, see [below](#camera-and-microphone) |
+
+Every app can import these without requesting anything: `acde:window` (its own window), `acde:capabilities` (what it has, see [below](#acdecapabilities)), `acde:apps` (`list()` and `open()`), and `acde:open` (opening another app still needs `open`).
+
+A name that is not in the table is an error in `acde check`:
+
+- **Desktop services** are listed under `services`, not under `capabilities`: `"services": ["clock"]`, then `import { clock } from 'acde:clock'`. The app then starts only in a desktop that runs the service. See [Services](services.md).
+- **Shell modules** (`acde:windows`, `acde:packages`, `acde:session`, `acde:desktops`, `acde:inspect`, `acde:desktop`, `acde:setDefault`, `acde:permissions`) belong to the desktop. Only the desktop page, its services, and the apps bundled with a desktop (system apps) get them; see [Desktops](desktop.md#system-apps).
+
+Importing a module the app has no right to fails with a `TypeError` that names the missing declaration, and `acde check` and `acde build` report the same thing for every `import` in your source before anything runs:
+
+```text
+error: app "notes": capability "clock" is not a system capability; list desktop services under services
+error: src/main.js:1: app "notes": acde:terminal needs "terminal" in the capabilities of Notes
+error: src/main.js:2: app "notes": acde:windows is a shell module: only the desktop, its services and system apps may import it, and Notes is not a system app
+```
+
+Calling a method the app has no right to is rejected with `status: 403` (`code: 'forbidden'`), for example `open('mail')` when `open` lists only other apps.
+
+## Camera and microphone
+
+Declaring a capability is what gives the app access to it: nothing is asked, also for shared places in `fs.roots`, `terminal`, `network`, `launch` and `slots`. Only the camera and the microphone ask the user. The apps bundled with a desktop (system apps) are not asked.
+
+- **When**: the first time a page calls `navigator.mediaDevices.getUserMedia()` (or `request()`, below); the call waits for the answer. In 0.0.9, a camera or microphone the app requires (not in `optional`) is asked for when the app starts, and the window opens after the answer; after 0.0.9, it is asked for on first use too.
+- **Allowed**: the decision is stored per app (`$XDG_CONFIG_HOME/acde/permissions.json`) and the user is not asked again.
+- **Denied**: `getUserMedia()` rejects with `NotAllowedError`, as in a browser. In 0.0.9, denying a required one keeps the app from starting (`Notes: "camera" is denied by the user`, 403 `denied`) and takes it off the app list; after 0.0.9, the app keeps running and stays in the list.
+- **Who asks**: in a desktop, the desktop shows the prompt (see [Desktops](desktop.md#camera-and-microphone-prompts)). In the host window of a single app, Windows asks in a dialog; in 0.0.9, macOS and Linux show nothing. After 0.0.9, a macOS host window asks in a sheet (`Allow` / `Don't Allow`) and a Linux host window in a desktop notification with Allow and Deny (without a notification service, nothing shows).
+- **In a dev session**: answer with `acde allow` or `acde deny` (also when nothing shows, and headless), take a decision back with `acde revoke`; see [Debugging](tools.md#camera-and-microphone). Tests answer with `acde.allow()` (see [Testing](testing.md#approvals)).
+
+## Optional capabilities
+
+Everything in `capabilities` is required by default: if the platform lacks one, the app does not start. List the ones the app can run without in `optional`:
+
+```jsonc
+{
+  "capabilities": { "terminal": true },
+  "optional": ["terminal"]
+}
+```
+
+- The app also starts on a platform that lacks the capability.
+- An optional module must not be imported statically (`acde check`: `acde:terminal is optional ("terminal" is in optional): reach it with load('terminal') from @dopame/acde-api instead of importing it`). Get it with `load()`, which resolves to `null` while the module is unavailable.
+- `camera` and `microphone` have no module to load: the page calls `navigator.mediaDevices.getUserMedia()`, which asks the user the first time. See [Web compatibility](../reference/web.md#media).
+
+```js
+import { load } from '@dopame/acde-api'
+
+const terminal = await load('terminal') // null where this platform lacks it
+```
+
+Making `fs` optional makes its shared places optional too.
+
+## acde:capabilities
+
+```js
+import { capabilities } from 'acde:capabilities'
+
+capabilities.level // 1: the contract level of the runtime
+capabilities.platform // 'linux' | 'darwin' | 'win32'
+capabilities.mode // 'session' (Dopame OS) | 'desktop' (a desktop in the host window) | 'standalone' (a single app in the host window)
+capabilities.get('terminal') // { name, kind: 'system' | 'service', state, reason, optional }
+capabilities.list() // the same for every system capability and shell module, notifications, and each fs.<place> and service the app declares
+await capabilities.request('camera') // asks the user for the camera or microphone; resolves with the status
+```
+
+| `state` | Meaning |
+| --- | --- |
+| `available` | Declared and this platform has it (camera, microphone: and the user allowed it) |
+| `not-asked` | Camera or microphone, and the user was not asked yet: `request()` asks |
+| `asking` | The camera or microphone prompt waits for the user's answer |
+| `not-declared` | Not in the app's `capabilities` / `services` |
+| `unsupported` | This platform, or this way of running, lacks it |
+| `service-not-running` | The desktop service is not running |
+| `shell-only` | A shell module, and the app is not a system app |
+| `denied` | Camera or microphone: the user denied it, or the decision was taken back |
+
+`request()` of any other capability, or of one the user already answered, resolves at once with the current status.
+
+`notifications` is the standard `Notification` API, which needs no declaration: it is `available`, or `unsupported` where this way of running shows no notifications (a single app on Windows).
+
+## Types
+
+Types for every module ship in the SDK, `@dopame/acde-api`. Reference the entry point that fits the project and your editor understands the `acde:*` modules it can import:
+
+```js
+/// <reference types="@dopame/acde-api/app" />
+```
+
+- `@dopame/acde-api/app`: the modules of an app (`acde:fs`, `acde:window`, `acde:open`, ...).
+- `@dopame/acde-api/shell`: those plus the shell modules, for a desktop and its bundled apps.
+- `@dopame/acde-api`: all of them.
+
+## In a browser
+
+To preview the same code in an ordinary browser:
+
+- In a Vite project, add the `@dopame/acde-api/vite` plugin; the dev server then stubs `acde:*`. See [Frameworks](frameworks.md#vite-plugin).
+- Or load modules on demand with `load()`, which returns `null` when the module is unavailable:
+
+```js
+import { load } from '@dopame/acde-api'
+
+const fs = await load('fs')
+```
+
+## Modules
+
+| Module | Purpose | Docs |
+| --- | --- | --- |
+| `acde:window` | Your own window: title, menus, closing, state, shortcuts, events | [Windows](window.md) |
+| `acde:capabilities` | What the app has, asking for optional capabilities | [Above](#acdecapabilities) |
+| `acde:fs` | Files | [Files and folders](files.md) |
+| `acde:apps` `acde:open` `acde:openPath` `acde:handlers` | Other apps, opening files and links | [Opening apps](open.md) |
+| `acde:launch` | Native programs | [Reference](../reference/modules.md#acdelaunch) |
+| `acde:terminal` | Pseudo-terminals | [Reference](../reference/modules.md#acdeterminal) |
+| `acde:network` | Networking | [Reference](../reference/modules.md#acdenetwork) |
+| `acde:windows` `acde:packages` `acde:desktop` `acde:inspect` `acde:permissions` `acde:session` `acde:desktops` `acde:setDefault` | Shell modules: the desktop and system apps | [Desktops](desktop.md) |
+
+For full signatures, see [Reference: acde: modules](../reference/modules.md).

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

@@ -0,0 +1,73 @@
+# Configuration
+
+A project's config lives in `acde.config.jsonc` at its root (`acde.config.json` also works). JSONC allows comments and trailing commas. A `$schema` at the top gives your editor completion and validation:
+
+```jsonc
+{
+  "$schema": "./node_modules/@dopame/acde-api/config.schema.json",
+  "type": "app",
+  "id": "notes",
+  "label": "Notes",
+  "icon": "editor",
+  "entry": "index.html",
+  "size": [960, 640],
+  "capabilities": { "fs": true }
+}
+```
+
+## Apps (`"type": "app"`)
+
+| Field | Description |
+| --- | --- |
+| `id` | App id: lowercase letters, digits, and `-`. Defaults to one derived from `name` in `package.json` |
+| `label` | Display name, shown in the title bar and on the desktop |
+| `icon` | An icon name, or a `.svg` / `.png` in the project; see [Assets and icons](assets.md) |
+| `entry` | Entry point: an HTML page (default `index.html`), or a module whose default export is a `WindowApp`. Omit it when building with a framework |
+| `framework` | How to build; defaults to `auto`. See [Frameworks](frameworks.md) |
+| `capabilities` | System capabilities the app requests, such as `{ "fs": true }`; see [Capabilities](capabilities.md). Declaring one grants it; the camera and the microphone also ask the user (see [Camera and microphone](capabilities.md#camera-and-microphone)) |
+| `optional` | Names from `capabilities` that the app can run without; the app starts where this platform lacks them, and reaches them with `load()`. See [Optional capabilities](capabilities.md#optional-capabilities) |
+| `services` | Names of the [desktop services](services.md) the app uses, e.g. `["clock"]`. The app starts only where they run |
+| `size` | Default size of the window's content area, `[width, height]` in logical pixels; defaults to `[800, 600]`. The title bar is not included. A desktop opens the window at this size; a single app run by `acde dev` fills the host window, which opens at this size (see [Windows](window.md#size-and-title-bar)) |
+| `frame` | Whether the window has a system title bar; defaults to `true` |
+| `multiple` | Whether multiple windows can be open at once |
+| `mimeTypes` | File types the app can open, e.g. `["text/markdown", "image/*"]`; see [Opening apps](open.md#files-and-links) |
+| `schemes` | URL schemes of the links the app can open, lowercase and without the colon, e.g. `["mailto"]` |
+| `requests` | Kinds of request the app accepts from other apps' `open()`, e.g. `["show-image"]`; see [Opening apps](open.md#apps) |
+| `heapMb` | JS heap limit per window, in MB; defaults to 256, minimum 32 |
+| `backend` | The backend: `false` for none, or `{ "entry": "server.ts", "port": 3000 }`. Detected automatically by default; see [Backend](backend.md) |
+| `public` | Directory of static files copied as is; defaults to `public` |
+| `name` / `version` | Package name and version; taken from `package.json` by default |
+| `apiLevel` | The contract level the package is built for. Leave it out: `acde build` writes the level of the installed SDK |
+
+## Desktops (`"type": "desktop"`)
+
+| Field | Description |
+| --- | --- |
+| `id` / `label` / `description` | The desktop's id, name, and description |
+| `entry` | The desktop page; defaults to `index.html` |
+| `heapMb` | JS heap limit for the desktop page; defaults to 1024 |
+| `services` | Desktop services: name → module path, or name → `{ "module": path, "modules": [shell modules] }` for a service that uses shell modules; see [Services](services.md) |
+| `apps` | Apps bundled with this desktop (system apps). Each entry has the same fields as an app, but `id` and `entry` are required; its `capabilities` may also name shell modules, such as `"windows": true` |
+
+See [Desktops](desktop.md).
+
+## Check
+
+```sh
+acde check
+```
+
+This checks that the id is valid, the entry file exists, the icon is a known name or an existing image, service modules exist, and the framework is recognized. It also checks the declarations against the rules of the runtime: capability names, the shared places in `fs.roots`, `optional`, `services`, and every `acde:` import in the source against what the app declares. Errors make the command exit with 1; warnings and notes are only printed.
+
+```text
+error: app "notes": fs.roots "work" is not a shared place (desktop, documents, downloads, music, pictures, videos); any other folder is one the user picks (showDirectoryPicker() with "fs": true)
+error: app "notes": capability "clock" is not a system capability; list desktop services under services
+error: src/main.js:1: app "notes": acde:terminal needs "terminal" in the capabilities of Notes
+error: src/main.js:2: app "notes": acde:windows is a shell module: only the desktop, its services and system apps may import it, and Notes is not a system app
+```
+
+A path in `fs.roots` is answered with the name to write instead: `fs.roots "~/Documents" is not a shared place: write "documents", the runtime finds that folder through the system (also when it was moved)`. An `optional` name that is not in `capabilities` is reported first, on its own: `error: app notes: optional "launch" is not in capabilities (optional lists declared capabilities that the app can run without)`. That line really names the app without quotes, unlike the ones above; match either form when you read these lines by program.
+
+`acde check --platform windows` (or `macos`, `linux`) adds what that platform lacks: a required capability it does not have is an error, an optional one a note.
+
+For the full field definitions, see [Reference: acde.config.jsonc](../reference/config.md).

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

@@ -0,0 +1,165 @@
+# Desktops
+
+The Dopame OS desktop is itself an acde project: a web page that fills the screen behind every window. A desktop can import every `acde:` module this platform has except `acde:window` (which is for app windows), including the shell modules that apps do not get, and is responsible for the "system UI": the Dock, the menu bar, window switching, notifications, camera and microphone prompts, and so on. The desktop that ships with Dopame is called `dopame`; you can build your own.
+
+```sh
+acde new my-desktop --template desktop
+cd my-desktop
+acde dev
+```
+
+## Configuration
+
+```jsonc
+{
+  "$schema": "./node_modules/@dopame/acde-api/config.schema.json",
+  "type": "desktop",
+  "id": "my-desktop",
+  "label": "My Desktop",
+  "entry": "index.html",
+  "services": { "clock": "services/clock.ts" },
+  "apps": [
+    { "id": "hello", "label": "Hello", "icon": "app", "entry": "apps/hello/index.html" }
+  ]
+}
+```
+
+- `services`: [desktop services](services.md) running in the background, name → module.
+- `apps`: apps that ship with this desktop, with the same fields as an app project (`id` and `entry` are required). They are [system apps](#system-apps).
+
+For editor types in a desktop project, reference the shell entry point of the SDK: `/// <reference types="@dopame/acde-api/shell" />`.
+
+## Apps
+
+```js
+import { apps } from 'acde:apps'
+
+for (const app of await apps.list()) {
+  const button = document.createElement('button')
+  button.textContent = app.label
+  button.onclick = () => apps.open(app.id)
+  dock.append(button)
+}
+
+apps.on('changed', ({ apps }) => render(apps))
+```
+
+`app.icon` is an icon name or an image URL; the desktop decides how to draw it. An app that cannot run here is not in the list: one that requires a capability this platform lacks. `changed` fires with the new list when it changes.
+
+`apps.open(id)` rejects when the app cannot start: with `status: 404`, `code: 'unsupported_app'` for an app that requires what this platform lacks (`Viewer needs "network" (not available on macOS host windows); list it in "optional" to run without it`), and with `status: 503`, `code: 'service_not_running'` for one whose service is not running (`Viewer needs "clock" (service not running)`). In 0.0.9, an app whose required camera or microphone the user denied also rejects, with `status: 403`, `code: 'denied'` (`Viewer: "camera" is denied by the user`); after 0.0.9 it starts. The desktop also imports `acde:openPath`, `acde:handlers`, and `acde:setDefault` (see [Opening apps](open.md#files-and-links)). Installing packages and listing native programs are in `acde:packages` (`refresh`, `install`, `natives`, `runNative`).
+
+## Windows
+
+```js
+import { windows } from 'acde:windows'
+
+windows.on('open', (e) => addToTaskbar(e.window))
+windows.on('close', (e) => removeFromTaskbar(e.window))
+windows.on('state', (e) => markMinimized(e.window, e.state === 'minimized'))
+
+await windows.focus(id)
+await windows.requestState(id, 'minimized')
+await windows.animate(id, { opacity: 0, scale: 0.9, duration: 180, easing: 'ease-out' })
+```
+
+Window events: `open` `close` `title` `state` `activate` `minsize` `parent` `menus` `crash` `hang` `responsive` `attention` `ready` `show` `animated`. Any other name throws a `TypeError`. Each event is `{type: 'window<name>', window, …}`.
+
+A window's state is `normal`, `minimized`, `filled`, or `fullscreen`. The runtime carries out state changes itself, whether the app asked (`minimize()`, `requestState()`), the user pressed a title bar button, or the desktop called `windows.requestState(id, state)`; the desktop learns of every change from the `state` event (`{window, state, previous}`). `windows.list()` gives every window with its current `state`. `windows.focus(id)` or `windows.show(id)` on a minimized window brings it back in the state it had before. Hiding (`hide` / `show`) is separate from the state and only the desktop can do it. A window that hangs (`hang`) can be ended with `kill`; `close(id)` asks the app first (its `beforeclose`).
+
+## Panels
+
+For things that must float **above** app windows, such as the Dock, the menu bar, and popovers, use `pin` to turn an element of the desktop page into its own always-on-top window:
+
+```js
+import { desktop } from 'acde:desktop'
+
+const panel = desktop.pin(document.querySelector('#dock'), { margin: 8, reserve: { edge: 'bottom' } })
+// The system re-measures automatically when the element changes; you can also do it by hand:
+panel.update()
+panel.reserve({ edge: 'bottom', thickness: 64 }) // or null to reserve nothing
+panel.unpin()
+```
+
+The element stays in the same document, so its state, React tree, and events work as usual. The element must be a stacking context (for example, `position` plus `z-index`, or `isolation: isolate`); its `backdrop-filter` becomes real frosted glass across windows.
+
+`reserve` keeps a strip along one edge of the screen (`top`, `bottom`, `left`, `right`) free of filled windows: the work area shrinks by it, `filled` windows follow, and apps see the new `workArea` in `acde:window`'s `output`. Without `thickness` the strip reaches from the edge to the far side of the panel. A panel without `reserve` takes no space.
+
+## Title bars
+
+The runtime draws the title bar of every app window; the desktop sets how it looks and behaves:
+
+```js
+desktop.setDoubleClick('fill') // double-clicking a title bar: 'fill' | 'minimize' | 'none'
+desktop.setFrameTheme({
+  active: { background: '#202030', title: '#ffffff' },
+  inactive: { background: '#2a2a35', title: '#a0a0b0' },
+  buttonStyle: 'glyphs', // or 'dots'
+  buttonSide: 'right', // or 'left'
+  titleAlign: 'start', // or 'center'
+})
+desktop.setFrameTheme(null) // back to the default look
+```
+
+Colors are `#rgb`, `#rgba`, `#rrggbb`, `#rrggbbaa`, `rgb()` or `rgba()`; each of `active` and `inactive` takes `background`, `title`, `line`, and `buttons`. Add `light: { active, inactive }` for the windows whose page does not declare dark support (no `dark` in its `color-scheme`, see [Windows](window.md#size-and-title-bar)); `active` and `inactive` are then for pages that do. Every call gives the whole theme. A bad value throws a `TypeError`; an unknown key is ignored, with a warning in the log.
+
+## Notifications, downloads, and shortcuts
+
+```js
+desktop.on('notification', (n) => toast(n.title, n.body, n.icon))
+desktop.on('download', (d) => showDownload(d.name, d.path))
+desktop.on('edge', ({ edge, entered }) => { if (edge === 'top') menuBar.hidden = !entered })
+
+await windows.shortcut('ctrl+alt+t', 'desktop')
+desktop.on('shortcut', ({ key }) => { if (key === 'ctrl+alt+t') apps.open('term') })
+```
+
+Shortcut scopes: `session` (highest, cannot be overridden) → app-level shortcuts of the focused window → `desktop`. On conflicts, the first registration wins.
+
+`edge` fires when the pointer reaches (`entered: true`) or leaves an edge of the screen (`top`, `right`, `bottom`, `left`), without taking focus: a desktop that hides its menu bar or Dock over a full-screen window shows them again with it.
+
+## Camera and microphone prompts
+
+The camera and the microphone ask the user the first time an app uses them (see [Capabilities](capabilities.md#camera-and-microphone)); no other capability asks. In 0.0.9, one that an app requires is asked for when the app starts, with `reason: 'launch'`; after 0.0.9, `reason` is always `'request'`. The desktop shows these prompts and passes the answers on with `acde:permissions`:
+
+```js
+import { permissions } from 'acde:permissions'
+
+const ask = async (prompt) => {
+  // prompt: { id, app, label, capability: 'camera' | 'microphone', reason: 'request' }
+  const allow = await showPrompt(`Allow ${prompt.label} to use ${prompt.capability}?`)
+  await permissions.answer(prompt.id, allow)
+}
+
+permissions.on('prompt', ask)
+for (const prompt of await permissions.pending()) ask(prompt) // prompts raised before the page subscribed
+```
+
+`permissions.list(app?)` returns the stored decisions (`{app, label, capability, decision: 'granted' | 'denied'}`; a folder the user picked for an app is listed as `fs.folder-…` with `folder: {label, exists}`), and `permissions.revoke(app, capability)` takes one back, resolving to `false` when there was none. The `answered` event (`{id, app, capability, allowed}`) reports each answer.
+
+## System apps
+
+The apps in a desktop's `apps` ship in the same package as the desktop, which makes them **system apps**. They differ from other apps in three ways:
+
+- They may declare shell modules as capabilities and import them: `"capabilities": { "windows": true, "permissions": true }`. An app outside a desktop package that declares one fails `acde check` (`acde:windows is a shell module: only apps of a desktop package (system apps) may declare it`).
+- The user is not asked about their camera and microphone.
+- With shared places in `fs.roots`, their `acde:fs` roots carry the folder's `path`, and `fs.locate()` / `fs.openPath()` work.
+
+A system app imports only what it declares: `import 'acde:session'` without `"session": true` fails with `acde:session is a shell module: declare "session" in the capabilities of <label>`.
+
+## Other modules
+
+- `acde:session`: `logout()`, `reboot()`, `poweroff()`, `setLanguage(tag)`. Only the desktop page and its system apps that declare `"session": true` can use it; an ordinary app cannot.
+- `acde:desktops`: `list()`, `choose(id, remember?)` to switch desktops.
+- `acde:launch`: `start(argv)` runs a native program, `embed(argv)` embeds one in a window (Dopame OS only).
+- `acde:inspect`: turns the screen into a text semantic tree and acts on it by ref (for AI agents). See the [reference](../reference/modules.md#acdeinspect).
+
+## Developing in a desktop
+
+While developing an app, you can also run it inside a desktop:
+
+```sh
+acde dev ./my-app --desktop ./my-desktop
+acde dev ./my-app --desktop dopame
+```
+
+See [acde dev](dev.md).

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

@@ -0,0 +1,66 @@
+# acde dev
+
+```sh
+acde dev
+```
+
+This does three things:
+
+1. Builds the project (into `.acde/`).
+2. Starts acdert, which opens **one** window on your computer: the **host window**, standing in for the screen of a Dopame OS machine.
+3. Watches the project's files, and on every change rebuilds and reloads the affected windows.
+
+A running `acde dev` is a **dev session**: the [debugging commands](tools.md), [MCP](mcp.md), and `acde test` all work with one.
+
+## What runs
+
+| Command | What you get |
+| --- | --- |
+| `acde dev` (app project) | Just this app, filling the host window; closing the app ends the session |
+| `acde dev` (desktop project) | This desktop |
+| `acde dev --app ID` | Picks one app when the project has several |
+| `acde dev ./a ./b` | Several projects together, in one desktop |
+| `acde dev ./app --desktop ./my-desktop` | The app runs in the given desktop project |
+| `acde dev ./app --desktop dopame` | The app runs in the `dopame` desktop, once it is [installed](../start/install.md#install-the-dopame-desktop) |
+
+With several projects or `--desktop`, the desktop is chosen like this: the value of `--desktop`; otherwise the only desktop project among them; otherwise `dopame`. A `--desktop` value that looks like a path (contains `/`, or is `.` / `..`), or that names a project in the current directory, is treated as one more project.
+
+The session is ready when `acde webs`, run from the project directory, lists the app's page. Declaring a capability grants it, so the app opens its window right away. The camera and the microphone wait for an answer, which `acde allow` or `acde deny` gives from another terminal: in 0.0.9, an app that declares one opens its window only once answered; after 0.0.9, only a page that asks for one waits. See [Camera and microphone](tools.md#camera-and-microphone).
+
+`--headless` doesn't open a window (a **headless session**), which suits scripts and CI. Pages still render and screenshots still work. It still needs a GPU, so it doesn't run on Linux CI machines without one (macOS CI runners work); see [Platform support](../reference/platforms.md).
+
+On a machine without a display, such as a Linux server over ssh, use `--headless` and look at the session with `acde shot`, `acde screen` and `acde inspect` (see [Without a display](tools.md#without-a-display)). On Linux, `acde dev` without `--headless` (and `acde test --headed`) stops at once when neither `WAYLAND_DISPLAY` nor `DISPLAY` is set, and says so. If acdert exits with an error anyway, `acde dev` adds the same `--headless` hint after acdert's own messages.
+
+## Reloading
+
+- Changes within 150 ms are merged into one build, and only the project that changed is rebuilt.
+- Apps: the window is closed and reopened at its previous position and size (or the new `size`, if that changed in the config). Desktops: the desktop page reloads; services are not restarted.
+- State survives a reload where possible: form values, scroll position, focus, and selection are restored. The page itself reloads: there is no hot module replacement, so component state (a React counter, Vue state, values in memory) starts over; see [Frameworks](frameworks.md#saving-in-acde-dev).
+- A failed build prints a single error line, and windows keep showing the last good build.
+- Changes in `node_modules`, `.acde`, `.git`, framework output directories such as `dist` / `build` / `.next`, `*.e2e.*` test files, and `__screenshots__` do not trigger a build.
+
+## Build output
+
+By default the build goes into the project's `.acde/`. `--out DIR` changes that: an absolute path is used as is, and a relative path is resolved against **the project being built**. Dev session builds reach acdert only through `ACDE_PATH`; they are **not** installed into the local package directory.
+
+## Stopping
+
+`acde dev` ends on Ctrl+C, when you close the window, or when acdert exits. Its exit code is the same as acdert's. To end one running in the background, run `acde stop` from the project directory (or `acde stop --session <pid>`): it asks acdert to quit, waits for `acde dev` to exit, and prints `acde: stopped acde dev <pid>`.
+
+## Logs
+
+The terminal shows builds and reloads, the pages' `console.*` output (lines such as `6975.356 I acde js: …`) and uncaught errors (`[<app>#<window>] page error: …`), backend output (`[<app>#backend] …`), what happens to an app (its backend started or stopped, its state restored after a reload, an `alert()`, a permission prompt waiting for an answer), and the runtime's warnings and errors (lines such as `14.383 W main …`). After 0.0.9, the runtime's own info log (startup timings, GPU and the like: `14.382 I main …`) is left out and `acde dev --verbose` shows it too; in 0.0.9 it is always shown.
+
+To watch them from another terminal, or to read them from a script, use `acde console` / `acde network` from the [debugging tools](tools.md).
+
+## DevTools
+
+After 0.0.9, press **F12** in the host window (fn+F12 on a Mac keyboard) to open the DevTools of Chrome or Edge on the page in that window: Elements, Console, Network, and Sources with breakpoints. The terminal says `acde: opened DevTools for <page> in <browser>`; F12 again brings that DevTools window to the front. `acde devtools [web]` does the same from another terminal (see [DevTools](tools.md#devtools)). The page never sees that F12; F12 with Ctrl, Shift, Alt or Cmd still reaches it.
+
+DevTools open in a browser profile of acde's own, not your everyday one. `ACDE_BROWSER` names another browser; without Chrome or Edge, or with `ACDE_BROWSER=none`, the terminal prints the address to paste into one instead.
+
+## Runtime
+
+`acde dev` runs the acdert named by `ACDERT` (a path, or a name on PATH), otherwise the acdert the installer put next to acde, otherwise the `acdert` on PATH. `acde --version` shows which one it finds, and `acde doctor` checks that it runs here; see [The runtime](../start/install.md#the-runtime) and [Check the setup](doctor.md).
+
+When acdert exits before the session is ready (for example because it cannot use the GPU), `acde dev` prints its log line, then `acde: acdert exited (1) before it was ready; acde doctor checks the runtime, the GPU and this setup`, and exits with that code.