acrylblends 1.0.10 → 1.2.0

package/docs/framework/agents/index.md

@@ -7,7 +7,7 @@ A coding agent (Claude Code, Codex, OpenCode, Copilot and others) builds on Acry
 - `AGENTS.md`: where the API is, how a feature is built (an `Acryl` app mounted with `ctx.router.route`, a plugin registered in `src/app.ts` and `blend.yaml`, a state cell),
   the defaults and how each is swapped, the things that surprise people, and what must pass before a task is done (`npm test` and `npm run check`).
 - `CLAUDE.md`: the same text as `AGENTS.md`, so tools that read either file read the same guide.
-- One skill, `app-guide`, in `.claude/skills/app-guide/SKILL.md` and `.agents/skills/app-guide/SKILL.md` (the same text): where to read first, the one plugin folder, the defaults, the door, and what "done" means.
+- Two skills, `acryl-app` and `cordis-plugin`, in `.claude/skills/<name>/SKILL.md` and `.agents/skills/<name>/SKILL.md` (the same text in both places): how the app is put together and how to change and check it through the door, and how to add a feature as a Cordis plugin.
 - `.gitignore` lists `.acryl/`, the folder the door keeps its secret and state in, so `git add -A` stages none of it.
 
 ## One plugin folder

package/docs/framework/api/summary.md

@@ -131,7 +131,7 @@ Do not start timers inside a handler for keep-alives; let the plugin own one tim
 | `ctx.nodeServer.url`, `ctx.nodeServer.port` | `nodeServer` (`acryl-node-server`) | without the Host: one Node server for the whole router; options `hostname` (`127.0.0.1`), `port` (`0`), `scan` (`20`). See [Node server](../cordis/node-server.md) |
 | `ctx.state.cell(key, initial)` | `state` (`acryl-state`) | a writable cell owned by the plugin: `get()`, `set(value)`, `update(fn)`, `subscribe(fn)` returning an unsubscribe |
 | `ctx.state.derive(key, [cells], fn)` | `state` | a read-only cell computed from others |
-| `GET /api/state/:key`, `GET /api/state/:key/events` | `state` | each cell over the router, read-only; `useCell(cell)` from `acryl-state/react` in a React page |
+| `GET /api/state/:key`, `GET /api/state/:key/events`, `GET /api/state/ws`, `GET /api/state/client.js` | `state` | each cell over the router, read-only; `watch(key, fn)` of `/api/state/client.js` follows keys in a page over one WebSocket (event streams as the fallback); `useCell(cell)` from `acryl-state/react` in a React page |
 
 Everything a plugin registers this way (mounts, cells, handlers) goes away when the plugin unloads, and comes back once when it reloads:
 see [Plugin lifecycle and disposal](../cordis/plugin-lifecycle.md).

package/docs/framework/getting-started/desktop.md

@@ -1,6 +1,7 @@
 # Desktop
 
-An Acryl app also runs as a desktop app: an Electron window opens on the app's own server. It is the same app and the same code as `npm run dev`; nothing in the app changes. This page covers a plain Acryl app (the `nodejs`
+An Acryl app also runs as a desktop app: an Electron window opens on the app's own server. It is the same app and the same code as `npm run dev`; nothing in the app changes. A Blend app that runs inside the ACRYL frame
+(it has `scripts/ide-host.mjs`) gets the whole frame in the window, the same one `npm run dev` serves to the browser: see [The frame in the window](#the-frame-in-the-window). This page covers a plain Acryl app (the `nodejs`
 template) and a Blend app (the `agent` template or any other `acrylblends init` template). It runs from source today: packaging a distributable app (dmg, exe, deb) is not part of it yet.
 
 ## Add it
@@ -26,10 +27,28 @@ In a Blend app, the same two commands (`npx acrylblends add desktop`, `npm insta
 
 ## What `npm run desktop` does
 
-1. Serves the app on `127.0.0.1` with a free port: for a plain app, `app.fetch` from `src/app.ts` (`export default app`) through `acrylblends/node-server`; for a Blend app, its own `createApp`.
+1. For a frame app, attaches to the running frame or starts its host (see [The frame in the window](#the-frame-in-the-window)). Otherwise it serves the app on `127.0.0.1` with a free port: for a plain app, `app.fetch` from `src/app.ts` (`export default app`) through `acrylblends/node-server`; for a Blend app, its own `createApp`.
 2. Takes a single-instance lock: a second launch of the same app focuses the first window and exits.
-3. Opens one window on the server's address, with a locked-down renderer (context isolation, no Node in the page, the sandbox, web security). Navigation stays on the app's own origin; any other link opens in the system browser.
-4. When the window closes (or on SIGINT or SIGTERM), stops the server and exits.
+3. Opens one window on the server's address, with a locked-down renderer (context isolation, no Node in the page, the sandbox, web security). Navigation stays on the app's own origin; a link to any other `http(s)` or `mailto` address opens in the system browser.
+4. When the window closes (or on SIGINT or SIGTERM), stops the server or frame host it started (never one it attached to) and exits.
+
+## The frame in the window
+
+A Blend app made with the frame (`npm run dev` runs `scripts/ide-host.mjs`) opens the ACRYL frame in its desktop window, not only its page: the left panel with the
+projects and sessions, the right panel with Files, Changes and Review, Settings, terminal tabs, the DSH chat, and the app's own page in a browser tile. It is the
+same frame the browser shows; the desktop builds nothing of its own.
+
+1. When the frame already runs for this folder (`npm run dev` in another terminal), the window attaches to it: it reads the address the host keeps in
+   `.acrylblends/frame-url.json` (owner-only, with the launch token) and opens it. Closing the window leaves that host running.
+2. Otherwise the window starts the host itself, exactly as `npm run dev` does (the same npm and Node that ran `npm run desktop`; the host never runs inside
+   Electron), and opens the address it prints. Closing the window stops that host and everything it started, including its terminals, so its port is free
+   again. Ctrl-C in the terminal does the same: Electron runs in a process group of its own, and `npm run desktop` passes it exactly one signal (a second
+   one would end Electron before it could stop the host).
+3. Navigation follows ACRYL Desktop's rule: the frame's own address stays in the window, and its tiles (the app's page in an iframe) load freely. A link to any
+   other `http(s)` or `mailto` address opens in the system browser, and nothing else opens at all.
+4. The door's `window list` shows each window's address without the launch token.
+
+The application menu's `Settings...` (`Cmd+,` on macOS, in the app menu; `Ctrl+,` and the File menu on Windows and Linux) opens the frame's own Settings, the dialog the left panel's Settings button opens. `acrylblends.desktopPath` does not apply to a frame app, because the frame opens the app's page in its tile on first run.
 
 ## The first launch downloads Electron
 

package/docs/framework/guides/create-acrylblends.md

@@ -16,7 +16,7 @@
 
 Every template is a Cordis app: `blend.yaml` lists the plugins that are mounted, every plugin is a folder in `plugins/`, and the app is started by `src/main.ts`. A bare template name after the directory is the same as `--template`: `npm create acrylblends@latest my-app notes`. `bun` is no longer a template; the framework still runs on Bun (see [Bun](../getting-started/bun.md)), but a new app is a Cordis app on Node.
 
-Every template includes `AGENTS.md` and `CLAUDE.md` (the same text), one skill (`app-guide`) in `.claude/skills/` and `.agents/skills/`, and a copy of these docs in `docs/framework/`, so a coding agent working in the folder reads the
+Every template includes `AGENTS.md` and `CLAUDE.md` (the same text), two skills (`acryl-app`, `cordis-plugin`) in `.claude/skills/` and `.agents/skills/`, and a copy of these docs in `docs/framework/`, so a coding agent working in the folder reads the
 API from the folder.
 
 ## Passing arguments

package/docs/framework/guides/production.md

@@ -48,6 +48,26 @@ Installing a plugin (`ctx.extensions.install`, the door's `plugin add`, the buil
 - It **stops**: reading any file outside the tool's own folder; writing files; starting child processes or workers; loading native addons; using the inspector. It gets an empty environment (no keys, no paths). It is killed after a time limit and capped in memory and output size. Calls are independent: nothing survives into the next one.
 - It **does not stop**: network access (Node 24 has no network permission: restrict egress outside the process where that matters), and it does not apply to plugins installed live (those are not run in the sandbox).
 
+## The address and the port
+
+A server made from a template listens on `127.0.0.1` and starts looking for a free port at a number of its own (3100 and up, chosen from the app's folder). A hosting platform tells the process where to listen with `PORT`, and a container needs `0.0.0.0` to be reached from outside. The app reads four variables, in this order:
+
+| What | First | Then | Otherwise |
+| --- | --- | --- | --- |
+| The port to start from (`0` for any free port) | `ACRYLBLENDS_PORT` | `PORT` | a number of its own, from the app's folder |
+| The interface | `ACRYLBLENDS_HOST` | `HOST` | `127.0.0.1` (this machine only) |
+
+`PORT` and `HOST` have been read since 1.1.0; before it, the `agent` and `blank` templates ignored `PORT` (`PORT=3299` still listened on the app's own number). If the port is taken the server tries the next ones, and the line it prints at start (`app listening on http://0.0.0.0:3299`) says which it got; a platform that routes to a fixed port should be given one that is free. For example, on a plain server:
+
+```sh
+npm ci --omit=dev
+NODE_ENV=production HOST=0.0.0.0 PORT=3299 npm start
+# app listening on http://0.0.0.0:3299 (data in /srv/app/.acrylblends; ...)
+curl http://127.0.0.1:3299/health
+```
+
+Putting the app on `0.0.0.0` makes it reachable by anyone who can reach the machine: put the login or the proxy in front first (see the checklist below).
+
 ## Checklist for a deployment
 
 1. `NODE_ENV=production` (the process manager or the Dockerfile sets it; the templates' Dockerfile does).