acrylblends 0.7.7 → 0.8.0

package/lib/index-BLTYsyc1.d.ts

@@ -0,0 +1,93 @@
+//#region ../../plugins/acryl-kv/src/kv.d.ts
+/** `T`, except a promise: the callback of `update` is synchronous, and an async one is a type error. */
+type NotPromise<T> = T extends PromiseLike<unknown> ? never : T;
+/** Anything JSON can hold. */
+type JsonValue = null | boolean | number | string | JsonValue[] | {
+  [key: string]: JsonValue;
+};
+/**
+ * Named JSON documents. Every call returns a promise, so a file, SQLite and Postgres answer alike.
+ *
+ * Keys are non-empty strings. Values are JSON: `undefined`, functions, symbols, bigints and non-finite numbers are refused with a
+ * `TypeError` before anything is written, and a value read back is a copy.
+ *
+ * There is no `close`: the code that opened a store closes it (see {@link KvOpened}), so a plugin cannot close the store another uses.
+ */
+interface Kv {
+  /** The value stored under the key, or `undefined`. */
+  get<T = JsonValue>(key: string): Promise<T | undefined>;
+  /** Store a value under the key, replacing any. Resolves once it is durable. */
+  set<T = JsonValue>(key: string, value: T): Promise<void>;
+  /**
+   * Replace the value under the key by `change(current)`, atomically: `current` is `undefined` when the key is missing, `change` is
+   * synchronous (an `async` function is a type error, and a returned promise is rejected at run time: read what you need first, then update), and no other write to the key happens between reading it and writing the result. Resolves the new value. A `change` that
+   * throws, or returns something that is not JSON, leaves the value as it was and rejects with its error.
+   */
+  update<T = JsonValue>(key: string, change: (current: T | undefined) => NotPromise<T>): Promise<T>;
+  /** Remove the key. A missing key is not an error. */
+  delete(key: string): Promise<void>;
+  /** The keys that start with the prefix (all of them without one), sorted by code point (the order of their UTF-8 bytes, not of UTF-16 units). */
+  list(prefix?: string): Promise<string[]>;
+}
+/** An open store and the one function that closes it. */
+interface KvOpened {
+  readonly kv: Kv;
+  /** Waits for the writes in flight, then releases the storage. Calling it again does nothing; calls on `kv` after it reject. */
+  close(): Promise<void>;
+}
+//#endregion
+//#region ../../plugins/acryl-kv/src/check.d.ts
+/**
+ * What every `kv` provider checks the same way, so a bad call fails alike on a file and on SQL: the key, the value, and the order of keys.
+ */
+/** A key is a non-empty string. */
+declare function checkKey(key: unknown): asserts key is string;
+/**
+ * The JSON text of a value. `undefined`, functions, symbols, bigints, circular structures and non-finite numbers (which JSON would turn
+ * into `null`) are refused with a `TypeError`; nothing is stored for them.
+ */
+declare function encodeValue(value: unknown): string;
+/** The value of stored JSON text: a new copy each time, so changing what `get` returned changes nothing stored. */
+declare function decodeValue<T>(text: string): T;
+/** Order two keys by code point (the order of UTF-8 bytes, which SQLite's binary collation and Postgres' "C" collation give too). */
+declare function compareKeys(a: string, b: string): number;
+/** The number of code points in a string (what SQL's `substr` counts). */
+declare function codePoints(text: string): number;
+/**
+ * Call an `update` callback and check what it returns: the callback is synchronous, so a promise (an `async` function the types should have
+ * refused) is rejected with a message that says what to do, instead of being stored as `{}`.
+ */
+declare function runChange<T>(change: (current: T | undefined) => T, current: T | undefined): T;
+//#endregion
+//#region ../../plugins/acryl-kv/src/copy.d.ts
+interface CopyKvOptions {
+  /** Replace keys the target already has. Without it, a shared key stops the copy before anything is written. */
+  readonly overwrite?: boolean;
+  /** Copy only the keys that start with this. */
+  readonly prefix?: string;
+}
+interface CopyKvResult {
+  /** Keys written to the target. */
+  readonly copied: number;
+  /** Of those, keys the target already had. */
+  readonly overwritten: number;
+}
+/**
+ * Copy every key of one store into another: the import when an app moves from a JSON file to SQL (the file opened with
+ * `acryl-kv-json` is the source, `kvOnDb` the target). The source is not changed.
+ * @throws when the target has a key the source has and `overwrite` is not set; nothing is written then.
+ */
+declare function copyKv(source: Kv, target: Kv, options?: CopyKvOptions): Promise<CopyKvResult>;
+//#endregion
+//#region ../../plugins/acryl-kv/src/index.d.ts
+/**
+ * The `kv` port: named JSON documents for an app too small for SQL, whichever provider serves it (`acryl-kv-json` for one file,
+ * `acryl-kv-db` over the `db` port). Plain code opens a store with a provider's `openKv`; a Cordis plugin declares `inject: ['kv']`, imports
+ * `acryl-kv/cordis` for the `ctx.kv` type, and never imports a provider.
+ *
+ * This entry imports nothing from Cordis, at runtime or in its types.
+ */
+/** The service name every `kv` provider registers. */
+declare const KV_SERVICE = "kv";
+//#endregion
+export { checkKey as a, decodeValue as c, JsonValue as d, Kv as f, copyKv as i, encodeValue as l, NotPromise as m, CopyKvOptions as n, codePoints as o, KvOpened as p, CopyKvResult as r, compareKeys as s, KV_SERVICE as t, runChange as u };

package/lib/index-D4FAsBZu.d.ts

@@ -0,0 +1,85 @@
+//#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
+export { Migration as a, DbExecutor as c, validateSchemaPrefix as i, SqlValue as l, MIGRATIONS_TABLE as n, applyMigrations as o, readMigrationFiles as r, Db as s, DB_SERVICE as t };

package/lib/kv/db.d.ts

@@ -1,5 +1,5 @@
-import { t as Db } from "../database-D_UN6We8.js";
-import { t as Kv } from "../kv-DWDm0Lja.js";
+import { s as Db } from "../index-D4FAsBZu.js";
+import { f as Kv } from "../index-BLTYsyc1.js";
 
 //#region ../../plugins/acryl-kv-db/src/open.d.ts
 interface KvOnDbOptions {

package/lib/kv/json.d.ts

@@ -1,4 +1,4 @@
-import { n as KvOpened, t as Kv } from "../kv-DWDm0Lja.js";
+import { f as Kv, p as KvOpened } from "../index-BLTYsyc1.js";
 
 //#region ../../plugins/acryl-kv-json/src/open.d.ts
 interface OpenKvOptions {

package/lib/kv/json.js

@@ -7,9 +7,12 @@ import { basename, dirname, join, resolve } from "node:path";
 * memory and resolves the `kv` port with the function that closes it. The Cordis plugin is a thin wrapper over this, so both run one code
 * path. This entry imports nothing from Cordis.
 *
-* Every write queues behind the writes before it and persists the whole map: serialize to a temporary file in the same folder, flush it,
-* rename it over the file, and flush the folder where the platform allows. The call resolves after the rename, so a crash leaves the old file
-* or the new one, never half of one. One process owns the file: two writers would overwrite each other.
+* Every write persists the whole map: serialize to a temporary file in the same folder, flush it, rename it over the file, and flush the
+* folder where the platform allows. The call resolves after the rename, so a crash leaves the old file or the new one, never half of one.
+* Writes are grouped: the calls made in one turn of the event loop, and those that queue while a file write is in flight, are applied in
+* call order and persisted together by one write, so a burst of calls costs one flush and one rename, not one each (on Windows each costs
+* tens of milliseconds). One process owns the
+* file: two writers would overwrite each other.
 */
 /** The file's own format version, for a later change of layout. */
 const FORMAT = 1;
@@ -80,7 +83,12 @@ async function openKv(options) {
 	let state = await load(file);
 	let closed = false;
 	let sequence = 0;
-	let tail = Promise.resolve();
+	/** Calls waiting for the next file write, in call order. */
+	let queue = [];
+	/** Whether the loop that writes the queue runs; cleared by the loop itself, so a call queued after it ends starts a new one. */
+	let draining = false;
+	/** The latest loop, for `close` to wait on. */
+	let drained = Promise.resolve();
 	const guard = () => {
 		if (closed) throw new Error(`acryl-kv-json: ${file} is closed`);
 	};
@@ -103,18 +111,66 @@ async function openKv(options) {
 		}
 		await flushFolder(dirname(file));
 	};
-	/** Run a change after every earlier one; the map it works on becomes the state only once it is on disk. */
-	const write = (change) => {
-		guard();
-		const task = tail.then(async () => {
+	/**
+	* Write the queue until it is empty. Each round takes every call queued so far and applies them in order to one copy of the state. A call
+	* whose change throws rejects with its error and changes nothing, and the others in the round still apply. The copy becomes the state
+	* only once it is on disk. A failed file write rejects every call in its round and leaves the state as it was.
+	*/
+	const drain = async () => {
+		try {
+			await Promise.resolve();
+			await rounds();
+		} finally {
+			draining = false;
+		}
+	};
+	const rounds = async () => {
+		while (queue.length > 0) {
+			const round = queue;
+			queue = [];
 			const draft = new Map(state);
-			const result = change(draft);
-			await persist(draft);
+			const applied = [];
+			for (const call of round) {
+				let change;
+				try {
+					change = call.change((key) => draft.get(key));
+				} catch (error) {
+					call.reject(error);
+					continue;
+				}
+				if (change.text === void 0) draft.delete(change.key);
+				else draft.set(change.key, change.text);
+				applied.push({
+					call,
+					result: change.result
+				});
+			}
+			if (applied.length === 0) continue;
+			try {
+				await persist(draft);
+			} catch (error) {
+				for (const { call } of applied) call.reject(error);
+				continue;
+			}
 			state = draft;
-			return result;
+			for (const { call, result } of applied) call.resolve(result);
+		}
+	};
+	/** Queue one change behind every earlier call; it resolves once a file write that contains it is on disk. */
+	const write = (change) => {
+		guard();
+		const done = new Promise((resolveCall, rejectCall) => {
+			queue.push({
+				change,
+				resolve: resolveCall,
+				reject: rejectCall
+			});
 		});
-		tail = task.catch(() => void 0);
-		return task;
+		if (!draining) {
+			draining = true;
+			drained = drain();
+		}
+		return done;
 	};
 	return {
 		kv: {
@@ -127,24 +183,31 @@ async function openKv(options) {
 			async set(key, value) {
 				checkKey(key);
 				const text = encodeValue(value);
-				await write((draft) => {
-					draft.set(key, text);
-				});
+				await write(() => ({
+					key,
+					text,
+					result: void 0
+				}));
 			},
 			async update(key, change) {
 				checkKey(key);
-				return write((draft) => {
-					const text = draft.get(key);
+				return write((read) => {
+					const text = read(key);
 					const encoded = encodeValue(runChange(change, text === void 0 ? void 0 : decodeValue(text)));
-					draft.set(key, encoded);
-					return decodeValue(encoded);
+					return {
+						key,
+						text: encoded,
+						result: decodeValue(encoded)
+					};
 				});
 			},
 			async delete(key) {
 				checkKey(key);
-				await write((draft) => {
-					draft.delete(key);
-				});
+				await write(() => ({
+					key,
+					text: void 0,
+					result: void 0
+				}));
 			},
 			async list(prefix = "") {
 				guard();
@@ -153,7 +216,7 @@ async function openKv(options) {
 		},
 		close: async () => {
 			closed = true;
-			await tail;
+			await drained;
 		}
 	};
 }

package/lib/kv.d.ts

@@ -1,93 +1,2 @@
-//#region ../../plugins/acryl-kv/src/kv.d.ts
-/** `T`, except a promise: the callback of `update` is synchronous, and an async one is a type error. */
-type NotPromise<T> = T extends PromiseLike<unknown> ? never : T;
-/** Anything JSON can hold. */
-type JsonValue = null | boolean | number | string | JsonValue[] | {
-  [key: string]: JsonValue;
-};
-/**
- * Named JSON documents. Every call returns a promise, so a file, SQLite and Postgres answer alike.
- *
- * Keys are non-empty strings. Values are JSON: `undefined`, functions, symbols, bigints and non-finite numbers are refused with a
- * `TypeError` before anything is written, and a value read back is a copy.
- *
- * There is no `close`: the code that opened a store closes it (see {@link KvOpened}), so a plugin cannot close the store another uses.
- */
-interface Kv {
-  /** The value stored under the key, or `undefined`. */
-  get<T = JsonValue>(key: string): Promise<T | undefined>;
-  /** Store a value under the key, replacing any. Resolves once it is durable. */
-  set<T = JsonValue>(key: string, value: T): Promise<void>;
-  /**
-   * Replace the value under the key by `change(current)`, atomically: `current` is `undefined` when the key is missing, `change` is
-   * synchronous (an `async` function is a type error, and a returned promise is rejected at run time: read what you need first, then update), and no other write to the key happens between reading it and writing the result. Resolves the new value. A `change` that
-   * throws, or returns something that is not JSON, leaves the value as it was and rejects with its error.
-   */
-  update<T = JsonValue>(key: string, change: (current: T | undefined) => NotPromise<T>): Promise<T>;
-  /** Remove the key. A missing key is not an error. */
-  delete(key: string): Promise<void>;
-  /** The keys that start with the prefix (all of them without one), sorted by code point (the order of their UTF-8 bytes, not of UTF-16 units). */
-  list(prefix?: string): Promise<string[]>;
-}
-/** An open store and the one function that closes it. */
-interface KvOpened {
-  readonly kv: Kv;
-  /** Waits for the writes in flight, then releases the storage. Calling it again does nothing; calls on `kv` after it reject. */
-  close(): Promise<void>;
-}
-//#endregion
-//#region ../../plugins/acryl-kv/src/check.d.ts
-/**
- * What every `kv` provider checks the same way, so a bad call fails alike on a file and on SQL: the key, the value, and the order of keys.
- */
-/** A key is a non-empty string. */
-declare function checkKey(key: unknown): asserts key is string;
-/**
- * The JSON text of a value. `undefined`, functions, symbols, bigints, circular structures and non-finite numbers (which JSON would turn
- * into `null`) are refused with a `TypeError`; nothing is stored for them.
- */
-declare function encodeValue(value: unknown): string;
-/** The value of stored JSON text: a new copy each time, so changing what `get` returned changes nothing stored. */
-declare function decodeValue<T>(text: string): T;
-/** Order two keys by code point (the order of UTF-8 bytes, which SQLite's binary collation and Postgres' "C" collation give too). */
-declare function compareKeys(a: string, b: string): number;
-/** The number of code points in a string (what SQL's `substr` counts). */
-declare function codePoints(text: string): number;
-/**
- * Call an `update` callback and check what it returns: the callback is synchronous, so a promise (an `async` function the types should have
- * refused) is rejected with a message that says what to do, instead of being stored as `{}`.
- */
-declare function runChange<T>(change: (current: T | undefined) => T, current: T | undefined): T;
-//#endregion
-//#region ../../plugins/acryl-kv/src/copy.d.ts
-interface CopyKvOptions {
-  /** Replace keys the target already has. Without it, a shared key stops the copy before anything is written. */
-  readonly overwrite?: boolean;
-  /** Copy only the keys that start with this. */
-  readonly prefix?: string;
-}
-interface CopyKvResult {
-  /** Keys written to the target. */
-  readonly copied: number;
-  /** Of those, keys the target already had. */
-  readonly overwritten: number;
-}
-/**
- * Copy every key of one store into another: the import when an app moves from a JSON file to SQL (the file opened with
- * `acryl-kv-json` is the source, `kvOnDb` the target). The source is not changed.
- * @throws when the target has a key the source has and `overwrite` is not set; nothing is written then.
- */
-declare function copyKv(source: Kv, target: Kv, options?: CopyKvOptions): Promise<CopyKvResult>;
-//#endregion
-//#region ../../plugins/acryl-kv/src/index.d.ts
-/**
- * The `kv` port: named JSON documents for an app too small for SQL, whichever provider serves it (`acryl-kv-json` for one file,
- * `acryl-kv-db` over the `db` port). Plain code opens a store with a provider's `openKv`; a Cordis plugin declares `inject: ['kv']`, imports
- * `acryl-kv/cordis` for the `ctx.kv` type, and never imports a provider.
- *
- * This entry imports nothing from Cordis, at runtime or in its types.
- */
-/** The service name every `kv` provider registers. */
-declare const KV_SERVICE = "kv";
-//#endregion
+import { a as checkKey, c as decodeValue, d as JsonValue, f as Kv, i as copyKv, l as encodeValue, m as NotPromise, n as CopyKvOptions, o as codePoints, p as KvOpened, r as CopyKvResult, s as compareKeys, t as KV_SERVICE, u as runChange } from "./index-BLTYsyc1.js";
 export { type CopyKvOptions, type CopyKvResult, type JsonValue, KV_SERVICE, type Kv, type KvOpened, type NotPromise, checkKey, codePoints, compareKeys, copyKv, decodeValue, encodeValue, runChange };

package/lib/node-server.d.ts

@@ -136,7 +136,7 @@ interface ClientModulesOptions {
   readonly compiled?: string | undefined;
   /** At most this many bytes of compiled modules are kept in memory (least recently served first out); 16 MiB when not given. */
   readonly cacheBytes?: number | undefined;
-  /** The folder holding `jsx-dom.js` and `client.js`; the framework's own when not given. */
+  /** The folder holding `jsx-dom.js`, `client.js` and `read-sse.js`; the framework's own when not given. */
   readonly runtimeDir?: string | undefined;
 }
 /** Options of {@link buildClientModules}. */
@@ -145,7 +145,7 @@ interface BuildClientModulesOptions {
   readonly root: string;
   /** Where the compiled modules go, at the same relative paths and file names; it must not lie inside `root`. */
   readonly outDir: string;
-  /** The folder holding `jsx-dom.js` and `client.js`; the framework's own when not given. */
+  /** The folder holding `jsx-dom.js`, `client.js` and `read-sse.js`; the framework's own when not given. */
   readonly runtimeDir?: string | undefined;
 }
 /**
@@ -159,7 +159,7 @@ interface BuildClientModulesOptions {
 declare function clientModules(options: ClientModulesOptions): Acryl;
 /**
  * Compile a folder of client modules once, for a production that has no `typescript`: each module is written to `outDir` at the same
- * relative path and file name (so the page's URLs stay the same), compiled exactly as {@link clientModules} compiles it, and the two
+ * relative path and file name (so the page's URLs stay the same), compiled exactly as {@link clientModules} compiles it, and the three
  * browser files are copied to `outDir/@acrylblends/`. Files already in `outDir` that no source produces are left there.
  * @param options - the source folder and the output folder.
  * @returns the paths written, relative to `outDir`.

package/lib/node-server.js

@@ -835,6 +835,7 @@ const drainIncoming = (incoming) => {
 		bytesRead += chunk.length;
 		if (bytesRead > MAX_DRAIN_BYTES) forceClose();
 	};
+	incoming.removeAllListeners("data");
 	incoming.on("data", onData);
 	incoming.on("end", cleanup);
 	incoming.on("error", cleanup);
@@ -1330,14 +1331,14 @@ function serve(options, listeningListener) {
 /**
 * Client components without a bundler. `clientModules({ root: 'src/client' })` is an app that serves the TypeScript and JSX modules of a
 * folder to the browser as ES modules: a `.tsx`/`.ts`/`.jsx` file compiled with the app's own `typescript` (JSX for `acrylblends/jsx/dom`),
-* a `.js`/`.mjs` file as it is. The framework's own browser imports (`acrylblends/jsx/dom` with its runtimes and `client`, and
-* `acrylblends/client`) are rewritten to two self-contained files the same app serves, at a URL relative to each module, so a page needs
+* a `.js`/`.mjs` file as it is. The framework's own browser imports (`acrylblends/jsx/dom` with its runtimes and `client`,
+* `acrylblends/client` and `acrylblends/read-sse`) are rewritten to three self-contained files the same app serves, at a URL relative to each module, so a page needs
 * one `<script type="module" src="/client/counter.tsx">` and no import map, under whatever path the app is routed at.
 *
 * Production runs without `typescript` (a deploy that leaves out devDependencies): `buildClientModules` writes the same compiled modules
-* and the two browser files into a folder, and with `NODE_ENV=production` and `compiled` set, only that folder is served.
+* and the three browser files into a folder, and with `NODE_ENV=production` and `compiled` set, only that folder is served.
 */
-/** The folder the two browser files are served from, below the app's mount. A source folder of this name is not served. */
+/** The folder the three browser files are served from, below the app's mount. A source folder of this name is not served. */
 const RUNTIME_DIR = "@acrylblends";
 /** The framework's browser imports and the browser file that provides each. */
 const BROWSER_IMPORTS = {
@@ -1345,9 +1346,14 @@ const BROWSER_IMPORTS = {
 	"acrylblends/jsx/dom/jsx-runtime": "jsx-dom.js",
 	"acrylblends/jsx/dom/jsx-dev-runtime": "jsx-dom.js",
 	"acrylblends/jsx/dom/client": "jsx-dom.js",
-	"acrylblends/client": "client.js"
+	"acrylblends/client": "client.js",
+	"acrylblends/read-sse": "read-sse.js"
 };
-const RUNTIME_FILES = ["jsx-dom.js", "client.js"];
+const RUNTIME_FILES = [
+	"jsx-dom.js",
+	"client.js",
+	"read-sse.js"
+];
 const COMPILED = /* @__PURE__ */ new Set([
 	".ts",
 	".tsx",
@@ -1362,7 +1368,7 @@ const SERVED = /* @__PURE__ */ new Set([
 const JS_TYPE = "text/javascript; charset=utf-8";
 /** The cache bound when `cacheBytes` is not given. */
 const DEFAULT_CACHE_BYTES = 16 * 1024 * 1024;
-/** The framework's two browser files, next to the built module that contains this code. */
+/** The framework's three browser files, next to the built module that contains this code. */
 const defaultRuntimeDir = () => fileURLToPath(new URL("./browser/", import.meta.url));
 /** A module path below the root (`widgets/counter.tsx`) with the URL prefix that reaches the browser files from it. */
 const runtimePrefix = (relativePath) => {
@@ -1551,7 +1557,7 @@ function sourceFiles(root, dir = root) {
 }
 /**
 * Compile a folder of client modules once, for a production that has no `typescript`: each module is written to `outDir` at the same
-* relative path and file name (so the page's URLs stay the same), compiled exactly as {@link clientModules} compiles it, and the two
+* relative path and file name (so the page's URLs stay the same), compiled exactly as {@link clientModules} compiles it, and the three
 * browser files are copied to `outDir/@acrylblends/`. Files already in `outDir` that no source produces are left there.
 * @param options - the source folder and the output folder.
 * @returns the paths written, relative to `outDir`.

package/lib/read-sse.d.ts

@@ -0,0 +1,33 @@
+//#region ../../plugins/acryl-router/src/helpers/read-sse.d.ts
+/**
+ * `readSSE(response)`: the events of a `text/event-stream` answer from `fetch`, for the browser. `EventSource` reads GET streams only; a chat
+ * or any stream that needs a POST body, a header or an `AbortSignal` is read with `fetch`, and this is the loop every such page otherwise writes by
+ * hand. It follows the parsing rules of the HTML standard (lines end in LF, CRLF or CR; the `data` lines of one event join with LF; a line that
+ * starts with a colon is a comment; an event ends at a blank line; an event with no `data` line is not dispatched; the last event is dispatched
+ * only if its blank line arrived), and it is one module with no imports, so it also runs in a service worker and on a fetch runtime.
+ *
+ * ACRYL's own addition, not part of the upstream port.
+ */
+/** One event of the stream. */
+interface SSEEvent {
+  /** The `event:` name; `message` when the event has none. */
+  readonly event: string;
+  /** The `data:` lines of the event, joined with a line feed. */
+  readonly data: string;
+  /** The `id:` of the event, when it had one. */
+  readonly id?: string;
+  /** The `retry:` of the event in milliseconds, when it had one. */
+  readonly retry?: number;
+}
+interface ReadSSEOptions {
+  /** Stops the loop and cancels the response body when it aborts. (Abort the `fetch` itself with the signal you pass to it.) */
+  readonly signal?: AbortSignal;
+}
+/**
+ * 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.
+ */
+declare function readSSE(response: Response, options?: ReadSSEOptions): AsyncGenerator<SSEEvent, void, undefined>;
+//#endregion
+export { ReadSSEOptions, SSEEvent, readSSE };

package/lib/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 };