acrylblends 0.7.6 → 0.7.8

package/plugins/acryl-kv-db/src/open.ts

@@ -0,0 +1,80 @@
+/**
+ * The plain way to use SQL as the `kv` store, for code without Cordis (an acrylblends app): `kvOnDb(db)` gives the `kv` port over a `kv`
+ * table of the `db` port (SQLite today, Postgres after spec 049 slice 2), so an app that grows from a JSON file into SQL keeps its data. The
+ * Cordis plugin is a thin wrapper over it. This entry imports nothing from Cordis.
+ *
+ * The table is created on first use with `CREATE TABLE IF NOT EXISTS`, so it needs no migration of the app's. `update` reads and writes in
+ * one `db.transaction`. `list` selects with `substr(key, 1, n) = ?`, not `LIKE`, so `%`, `_` and letter case need no escaping, and sorts by
+ * code point in the end, whatever collation the database sorts with.
+ */
+
+import type { Db } from '../../acryl-db/src/index.ts'
+import { checkKey, codePoints, compareKeys, decodeValue, encodeValue, type Kv, runChange } from '../../acryl-kv/src/index.ts'
+
+export type { Kv } from '../../acryl-kv/src/index.ts'
+
+export interface KvOnDbOptions {
+  /** The table that holds the documents. Defaults to `kv`; a plain SQL identifier. */
+  readonly table?: string
+}
+
+const IDENTIFIER = /^[a-z_][a-z0-9_]*$/u
+
+/** The `kv` port over a `db`. It does not own the database: whoever opened it closes it, and calls after that reject. */
+export function kvOnDb(db: Db, options: KvOnDbOptions = {}): Kv {
+  const table = options.table ?? 'kv'
+  if (!IDENTIFIER.test(table)) throw new TypeError(`acryl-kv-db: the table name must be a plain lower case SQL identifier, got ${JSON.stringify(table)}`)
+
+  let ready: Promise<void> | undefined
+  const ensure = (): Promise<void> => {
+    ready ??= db.exec(`CREATE TABLE IF NOT EXISTS ${table} (key TEXT PRIMARY KEY, value TEXT NOT NULL)`).catch((error: unknown) => {
+      ready = undefined
+      throw error
+    })
+    return ready
+  }
+  /**
+   * Run a statement after the table exists. The table's statement and this one are both handed to the database at once (its queue keeps
+   * their order), so a `close()` called right after a write cannot slip between them and leave the write on a closed database.
+   */
+  const after = async <T>(work: () => Promise<T>): Promise<T> => {
+    const created = ensure()
+    const result = work()
+    const [, value] = await Promise.all([created, result])
+    return value
+  }
+  const upsert = `INSERT INTO ${table} (key, value) VALUES (?, ?) ON CONFLICT (key) DO UPDATE SET value = excluded.value`
+
+  return {
+    async get<T>(key: string) {
+      checkKey(key)
+      const row = await after(() => db.get<{ value: string }>(`SELECT value FROM ${table} WHERE key = ?`, key))
+      return row === undefined ? undefined : decodeValue<T>(row.value)
+    },
+    async set(key, value) {
+      checkKey(key)
+      const text = encodeValue(value)
+      await after(() => db.run(upsert, key, text))
+    },
+    async update<T>(key: string, change: (current: T | undefined) => T) {
+      checkKey(key)
+      return after(() => db.transaction(async tx => {
+        const row = await tx.get<{ value: string }>(`SELECT value FROM ${table} WHERE key = ?`, key)
+        const next = runChange(change, row === undefined ? undefined : decodeValue<T>(row.value))
+        const text = encodeValue(next)
+        await tx.run(upsert, key, text)
+        return decodeValue<T>(text)
+      }))
+    },
+    async delete(key) {
+      checkKey(key)
+      await after(() => db.run(`DELETE FROM ${table} WHERE key = ?`, key))
+    },
+    async list(prefix = '') {
+      const rows = await after(() => prefix === ''
+        ? db.all<{ key: string }>(`SELECT key FROM ${table}`)
+        : db.all<{ key: string }>(`SELECT key FROM ${table} WHERE substr(key, 1, ?) = ?`, codePoints(prefix), prefix))
+      return rows.map(row => row.key).sort(compareKeys)
+    },
+  }
+}

package/plugins/acryl-kv-db/upstream.json

@@ -0,0 +1,21 @@
+{
+  "source": {
+    "repo": "acryldev/acryl",
+    "path": "plugins/acryl-kv-db",
+    "commit": "f132283c43337f5e1d58dfbbbc15786efb5e756c"
+  },
+  "vendored": [
+    "src",
+    "tests",
+    "LICENSE"
+  ],
+  "rewrittenSpecifiers": 10,
+  "digest": "sha256:266a44080a78b3d10fc05e5b83a39599e44a5be998eb97368aa07507ac4e3a48",
+  "testsNotRun": {
+    "tests/loader.spec.ts": "loads the plugin through the real Loader (@deepseek-ai/cordis-plugin-loader), which generated apps do not install; kvOnDb is tested here by open.spec.ts and conformance.spec.ts",
+    "tests/plain-entry-imports.spec.ts": "a copy vendored into an app (with relative imports, no build of its own) has neither `lib/`; the app's own typecheck is what proves the copy names no Cordis type it does not provide."
+  },
+  "notice": [
+    "LICENSE"
+  ]
+}

package/plugins/acryl-kv-json/LICENSE

@@ -0,0 +1,47 @@
+MIT License
+
+Copyright (c) 2026 WebBoxes s.r.o.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---
+
+The files under src/facade are derived from the SQLite facade of chord in pi (https://github.com/earendil-works/pi, packages/chord, commit d5b3de22d0e24a3e9c38a9410d3329b099717283), used under this license:
+
+MIT License
+
+Copyright (c) 2025 Mario Zechner
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/plugins/acryl-kv-json/plugin.json

@@ -0,0 +1,13 @@
+{
+  "name": "acryl-kv-json",
+  "description": "The JSON-file provider of the kv port: one file in the app home, rewritten atomically (temp file, then rename) on every write. Vendored from ACRYL.",
+  "requires": ["acryl-kv", "instance"],
+  "inject": [],
+  "provides": ["kv"],
+  "dependencies": {
+    "@deepseek-ai/cordis": "4.0.4",
+    "@deepseek-ai/schemastery": "3.18.4"
+  },
+  "mount": "mount it after instance: root.plugin(kvJson, {}) (the file is kv.json in the app home, or set path); then a plugin that declares inject: ['kv'] calls await ctx.kv.set('theme', 'dark') and ctx.kv.update('visits', (n) => (n ?? 0) + 1)",
+  "omit": ["**/*.test.*", "**/*.spec.*", "**/*.case.ts"]
+}

package/plugins/acryl-kv-json/src/index.ts

@@ -0,0 +1,71 @@
+/**
+ * The JSON-file provider of the `kv` port (spec 049 slice 3): one file, rewritten atomically on every write, opened with the plain
+ * `openKv` and provided as `kv` by this Cordis plugin. App plugins declare `inject: ['kv']` and import types from `acryl-kv` only, so
+ * replacing this row with `acryl-kv-db` does not touch them.
+ *
+ * Unloading withdraws `kv` first, so consumers stop calling, and then closes the store: the close waits for the writes in flight.
+ */
+
+import { dirname, isAbsolute, join, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import type { Context } from '@deepseek-ai/cordis'
+import z from '@deepseek-ai/schemastery'
+import { KV_SERVICE } from '../../acryl-kv/src/index.ts'
+import { openKv } from './open.ts'
+
+export { openKv, type OpenKvOptions } from './open.ts'
+
+/** Stable Cordis plugin name, equal to the package name and the Loader row id. */
+export const name = 'acryl-kv-json'
+
+/**
+ * What this plugin reads of the runtime's optional `appInstance` service: its home folder. The service belongs to the runtime (and to an
+ * app's own instance plugin), so this plugin declares no type for it on Cordis' Context; it checks the one field it uses at runtime.
+ */
+interface AppHome {
+  readonly home: string
+}
+
+function isAppHome(value: unknown): value is AppHome {
+  return typeof value === 'object' && value !== null && 'home' in value && typeof value.home === 'string'
+}
+
+export interface Config {
+  path?: string
+}
+
+export const Config: z<Config> = z.object({
+  path: z.string().description('The JSON file, absolute or relative to the app. Defaults to kv.json in the ACRYL app home; required where there is none.'),
+})
+
+/** The file name used in the app home when `path` is not configured. */
+export const DEFAULT_FILE = 'kv.json'
+
+/** A configured path as a file path: absolute as given, relative to the Loader's base URL (the app) otherwise. */
+function resolveFromApp(ctx: Context, path: string): string {
+  if (path.startsWith('file:')) return fileURLToPath(path)
+  if (isAbsolute(path)) return path
+  const base = ctx.baseUrl
+  if (base === undefined || !base.startsWith('file:')) {
+    throw new Error(`acryl-kv-json: path ${JSON.stringify(path)} is relative, but this app has no file base URL to resolve it from; give an absolute path`)
+  }
+  const appDir = base.endsWith('/') ? fileURLToPath(base) : dirname(fileURLToPath(base))
+  return resolve(appDir, path)
+}
+
+export async function apply(ctx: Context, rawConfig: Config = {}): Promise<void> {
+  const config = Config(rawConfig)
+  // The app home comes from the runtime's `appInstance` service when this runs inside an ACRYL app; a plain framework app names its file.
+  const appInstance: unknown = ctx.get('appInstance')
+  let file: string
+  if (config.path !== undefined) file = resolveFromApp(ctx, config.path)
+  else if (isAppHome(appInstance)) file = join(appInstance.home, DEFAULT_FILE)
+  else throw new Error('acryl-kv-json: no file path; set `path` in this row\'s config (there is no ACRYL app home to default to)')
+
+  // Disposers run in reverse: the service is withdrawn before the store closes.
+  await ctx.effect(async function* () {
+    const opened = await openKv({ path: file })
+    yield () => opened.close()
+    yield ctx.reflect.provide(KV_SERVICE, opened.kv)
+  }, `acryl-kv-json: ${file}`)
+}

package/plugins/acryl-kv-json/src/open.ts

@@ -0,0 +1,249 @@
+/**
+ * The plain way to open the JSON-file provider, for code without Cordis (an acrylblends app): `openKv({ path })` reads one JSON file into
+ * 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 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.
+ */
+
+import { mkdir, open, readdir, readFile, rename, rm } from 'node:fs/promises'
+import { basename, dirname, join, resolve } from 'node:path'
+import { checkKey, compareKeys, decodeValue, encodeValue, type Kv, type KvOpened, runChange } from '../../acryl-kv/src/index.ts'
+
+export type { Kv, KvOpened } from '../../acryl-kv/src/index.ts'
+
+export interface OpenKvOptions {
+  /** The JSON file; its folder is created if missing. */
+  readonly path: string
+}
+
+/** The file's own format version, for a later change of layout. */
+const FORMAT = 1
+
+/** Stray temporary files from a crash end in `.tmp` and start with the file's name. */
+const tempPrefix = (file: string): string => `${basename(file)}.`
+
+/** The file content for a map of key to JSON text, keys in code point order, so the same data is the same bytes. */
+function serialize(entries: ReadonlyMap<string, string>): string {
+  const body = [...entries.keys()].sort(compareKeys).map(key => `${JSON.stringify(key)}:${entries.get(key)}`).join(',')
+  return `{"version":${FORMAT},"entries":{${body}}}\n`
+}
+
+function unreadable(file: string, reason: string): Error {
+  return new Error(`acryl-kv-json: ${file} is not a readable kv file (${reason}); it was not changed`)
+}
+
+/** The entries of a file, or none when it does not exist. A file that exists and does not parse is an error: it is never started over. */
+async function load(file: string): Promise<Map<string, string>> {
+  let text: string
+  try {
+    text = await readFile(file, 'utf8')
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return new Map()
+    throw error
+  }
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(text)
+  } catch (error) {
+    throw unreadable(file, (error as Error).message)
+  }
+  if (typeof parsed !== 'object' || parsed === null || (parsed as { version?: unknown }).version !== FORMAT) throw unreadable(file, 'not a version 1 kv file')
+  const entries = (parsed as { entries?: unknown }).entries
+  if (typeof entries !== 'object' || entries === null || Array.isArray(entries)) throw unreadable(file, 'no entries object')
+  return new Map(Object.entries(entries).map(([key, value]) => [key, JSON.stringify(value)]))
+}
+
+/** Remove the temporary files an earlier crash left beside the file. */
+async function removeStrays(file: string): Promise<void> {
+  const prefix = tempPrefix(file)
+  for (const name of await readdir(dirname(file))) {
+    if (name.startsWith(prefix) && name.endsWith('.tmp')) await rm(join(dirname(file), name), { force: true })
+  }
+}
+
+const RENAME_RETRIES = 8
+
+/** Rename over the target. Windows refuses while a scanner or an indexer holds the target for a moment, so it is retried briefly. */
+async function replace(from: string, to: string): Promise<void> {
+  for (let attempt = 0; ; attempt += 1) {
+    try {
+      await rename(from, to)
+      return
+    } catch (error) {
+      const code = (error as NodeJS.ErrnoException).code
+      if (attempt >= RENAME_RETRIES || (code !== 'EPERM' && code !== 'EBUSY' && code !== 'EACCES')) throw error
+      await new Promise(resolveWait => setTimeout(resolveWait, 10 * (attempt + 1)))
+    }
+  }
+}
+
+/** Flush the folder entry of a renamed file (POSIX); Windows cannot open a folder, and a filesystem that refuses is no worse than before. */
+async function flushFolder(folder: string): Promise<void> {
+  if (process.platform === 'win32') return
+  try {
+    const handle = await open(folder, 'r')
+    try {
+      await handle.sync()
+    } finally {
+      await handle.close()
+    }
+  } catch {
+    // Best effort: the rename itself is already atomic.
+  }
+}
+
+/** What one call does to the map: the key's new JSON text (`undefined` deletes it), and what the call resolves with. */
+interface Change<T = unknown> {
+  readonly key: string
+  readonly text: string | undefined
+  readonly result: T
+}
+
+/** A call waiting for the file write that will contain it. Its change reads the state as the calls before it in the round left it. */
+interface Pending {
+  readonly change: (read: (key: string) => string | undefined) => Change
+  readonly resolve: (result: unknown) => void
+  readonly reject: (error: unknown) => void
+}
+
+/** Open (and create, when missing) a JSON-file store. @throws when the file exists and is not a readable kv file. */
+export async function openKv(options: OpenKvOptions): Promise<KvOpened> {
+  const file = resolve(options.path)
+  await mkdir(dirname(file), { recursive: true })
+  await removeStrays(file)
+  let state = await load(file)
+  let closed = false
+  let sequence = 0
+  /** Calls waiting for the next file write, in call order. */
+  let queue: Pending[] = []
+  /** 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<void> = Promise.resolve()
+
+  const guard = (): void => {
+    if (closed) throw new Error(`acryl-kv-json: ${file} is closed`)
+  }
+
+  /** Persist a map: the file is the old one or this one, never between. */
+  const persist = async (next: ReadonlyMap<string, string>): Promise<void> => {
+    sequence += 1
+    const temp = join(dirname(file), `${tempPrefix(file)}${process.pid}.${sequence}.tmp`)
+    try {
+      const handle = await open(temp, 'w')
+      try {
+        await handle.writeFile(serialize(next), 'utf8')
+        await handle.sync()
+      } finally {
+        await handle.close()
+      }
+      await replace(temp, file)
+    } catch (error) {
+      await rm(temp, { force: true })
+      throw error
+    }
+    await flushFolder(dirname(file))
+  }
+
+  /**
+   * 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 (): Promise<void> => {
+    try {
+      // Let the calls made in this turn join the first round.
+      await Promise.resolve()
+      await rounds()
+    } finally {
+      draining = false
+    }
+  }
+
+  const rounds = async (): Promise<void> => {
+    while (queue.length > 0) {
+      const round = queue
+      queue = []
+      const draft = new Map(state)
+      const applied: { readonly call: Pending; readonly result: unknown }[] = []
+      for (const call of round) {
+        let change: Change
+        try {
+          change = call.change(key => draft.get(key))
+        } catch (error) {
+          call.reject(error)
+          continue
+        }
+        if (change.text === undefined) 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
+      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 = <T>(change: (read: (key: string) => string | undefined) => Change<T>): Promise<T> => {
+    guard()
+    const done = new Promise<T>((resolveCall, rejectCall) => {
+      queue.push({ change, resolve: resolveCall as (result: unknown) => void, reject: rejectCall })
+    })
+    if (!draining) {
+      draining = true
+      drained = drain()
+    }
+    return done
+  }
+
+  const kv: Kv = {
+    async get<T>(key: string) {
+      guard()
+      checkKey(key)
+      const text = state.get(key)
+      return text === undefined ? undefined : decodeValue<T>(text)
+    },
+    async set(key, value) {
+      checkKey(key)
+      const text = encodeValue(value)
+      await write(() => ({ key, text, result: undefined }))
+    },
+    async update<T>(key: string, change: (current: T | undefined) => T) {
+      checkKey(key)
+      return write(read => {
+        const text = read(key)
+        const encoded = encodeValue(runChange(change, text === undefined ? undefined : decodeValue<T>(text)))
+        return { key, text: encoded, result: decodeValue<T>(encoded) }
+      })
+    },
+    async delete(key) {
+      checkKey(key)
+      await write(() => ({ key, text: undefined, result: undefined }))
+    },
+    async list(prefix = '') {
+      guard()
+      return [...state.keys()].filter(key => key.startsWith(prefix)).sort(compareKeys)
+    },
+  }
+
+  return {
+    kv,
+    close: async () => {
+      closed = true
+      await drained
+    },
+  }
+}

package/plugins/acryl-kv-json/upstream.json

@@ -0,0 +1,22 @@
+{
+  "source": {
+    "repo": "acryldev/acryl",
+    "path": "plugins/acryl-kv-json",
+    "commit": "f132283c43337f5e1d58dfbbbc15786efb5e756c"
+  },
+  "vendored": [
+    "src",
+    "tests",
+    "LICENSE"
+  ],
+  "rewrittenSpecifiers": 6,
+  "digest": "sha256:10613b53bdcf15cce86d6dce5e606d0cd93367cc2569b7603cbf157ebc557548",
+  "testsNotRun": {
+    "tests/loader.spec.ts": "loads the plugin through the real Loader (@deepseek-ai/cordis-plugin-loader), which generated apps do not install; the plain opener it wraps is tested here by open.spec.ts and conformance.spec.ts",
+    "tests/crash.spec.ts": "kills a child process that imports the package build (lib/), which a copy vendored into an app does not have; it runs in ACRYL",
+    "tests/plain-entry-imports.spec.ts": "a copy vendored into an app (with relative imports, no build of its own) has neither `lib/`; the app's own typecheck is what proves the copy names no Cordis type it does not provide."
+  },
+  "notice": [
+    "LICENSE"
+  ]
+}

package/plugins/acryl-node-server/src/client-modules.ts

@@ -1,12 +1,12 @@
 /**
  * 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.
  */
 
 import { copyFileSync, mkdirSync, readFileSync, readdirSync, realpathSync, statSync, writeFileSync } from 'node:fs'
@@ -16,7 +16,7 @@ import { Acryl } from '../../acryl-router/src/index.ts'
 import { basePath } from '../../acryl-router/src/helpers/index.ts'
 import { MissingTypeScriptError, compileModule } from './transpile.ts'
 
-/** 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: Readonly<Record<string, string>> = {
@@ -25,8 +25,9 @@ const BROWSER_IMPORTS: Readonly<Record<string, string>> = {
   'acrylblends/jsx/dom/jsx-dev-runtime': 'jsx-dom.js',
   'acrylblends/jsx/dom/client': 'jsx-dom.js',
   'acrylblends/client': 'client.js',
+  'acrylblends/read-sse': 'read-sse.js',
 }
-const RUNTIME_FILES = ['jsx-dom.js', 'client.js'] as const
+const RUNTIME_FILES = ['jsx-dom.js', 'client.js', 'read-sse.js'] as const
 const COMPILED = new Set(['.ts', '.tsx', '.jsx', '.mts'])
 const SERVED = new Set([...COMPILED, '.js', '.mjs'])
 const JS_TYPE = 'text/javascript; charset=utf-8'
@@ -41,7 +42,7 @@ export 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
 }
 
@@ -51,11 +52,11 @@ export 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
 }
 
-/** 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 = (): string => 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. */
@@ -264,7 +265,7 @@ function sourceFiles(root: string, dir = root): string[] {
 
 /**
  * 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/plugins/acryl-node-server/src/index.ts

@@ -93,13 +93,24 @@ export class NodeServer extends Service {
         this.bound = (this.server.address() as AddressInfo).port
         return
       } catch (error) {
-        if ((error as NodeJS.ErrnoException).code !== 'EADDRINUSE') throw error
+        if (!isPortUnavailable(error)) throw error
       }
     }
     throw new Error(`acryl-node-server: no free port from ${String(port)} to ${String(last)} on ${hostname}`)
   }
 }
 
+/**
+ * Whether a failed bind means "this port, try the next one". A port another socket holds answers `EADDRINUSE` everywhere. On Windows a port
+ * inside a range the system reserves (Hyper-V, WSL and Docker exclude ranges, `netsh interface ipv4 show excludedportrange`) answers
+ * `EACCES`, which is a property of that port too; elsewhere `EACCES` means the process may not bind low ports at all, so moving on would
+ * only hide the reason.
+ */
+export function isPortUnavailable(error: unknown, platform: NodeJS.Platform = process.platform): boolean {
+  const code = (error as NodeJS.ErrnoException | undefined)?.code
+  return code === 'EADDRINUSE' || (platform === 'win32' && code === 'EACCES')
+}
+
 /** Loads once the server listens, so a plugin that injects `nodeServer` can rely on `url`. A failure to bind fails the plugin. */
 export async function apply(ctx: Context, config: Partial<Config> = {}): Promise<void> {
   const server = new NodeServer(ctx, { hostname: '127.0.0.1', port: 0, scan: 20, ...config })

package/plugins/acryl-node-server/upstream.json

@@ -2,7 +2,7 @@
   "source": {
     "repo": "acryldev/acryl",
     "path": "plugins/acryl-node-server",
-    "commit": "8e23e14336647943d4232047e3ea253e434535d3"
+    "commit": "f132283c43337f5e1d58dfbbbc15786efb5e756c"
   },
   "vendored": [
     "src",
@@ -10,7 +10,7 @@
     "LICENSE"
   ],
   "rewrittenSpecifiers": 31,
-  "digest": "sha256:0a3278e006540d0dbecdfb6ada3ca865f3a9a78b649edd9454dab0c76281eda0",
+  "digest": "sha256:e92c0621600e414cffd3e063c117a887410de53113ac4f5966231b419ed92da1",
   "testsNotRun": {
     "tests/client-modules.spec.ts": "links typescript from the plugin's own node_modules (ACRYL's workspace layout); clientModules and build-client are exercised here by the templates' tests and verify:scaffolder",
     "tests/register.spec.ts": "links typescript from the plugin's own node_modules (ACRYL's workspace layout); the hook is exercised here by the templates' own .tsx tests and verify:scaffolder"

package/plugins/acryl-router/src/browser/read-sse.ts

@@ -0,0 +1,3 @@
+/** `readSSE` (`acrylblends/read-sse`) as one browser module with no imports, served by `clientModules`. */
+
+export * from '../helpers/read-sse.ts'