@abide/abide 0.102.0 → 0.104.0

package/src/server/launcherOptions.ts

@@ -1,12 +1,11 @@
-// 38.80 — THE `launcher` A `src/launcher.abide`'S `<script module>` EXPORTS: the window the desktop
-// app opens and the forms its launcher offers. 34.32 — read off the module as the app launches,
-// never by evaluating it during the bundle.
+// 38.80 — WHAT THE `onLauncher` A `src/launcher.abide` CALLS ANSWERS: the window the desktop app opens
+// and the forms its launcher offers, read as the app launches.
 
 import { isRecord } from '#shared/isRecord.ts'
 
 /**
- * What the `launcher` export may set. 38.81 — turning off both forms is not one of them, so the
- * checker refuses it where the export is typed.
+ * What `onLauncher` may answer. 38.81 — turning off both forms is not one of them, so the checker
+ * refuses it where the answer is typed.
  */
 export type LauncherOptions = {
     width?: number
@@ -29,10 +28,10 @@ const SIZES = ['width', 'height', 'minWidth', 'minHeight'] as const
 const FORMS = ['start', 'connect'] as const
 
 /**
- * The launcher `exported` sets, or the refusal naming what is wrong with it — the export read at
- * run time, where an untyped one can still name a key it does not take.
+ * The launcher what `onLauncher` answered sets, or the refusal naming what is wrong with it — read
+ * at run time, where an untyped answer can still name a key it does not take.
  */
-export function launcherOf(exported: unknown): Launcher | string {
+export function launcherOf(answered: unknown): Launcher | string {
     const launcher: Launcher = {
         width: 1100,
         height: 760,
@@ -41,9 +40,9 @@ export function launcherOf(exported: unknown): Launcher | string {
         start: true,
         connect: true,
     }
-    if (exported === undefined) return launcher
-    if (!isRecord(exported)) return '`launcher` is an object'
-    for (const [key, value] of Object.entries(exported)) {
+    if (answered === undefined) return launcher
+    if (!isRecord(answered)) return '`onLauncher` answers an object'
+    for (const [key, value] of Object.entries(answered)) {
         if (
             (SIZES as readonly string[]).includes(key) &&
             typeof value === 'number' &&
@@ -56,10 +55,10 @@ export function launcherOf(exported: unknown): Launcher | string {
         )
             launcher[key as (typeof FORMS)[number]] = value
         else
-            return `\`launcher.${key}\` is not a launcher option, or ${JSON.stringify(value)} is not a value it takes`
+            return `\`${key}\` is not a launcher option, or ${JSON.stringify(value)} is not a value it takes`
     }
     // 38.81.
     if (!launcher.start && !launcher.connect)
-        return '`launcher` turns off both start and connect, which leaves the launcher nothing to do'
+        return '`onLauncher` turns off both start and connect, which leaves the launcher nothing to do'
     return launcher
 }

package/src/server/launcherPage.ts

@@ -21,9 +21,9 @@ const SYSTEM_ACCENT = '#0a84ff'
 export type Launch = {
     /** The app's name, as its package gives it. */
     name: string
-    /** Where the start form posts, or `undefined` where the `launcher` export turns starting off. */
+    /** Where the start form posts, or `undefined` where what `onLauncher` answers turns starting off. */
     start: string | undefined
-    /** Where the connect form posts, or `undefined` where the `launcher` export turns connecting off. */
+    /** Where the connect form posts, or `undefined` where what `onLauncher` answers turns connecting off. */
     connect: string | undefined
     fields: ConfigField[]
     /** The URL the last connect was given. */

package/src/server/nativeMenu.ts

@@ -1,5 +1,5 @@
-// THE DESKTOP APP'S MENU BAR (38.88): the default, with what the page the window shows exports,
-// built as an `NSMenu`.
+// THE DESKTOP APP'S MENU BAR (38.88): the default, with the menus the standing layouts and page file
+// with `onMenu`, built as an `NSMenu`.
 
 import { FFIType } from 'bun:ffi'
 import type { MenuRole } from '#shared/menuItem.ts'
@@ -77,7 +77,7 @@ const NAMED_KEYS: Record<string, string> = {
  * The menu bar the window shows: the application, File, Edit, View and Window menus, and `added`.
  *
  * 38.88 — AN ADDED MENU NAMED AS A DEFAULT ONE GROWS IT, and any other stands before Window, where
- * the platform puts an app's own. 38.83 — no Connect… where the `launcher` export turns connecting off.
+ * the platform puts an app's own. 38.83 — no Connect… where what `onLauncher` answers turns connecting off.
  */
 export function menuBar(
     appName: string,

package/src/server/preload.ts

@@ -0,0 +1,13 @@
+// 38.109 — `@abide/abide/test`, PRELOADED BY `bun test`: the app's compilation served before any test
+// file is loaded, so a test imports a `.abide` as any module — beside the code it tests, at the top
+// of the file, with no `createApp` run first. Bun loads every import of a file before it evaluates
+// any, so registering the compilation from inside a test is always too late; a preload is the
+// one place that runs first. The build is `createApp`'s own under `bun test` (42.16), so a test that
+// boots the app afterwards reuses it rather than building twice.
+
+import { appRoot, servedBuild } from './createApp.ts'
+
+const root = appRoot(undefined)
+// A run from a directory that holds no app — a workspace's root — preloads nothing.
+// Fresh whatever `NODE_ENV` says: `bun test` sets it only where nothing else has.
+if (root !== undefined) await servedBuild(root, true)

package/src/server/runDesktop.ts

@@ -26,7 +26,7 @@ import { APP_PACKAGE, configuredMount, dataDirectory } from './config.ts'
 import { configFields } from './configFields.ts'
 import { type App, type AppOrigin, bootApp } from './createApp.ts'
 import { executableName } from './executableName.ts'
-import { reportUnexpected } from './hooks.ts'
+import { HOOKS, inOrder, reportUnexpected } from './hooks.ts'
 import { installServer } from './installServer.ts'
 import { launcherOf } from './launcherOptions.ts'
 import { type Launch, launcherPage } from './launcherPage.ts'
@@ -53,15 +53,10 @@ type Failure = {
 
 /** What `abide bundle` read of the launcher's files, carried in the executable. */
 export type Desktop = {
-    /** 38.80 — `src/launcher.abide`, where the app has one: its `launcher`, and its page. */
+    /** 38.82 — `src/launcher.abide`'s page, where the app has one that paints. */
     launch:
-        | (() => Promise<{
-              default: (props: Launch) => Component
-              launcher?: unknown
-          }>)
+        | (() => Promise<{ default: (props: Launch) => Component }>)
         | undefined
-    /** 38.82 — whether that file has markup of its own, which then stands in for the built-in page. */
-    custom: boolean
     /** The document the launch page renders into, its stylesheet already in its head (38.84). */
     document: string
     /** 38.101 — the app's icon as a data URL, and the accent taken from it. */
@@ -87,23 +82,23 @@ export async function runDesktop(
 async function launch(
     origin: AppOrigin,
     load: () => ReturnType<typeof builtSources>,
-    { launch: launchModule, custom, document, icon, accent }: Desktop,
+    { launch: launchModule, document, icon, accent }: Desktop,
 ): Promise<void> {
     installServer()
     APP_PACKAGE.current = origin.package
-    // 37.1 — imported for what it files, so the start form reads `onConfig`.
+    // 37.1 — imported for what it files, so the start form reads `onConfig` and the launcher's
+    // `onLauncher` is filed.
     await origin.hooks?.()
-    // 34.32 — the `launcher` export, read off its module as the app launches. 38.85 — one that fails
-    // to load leaves the built-in page, with its defaults.
-    const launcherModule = await launchModule?.().catch((thrown: unknown) => {
+    // 38.85 — a launcher page that fails to load leaves the built-in page, with its defaults.
+    const launchPage = await launchModule?.().catch((thrown: unknown) => {
         reportUnexpected(thrown)
         return undefined
     })
-    const options = launcherOf(launcherModule?.launcher)
-    // 38.81 — a `launcher` the checker would have refused, written where nothing checked it.
+    // 38.80 — what its `onLauncher` answers.
+    const options = launcherOf(inOrder(HOOKS.launcher).at(-1)?.())
+    // 38.81 — an `onLauncher` answer the checker would have refused, written where nothing checked it.
     if (typeof options === 'string')
         throw new Error(`abide: ${options}. RULEBOOK 38.81.`)
-    const launchPage = custom ? launcherModule : undefined
     const appName = executableName(origin.package.name)
     const directory = dataDirectory(origin.package.name ?? 'app')
     const stateFile = `${directory}/desktop.json`

package/src/server/serveDev.ts

@@ -22,6 +22,7 @@ import { watch } from 'node:fs' // bun exposes no file watcher of its own
 import { dirname, resolve } from 'node:path' // bun exposes no path helpers of its own
 import {
     type AppChecker,
+    compilationOf,
     compileApp,
     openChecker,
 } from '#compiler/compileApp.ts'
@@ -144,7 +145,7 @@ export async function serveDev(
                 console.warn(formatDiagnosis(warning, process.cwd()))
             watchDependencies(compiled.files)
             return {
-                compilation: { files: compiled.files, tables: compiled.tables },
+                compilation: compilationOf(compiled),
                 published: compiled.published,
                 failure: '',
             }
@@ -154,7 +155,12 @@ export async function serveDev(
                 thrown instanceof Error ? thrown.message : String(thrown)
             console.error(`abide dev: ${failure}`)
             return {
-                compilation: { files: {}, tables: {} },
+                compilation: {
+                    files: {},
+                    handlers: {},
+                    tables: {},
+                    mounted: {},
+                },
                 published: new Map(),
                 failure,
             }

package/src/server/surfaceOf.ts

@@ -31,6 +31,8 @@ export function surfaceOf(
     mount: Mount | Mounted,
     surface: Surface,
 ): Listed | undefined {
+    // 16.71 — a private handler is its file's alone.
+    if (mount.private) return undefined
     const live = 'handler' in mount ? mount : undefined
     // 16.37 — what its `clients` says, and the build's default where it says nothing.
     const carried =

package/src/server/versionOf.ts

@@ -1,8 +1,7 @@
 // 18.7 — THE VERSION A VALUE'S STANDING PRODUCTION IS NAMED BY OVER THE WIRE. Stamped where it is
 // asked for rather than where a production is minted, so a value no browser follows pays nothing on
 // its production path. A production is told apart from the one before by the ordinal, what is held
-// (6.10 moves no ordinal for `undefined`) and the patch epoch of what is held (5.7 moves no ordinal
-// for a patch).
+// and the patch epoch of what is held (5.7 moves no ordinal for a patch).
 //
 // ONE COUNTER FOR THE PROCESS, started at the boot time in microseconds, so no two productions share
 // a number: not two values, not an entry evicted and built again, and not this process and the one

package/src/server/withAbideSources.ts

@@ -96,7 +96,7 @@ export async function withAbideSources(
 }
 
 /**
- * 16.28, 34.20 — the `.abide`'s text with every `<script server>` body blanked: the map is served
+ * 16.28, 34.19 — the `.abide`'s text with every `<script server>` body blanked: the map is served
  * to a browser, which reads none of one. Each line is kept, so every line the map places is still
  * the line it names.
  */

package/src/shared/ADDRESSES.ts

@@ -24,6 +24,9 @@ export const ABIDE_ADDRESS = '/__abide'
  */
 export const CLIENT_ADDRESS = `${ABIDE_ADDRESS}/client`
 
+/** Where a private handler is answered, below its file's path and then its name (16.70). */
+export const PRIVATE_HANDLERS_ADDRESS = `${ABIDE_ADDRESS}/handlers`
+
 // 20.5, 20.9, 36.7 — the generated surfaces, which the CLI reaches as well as the server answers.
 
 /** The generated OpenAPI document. */

package/src/shared/LAUNCHER_FILES.ts

@@ -0,0 +1,9 @@
+// THE DESKTOP LAUNCHER'S FILES. Its page, which calls `onLauncher`, sits at the app's root beside the
+// root layout, a name the framework finds rather than a page (23.21); the icon is a public file,
+// so it is wherever the address it answers at says (36.11).
+
+/** The `.abide` the desktop launcher renders, at the root alone. 38.80, 38.82. */
+export const LAUNCHER_PAGE = 'launcher.abide'
+
+/** The addresses of the desktop app's icon, the `.icns` first. 38.79. */
+export const ICON_ADDRESSES = { icns: '/icon.icns', png: '/icon.png' } as const

package/src/shared/RESERVED_DIRECTORIES.ts

@@ -1,6 +1,7 @@
-// THE TWO DIRECTORY NAMES THAT ARE NEVER AN ADDRESS (23.15): `server` fences a graph (16.29) and
-// `public` is answered as authored (36.11). Every other directory under the root is a segment of the
-// address of the `page.abide`, `layout.abide` and `error.abide` in it (23.14).
+// THE FENCES: the four directory names that are never an address (23.15). `server` fences a graph
+// (16.29), `public` is answered as authored (36.11), and `lib` and `tests` hold what is neither an
+// address nor either of those. Every other directory under the root is a segment of the routes of
+// the files directly in it (23.14), and holds nothing else (23.22).
 
 /** A module under one only the server loads. */
 export const SERVER_DIRECTORY = 'server'
@@ -8,8 +9,22 @@ export const SERVER_DIRECTORY = 'server'
 /** A file under one is answered as authored, at the path above it. */
 export const PUBLIC_DIRECTORY = 'public'
 
-/** Both, as the walk of the app tests a directory against them. */
+/** The app's own code that is no address: components, modules, both sides. */
+export const LIB_DIRECTORY = 'lib'
+
+/** The app's tests. */
+export const TESTS_DIRECTORY = 'tests'
+
+/** All four, as the walk of the app tests a directory against them. */
 export const RESERVED_DIRECTORIES: ReadonlySet<string> = new Set([
     SERVER_DIRECTORY,
     PUBLIC_DIRECTORY,
+    LIB_DIRECTORY,
+    TESTS_DIRECTORY,
+])
+
+/** 23.16 — the fences a `server` directory nests in: it fences a graph rather than an address. */
+export const HOLDS_SERVER: ReadonlySet<string> = new Set([
+    LIB_DIRECTORY,
+    TESTS_DIRECTORY,
 ])

package/src/shared/index.ts

@@ -36,13 +36,14 @@ export { listOf } from './listOf.ts'
 export { type Logger, type LogRecord, log } from './log.ts'
 export type { Middleware } from './Middleware.ts'
 export type { Params } from './matchRoute.ts'
-// 38.88 — a desktop app's menu items, exported by the route's layouts and page.
+// 38.88 — a desktop app's menu items, and the hook a route's layouts and page file them with.
 export {
     type MenuEntry,
     type MenuItem,
     type MenuRole,
     menuItem,
 } from './menuItem.ts'
+export { onMenu } from './onMenu.ts'
 // `navigate` ALONE, of everything routing needs. This barrel is what an app resolves through the
 // bare `@abide/abide` specifier, and the matcher, the pattern grammar and `routeOf` are reached by path
 // from the two places that have them — the build and the client router. Putting them here would

package/src/{ui → shared}/menuBridge.ts

@@ -1,7 +1,7 @@
 /**
  * The channel a desktop app's window opens to the page for its menu, or `undefined` in a browser.
  *
- * ITS OWN MODULE, so the router asks without importing the reporter: `reportMenu` is a chunk only a
+ * ITS OWN MODULE, so `onMenu` asks without importing the reporter: `reportMenu` is a chunk only a
  * page inside a desktop app loads. 38.88.
  */
 export function menuBridge():

package/src/shared/menuItem.ts

@@ -1,5 +1,5 @@
-// 38.88 — THE DESKTOP APP'S MENU BAR IS THE ROUTE'S: a layout or a page exports `menu` from its
-// `<script module>`, and the window shows what the route it stands on exports. An item made by
+// 38.88 — THE DESKTOP APP'S MENU BAR IS THE ROUTE'S: a layout or a page calls `onMenu` in its
+// `<script>`, and the window shows the menus filed while it stands. An item made by
 // `menuItem` is one a page answers; the rest are an address or a role, which need no page.
 
 /** What a menu item does natively, where an address or a page's own answer could not. 38.89. */

package/src/shared/onMenu.ts

@@ -0,0 +1,58 @@
+// 38.88, 38.92 — THE MENUS A LAYOUT OR A PAGE ADDS TO A DESKTOP APP'S MENU BAR, filed while it
+// stands. Called in its `<script>`, so the menus are a function of its state: what `read` reads moving
+// tells the window again, and the component going takes them with it. Outside a desktop app's window
+// there is no menu bar, and nothing is filed.
+
+import { menuBridge } from './menuBridge.ts'
+import type { MenuItem } from './menuItem.ts'
+import { watch } from './reactive/index.ts'
+
+/** One `onMenu`'s menus, as it last answered, and whether its component has gone. */
+type Filed = { menus: MenuItem[]; gone: boolean }
+
+// IN THE ORDER FILED, which is outermost first: a layout's setup runs before the page inside it.
+let filed: Filed[] = []
+let telling = false
+
+/** Files the menus `read` answers for as long as the calling component stands; returns what unfiles them. */
+export function onMenu(read: () => readonly MenuItem[]): () => void {
+    if (menuBridge() === undefined) return () => {}
+    const entry: Filed = { menus: [], gone: false }
+    filed.push(entry)
+    const stop = watch(() => {
+        entry.gone = false
+        entry.menus = [...read()]
+        tell()
+        // A rerun files again at once; a component that went stays gone.
+        return () => {
+            entry.gone = true
+            tell()
+        }
+    })
+    // 12.8 — a `read` that threw stopped the watch with no cleanup to run, so the unfiling is
+    // done here too.
+    return () => {
+        stop()
+        entry.gone = true
+        tell()
+    }
+}
+
+// ONCE PER TURN, after every rerun and every component a navigation took has settled.
+function tell(): void {
+    if (telling) return
+    telling = true
+    queueMicrotask(async () => {
+        telling = false
+        const standing: Filed[] = []
+        const menus: MenuItem[] = []
+        for (const entry of filed) {
+            if (entry.gone) continue
+            standing.push(entry)
+            menus.push(...entry.menus)
+        }
+        filed = standing
+        const { reportMenu } = await import('./reportMenu.ts')
+        reportMenu(menus)
+    })
+}

package/src/shared/reactive/Cursor.ts

@@ -1,14 +1,12 @@
-// THE CURSOR. RULEBOOK 2.5: `for await (… of s)` — the production in flight, then each one after
-// it. On a streaming producer that is one turn per CHUNK, read from the chunk buffer by ordinal,
-// so two chunks between two `await`s are two turns of the loop. On every other value it is the
-// standing production: a burst between two turns collapses to the latest, since nothing else is
-// held. An app that wants every message keeps them — a channel is an array.
+// THE CURSOR. RULEBOOK 2.6: a streaming producer's chunks, read from the chunk buffer by ordinal,
+// so two chunks between two `await`s are two turns of the loop, and a patch or a write over the
+// stream moves no place (5.7, 9.12). Where the run ENDS is the caller's settling, handed to
+// `closeOn`: `for await` over a `Reactive` is `Reactive.ts`'s `producedRun`.
 //
 // A NARROW FACE rather than the `Cell`, the same way `tracking.ts` takes a `Tracked`: what a
 // cursor reads is a handful of fields, and naming them keeps the cell's internals out of a
 // second file.
 
-import { PATCHES } from './PATCHES.ts'
 import {
     dropReader,
     newSubscriber,
@@ -23,21 +21,14 @@ import {
  * place in a stream's chunk buffer without the buffer having to hold one.
  */
 export type Retained = Tracked & {
-    /** The window a `throttle` or a `debounce` holds open, `holding` while a production waits on it. */
-    cap: { holding: boolean } | null
     ordinal: number
     ring: unknown[]
     ringBase: number
-    servable: boolean
-    state: number
-    /**
-     * Non-null on a streaming producer, whose ring is the accumulation of the run being served
-     * (9.1) and is retained whole — the chunks ARE the value.
-     */
-    stream: object | null
-    value: unknown
 }
 
+/** What `take` answers when the cursor has caught up — never a chunk, which may be `undefined`. */
+export const CAUGHT_UP: unique symbol = Symbol('caught up')
+
 // The cursors standing over each source, for a patch to keep the place of the ones behind (5.7).
 const CURSORS = new WeakMap<Retained, Set<Cursor>>()
 
@@ -70,61 +61,36 @@ export function hasCursorBehind(source: Retained): boolean {
 }
 
 /**
- * A live reader of a source's productions, one turn per production, in order.
+ * A reader of a stream's chunks, in order, waking whoever waits on it when one lands.
  *
- * A RECORD, NOT A SCOPE. The four closures this was — `take`, `notify`, `stop` and `next` — shared
- * one environment holding `at`, `waiting`, `source` and `reader`, and a cursor OUTLIVES the call
- * that made it: a `for await` holds one for the life of the loop, so the environment and every
- * function object hanging off it is live that whole time. Fields on a prototype are the object
- * alone, and `at` — read and written on every turn — becomes a property load on a fixed structure
- * rather than a scope load.
+ * A RECORD, NOT A SCOPE. A cursor outlives the call that made it — a `for await` holds one for the
+ * life of the loop — so fields on a prototype are the object alone, and `at`, read and written on
+ * every turn, is a property load on a fixed structure rather than a scope load.
  */
-export class Cursor implements AsyncIterator<unknown> {
+export class Cursor {
     source: Retained
-    /** The ordinal of the last production this cursor handed over. */
+    /** The ordinal of the last chunk this cursor handed over. */
     at: number
-    /**
-     * The patch epoch the value it last handed over stood at.
-     *
-     * A PATCH MINTS NO ORDINAL (5.7) — the follow's version tells a patch from a production by
-     * exactly that — so a cursor over a value patched in place reads the change off the object.
-     */
-    patched: number
-    /**
-     * The turns asked for and not yet answered.
-     *
-     * A QUEUE rather than one slot because a consumer may ask twice before either answer arrives
-     * — `Promise.all([ it.next(), it.next() ])` is the shape, and with one slot the second `next`
-     * overwrote the first's resolver and that promise never settled at all. `for await` asks one
-     * at a time, which is why nothing here said so.
-     */
-    waiting: ((result: IteratorResult<unknown>) => void)[]
+    /** Called once at the next wake, then cleared. */
+    wake: (() => void) | null
+    /** Whether the run `closeOn` was handed has settled. */
+    closed: boolean
+    /** What that run rejected with. */
+    failure: unknown
     reader: Subscriber
 
     constructor(source: Retained, from: number) {
         this.source = source
         this.at = from
-        this.patched = 0
-        this.waiting = []
-        // The one closure left, and it captures this cursor and nothing else. `notify` is
-        // called as a method on the SUBSCRIBER, so it cannot be the cursor's own method —
-        // and widening `Subscriber` with a back-edge would put a field on the shape every
-        // reader in the graph carries for the sake of the few that are cursors.
-        // Registered outside the tracking protocol, so the source it waits on is declared
-        // rather than discovered — see the same shape in `Reactive`'s `settled`.
+        this.wake = null
+        this.closed = false
+        this.failure = undefined
+        // The one closure left, and it captures this cursor and nothing else. `notify` is called as a
+        // method on the SUBSCRIBER, so it cannot be the cursor's own method. Registered outside the
+        // tracking protocol, so the source it waits on is declared rather than discovered — see the
+        // same shape in `Reactive`'s `settled`.
         this.reader = newSubscriber([source], null)
-        // One production per waiting turn, in the order they were asked for: a burst that
-        // lands three productions on a consumer holding two turns answers both.
-        this.reader.notify = (): void => {
-            const waiting = this.waiting
-            while (waiting.length !== 0) {
-                const next = this.take()
-                if (next === null) return
-                ;(waiting.shift() as (result: IteratorResult<unknown>) => void)(
-                    next,
-                )
-            }
-        }
+        this.reader.notify = (): void => this.woken()
         source.readers.push(this.reader)
         let cursors = CURSORS.get(source)
         if (cursors === undefined) {
@@ -135,83 +101,60 @@ export class Cursor implements AsyncIterator<unknown> {
     }
 
     /**
-     * One production, or `null` where the cursor has caught up.
+     * The next chunk, or `CAUGHT_UP`.
      *
-     * Reading a stream's chunks by ordinal is what keeps a burst from being a gap or a repeat.
+     * Reading by ordinal is what keeps a burst from being a gap or a repeat.
      */
-    take(): IteratorResult<unknown> | null {
+    take(): unknown {
         const source = this.source
-        let at = this.at
-        if (source.stream === null) {
-            const value = source.value
-            // 6.10: an `undefined` standing is caught up, not a turn.
-            if (value === undefined) return null
-            const patched =
-                value !== null && typeof value === 'object'
-                    ? (PATCHES.written.get(value) ?? 0)
-                    : 0
-            if (at >= source.ordinal && patched === this.patched) return null
-            // 5.9 — A PRODUCTION A WINDOW HOLDS has minted its ordinal and is not yet the value: the
-            // turn is the release's, which wakes this cursor.
-            if (source.cap?.holding === true) return null
-            // The standing production is the only one held, so everything minted or patched
-            // since the last turn collapses into it.
-            this.at = source.ordinal
-            this.patched = patched
-            return { value, done: false }
-        }
-        if (at >= source.ordinal) return null
-        // A run that restarted moved the buffer past this cursor: answer from its start.
-        if (at < source.ringBase) at = source.ringBase
-        const value = source.ring[at - source.ringBase]
-        this.at = at + 1
-        return { value, done: false }
-    }
-
-    next(): Promise<IteratorResult<unknown>> {
-        if (!this.reader.alive)
-            return Promise.resolve({ value: undefined, done: true })
-        // A TURN ALREADY ASKED FOR AND NOT ANSWERED KEEPS THE ORDER: taking from the
-        // ring here while one is queued would hand the later caller the earlier
-        // production.
-        if (this.waiting.length === 0) {
-            const ready = this.take()
-            // NOT `async`, and no `await` on the caught-up arm. A cursor behind a
-            // stream's chunks is the common shape while a burst drains, and an
-            // `async` here would put a microtask tick between every one of those
-            // turns.
-            if (ready !== null) return Promise.resolve(ready)
-        }
-        const waiting = this.waiting
-        return new Promise((resolve) => {
-            waiting.push(resolve)
-        })
+        if (this.at >= source.ordinal) return CAUGHT_UP
+        const value = source.ring[this.at - source.ringBase]
+        this.at += 1
+        return value
     }
 
     /**
-     * Ends the cursor: `for await` calls this on `break`, on `return` and on a throw.
+     * Ends the cursor's run where `run` settles: `closed` is set, `failure` holds a rejection, and
+     * the current `turn` wakes.
      *
-     * It is the only thing that drops the subscriber — a live cursor has no end of its own.
+     * ONE REACTION ON THE CLOSE FOR THE WHOLE RUN, never one per chunk held until the run ends. A
+     * chunk landing in the same turn as the close is still unread when the close wakes the caller,
+     * so a drain before reading `closed` hands it over rather than losing it to whichever settled
+     * first.
      */
-    return(): Promise<IteratorResult<unknown>> {
-        return this.stop()
+    closeOn(run: PromiseLike<unknown>): void {
+        run.then(
+            () => {
+                this.closed = true
+                this.woken()
+            },
+            (error: unknown) => {
+                this.closed = true
+                this.failure = error
+                this.woken()
+            },
+        )
+    }
+
+    /** Settles at the next chunk or the close, whichever lands first. */
+    turn(): Promise<void> {
+        return new Promise((resolve) => {
+            this.wake = resolve
+        })
     }
 
-    throw(): Promise<IteratorResult<unknown>> {
-        return this.stop()
+    private woken(): void {
+        const wake = this.wake
+        this.wake = null
+        wake?.()
     }
 
-    stop(): Promise<IteratorResult<unknown>> {
+    /** Drops the subscriber; nothing else does. */
+    stop(): void {
         const reader = this.reader
         reader.alive = false
         dropReader(this.source, reader)
         CURSORS.get(this.source)?.delete(this)
-        const waiting = this.waiting
-        while (waiting.length !== 0)
-            (waiting.shift() as (result: IteratorResult<unknown>) => void)({
-                value: undefined,
-                done: true,
-            })
-        return Promise.resolve({ value: undefined, done: true })
+        this.wake = null
     }
 }