@stacksjs/defaults 0.75.231 → 0.75.233

package/ai/skills/stacks-native/CATALOG.md

@@ -86,9 +86,9 @@ Browser runtime bindings are documented separately in `stacks-auto-imports`.
 | `@stacksjs/slug` | [`stacks-slug`](../stacks-slug/SKILL.md) | [entrypoint](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/slug/src/index.ts) | 4 |
 | `@stacksjs/sms` | [`stacks-sms`](../stacks-sms/SKILL.md) | [entrypoint](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/sms/src/index.ts) | 5 |
 | `@stacksjs/socials` | [`stacks-socials`](../stacks-socials/SKILL.md) | [entrypoint](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/socials/src/index.ts) | 17 |
-| `@stacksjs/storage` | [`stacks-storage`](../stacks-storage/SKILL.md) | [entrypoint](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/storage/src/index.ts) | 40 |
+| `@stacksjs/storage` | [`stacks-storage`](../stacks-storage/SKILL.md) | [entrypoint](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/storage/src/index.ts) | 42 |
 | `@stacksjs/strings` | [`stacks-strings`](../stacks-strings/SKILL.md) | [entrypoint](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/strings/src/index.ts) | 7 |
-| `@stacksjs/testing` | [`stacks-testing`](../stacks-testing/SKILL.md) | [entrypoint](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/testing/src/index.ts) | 14 |
+| `@stacksjs/testing` | [`stacks-testing`](../stacks-testing/SKILL.md) | [entrypoint](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/testing/src/index.ts) | 15 |
 | `@stacksjs/tinker` | [`stacks-repl`](../stacks-repl/SKILL.md) | [entrypoint](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/tinker/src/index.ts) | 1 |
 | `@stacksjs/tunnel` | [`stacks-tunnel`](../stacks-tunnel/SKILL.md) | [entrypoint](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/tunnel/src/index.ts) | 1 |
 | `@stacksjs/types` | [`stacks-types`](../stacks-types/SKILL.md) | [entrypoint](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/types/src/index.ts) | 2 |
@@ -831,7 +831,7 @@ Declared runtime exports: `PathSanitizeError`, `Storage`, `StorageManager`, `Upl
 
 Local source modules: [src/adapters/index.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/storage/src/adapters/index.ts), [src/bounded-text-file.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/storage/src/bounded-text-file.ts), [src/completed-artifact-directory.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/storage/src/completed-artifact-directory.ts), [src/copy.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/storage/src/copy.ts), [src/delete.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/storage/src/delete.ts), [src/drivers/index.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/storage/src/drivers/index.ts), [src/facade.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/storage/src/facade.ts), [src/file-info.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/storage/src/file-info.ts), [src/files.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/storage/src/files.ts), [src/folders.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/storage/src/folders.ts), [src/fs.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/storage/src/fs.ts), [src/glob.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/storage/src/glob.ts), [src/hash.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/storage/src/hash.ts), [src/helpers.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/storage/src/helpers.ts), [src/mime-verify.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/storage/src/mime-verify.ts), [src/path-sanitize.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/storage/src/path-sanitize.ts), [src/provision.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/storage/src/provision.ts), [src/s3-presigned-post.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/storage/src/s3-presigned-post.ts), [src/signed-url.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/storage/src/signed-url.ts), [src/static-serve.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/storage/src/static-serve.ts), [src/storage.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/storage/src/storage.ts), [src/temporary-workspaces.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/storage/src/temporary-workspaces.ts), [src/types.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/storage/src/types.ts), [src/types/filesystem.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/storage/src/types/filesystem.ts), [src/uploaded-file.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/storage/src/uploaded-file.ts), [src/zip.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/storage/src/zip.ts).
 
-Evidence directory: [40 retained tests](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/storage/tests). These files are evidence pointers, not a claim that all tests were run for this catalog.
+Evidence directory: [42 retained tests](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/storage/tests). These files are evidence pointers, not a claim that all tests were run for this catalog.
 
 ### @stacksjs/strings
 
@@ -851,7 +851,7 @@ Read the entrypoint and package export map for re-exported or type-only surfaces
 
 Local source modules: [src/console.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/testing/src/console.ts), [src/disposable-database.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/testing/src/disposable-database.ts), [src/events.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/testing/src/events.ts), [src/feature.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/testing/src/feature.ts), [src/isolated.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/testing/src/isolated.ts), [src/mail.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/testing/src/mail.ts), [src/time.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/testing/src/time.ts).
 
-Evidence directory: [14 retained tests](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/testing/tests). These files are evidence pointers, not a claim that all tests were run for this catalog.
+Evidence directory: [15 retained tests](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/testing/tests). These files are evidence pointers, not a claim that all tests were run for this catalog.
 
 ### @stacksjs/tinker
 

package/ai/skills/stacks-storage/SKILL.md

@@ -85,6 +85,36 @@ parent-directory authorization and domain validation. This is a local hard-link
 and directory-fsync protocol, not a cloud-adapter transaction or tested hardware
 power-loss guarantee.
 
+For a durable ownership checkpoint before private bytes, use
+`prepareCompletedArtifactDirectorySync(directory, entries, manifestJson, options)`
+from the same subpath or package root. Its deeply frozen handle contains only
+`receipt` and single-use `publishSync()`. Preparation exclusively creates and
+syncs a private empty tree, then closes every descriptor. Persist the receipt
+before calling the same live handle's publication method. The receipt records
+canonical parent/tree/file identities and planned lengths/SHA-256; observed
+file lengths are zero and `manifest.json` is absent. Planned metadata is not
+completed content or a deletion receipt.
+
+Pass plain data records/lists and unshared Uint8Array/Buffer views. Record/list
+validation refuses proxies, getters, holes and hidden/symbol aliases without
+executing caller code; byte views use intrinsic offsets rather than overrides.
+Publication rechecks the empty tree and identities, writes/syncs
+detached bytes, verifies readback hashes and exclusively links the registered
+pending-manifest inode to completion. Every attempt consumes the handle, even
+on error. Errors preserve state; JSON cannot rehydrate a writer. There is no
+overwrite, arbitrary existing-directory writer or implicit cleanup.
+
+Read the storage README's prepared-artifact section before integrating an
+ownership ledger. It defines decimal-string identities, planned byte semantics,
+birth-time availability, prepublication-only change time and legitimate link
+transitions. Parent paths must already exist, belong to the operator and remain
+controlled. Canonical ancestor aliases are allowed; final targets are exclusive.
+Both calls block the isolate, including while holding any caller transaction.
+Caps bound bytes/files rather than I/O duration; database contention and SQL/FS
+atomicity remain caller concerns. The existing async writer keeps asynchronous
+filesystem execution. Real process-interruption tests do not establish hardware
+power-loss, hostile same-user race, deletion or media-erasure guarantees.
+
 ### Recoverable temporary workspaces
 
 Use `TemporaryWorkspaceJournal` for workers that recover temporary directories after a process interruption. Keep its private journal outside job-controlled checkouts and separate it by stable worker and controller identity. `create(key)` returns a frozen live ownership handle; stop its resources, then call `complete(handle)` for normal disposal. A restarted instance cannot forge this capability from a listed record.
@@ -106,6 +136,19 @@ await journal.retire(recovered.id, record => controllerConfirmsFinished(record.k
 
 The `Storage` singleton is a pre-instantiated `StorageManager`. It lazily builds its config from `@stacksjs/config` (which reads `config/filesystems.ts` and env vars).
 
+### Directory mounts without retirement
+
+Use `inspectDirectoryMounts(canonicalDirectory)` for read-only current-namespace
+mount checks where legitimate readers may stay open. Supply an existing,
+checked canonical directory. An unmounted result means only that the native
+mount table did not reference that directory or a descendant. Unavailable,
+unsupported, aliased or missing paths never return `unmounted: true`.
+
+Keep `inspectTemporaryWorkspace` and journal retirement for deletion: they also
+check process references and inspection permissions. Mount inspection alone
+grants no ownership, quiescence or retirement authority and does not inspect
+other namespaces or prevent later host changes.
+
 ### Basic Operations
 
 ```typescript

package/ai/skills/stacks-testing/SKILL.md

@@ -169,7 +169,8 @@ expect(result.exitCode).toBe(0)
 
 Retained implementation evidence lives under `core/testing/tests/`:
 `http-client`, `acting-as`, `database-assertions`, `events`, `mail`, `time`,
-`console`, `isolated`, `disposable-database` and `browser` test files. Fixture mechanics live in `core/testing/src/`;
+`console`, `isolated`, `disposable-database`, `browser` and `declarations` (what dtsx
+publishes for `browser.ts` / `isolated.ts`: no `unknown` fields) test files. Fixture mechanics live in `core/testing/src/`;
 `package.json` declares the root and database/DynamoDB/browser export boundaries.
 
 ## Isolated processes and disposable databases
@@ -191,7 +192,7 @@ for (const dialect of ['sqlite', 'postgres'] as const) {
         env: { APP_ENV: 'test', ...database.env },
         timeoutMs: 45_000,
         envFile: false,      // --no-env-file
-        preload: [],         // replace bunfig preloads (none)
+        preload: [],         // replace bunfig preloads (none); or bunfig: 'tests/isolated/bunfig.toml'
       })
       assertIsolatedOk(result, 'checkout flow OK') // throws with stdout + stderr otherwise
     })
@@ -199,10 +200,14 @@ for (const dialect of ['sqlite', 'postgres'] as const) {
 }
 ```
 
-- `runIsolated(file, { env, timeoutMs = 60_000, args, cwd, mode, preload, envFile, inheritEnv, stdin })`
+- `runIsolated(file, { env, timeoutMs = 60_000, args, cwd, mode, preload, bunfig, envFile, inheritEnv, stdin })`
   resolves `{ code, signal, stdout, stderr, timedOut, durationMs, command }`. `mode: 'auto'` runs
   `*.test.*` / `*.spec.*` with `bun test`, anything else as a script; `env` values of `undefined`
   remove a variable. The watchdog sends SIGTERM at the timeout and SIGKILL 2 s later.
+- `bunfig: 'path/bunfig.toml'` runs the child with that config (`--config=`), resolved against
+  `cwd`; it must exist. `preload` instead generates a config holding only those preloads. They are
+  exclusive (a TypeError): list the preloads in your bunfig. Bun resolves a bunfig's relative
+  `preload` paths against the child's cwd, not the bunfig's directory.
 - `withDisposableDatabase(dialect, fn, { url?, prefix? })`: SQLite is a file in a fresh temp
   directory; Postgres is `CREATE DATABASE` on `url` or `STACKS_TEST_POSTGRES_URL`, dropped with
   `DROP DATABASE ... WITH (FORCE)` after `fn`, even when it throws (the test's error wins over a
@@ -236,18 +241,41 @@ expect(pageAuditClean(report)).toBe(true) // no duplicate /api/ requests, failed
 ```
 
 - `Cdp`: `send`, `evaluate`, `on(method, fn)` (any number of listeners per method; returns an
-  unsubscribe), `off`, `once(method, match?, timeoutMs?)`, `errors`, `inFlight` (event streams
-  leave it when their response starts, so a page with live updates can still settle), `closed`
-  (every pending command fails at once when Chrome goes away).
+  unsubscribe), `off`, `once(method, match?, timeoutMs?)`, `intercept(patterns, handler)`,
+  `errors`, `inFlight: Map<requestId, 'METHOD url'>` (event streams leave it when their response
+  starts, so a page with live updates can still settle), `closed` (every pending command fails at
+  once when Chrome goes away).
 - `launch(options)` enables Page/Runtime/Network/Log, sets a 1440x1000 viewport, answers stx's
   live-reload stream (`*/_stx/hmr*`) with a day-long retry so a save mid-run cannot reload the
   page, accepts JavaScript dialogs and records them in `errors`, removes "HeadlessChrome" from the
   user agent, and passes `--use-mock-keychain`. `profile` keeps one profile across relaunches.
+- **Pausing requests next to live reload.** Chrome keeps one `Fetch.enable` pattern set per
+  session (a second call replaces it, `Fetch.disable` drops all) and sends every paused request to
+  every listener, so the session layers them. `await cdp.intercept([{ urlPattern: '*/api/slow*' }],
+  (paused, cdp) => ...)` hands a handler only what its own patterns match and resolves with an
+  async remover; `quietLiveReload(cdp, patterns?)` is one (what `launch()` runs). Your own
+  `cdp.send('Fetch.enable' | 'Fetch.disable')` sets one more layer and the session enables the
+  union, so a journey that holds its own request needs no `quietLiveReload: false`.
+  `on('Fetch.requestPaused')` listeners see the requests your patterns match, not the live-reload
+  stream. The first answer wins: a second `continueRequest`/`fulfillRequest`/`failRequest` for one
+  pause resolves without reaching Chrome. A pause nobody could answer is continued; one your own
+  pattern holds with no listener stays held (a hanging request on purpose).
+  `matchesUrlPattern(pattern, url)` and `pausedRequestMatches(pattern, paused)` are Chrome's
+  matching rules (`*`, `?`, `\` escape; stage and resource type).
 - `settle(cdp, { quietMs, timeoutMs })` resolves false (not throws) when a page never goes quiet.
-- `auditPage(url, { cdp?, launch?, viewport?, isApiRequest?, beforeNavigate?, quietMs, timeoutMs })`
-  returns `{ apiRequests, duplicates, failed, errors, settled, durationMs }` and never throws for a
-  page problem. `beforeNavigate` is where to seed a token (`Page.addScriptToEvaluateOnNewDocument`).
-  `formatPageAudit(report)` prints one line.
+- `auditPage(url, { cdp?, launch?, viewport?, isApiRequest?, beforeNavigate?, pageLoads?, quietMs, timeoutMs })`
+  returns `{ url, finalUrl, apiRequests, duplicates, loads, failed, errors, settled, durationMs }`
+  and never throws for a page problem. `beforeNavigate` is where to seed a token
+  (`Page.addScriptToEvaluateOnNewDocument`). `formatPageAudit(report)` prints one line, with
+  `/today -> /home` when the page landed elsewhere.
+- Duplicates are counted **per page load**: a page that sends you on (`/today` replacing itself with
+  `/home`) is two loads, so `/api/me` once in each is not a duplicate. A load starts with each new
+  main-frame document after the first and each same-document (history API) navigation to a
+  different path; a query or hash change stays in the load. `loads` lists them
+  (`{ url, apiRequests, duplicates }`), `duplicates` is the highest count any one load reached,
+  `finalUrl` is `location.href` once settled. `pageLoads: 'visit'` counts the whole visit as one
+  load (the old behaviour). `splitPageLoads(url, events, mode)` and `loadDuplicates(loads)` are the
+  pure logic. `finalUrl` and `loads` are optional on the type, so hand-built reports still compile.
 - **macOS: the installed Chrome quits about 30 s in.** GoogleUpdater SIGTERMs every process with
   Chrome's bundle id while an update is pending; to a test that looks like a hung page. When
   `CHROME_PATH` is not set, `launch()` runs `prepareMacChrome()`: a `cp -cR` clone in the temp

package/functions/dashboard-form.test.ts

@@ -0,0 +1,41 @@
+import { describe, expect, it } from 'bun:test'
+import { formErrorMessages } from './dashboard-form'
+
+/**
+ * stacksjs/stacks#2918 — this was duplicated across fourteen dialogs. The
+ * cases below are the formatting those copies encoded; they are pinned here
+ * so the single definition cannot quietly change what a user reads.
+ */
+describe('formErrorMessages', () => {
+  it('turns a snake_case field into a sentence-case label', () => {
+    expect(formErrorMessages({ first_name: 'is required' })).toEqual(['First name: is required'])
+  })
+
+  it('splits camelCase, but not to the same result', () => {
+    // Pinning a wart, not endorsing it. The split inserts a space without
+    // lowering the second word, so `firstName` and `first_name` do not read
+    // alike. Changing that is a product call; this test exists so the change
+    // is deliberate when it happens.
+    expect(formErrorMessages({ firstName: 'is required' })).toEqual(['First Name: is required'])
+  })
+
+  it('splits every word, not just the first', () => {
+    expect(formErrorMessages({ shipping_zone_name: 'is taken' })).toEqual(['Shipping zone name: is taken'])
+    expect(formErrorMessages({ taxRateCode: 'is invalid' })).toEqual(['Tax Rate Code: is invalid'])
+  })
+
+  it('keeps one line per field, in the order given', () => {
+    expect(formErrorMessages({ name: 'is required', code: 'is taken' })).toEqual([
+      'Name: is required',
+      'Code: is taken',
+    ])
+  })
+
+  it('has nothing to say about an empty map', () => {
+    expect(formErrorMessages({})).toEqual([])
+  })
+
+  it('leaves an already-capitalised single word alone', () => {
+    expect(formErrorMessages({ Name: 'is required' })).toEqual(['Name: is required'])
+  })
+})

package/functions/dashboard-form.ts

@@ -0,0 +1,30 @@
+/**
+ * Form helpers shared by the dashboard's editor dialogs.
+ *
+ * `formErrorMessages` was copied verbatim into fourteen Commerce dialogs
+ * (stacksjs/stacks#2918). It is a pure function of a validation-error map with
+ * no reactive dependency and no markup, so a component was the wrong home for
+ * it: the label formatting it encodes had fourteen definitions, and a change
+ * to how a field name becomes a label had to be made in all of them or drift.
+ */
+
+/**
+ * Turn a map of field errors into lines a person can read.
+ *
+ * Behaviour is the fourteen copies' behaviour, unchanged, including one wart
+ * worth naming rather than silently fixing: the two spellings do not read
+ * alike. `first_name` becomes "First name", while `firstName` becomes
+ * "First Name", because the split inserts a space without lowering the second
+ * word. A server reporting snake_case and a client reporting camelCase
+ * therefore render differently for the same field.
+ *
+ * Left as-is here because extracting and changing at once makes a regression
+ * impossible to attribute. Fixing it is a one-line change in one place now,
+ * which is the point of the extraction.
+ */
+export function formErrorMessages(errors: Record<string, string>): string[] {
+  return Object.entries(errors).map(([field, message]) => {
+    const label = field.replace(/([a-z])([A-Z])/g, '$1 $2').replaceAll('_', ' ')
+    return `${label.charAt(0).toUpperCase()}${label.slice(1)}: ${message}`
+  })
+}

package/functions/dashboard-list.test.ts

@@ -0,0 +1,228 @@
+import { describe, expect, it } from 'bun:test'
+import { pageControls, useRecordsDashboard } from './dashboard-list'
+
+/** The smallest thing with the two members `pageControls` reads. */
+function pageSignal(initial: number) {
+  let value = initial
+  const signal = (() => value) as { (): number, set: (next: number) => void }
+  signal.set = (next: number) => { value = next }
+  return signal
+}
+
+describe('pageControls', () => {
+  it('moves a page back and forward', () => {
+    const page = pageSignal(2)
+    const { previousPage, nextPage } = pageControls(page, () => 5)
+    previousPage()
+    expect(page()).toBe(1)
+    nextPage()
+    nextPage()
+    expect(page()).toBe(3)
+  })
+
+  it('will not go below the first page', () => {
+    const page = pageSignal(1)
+    const { previousPage } = pageControls(page, () => 5)
+    previousPage()
+    previousPage()
+    expect(page()).toBe(1)
+  })
+
+  it('will not go past the last page', () => {
+    const page = pageSignal(5)
+    const { nextPage } = pageControls(page, () => 5)
+    nextPage()
+    expect(page()).toBe(5)
+  })
+
+  it('reads the last page at click time, not when it was wired up', () => {
+    // A filter that shrinks the result set has to shrink the range too.
+    const page = pageSignal(1)
+    let last = 9
+    const { nextPage } = pageControls(page, () => last)
+    last = 2
+    nextPage()
+    nextPage()
+    nextPage()
+    expect(page()).toBe(2)
+  })
+
+  it('clamps an out-of-range page back into the range', () => {
+    // The guard style the Marketing dashboards used could not do this: a page
+    // already past the end stayed there.
+    const page = pageSignal(40)
+    const { nextPage, previousPage } = pageControls(page, () => 3)
+    nextPage()
+    expect(page()).toBe(3)
+    page.set(40)
+    previousPage()
+    expect(page()).toBe(39)
+  })
+
+  it('survives an empty result set, where the last page is zero', () => {
+    const page = pageSignal(1)
+    const { nextPage } = pageControls(page, () => 0)
+    nextPage()
+    expect(page()).toBe(1)
+  })
+})
+
+interface Row { id: number, name: string }
+
+const byName = (rows: Row[], query: string) => rows.filter(r => r.name.toLowerCase().includes(query))
+
+function seeded(count: number, perPage = 10) {
+  const d = useRecordsDashboard<Row>({ filter: byName, perPage })
+  d.records.set(Array.from({ length: count }, (_, i) => ({ id: i + 1, name: `row ${i + 1}` })))
+  return d
+}
+
+describe('useRecordsDashboard', () => {
+  it('starts loading, empty, on the first page', () => {
+    const d = useRecordsDashboard<Row>({ filter: byName })
+    expect(d.loading()).toBe(true)
+    expect(d.records()).toEqual([])
+    expect(d.page()).toBe(1)
+    expect(d.pageCount()).toBe(1)
+    expect(d.paginatedRecords()).toEqual([])
+  })
+
+  it('pages through the records', () => {
+    const d = seeded(25)
+    expect(d.pageCount()).toBe(3)
+    expect(d.paginatedRecords().map(r => r.id)).toEqual([1, 2, 3, 4, 5, 6, 7, 8, 9, 10])
+    d.nextPage()
+    expect(d.paginatedRecords()[0]!.id).toBe(11)
+    d.page.set(3)
+    expect(d.paginatedRecords()).toHaveLength(5)
+  })
+
+  it('searching returns to the first page, because page 3 of a new result set is meaningless', () => {
+    const d = seeded(25)
+    d.page.set(3)
+    d.handleSearch('row 1')
+    expect(d.page()).toBe(1)
+    // row 1, 10-19
+    expect(d.filteredRecords()).toHaveLength(11)
+  })
+
+  it('an edit replaces in place and does not move the page', () => {
+    const d = seeded(25)
+    d.page.set(2)
+    const target = d.records()[4]!
+    d.upsert({ id: target.id, name: 'renamed' }, target)
+    expect(d.records()[4]!.name).toBe('renamed')
+    expect(d.records()).toHaveLength(25)
+    expect(d.page()).toBe(2)
+  })
+
+  it('a create appends and lands on the page the new row is on', () => {
+    const d = seeded(20)
+    expect(d.pageCount()).toBe(2)
+    d.upsert({ id: 99, name: 'new' }, null)
+    expect(d.records()).toHaveLength(21)
+    expect(d.page()).toBe(3)
+    expect(d.paginatedRecords()).toEqual([{ id: 99, name: 'new' }])
+  })
+
+  it('removing the last row on the last page pulls the page back', () => {
+    const d = seeded(11)
+    d.page.set(2)
+    expect(d.paginatedRecords()).toHaveLength(1)
+    d.remove(d.records()[10]!)
+    expect(d.page()).toBe(1)
+    expect(d.records()).toHaveLength(10)
+  })
+
+  it('removing elsewhere leaves the page alone', () => {
+    const d = seeded(25)
+    d.page.set(2)
+    d.remove(d.records()[0]!)
+    expect(d.page()).toBe(2)
+    expect(d.records()).toHaveLength(24)
+  })
+
+  it('clampPage pulls a page back into range after a filter shrinks the list', () => {
+    const d = seeded(25)
+    d.page.set(3)
+    d.search.set('row 7')
+    d.clampPage()
+    expect(d.page()).toBe(1)
+  })
+
+  it('the editor opens for a create and for an edit, and remembers which', () => {
+    const d = seeded(3)
+    d.openCreate()
+    expect(d.editorOpen()).toBe(true)
+    expect(d.editorMode()).toBe('create')
+    expect(d.editing()).toBeNull()
+
+    const row = d.records()[1]!
+    d.openEdit(row)
+    expect(d.editorMode()).toBe('edit')
+    expect(d.editing()).toBe(row)
+  })
+
+  it('will not close the editor mid-save', () => {
+    // Otherwise a slow PATCH can land on a dialog the user already dismissed.
+    const d = seeded(3)
+    d.openEdit(d.records()[0]!)
+    d.editorError.set('something went wrong')
+    d.saving.set(true)
+    d.closeEditor()
+    expect(d.editorOpen()).toBe(true)
+    expect(d.editorError()).toBe('something went wrong')
+
+    d.saving.set(false)
+    d.closeEditor()
+    expect(d.editorOpen()).toBe(false)
+    expect(d.editing()).toBeNull()
+    expect(d.editorError()).toBe('')
+  })
+
+  it('will not close the delete confirmation mid-delete', () => {
+    const d = seeded(3)
+    d.requestDelete(d.records()[0]!)
+    d.deleteBusy.set(true)
+    d.closeDelete()
+    expect(d.deleting()).not.toBeNull()
+
+    d.deleteBusy.set(false)
+    d.closeDelete()
+    expect(d.deleting()).toBeNull()
+  })
+
+  it('honours a custom identity instead of id', () => {
+    const d = useRecordsDashboard<{ sku: string }>({
+      filter: rows => rows,
+      sameRecord: (a, b) => a.sku === b.sku,
+    })
+    d.records.set([{ sku: 'a' }, { sku: 'b' }])
+    d.remove({ sku: 'a' })
+    expect(d.records()).toEqual([{ sku: 'b' }])
+  })
+})
+
+describe('useRecordsDashboard goToPage', () => {
+  it('jumps to a page', () => {
+    const d = seeded(25)
+    d.goToPage(3)
+    expect(d.page()).toBe(3)
+  })
+
+  it('clamps a page that does not exist', () => {
+    const d = seeded(25)
+    d.goToPage(99)
+    expect(d.page()).toBe(3)
+    d.goToPage(0)
+    expect(d.page()).toBe(1)
+    d.goToPage(-4)
+    expect(d.page()).toBe(1)
+  })
+
+  it('survives a non-number from a component that emitted one', () => {
+    const d = seeded(25)
+    d.goToPage(Number.NaN)
+    expect(d.page()).toBe(1)
+  })
+})