acrylblends 0.7.7 → 0.8.0

package/docs/framework/guides/bring-your-own-tool.md

@@ -0,0 +1,216 @@
+# Bring your own tool: a provider of a port
+
+Every choice in an app is a plugin behind a port, and what the app starts with is only a fallback. Any outside npm tool (a database, a store, a renderer, an auth library) joins the
+app as another **provider** of the same port: a plugin that implements the port's interface on top of the tool and provides the service by its name. The code that uses the port
+does not change. The port's **conformance suite** decides whether your provider is accepted, whoever wrote it. And because Cordis finds services by name, the app can swap the
+provider **while it runs**: the plugins that use the port wait, and carry on when the new provider arrives. A person does it, or an agent working in the app folder, through the door.
+
+This page does it once, from start to end, with a real tool: [lowdb](https://github.com/typicode/lowdb), a small JSON-file database, becomes a provider of the `kv` port ([Data](data.md#a-tiny-app-kv)).
+Every step runs as written: the code on this page is extracted and run against a fresh app by `scripts/verify-byo-tool.mjs`.
+
+You need an app with the `extensions` plugin, which installs plugins while the app runs: `npx acrylblends init my-app --template agent`, then `cd my-app` and `npm install`.
+
+## 1. Bring the port, its suite and a way to run it
+
+```sh
+npx acrylblends add kv --suite
+npm install
+```
+
+`add kv` copies the port (`plugins/acryl-kv`) and the JSON-file provider (`plugins/acryl-kv-json`) and gives your plugins the names `#acryl-kv` and `#acryl-kv-json` (entries in `package.json` "imports").
+`--suite` also copies the port's conformance suite (`#acryl-kv/conformance`) and adds `vitest`, which runs it. The same works for the `db` port: `npx acrylblends add db --suite`.
+
+## 2. Install the tool
+
+```sh
+npm install lowdb
+```
+
+## 3. Write the provider
+
+A provider is a folder in `plugins/` with an `index.ts` that exports `name`, and `apply(ctx)` which provides the service. Keep the tool behind a plain function that returns the port's interface (`openKv`
+here), so tests and plain code use it without Cordis, and let `apply` be a thin wrapper that provides it for as long as the plugin runs.
+
+The port gives you the checks every provider must make alike (`checkKey`, `encodeValue`, `decodeValue`, `runChange`, `compareKeys`), so a bad call fails the same way on a file, on SQL and on your tool.
+
+```ts no-check
+// plugins/kv-lowdb/index.ts
+import { join } from 'node:path'
+import type { Context } from '@deepseek-ai/cordis'
+import { checkKey, compareKeys, decodeValue, encodeValue, KV_SERVICE, runChange } from '#acryl-kv'
+import type { Kv, KvOpened } from '#acryl-kv'
+import { Low } from 'lowdb'
+import { JSONFile } from 'lowdb/node'
+
+/** The kv port on lowdb: one JSON file, written atomically by lowdb after every change. */
+export async function openKv({ path }: { path: string }): Promise<KvOpened> {
+  const db = new Low<Record<string, unknown>>(new JSONFile(path), {})
+  await db.read()
+  // One call at a time, in order: that is what makes `update` atomic and lets `close` wait for the writes in flight.
+  let queue: Promise<unknown> = Promise.resolve()
+  let closed = false
+  const run = <T>(work: () => Promise<T>): Promise<T> => {
+    if (closed) return Promise.reject(new Error('the kv store is closed'))
+    const result = queue.then(work)
+    queue = result.catch(() => {})
+    return result
+  }
+  // A copy of the stored value, so changing what `get` returned changes nothing stored.
+  const copy = (key: string): unknown =>
+    key in db.data ? decodeValue(encodeValue(db.data[key])) : undefined
+  const kv: Kv = {
+    get: <T>(key: string) =>
+      run(async () => {
+        checkKey(key)
+        return copy(key) as T | undefined
+      }),
+    set: (key, value) =>
+      run(async () => {
+        checkKey(key)
+        db.data[key] = decodeValue(encodeValue(value))
+        await db.write()
+      }),
+    update: <T>(key: string, change: (current: T | undefined) => T) =>
+      run(async () => {
+        checkKey(key)
+        const next = runChange(change, copy(key) as T | undefined)
+        db.data[key] = decodeValue(encodeValue(next))
+        await db.write()
+        return copy(key) as T
+      }),
+    delete: (key) =>
+      run(async () => {
+        checkKey(key)
+        delete db.data[key]
+        await db.write()
+      }),
+    list: (prefix = '') =>
+      run(async () =>
+        Object.keys(db.data)
+          .filter((key) => key.startsWith(prefix))
+          .sort(compareKeys),
+      ),
+  }
+  return {
+    kv,
+    async close() {
+      closed = true
+      await queue
+    },
+  }
+}
+
+export const name = 'kv-lowdb'
+
+/** As a plugin: provide `kv` for as long as the plugin runs; the store closes after `kv` is withdrawn. */
+export async function apply(ctx: Context, config: { path?: string } = {}): Promise<void> {
+  const file = config.path ?? join(ctx.appInstance.home, 'kv-lowdb.json')
+  await ctx.effect(async function* () {
+    const opened = await openKv({ path: file })
+    yield () => opened.close()
+    yield ctx.reflect.provide(KV_SERVICE, opened.kv)
+  }, `kv-lowdb: ${file}`)
+}
+```
+
+(A block whose first line is a path comment is the file of that name.)
+
+## 4. Pass the suite
+
+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.
+
+```ts no-check
+// test/kv-lowdb.spec.ts
+import { mkdir, mkdtemp } from 'node:fs/promises'
+import { join } from 'node:path'
+import { describeKvConformance, type KvUnderTest } from '#acryl-kv/conformance'
+import { openKv } from '../plugins/kv-lowdb/index.ts'
+
+const underTest = async (path: string): Promise<KvUnderTest> => {
+  const opened = await openKv({ path })
+  return {
+    kv: opened.kv,
+    close: opened.close,
+    reopen: async () => {
+      await opened.close()
+      return underTest(path)
+    },
+  }
+}
+
+// A fresh file per case, in a folder of the project (a sandboxed agent may not write to the system temp folder).
+describeKvConformance('kv-lowdb', async () => {
+  await mkdir('.acrylblends', { recursive: true })
+  return underTest(join(await mkdtemp(join('.acrylblends', 'kv-lowdb-')), 'kv.json'))
+})
+```
+
+```sh
+npx vitest run test/kv-lowdb.spec.ts
+```
+
+All the cases must pass. A failure names the rule that broke (`counts fifty concurrent updates to exactly fifty`, `keeps what was written across close and reopen`, ...): fix the provider, not the test.
+
+## 5. Make the default swappable, and swap
+
+A provider that the app's code mounts at start (a row of `blend.yaml`) is fixed until the next start. To swap while the app runs, install both the default and yours as plugins of the app. A one-line plugin
+names the default:
+
+```ts no-check
+// plugins/kv/index.ts
+export { apply, Config } from '#acryl-kv-json'
+export const name = 'kv'
+```
+
+Start the app and open it in a browser (`npm run dev`). The door is the command `.acryl/bin/acryl` in the app folder:
+
+```sh
+.acryl/bin/acryl plugin add plugins/kv
+```
+
+Any plugin that declares `inject: ['kv']` now has a store. This one counts visits:
+
+```ts no-check
+// plugins/visits/index.ts
+import type { Context } from '@deepseek-ai/cordis'
+import { Acryl } from 'acrylblends'
+import type {} from '#acryl-kv'
+
+export const name = 'visits'
+export const inject = ['router', 'kv']
+
+/** GET /visits counts the visits in the kv store, whichever provider holds it. */
+export function apply(ctx: Context): void {
+  ctx.router.route(
+    '/',
+    new Acryl().get('/visits', async (c) =>
+      c.json({ visits: await ctx.kv.update<number>('visits', (n) => (n ?? 0) + 1) }),
+    ),
+  )
+}
+```
+
+```sh
+.acryl/bin/acryl plugin add plugins/visits
+curl <the address npm run dev printed>/visits       # {"visits":1}, then 2, then 3
+```
+
+Now swap. Two providers of one service cannot run together (the second is refused and nothing changes), so take the default out and put yours in:
+
+```sh
+.acryl/bin/acryl plugin remove kv
+.acryl/bin/acryl plugin list            # visits: pending, missing kv
+.acryl/bin/acryl plugin add plugins/kv-lowdb
+curl <the address>/visits       # {"visits":1}: served again, by the same process
+```
+
+`visits` was never edited. While no provider existed its route was gone and its state was `pending`; the moment `kv-lowdb` provided `kv` it started again. The process did not restart, and the swap survives a
+restart: the app remembers what was installed.
+
+## What to know
+
+- **Data does not move by itself.** The new store starts empty (the visits counted from 1 again). To carry it over, copy before you swap, in a script or a plugin: `copyKv(source, target)` from `#acryl-kv` copies one store into another.
+- **A failed install changes nothing.** A provider that throws on start, or that cannot import something, is refused and the previous state stays. To go back: `plugin remove kv-lowdb`, then `plugin add plugins/kv`.
+- **The suite checks the port, not your tool.** It cannot know that lowdb loses a write on a power cut. Read what the tool promises about durability before you trust it with more than a demo.
+- **Other ports and tools work the same way.** `db`: `npx acrylblends add db --suite`, wrap a driver or an ORM behind `Db`, pass `describeDbConformance`. Keep the opener rule ([Data](data.md#why-the-database-is-opened-in-one-place)): only the file that mounts the provider imports the tool.
+- **An agent can do all of it.** Give a coding agent in the app folder the page and one line: "wrap `<package>` as a provider of the `kv` port, pass its suite, and swap it in through the door". `AGENTS.md` in the app names the door.

package/docs/framework/guides/client-modules.md

@@ -149,8 +149,9 @@ For a request that streams its answer and a Stop button (an `AbortController` ke
 - JSX in a client module always compiles for the DOM renderer (`acrylblends/jsx/dom`), whatever the server's `tsconfig.json` says. A file's
   own `/** @jsxImportSource ... */` comment still wins.
 - `acrylblends/jsx/dom`, its `jsx-runtime`, `jsx-dev-runtime` and `client` are one browser module (`@acrylblends/jsx-dom.js`), and
-  `acrylblends/client` is another (`@acrylblends/client.js`). Neither imports anything. The same app serves them, and each import is
-  rewritten to a URL relative to the module, so the setup works under whatever path you route `clientModules` at.
+  `acrylblends/client` is another (`@acrylblends/client.js`), and `acrylblends/read-sse` (the reader of a POST event stream, see
+  [Streaming](../helpers/streaming.md#reading-a-post-event-stream-in-the-browser)) a third (`@acrylblends/read-sse.js`). None imports anything. The same app
+  serves them, and each import is rewritten to a URL relative to the module, so the setup works under whatever path you route `clientModules` at.
 - Import your own modules with their file names, as the browser fetches them: `import { label } from './parts/label.ts'`.
 - Another package (`import confetti from 'canvas-confetti'`) is left as it is: add an
   [import map](https://developer.mozilla.org/docs/Web/HTML/Element/script/type/importmap) to the page for it, or use a bundler.
@@ -185,7 +186,7 @@ Compile the client folder once when you build, as the `build` script of your `pa
 }
 ```
 
-It writes each module compiled to `dist/client` at the same path and file name, so the page's URLs stay the same, and copies the two
+It writes each module compiled to `dist/client` at the same path and file name, so the page's URLs stay the same, and copies the three
 browser modules to `dist/client/@acrylblends/`. Run it where `typescript` is installed, before the development dependencies are removed.
 
 With `NODE_ENV=production` and the `compiled` option set, `clientModules` serves only that folder and compiles nothing. A module that is in

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

@@ -7,13 +7,14 @@
 
 | Template | What you get |
 | --- | --- |
-| `nodejs` | an Acryl application served with `serve()` from `acrylblends/node-server`; run with Node.js 22.19 or newer |
+| `nodejs` | a web app: routes, a server-rendered JSX page and a client component, mounted by the app's own plugin; run with Node.js 22.19 or newer |
 | `notes` | a full-stack starter: accounts (scrypt, cookie session), notes in SQLite through the [`db` port](data.md) with numbered migrations, validated forms, search, a JSON API with a typed test client, csrf, a test for every route, a client-component counter |
 | `chat` | an AI chat starter: the answer streams token by token from an OpenAI-compatible API (DeepSeek by default, key only from `DEEPSEEK_API_KEY`), a client component with a Stop button that also stops the request to the model, history in SQLite through the [`db` port](data.md), tests with a mock model |
-| `bun` (experimental) | an Acryl application with `export default app`, run with `bun` |
 | `acryl-app` | a Cordis app built from plugins, with an agent that can extend it while it runs (the same app `npx acrylblends init --template agent` creates) |
 
-Every template includes `AGENTS.md` and `CLAUDE.md` (which imports `AGENTS.md`) and a copy of these docs in `docs/framework/`, so a coding agent working in the folder reads the
+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
 API from the folder.
 
 ## Passing arguments
@@ -50,7 +51,7 @@ bun create acrylblends@latest my-app --template nodejs
 | :-- | :-- | :-- |
 | `[directory]` | The folder to create. It must not exist or must be empty. Asked for when it is missing. | `my-app` |
 | `[source]` | A template from outside the package: `github:owner/repo[#ref]`, `@scope/name[@version]` or a packed `.tgz` file. See [Templates from a repository or a package](#templates-from-a-repository-or-a-package). | `github:acme/starter` |
-| `--template <template>` | One of `nodejs`, `notes`, `chat`, `bun` (experimental), `acryl-app`. Skips the template question. | `--template bun` |
+| `--template <template>` | One of `nodejs`, `notes`, `chat`, `acryl-app`. Skips the template question; a bare name after the directory means the same. | `--template notes` |
 | `--install` | Install the dependencies with the package manager after creating the project. For a template from a source, the install scripts it will run are listed first. | `--install` |
 | `--pm <packageManager>` | The package manager for `--install`: `npm`, `pnpm`, `yarn` or `bun`. Defaults to the one that started the initializer. | `--pm pnpm` |
 | `--yes`, `-y` | Ask nothing: use `nodejs` unless `--template` is given, and the directory `acryl-app`. | `-y` |

package/docs/framework/guides/data.md

@@ -2,16 +2,17 @@
 
 An app that keeps records (users, notes, orders) keeps them in a SQL database, and reaches it through one small interface, `db`. Handlers and
 stores take a `Db` as an argument and never import a driver, so the file or server behind it can change without touching them. SQLite is the
-provider today; a Postgres provider (Postgres or Supabase through `DATABASE_URL`) is planned and serves the same interface.
+provider in `acrylblends`. Postgres (or Supabase, through `DATABASE_URL`) is an optional plugin, `acryl-db-postgres`, that serves the same
+interface; it is not part of `acrylblends` or the templates, and an app adds it only when it must use Postgres.
 
 ## Choosing
 
 | The app | Use | State |
 | --- | --- | --- |
 | Normal web or desktop app, users, lists, orders | `db` with SQLite (the `notes` and `chat` templates) | available |
-| Hosted, many users | `db` with Postgres or Supabase | planned |
+| SQLite is not enough, but no server | `db` with the optional `acryl-db-pglite` plugin: Postgres in the app's process, one folder in the app home | optional, not in `acrylblends` |
+| Must use Postgres or Supabase | `db` with the optional `acryl-db-postgres` plugin | optional, not in `acrylblends` |
 | Tiny, one person, a few screens | [`kv`](#a-tiny-app-kv), named JSON documents with no SQL | available |
-| Agents or long tasks that must survive a restart | `durable`, in the same database as `db` | planned |
 
 Start with `db` when the data has users, lists or relations: SQL is what people and coding agents already know. Start with `kv` when the whole
 data is a handful of settings or a small list that one process reads and writes.
@@ -190,7 +191,7 @@ await db.transaction(async (tx) => {
 
 ## Writing SQL that moves to Postgres
 
-The Postgres provider is not released yet, and it will serve the same interface. SQL that stays inside this list runs on both:
+The optional Postgres plugins (`acryl-db-pglite` embedded, `acryl-db-postgres` on a server) serve the same interface. SQL that stays inside this list runs on both:
 
 - Placeholders are `?` on every provider.
 - Use `RETURNING` to get a new row, not a driver-specific "last id".
@@ -269,8 +270,8 @@ The rule is checked, not hoped for. The app names its opener once, in `package.j
 }
 ```
 
-`acrylblends check-deps` reads every `.ts`, `.tsx` and `.js` file in `src/`, `test/`, `tests/` and `extensions/`, and fails when a file other than
-the opener imports a database driver, an opener such as `acrylblends/db/sqlite` or `acryl-db-sqlite`, or (outside `src/plugins/desktop`) `electron`.
+`acrylblends check-deps` reads every `.ts`, `.tsx` and `.js` file in `src/`, `test/`, `tests/` and `plugins/`, and fails when a file other than
+the opener imports a database driver, an opener such as `acrylblends/db/sqlite` or `acryl-db-sqlite`, or (outside `plugins/desktop`) `electron`.
 It names the file and the line:
 
 ```

package/docs/framework/helpers/streaming.md

@@ -86,7 +86,7 @@ app.get('/sse', async (c) => {
 A reader that closes the tab, loses the network or presses a Stop button should not leave your server working for nobody (a request to a paid model, a database scan). There are two signals, and they are not the same:
 
 - **`c.req.raw.signal`** is the request's `AbortSignal`. It aborts when the client goes away. Pass it to anything that takes a `signal`, such as `fetch`, and the work stops with the client. This is the one to use for cancelling work.
-- **`stream.onAbort(callback)`** and **`stream.aborted`** belong to the response stream. They report that the *reader of the response* was cancelled. Measured: when you call `app.request()` with a `signal` and abort it, `c.req.raw.signal` aborts and `stream.aborted` stays `false`; when the reader of the response body is cancelled, `stream.onAbort` fires and `c.req.raw.signal` does not. On a real connection the request signal is what fired when a browser aborted its `fetch`. Use `c.req.raw.signal` for the work, and `stream.onAbort` for cleanup of the stream itself.
+- **`stream.onAbort(callback)`** and **`stream.aborted`** belong to the response stream. They report that the *reader of the response* was cancelled, and they are set when the response body is cancelled, which is what the Node adapter does when the connection closes. Over a real connection, a browser that aborts its `fetch` (or closes the tab) fires both: the request signal and `stream.onAbort`. Under `app.request()` (in-process, no socket) they come apart, and this is how the upstream behaves too: aborting the `signal` you passed to `app.request()` fires `c.req.raw.signal` while `stream.aborted` stays `false`, and cancelling the reader of the response body fires `stream.onAbort` while `c.req.raw.signal` does not. A test that simulates the client leaving therefore aborts the request signal (for work cancelled through the signal) or cancels the body reader (for `stream.onAbort`), whichever the handler listens to. Use `c.req.raw.signal` for the work, and `stream.onAbort` for cleanup of the stream itself.
 
 An abort event that has already fired does not fire again, so check `signal.aborted` before you wait for it:
 
@@ -160,31 +160,10 @@ app.post('/api/chat', async (c) => {
 
 ## Reading a POST event stream in the browser
 
-`EventSource` can only send a GET request. For a POST (a chat message), read the response body yourself; this function calls `on` for each event as it arrives:
+`EventSource` can only send a GET request. For a POST (a chat message), call `fetch` and read the events with `readSSE` from `acrylblends/read-sse`. It is an async iterator over the events of a `text/event-stream` response, parsed by the rules of the SSE standard (LF, CRLF and CR line ends, several `data` lines joined with a line feed, comments, UTF-8 split across chunks):
 
 ```ts
-async function readEvents(body: ReadableStream<Uint8Array>, on: (event: string, data: string) => void): Promise<void> {
-  const reader = body.getReader()
-  const decoder = new TextDecoder()
-  let buffer = ''
-  for (;;) {
-    const { done, value } = await reader.read()
-    if (done) return
-    // Line endings may be CRLF; a \r at the end of a chunk is completed by the next chunk, so normalise the whole buffer.
-    buffer = (buffer + decoder.decode(value, { stream: true })).replaceAll('\r\n', '\n')
-    const blocks = buffer.split('\n\n')
-    buffer = blocks.pop() ?? ''
-    for (const block of blocks) {
-      let event = 'message'
-      const data: string[] = []
-      for (const line of block.split('\n')) {
-        if (line.startsWith('event:')) event = line.slice(6).trim()
-        else if (line.startsWith('data:')) data.push(line.slice(5).replace(/^ /, '')) // the SSE spec strips one leading space only
-      }
-      on(event, data.join('\n'))
-    }
-  }
-}
+import { readSSE } from 'acrylblends/read-sse'
 
 const controller = new AbortController() // controller.abort() is the Stop button
 const response = await fetch('/api/chat', {
@@ -193,13 +172,19 @@ const response = await fetch('/api/chat', {
   body: JSON.stringify({ message: 'Hello' }),
   signal: controller.signal,
 })
+
 let answer = ''
-await readEvents(response.body!, (event, data) => {
+for await (const { event, data } of readSSE(response)) {
   if (event === 'token') answer += JSON.parse(data) as string
-})
+}
 ```
 
-A complete chat component built on this is in the `chat` template of `create-acrylblends` (`npm create acrylblends@latest my-chat -- --template chat`).
+- Each event is `{ event, data, id?, retry? }`; `event` is `message` when the server named none, and `data` is a string (parse it yourself when the server sends JSON).
+- Leaving the loop early (a `break`, a thrown error) cancels the response body, so the request to the server ends. Abort the `fetch` with its own `signal` for a Stop button; `readSSE(response, { signal })` also stops reading when a signal aborts.
+- A response that is not `ok` throws with its status (the body is not parsed as events), and a response without a body throws.
+- A client module served by `clientModules` can import it as it is (`import { readSSE } from 'acrylblends/read-sse'`): the import is pointed at a browser file the same app serves, like `acrylblends/client`. With a bundler it is an ordinary import.
+
+A complete chat component is in the `chat` template of `create-acrylblends` (`npm create acrylblends@latest my-chat -- --template chat`).
 
 ## Error Handling
 

package/docs/framework/upstream.json

@@ -2,8 +2,8 @@
   "source": {
     "repo": "acryldev/acryl",
     "path": "docs/framework",
-    "commit": "f8e385e4389fe2fdc6fd2a4366a7f2a7389faacb"
+    "commit": "20bdc263d6f0f8febbd967007bda4cf4a802efd2"
   },
-  "files": 99,
-  "digest": "sha256:075d537930a53f7ba46b989ff82f9d83a720270c60d848917e6501bfabff6df1"
+  "files": 100,
+  "digest": "sha256:ab5a055bc0bfb6c47ee6bb70c72ef6ec675ad070d790b58e601cd764591df788"
 }

package/lib/browser/read-sse.js

@@ -0,0 +1,84 @@
+//#region ../../plugins/acryl-router/src/helpers/read-sse.ts
+/**
+* Read the events of a `text/event-stream` response as they arrive. Leaving the loop early (`break`, a thrown error) cancels the body, so the
+* request to the server ends.
+* @throws when the response is not `ok` (the status is in the message; the body is cancelled, not parsed), has no body, or fails while it is read.
+*/
+async function* readSSE(response, options = {}) {
+	if (!response.ok) {
+		await response.body?.cancel().catch(() => void 0);
+		throw new Error(`readSSE: the request failed with ${String(response.status)}${response.statusText === "" ? "" : ` ${response.statusText}`}`);
+	}
+	if (response.body === null) throw new Error("readSSE: the response has no body to read");
+	const { signal } = options;
+	if (signal?.aborted === true) {
+		await response.body.cancel().catch(() => void 0);
+		return;
+	}
+	const reader = response.body.getReader();
+	const onAbort = () => {
+		reader.cancel().catch(() => void 0);
+	};
+	signal?.addEventListener("abort", onAbort, { once: true });
+	const decoder = new TextDecoder("utf-8");
+	let buffer = "";
+	let skipLineFeed = false;
+	let name = "";
+	let data = [];
+	let id;
+	let retry;
+	/** Apply one line; returns the event when this line completes one. */
+	const apply = (line) => {
+		if (line === "") {
+			const event = data.length === 0 ? void 0 : {
+				event: name === "" ? "message" : name,
+				data: data.join("\n"),
+				...id === void 0 ? {} : { id },
+				...retry === void 0 ? {} : { retry }
+			};
+			name = "";
+			data = [];
+			id = void 0;
+			retry = void 0;
+			return event;
+		}
+		if (line.startsWith(":")) return void 0;
+		const colon = line.indexOf(":");
+		const field = colon === -1 ? line : line.slice(0, colon);
+		let value = colon === -1 ? "" : line.slice(colon + 1);
+		if (value.startsWith(" ")) value = value.slice(1);
+		if (field === "event") name = value;
+		else if (field === "data") data.push(value);
+		else if (field === "id") {
+			if (!value.includes("\0")) id = value;
+		} else if (field === "retry" && /^\d+$/u.test(value)) retry = Number(value);
+	};
+	try {
+		for (;;) {
+			const { done, value } = await reader.read();
+			if (done) break;
+			let text = decoder.decode(value, { stream: true });
+			if (skipLineFeed && text.startsWith("\n")) text = text.slice(1);
+			if (text !== "") skipLineFeed = false;
+			buffer += text;
+			let start = 0;
+			for (let index = 0; index < buffer.length; index += 1) {
+				const code = buffer.charCodeAt(index);
+				if (code !== 10 && code !== 13) continue;
+				const line = buffer.slice(start, index);
+				if (code === 13) if (index + 1 < buffer.length) {
+					if (buffer.charCodeAt(index + 1) === 10) index += 1;
+				} else skipLineFeed = true;
+				start = index + 1;
+				const event = apply(line);
+				if (event !== void 0) yield event;
+			}
+			buffer = buffer.slice(start);
+		}
+	} finally {
+		signal?.removeEventListener("abort", onAbort);
+		await reader.cancel().catch(() => void 0);
+	}
+}
+//#endregion
+export { readSSE };

package/lib/db/sqlite.d.ts

@@ -1,4 +1,4 @@
-import { n as DbExecutor, r as SqlValue, t as Db } from "../database-D_UN6We8.js";
+import { c as DbExecutor, l as SqlValue, s as Db } from "../index-D4FAsBZu.js";
 
 //#region ../../plugins/acryl-db-sqlite/src/open.d.ts
 interface OpenDbOptions {

package/lib/db.d.ts

@@ -1,85 +1,2 @@
-//#region ../../plugins/acryl-db/src/facade/database.d.ts
-/** Values supported by the portable SQL drivers. */
-type SqlValue = null | number | bigint | string | Uint8Array;
-/**
- * Asynchronous SQL operations shared by a database and its transaction handles.
- *
- * `exec` runs SQL text without bindings and may contain several statements. `run`, `get`, and `all`
- * execute one statement with positional bindings. Adapters may cache prepared statements by SQL text,
- * so callers pass values as bindings instead of interpolating them. `run` resolves the number of rows
- * the statement changed.
- */
-interface DbExecutor {
-  exec(sql: string): Promise<void>;
-  run(sql: string, ...params: SqlValue[]): Promise<{
-    readonly changes: number;
-  }>;
-  get<T extends object>(sql: string, ...params: SqlValue[]): Promise<T | undefined>;
-  all<T extends object>(sql: string, ...params: SqlValue[]): Promise<T[]>;
-}
-/**
- * Minimal portable SQL database facade.
- *
- * All operations are asynchronous so adapters may execute outside the caller's runtime.
- *
- * `transaction` passes the callback a transaction handle. All work in the transaction
- * must use that handle; the handle is invalid after the callback settles. Adapters must
- * queue unrelated operations and other transactions until the transaction finishes. The
- * returned promise settles after commit or rollback. Calling the database itself (including
- * `transaction`) from inside a callback therefore waits for that transaction and
- * never settles.
- *
- * When the callback rejects, the adapter must roll the transaction back before rejecting
- * with that same error. If rollback fails, it must reject with a different error (for
- * example an `AggregateError`) so callers cannot mistake the callback error for a
- * guaranteed rollback.
- *
- * Closing is the adapter's: the plugin that opened a database closes it, so the facade an
- * app receives has no `close`.
- */
-interface Db extends DbExecutor {
-  transaction<T>(callback: (transaction: DbExecutor) => Promise<T>): Promise<T>;
-}
-//#endregion
-//#region ../../plugins/acryl-db/src/facade/migrations.d.ts
-type Migration = {
-  readonly version: number;
-  readonly statements: readonly string[];
-};
-/**
- * Apply all pending migrations atomically, tracking their version in the named metadata table.
- *
- * The bookkeeping SQL runs unchanged on SQLite and Postgres: no `STRICT` table, `ON CONFLICT DO NOTHING`
- * instead of `INSERT OR IGNORE`, and the version written as a checked integer rather than a binding,
- * since the two dialects spell placeholders differently.
- */
-declare function applyMigrations(database: Db, migrations: readonly Migration[], options: {
-  readonly table: string;
-}): Promise<void>;
-//#endregion
-//#region ../../plugins/acryl-db/src/facade/schema.d.ts
-/** Validate a prefix before using it as part of a SQL identifier. */
-declare function validateSchemaPrefix(prefix: string): void;
-//#endregion
-//#region ../../plugins/acryl-db/src/migration-files.d.ts
-/**
- * Read every `NNN-name.sql` file of a folder, in number order.
- * @throws when a `.sql` file is not named `NNN-name.sql`, or the numbers do not run 1, 2, 3, ... without gaps or repeats.
- */
-declare function readMigrationFiles(folder: string | URL): Promise<Migration[]>;
-//#endregion
-//#region ../../plugins/acryl-db/src/index.d.ts
-/**
- * The `db` port: what an app's code sees of its relational database, whichever provider (`acryl-db-sqlite`, `acryl-db-postgres`) serves
- * it. Plain code (an acrylblends app) opens a database with a provider's `openDb`; a Cordis plugin declares `inject: ['db']`, imports
- * `acryl-db/cordis` for the `ctx.db` type, and never imports a driver.
- *
- * Bindings are positional `?` placeholders on every provider; a provider whose database spells them differently translates them.
- * This entry imports nothing from Cordis, at runtime or in its types.
- */
-/** The service name every `db` provider registers. */
-declare const DB_SERVICE = "db";
-/** The table that records an app's migration version. */
-declare const MIGRATIONS_TABLE = "_migrations";
-//#endregion
+import { a as Migration, c as DbExecutor, i as validateSchemaPrefix, l as SqlValue, n as MIGRATIONS_TABLE, o as applyMigrations, r as readMigrationFiles, s as Db, t as DB_SERVICE } from "./index-D4FAsBZu.js";
 export { DB_SERVICE, type Db, type DbExecutor, MIGRATIONS_TABLE, type Migration, type SqlValue, applyMigrations, readMigrationFiles, validateSchemaPrefix };