acrylblends 1.0.9 → 1.1.0

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/guides/bring-your-own-tool.md

@@ -119,6 +119,8 @@ export async function apply(ctx: Context, config: { path?: string } = {}): Promi
 
 The suite is the contract: it runs the same cases against every provider. A test gives it a fresh store for each case and a way to reopen the same storage.
 
+The suite imports `vitest` from your project, where `--suite` put it as a dev dependency. The same suite is in the package as `acrylblends/kv/conformance` (and `acrylblends/db/conformance`), and there it runs on the vitest your test hands it: `import * as vitest from 'vitest'` and `describeKvConformance('my-provider', open, vitest)`. The package does not declare `vitest` as a peer, so a production install of an app that uses `acrylblends` carries no vitest, vite or native build tools (1.0.10 and later; before that, `pnpm deploy --prod` pulled them in).
+
 ```ts no-check
 // test/kv-lowdb.spec.ts
 import { mkdir, mkdtemp } from 'node:fs/promises'

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).