@ultimat3/testing 6.0.0 → 8.0.0

package/CLAUDE.md

@@ -23,6 +23,7 @@ is its own entry point and not part of the barrel.
 | No retries | a flake is fixed or deleted the day it flakes; there is no `retry: 3` |
 | `toBeUltimateError` reads THREE fields | an `X_` code plus a `cause` plus a `fix`, all through core's `stringField`. `typeof value.code === 'string'` alone passed a Node `ENOENT` — so a suite pinning "never throw a bare `Error`" stayed green through exactly the regression it guards (`matchers.test.ts`). Same discriminator `packages/cli/src/output.ts` uses to decide what the terminal shows, and a hostile getter answers `undefined` instead of raising inside the assertion |
 | Test names | the filename picks the step; `testName(type, name)` on the outer `describe` puts that type on every failure line under it. Never on the inner `test` too — the prefix would print twice |
+| `test` here is `fixtureTest`, and it takes no timeout | `(name, body)`, nothing else (`fixtures.ts:248`, exported as `test` by `index.ts:107`) — `bunTest` is called with two arguments, so bun's own third one is unreachable and no case can ask for more than the default 5s. Slow work goes in `beforeAll(fn, 60_000)`, which is `bun:test`'s own re-export and does take one; that is where both generated island tests and `examples/dummy/apps/web/app/settings/settings.island.test.ts` build their chunk, once, for every case to share — a Babel pass plus a browser bundle is seconds. A case that needs 60s of its own is work sitting in the wrong place |
 | Injection | `SqlRunner` and `connect` are parameters, so unit tests need no server |
 | Fixtures | the preload registers the whole framework bag — an app registers only what the framework cannot know (`seed`, `actorFor`) |
 | e2e without a driver | `e2eTest` becomes `test.skip`, and the gate reports the step GREEN over it — `bun test` exits 0 on a skip and the exit code is the only channel between the step and the child that registers the driver. `hasE2eDriver()` is what a harness asks instead of reading an all-skipped run as a pass. Zero drivers are registered `As of 2026-08` |
@@ -55,9 +56,27 @@ is its own entry point and not part of the barrel.
 | One write seam | `usePersister` is the only place `create()` writes. A factory that took a repo argument would put the seam at every call site |
 | Factory seeds | derived from the table name unless given, so two entities never draw the same uuid stream. `reset()` cascades into associated parents — a half-reset row is worse than none |
 | Shared examples | `behavesLike` calls `describe`, so it goes at declaration scope; bun rejects a `describe` inside a test body |
+| An island needs a BUILDER, not an import | `buildIslands` is `@ultimat3/cli`'s and both packages are tier 5; the one declared edge is `cli → testing`, so the reverse is a `bun run boundaries` failure. `mountIsland({ build, root, file })` takes the function as a parameter and declares only the two fields it reads — `IslandChunkLike` is `{ file, code }`, so a CSS artifact, a source map or a dev/production flag the bundler grows is invisible here. Moving the bundler down a tier was the alternative and it drags `@babel/core` and `babel-preset-solid` with it, into a package whose whole point is being importable from tier 0 |
+| The micro-DOM is the fixture's, once | `island-dom.ts`. `bun test` has no DOM and no DOM library may be added; `generate: 'dom'` builds every element from `_$template("<label …>")`, so a stub without a parsed `<template>` cannot run one line of a compiled island. It lived twice, ~200 lines each, in `packages/cli/src/island-bundle.test.ts` and the reference app's island test |
+| `style` and `classList` RECORD, `As of 2026-08` | `FakeStyle` is one declaration map behind all four spellings compiled Solid uses on one element: a STATIC entry baked into the template's `style=` attribute, a dynamic one through `setStyleProperty` → `style.setProperty`, a whole-object or string prop through `style()` → `cssText`, and a cleared one through `removeAttribute`. It was `style = {}` until 2026-08-21 — `<Form>`, `<Stack>`, `<Grid>` and `<Container>` each set a CSS custom property, so every one of them died inside `mount` with `e.style.setProperty is not a function`, and `x g resource` emitted a plain `<form>` rather than the design system's. A design-system component kept out of generated code by the limits of a TEST DOUBLE. A no-op `setProperty` would have stopped the crash and left "the component set `--form-gap`" unassertable, which is the same hole one layer down |
+| `classList` is the class attribute | not a list of its own, so `classList.toggle` — what the compiler emits INLINE for `classList={{ … }}`, with no runtime helper in front of it — and `className` can never answer one element two ways. `add` was the only method the stand-in had and is the one Solid never calls |
+| A `document` listener is the documentElement's | this DOM has no bubbling at all, so `document.addEventListener` registers on `documentElement` and `fire(mounted.documentElement, 'keydown', …)` drives it through the surface `MountedIsland` already exposes. `@ultimat3/ui`'s Menu, Popover and focus trap each close on an Escape registered on `document` and never on their own node — a no-op here made all three mountable and unclosable. One handler per type, last wins: two components listening for the same event is this design's limit, and `listeners`' value type is public surface a fix would break |
+| `querySelector` skips `this` | descendants only, as the DOM's does. Matching the element it is called on made a host `<div>` answer `find('div')` with the container the test built rather than the markup the island rendered |
+| A mount installs process globals | so `MountedIsland` is `Disposable` and a `mount` that THROWS restores before it rethrows. A fake `document` left installed reaches every later FILE in the run, and fails somewhere with no thread back |
+| `fire` answers whether a handler ran | a selector matching nothing and an island that attached no handler are the same silence otherwise — the second is a bug, the first a typo. It reads Solid's delegated `$$click` property or an `addEventListener` listener; a compiled island uses one or the other |
+| The chunk is imported from a temp FILE, `As of 2026-08-21` | `mkdtemp`ed on the FIRST mount and named by the chunk's SHA-256, so an edited island is a different module rather than a cache hit on the same path and no test leaves a `.mjs` behind in the app it just built. It was a `data:` URL until 2026-08-21 and that read better: `bun test --coverage` panics with `range end index N out of range for slice of length 4096` on `import()` of any `data:` module past ~4 kB, and an island chunk is 12-55 kB — so every island test dumped core in the per-package CI job while the root gate stayed green. Measured on Bun 1.4.0; `fixture-island.test.ts` pins the file form as a source rule, because the failure is invisible to a `bun test` without `--coverage` |
+| The scratch directory is lazy and removed, `As of 2026-08-22` | `mkdtempSync` ran at MODULE scope and nothing removed it, so every process importing `@ultimat3/testing` at all — this module is on the `.` barrel, so `expect` alone did it — left one directory in `/tmp` forever. Created on the first `modulePathFor` and `rmSync`ed from `process.on('exit')`: the handler has to be synchronous, and it is per PROCESS while `MountedIsland`'s `Disposable` is per mount and is never reached by a mount that threw. `fixture-island-cleanup.test.ts` asserts both halves from a CHILD process, which is the only place either is observable |
+| Attaching a node MOVES it | `appendChild`, `insertBefore` and `replaceChild` detach the node from its old parent first, and `removeChild` clears `parentNode` — as the DOM does, and as `reconcileArrays` requires: a `<For>` re-order calls `parentNode.insertBefore(child, ref)` on a child ALREADY in that parent (`solid-js/web`'s `web.js:155`), so an attach that only pushed left the node in BOTH positions and a five-row list reconciled to ten. A removal that left `parentNode` set was the same defect read backwards — `indexOf` answers -1, so the orphan's `nextSibling` was its old parent's FIRST child instead of `null`. `textContent = ''` detaches too; it opens every island's `mount` |
+| Globals install all-or-nothing | `installGlobals` saves DESCRIPTORS, not values — a saved value cannot tell "no such global" from "a global holding `undefined`", and the teardown deleted both — and rolls the whole install back if one assignment throws. That rollback is the half with teeth: the install runs BEFORE `mountIsland`'s own `try`, so a getter-only own global among the caller's `globals` used to leave the fake `document` installed for the rest of the process |
 | Which command shards | `bun test` is one process on one database, and that is still what a scaffolded app's `test` script runs. `x verify` DOES shard its parallel test steps, over `ULTIMATE_TEST_WORKER` and one database per worker; `live` and `e2e` stay serial because a replication slot is cluster-scoped and `e2e` has one built `dist/`. Say which command a claim is about |
 
 Commands: `bun test`, `bunx tsc --noEmit -p tsconfig.json`.
 
 Entry points: `.` (the API), `./preload` (side effects for bunfig) and `./registry-isolation`
 (`isolateEntityRegistry()`, kept off `.` because it loads `@ultimat3/entity`).
+
+`fixture-island.ts` and `island-dom.ts` are on `.` and import `@ultimat3/core` and nothing else, so
+they cost a tier-0 test nothing. The whole-chain proof — real Babel, real Solid, a real island —
+is `examples/dummy/apps/web/app/settings/settings.island.test.ts`; `fixture-island.test.ts` pins
+this package's own contract against modules written in the idiom `babel-preset-solid` emits, with
+no bundler, because a test here cannot import one.

package/README.md

@@ -20,6 +20,8 @@ frozen clock. Never let a test reach the network unmocked — it fails by design
 | `fixtures.ts` | the registry + `test('…', ({ clock }) => …)` injection |
 | `fixture-{clock,mail,jobs,network,statements}.ts` | the five fixtures the framework builds in-process |
 | `fixture-drivers.ts` | the five it declares but a driver must build — `page` `budget` `signIn` `deploy` `subscribe` |
+| `fixture-island.ts` | `mountIsland()` — build an island, import its chunk, run its `mount`. The BUILDER is a parameter |
+| `island-dom.ts` | the micro-DOM `mountIsland` drives: what compiled Solid touches, and nothing else |
 | `framework-fixtures.ts` | registers both sets; the app registers only what it owns |
 | `registry-leak-guard.ts` | fails the run naming the FILE that left a process-global registry dirty, and restores the ones that can be restored at the same boundary |
 | `registry-snapshot.ts` | `captureProcessRegistries()` / `restoreProcessRegistries()` — the locale config, the catalogs, the permission set and the role map, put back as a file inherited them. A module-scope declaration evaluates once per process (`bun test` without `--isolate`, `As of 2026-08`), so a neighbour's `clearPermissions()` is otherwise permanent |
@@ -235,10 +237,52 @@ core's `markListening()`, so a test may call its own `handle.url()` on a kernel-
 the seal fully on. Unsealing (`ULTIMATE_TEST_ALLOW_NET=1`) stays reserved for a deliberate live
 integration — never for a socket test.
 
+## Testing an island
+
+An island is the only client-side code Ultimate ships, so it is the only code an app cannot test
+by calling a function. `mountIsland` builds one with the same bundler `x build` uses, imports the
+emitted chunk the way the hydration runtime does, and runs its `mount` over a DOM small enough to
+read.
+
+```ts
+import { buildIslands } from '@ultimat3/cli';
+import { expect, mountIsland, test } from '@ultimat3/testing';
+
+declare const fakeFetch: typeof fetch; // yours — the island's own network, stubbed
+
+test('the counter is reactive', async () => {
+  using island = await mountIsland({
+    build: buildIslands,
+    root: import.meta.dir + '/../../..',
+    file: 'apps/web/site/counter.island.tsx',
+    props: { label: 'count' },
+    shell: '<p>0</p>',                 // what the server rendered; mount must replace it
+    globals: { fetch: fakeFetch },     // anything the micro-DOM does not supply
+  });
+
+  expect(island.text('[data-role="count"]')).toBe('count 0');
+  expect(island.fire('button', 'click')).toBe(true);
+  expect(island.text('[data-role="count"]')).toBe('count 1');
+});
+```
+
+**`build` is a parameter, not an import.** `buildIslands` lives in `@ultimat3/cli`, which is tier 5
+like this package, and the one declared edge between them runs `cli → testing` — so importing it
+here would be a tier violation `bun run boundaries` fails on. The app supplies it, which is one
+line and makes the direction visible instead of hidden.
+
+**`fire` answers whether a handler RAN.** A selector that matches nothing and an island that
+attached no handler are the same silence; the second is a bug and the first is a typo in the test.
+
+**A mount installs process-global state**, so `MountedIsland` is `Disposable` — `using`, or
+`island[Symbol.dispose]()` in an `afterAll`. Left installed it hands a fake `document` to every
+later FILE in the run.
+
 ## Errors
 
 `X_TEST_NETWORK_SEALED` `X_TEST_DB_UNAVAILABLE` `X_TEST_NONDETERMINISTIC` `X_TEST_FIXTURE_UNKNOWN`
 `X_TEST_FACTORY_TRAIT_UNKNOWN` `X_TEST_FACTORY_NOT_PERSISTED` `X_TEST_REGISTRY_LEAK`
+`X_TEST_ISLAND_NOT_BUILT` `X_TEST_ISLAND_NO_MOUNT`
 
 ## One process, one registry
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/testing",
-  "version": "6.0.0",
+  "version": "8.0.0",
   "description": "Test harness: cloned template DBs per worker, frozen clock, sealed network, 6 test types",
   "license": "MIT",
   "type": "module",
@@ -33,16 +33,16 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/cache": "6.0.0",
-    "@ultimat3/core": "6.0.0",
-    "@ultimat3/db": "6.0.0",
-    "@ultimat3/entity": "6.0.0",
-    "@ultimat3/i18n": "6.0.0",
-    "@ultimat3/jobs": "6.0.0",
-    "@ultimat3/mail": "6.0.0",
-    "@ultimat3/policy": "6.0.0",
-    "@ultimat3/query": "6.0.0",
-    "@ultimat3/realtime": "6.0.0",
-    "@ultimat3/time": "6.0.0"
+    "@ultimat3/cache": "8.0.0",
+    "@ultimat3/core": "8.0.0",
+    "@ultimat3/db": "8.0.0",
+    "@ultimat3/entity": "8.0.0",
+    "@ultimat3/i18n": "8.0.0",
+    "@ultimat3/jobs": "8.0.0",
+    "@ultimat3/mail": "8.0.0",
+    "@ultimat3/policy": "8.0.0",
+    "@ultimat3/query": "8.0.0",
+    "@ultimat3/realtime": "8.0.0",
+    "@ultimat3/time": "8.0.0"
   }
 }

package/src/errors.ts

@@ -27,6 +27,8 @@ export const TESTING_ERROR_CODES = [
   'X_TEST_REGISTRY_LEAK',
   'X_TEST_LIVE_NODE_EMPTY',
   'X_TEST_LIVE_NODE_UPGRADE_REFUSED',
+  'X_TEST_ISLAND_NOT_BUILT',
+  'X_TEST_ISLAND_NO_MOUNT',
 ] as const;
 
 export type TestingErrorCode = (typeof TESTING_ERROR_CODES)[number];
@@ -47,6 +49,8 @@ export const TESTING_ERROR_TITLES: Readonly<Record<TestingErrorCode, string>> =
   X_TEST_REGISTRY_LEAK: 'a test file left a process-global registry dirty',
   X_TEST_LIVE_NODE_EMPTY: 'the in-process sync node has no live query to serve',
   X_TEST_LIVE_NODE_UPGRADE_REFUSED: 'the in-process sync node refused the connection',
+  X_TEST_ISLAND_NOT_BUILT: 'the island build produced no chunk for the file the test named',
+  X_TEST_ISLAND_NO_MOUNT: 'an island chunk exports no mount function',
 };
 
 // Titles must be registered for `format()` to render the contract's first line. Every code above is
@@ -357,3 +361,83 @@ export class RegistryLeakError extends UltimateError {
     });
   }
 }
+
+/** Neither path is controlled by the framework: both arrive from the test's own call. */
+const ISLAND_PLACEHOLDER = '<the island path the cause names>';
+
+/**
+ * The builder produced no chunk for the file the test named. Listing what it DID build is the
+ * whole value: a path relative to the test file instead of to the app root, a typo, and an island
+ * outside the discovery glob are one symptom and three different edits, and only the list tells
+ * them apart. An empty list is its own answer — the glob found nothing at all under this root.
+ */
+export class IslandNotBuiltError extends UltimateError {
+  constructor(input: { file: string; root: string; built: readonly string[] }) {
+    const file = renderFixLiteral(input.file, ISLAND_PLACEHOLDER);
+    super({
+      code: 'X_TEST_ISLAND_NOT_BUILT',
+      cause:
+        input.built.length === 0
+          ? `no island was built under ${renderCauseValue(input.root)}, so ${renderCauseValue(input.file)} cannot be mounted`
+          : `${renderCauseValue(input.file)} is not in the bundle built from ${renderCauseValue(input.root)}; it built ${input.built.join(', ')}`,
+      fix:
+        input.built.length === 0
+          ? 'x g island <name> --at apps/web/site — then set root to the directory holding apps/'
+          : `mountIsland({ build, root, file: ${renderFixLiteral(input.built[0], ISLAND_PLACEHOLDER)} }) — the path is app-root-relative, not relative to the test, and ${file} is not one of them`,
+      docs: docsFor('X_TEST_ISLAND_NOT_BUILT'),
+    });
+  }
+}
+
+export const islandNotBuilt = (
+  file: string,
+  root: string,
+  built: readonly string[],
+): UltimateError => new IslandNotBuiltError({ file, root, built });
+
+/** A name that can be written as a JSX tag. `export default` and `export { x as 'a b' }` are both
+ *  legal ES and neither can — a paste emitting one is a syntax error in the reader's own file. */
+const JSX_NAME = /^[A-Za-z_$][\w$]*$/;
+
+/**
+ * The export the paste renders. A component first — an initial capital that is not the whole name,
+ * which is what separates `Counter` from a `PROPS` constant — and any other usable identifier
+ * after it, because a lowercase component still compiles and beats a name the reader must invent.
+ */
+const componentOf = (exported: readonly string[]): string | undefined => {
+  const usable = exported.filter((name) => JSX_NAME.test(name) && name !== 'default');
+  return usable.find((name) => /^[A-Z]/.test(name) && name !== name.toUpperCase()) ?? usable[0];
+};
+
+/**
+ * The chunk built and imported, and exports no `mount`. Distinct from a build failure: the island
+ * compiles, ships and is served — the hydration runtime calls `m.mount(el, props)` and the browser
+ * throws on a page that passed every gate. Naming the exports it DOES have is what separates a
+ * renamed export from a file that exports only its component.
+ *
+ * The paste is built from THOSE exports rather than from a sketch. It read
+ * `render(() => <Island {...props} />, el)` with `props: Props` until 2026-08-21, and none of
+ * `Island`, `Props` or `render` exists in the file the reader was told to paste it into — three
+ * compile errors handed out as the remedy for one. Two of them the error already knew the answer
+ * to, from its own cause; the third is an import, so the import is in the line.
+ */
+export class IslandMountMissingError extends UltimateError {
+  constructor(input: { file: string; exported: readonly string[] }) {
+    const file = renderFixLiteral(input.file, ISLAND_PLACEHOLDER);
+    const component = componentOf(input.exported);
+    super({
+      code: 'X_TEST_ISLAND_NO_MOUNT',
+      cause: `the chunk built from ${renderCauseValue(input.file)} exports ${
+        input.exported.length === 0 ? 'nothing' : input.exported.join(', ')
+      } — the hydration runtime calls m.mount(el, props)`,
+      fix:
+        component === undefined
+          ? `${file} exports nothing a mount could render — x g island <name> --at apps/web/site writes an island whose mount() is already there, and its shape is the one to copy`
+          : `in ${file} add: import { render } from 'solid-js/web'; export function mount(el: HTMLElement, props: Parameters<typeof ${component}>[0]): void { el.textContent = ''; render(() => <${component} {...props} />, el); }`,
+      docs: docsFor('X_TEST_ISLAND_NO_MOUNT'),
+    });
+  }
+}
+
+export const islandMountMissing = (file: string, exported: readonly string[]): UltimateError =>
+  new IslandMountMissingError({ file, exported });

package/src/fixture-island.ts

@@ -0,0 +1,206 @@
+// Build one island, import the chunk the way the hydration runtime does, and run its `mount` over
+// the micro-DOM. The BUILDER arrives as a parameter — `@ultimat3/cli` owns `buildIslands` and both
+// packages are tier 5, so importing it here would be the reverse of the one declared `cli → testing`
+// edge. A structural seam keeps the direction honest and survives the bundler changing underneath.
+
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { islandMountMissing, islandNotBuilt } from './errors';
+import { createIslandDocument, FakeElement, handlerFor, parseHtml } from './island-dom';
+
+/** The two fields a mounted island needs from a chunk. Anything else a bundler grows — a CSS
+ *  artifact, a source map, a dev/production flag — is invisible here on purpose. */
+export interface IslandChunkLike {
+  /** App-root-relative POSIX path of the client entry the chunk was built from. */
+  readonly file: string;
+  /** The built JavaScript, self-contained: an island chunk imports nothing at runtime. */
+  readonly code: string;
+}
+
+export interface IslandBundleLike {
+  readonly chunks: readonly IslandChunkLike[];
+}
+
+/** `buildIslands` from `@ultimat3/cli` satisfies this structurally — no import, no new tier edge. */
+export type IslandBuilder = (root: string) => Promise<IslandBundleLike>;
+
+export interface MountIslandOptions {
+  readonly build: IslandBuilder;
+  /** The app root the builder globs from. */
+  readonly root: string;
+  /** Which island, app-root-relative. Always named: an app with two islands has no default. */
+  readonly file: string;
+  /** The JSON the document would carry in `data-x-props`. */
+  readonly props?: unknown;
+  /** The markup the server rendered inside the island's wrapper, which `mount` must replace. */
+  readonly shell?: string;
+  /** Anything the micro-DOM does not supply — `fetch` above all. Merged over the DOM globals. */
+  readonly globals?: Readonly<Record<string, unknown>>;
+}
+
+export interface MountedIsland extends Disposable {
+  /** The chunk's source, for asserting on what did or did not reach the browser. */
+  readonly code: string;
+  /** The host element `mount` was given. */
+  readonly el: FakeElement;
+  /** The `<html>` this mount wrote to — `documentElement.dataset` is a real island's only door out. */
+  readonly documentElement: FakeElement;
+  find(selector: string): FakeElement | null;
+  all(selector: string): readonly FakeElement[];
+  /** `textContent` of the first match, `''` when there is none — an assertion reads a string. */
+  text(selector: string): string;
+  /**
+   * Drive a handler the compiled island attached, delegated (`$$change`) or not. Answers whether
+   * one RAN: a selector that matches nothing and an island that attached no handler are the same
+   * silence otherwise, and the second is a bug while the first is a typo in the test.
+   */
+  fire(
+    target: string | FakeElement | null | undefined,
+    type: string,
+    event?: Readonly<Record<string, unknown>>,
+  ): boolean;
+}
+
+interface IslandEntry {
+  readonly mount: (el: unknown, props: unknown) => void;
+}
+
+/** `unknown` + a check, not a cast: a chunk whose `mount` was renamed is a real authoring mistake
+ *  and `entry.mount is not a function` names neither the file nor the export it wanted. */
+function entryOf(module: unknown, file: string): IslandEntry {
+  const mount = (module as Record<string, unknown> | null)?.['mount'];
+  if (typeof mount !== 'function') {
+    throw islandMountMissing(file, Object.keys((module as object | null) ?? {}));
+  }
+  return { mount: mount as IslandEntry['mount'] };
+}
+
+let moduleDir: string | undefined;
+
+/**
+ * One directory per process, outside the app under test — so no test leaves a `.mjs` behind. Two
+ * properties the module-scope `mkdtempSync` it replaces had neither of:
+ *
+ * LAZY. This module is on the `.` barrel, so importing `@ultimat3/testing` for `expect` alone
+ * created a directory — in every test process in the repo, whether or not it ever mounts anything.
+ *
+ * REMOVED. `exit` and `rmSync`, because an exit handler runs synchronously and nothing else covers
+ * every path: `mountIsland` restores and rethrows on a failed mount, so that run never reaches the
+ * `Disposable`, and the directory is per PROCESS while the disposable is per mount.
+ */
+function moduleDirPath(): string {
+  const existing = moduleDir;
+  if (existing !== undefined) return existing;
+  const created = mkdtempSync(join(tmpdir(), 'ultimate-island-'));
+  process.on('exit', () => {
+    rmSync(created, { recursive: true, force: true });
+  });
+  moduleDir = created;
+  return created;
+}
+
+/**
+ * The scratch root, or `undefined` when nothing has been mounted. Read by the leak test, which
+ * asserts both halves of the above from a CHILD process — the only place where "this process
+ * created no directory" and "the directory is gone afterwards" are both observable.
+ */
+export const islandModuleDir = (): string | undefined => moduleDir;
+
+/**
+ * A temp file named by the chunk's own hash, NOT a `data:` URL. The URL form read better and
+ * crashed the coverage reporter: `bun test --coverage` panics with `range end index N out of range
+ * for slice of length 4096` on `import()` of any `data:` module whose URL exceeds ~4 kB, and an
+ * island chunk is 12-55 kB. Measured on Bun 1.4.0, threshold at a URL length of 4032; without
+ * `--coverage` the same import is fine, which is why only the per-package CI job ever saw it.
+ *
+ * The property the URL form was chosen for survives: the name is derived from the bytes, so an
+ * edited island is a different module rather than a cache hit on the same path.
+ */
+const modulePathFor = (code: string): string =>
+  join(moduleDirPath(), `${Bun.SHA256.hash(code, 'hex').slice(0, 16)}.mjs`);
+
+/**
+ * DESCRIPTORS, not values, and all-or-nothing.
+ *
+ * A saved value cannot tell "no such global" from "a global holding `undefined`", so a teardown
+ * reading one deletes both — and `key in globalThis` flips behind whoever owned it. It also cannot
+ * put an accessor back as an accessor.
+ *
+ * The rollback is the half with teeth. This runs BEFORE `mountIsland`'s own `try`, so an
+ * assignment that throws — a getter-only own global among the caller's `globals` — would leave the
+ * fake `document` already installed ahead of it for the whole rest of the process, which is the
+ * exact leak the `catch` below exists to prevent.
+ */
+function installGlobals(values: Readonly<Record<string, unknown>>): () => void {
+  const host = globalThis as unknown as Record<string, unknown>;
+  const saved = Object.keys(values).map(
+    (key) => [key, Object.getOwnPropertyDescriptor(host, key)] as const,
+  );
+  const restore = (): void => {
+    for (const [key, descriptor] of saved) {
+      if (descriptor === undefined) delete host[key];
+      else Object.defineProperty(host, key, descriptor);
+    }
+  };
+  try {
+    // Assignment, not `defineProperty`: a global with a setter is meant to see the write, and
+    // `Object.assign` over the lot would report the same failure with nothing rolled back.
+    for (const [key, value] of Object.entries(values)) host[key] = value;
+  } catch (error) {
+    restore();
+    throw error;
+  }
+  return restore;
+}
+
+/**
+ * The island fixture. Everything it installs is process-global, so the result is `Disposable` and
+ * the idiom is `using mounted = await mountIsland(…)` — a mount left installed hands a fake
+ * `document` to every later FILE in the run.
+ */
+export async function mountIsland(options: MountIslandOptions): Promise<MountedIsland> {
+  const bundle = await options.build(options.root);
+  const chunk = bundle.chunks.find((each) => each.file === options.file);
+  if (chunk === undefined) {
+    throw islandNotBuilt(
+      options.file,
+      options.root,
+      bundle.chunks.map((each) => each.file),
+    );
+  }
+
+  const { documentElement, globals } = createIslandDocument();
+  const restore = installGlobals({ ...globals, ...options.globals });
+  try {
+    const path = modulePathFor(chunk.code);
+    await Bun.write(path, chunk.code);
+    const entry = entryOf(await import(path), chunk.file);
+    const el = new FakeElement('div');
+    if (options.shell !== undefined) {
+      for (const child of [...parseHtml(options.shell).children]) el.appendChild(child);
+    }
+    entry.mount(el, options.props);
+    return {
+      code: chunk.code,
+      el,
+      documentElement,
+      find: (selector) => el.querySelector(selector),
+      all: (selector) => el.querySelectorAll(selector),
+      text: (selector) => el.querySelector(selector)?.textContent ?? '',
+      fire: (target, type, event) => {
+        const node = typeof target === 'string' ? el.querySelector(target) : target;
+        const handler = node == null ? undefined : handlerFor(node, type);
+        if (handler === undefined) return false;
+        handler({ currentTarget: node, target: node, ...event });
+        return true;
+      },
+      [Symbol.dispose]: restore,
+    };
+  } catch (error) {
+    // A mount that throws restores the process before it rethrows: the alternative leaves every
+    // later file in the run holding a fake `document`, which fails somewhere with no thread back.
+    restore();
+    throw error;
+  }
+}

package/src/index.ts

@@ -83,6 +83,17 @@ export type {
   TestDeploy,
 } from './fixture-drivers';
 export { DRIVER_FIXTURE_NEEDS, driverFixtures, unavailableFixture } from './fixture-drivers';
+// The island fixture. `build` is a PARAMETER — `buildIslands` lives in `@ultimat3/cli`, which is
+// tier 5 like this package and whose one declared edge points the other way, so an app supplies it:
+// `mountIsland({ build: buildIslands, root, file })`.
+export type {
+  IslandBuilder,
+  IslandBundleLike,
+  IslandChunkLike,
+  MountedIsland,
+  MountIslandOptions,
+} from './fixture-island';
+export { mountIsland } from './fixture-island';
 export type { JobRunTrace, RunJobs, StepTally } from './fixture-jobs';
 export { createRunJobs } from './fixture-jobs';
 export type { MailRef, TestMail } from './fixture-mail';
@@ -102,6 +113,8 @@ export {
 } from './framework-fixtures';
 export type { AppHandle, AppOptions, BootedApp } from './harness';
 export { describeApp, testApp } from './harness';
+// Type-only: the micro-DOM is the fixture's to build, and a test only ever names what it handed back.
+export type { FakeElement, FakeNode, FakeText } from './island-dom';
 export type { LiveConnection, LiveNodeHandle, LiveNodeOptions } from './live-node';
 export { createLiveNode } from './live-node';
 export type { LiveReplicator, LiveReplicatorOptions } from './live-replicator';

package/src/island-dom.ts

@@ -0,0 +1,383 @@
+// A DOM small enough to read, implementing exactly what compiled Solid touches and nothing else.
+// `bun test` ships no DOM and no DOM library may be added, so an island — the only client-side
+// code Ultimate ships — was untestable without one. `generate: 'dom'` builds every element from
+// `_$template("<button …>")`, so a stub without a parsed `<template>` cannot run one line of it.
+
+/** `[data-role="preview"]` — the one selector shape a mounted island is queried by. */
+const ATTRIBUTE_SELECTOR = /^\[([\w-]+)="([^"]*)"\]$/;
+
+/**
+ * A node belongs to ONE parent, and the DOM enforces that by moving it: every attach detaches the
+ * node from wherever it was first. Not a nicety — `reconcileArrays` re-orders a `<For>` by calling
+ * `parentNode.insertBefore(child, ref)` on a child already in that parent (`solid-js/web`'s
+ * `web.js:155`, `:163`, `:184`), so an attach that only pushes leaves the node in BOTH positions
+ * and a five-row list becomes ten in an order no assertion can read back.
+ */
+function detach(node: FakeNode): void {
+  const parent = node.parentNode;
+  if (parent === null) return;
+  const at = parent.children.indexOf(node);
+  if (at >= 0) parent.children.splice(at, 1);
+  node.parentNode = null;
+}
+
+export class FakeNode {
+  readonly nodeType: number = 1;
+  children: FakeNode[] = [];
+  parentNode: FakeNode | null = null;
+  appendChild(child: FakeNode): FakeNode {
+    detach(child);
+    child.parentNode = this;
+    this.children.push(child);
+    return child;
+  }
+  /** `ref === child` is the spec's own no-op, spelled the way the spec spells it — the reference
+   *  becomes the node's next sibling, so a node asked to precede itself lands back where it was. */
+  insertBefore(child: FakeNode, ref: FakeNode | null): FakeNode {
+    const target = ref === child ? child.nextSibling : ref;
+    detach(child);
+    const at = target === null ? -1 : this.children.indexOf(target);
+    child.parentNode = this;
+    this.children.splice(at < 0 ? this.children.length : at, 0, child);
+    return child;
+  }
+  /** The node that leaves keeps no parent: `reconcileArrays` calls `.remove()` on nodes it has
+   *  already replaced, and a stale `parentNode` would take a live row out of the list instead. */
+  replaceChild(next: FakeNode, prev: FakeNode): FakeNode {
+    // The guard comes BEFORE the detach: a call that replaces nothing must move nothing either,
+    // and detaching `next` first would take it out of the tree it was in and put it nowhere.
+    if (next === prev || this.children.indexOf(prev) < 0) return prev;
+    detach(next);
+    // Read the index again — detaching `next` out of THIS parent shifts everything after it.
+    this.children[this.children.indexOf(prev)] = next;
+    next.parentNode = this;
+    prev.parentNode = null;
+    return prev;
+  }
+  /** A node that is not a child is left whole — the DOM throws `NotFoundError`, and clearing the
+   *  parent of a node belonging to someone else would be the worse of the two answers. */
+  removeChild(child: FakeNode): FakeNode {
+    const at = this.children.indexOf(child);
+    if (at < 0) return child;
+    this.children.splice(at, 1);
+    child.parentNode = null;
+    return child;
+  }
+  remove(): void {
+    this.parentNode?.removeChild(this);
+  }
+  cloneNode(deep?: boolean): FakeNode {
+    const copy = new FakeNode();
+    if (deep === true) for (const child of this.children) copy.appendChild(child.cloneNode(true));
+    return copy;
+  }
+  get childNodes(): readonly FakeNode[] {
+    return this.children;
+  }
+  get firstChild(): FakeNode | null {
+    return this.children[0] ?? null;
+  }
+  get nextSibling(): FakeNode | null {
+    const siblings = this.parentNode?.children ?? [];
+    return siblings[siblings.indexOf(this) + 1] ?? null;
+  }
+  get textContent(): string {
+    return this.children.map((child) => child.textContent).join('');
+  }
+  /** The dropped children are DETACHED, not merely forgotten: `el.textContent = ''` opens every
+   *  island's `mount` and closes Solid's `render` disposer (`web.js:201`), and a shell node left
+   *  holding its old parent is a node two trees claim. */
+  set textContent(text: string) {
+    for (const child of this.children) child.parentNode = null;
+    this.children = [];
+    if (text !== '') this.appendChild(new FakeText(text));
+  }
+}
+
+/** `data`, not a private field: Solid updates a text node in place through `node.data = value`,
+ *  and a stub without it reports a mount that renders once and never re-renders. */
+export class FakeText extends FakeNode {
+  override readonly nodeType = 3;
+  constructor(public data: string) {
+    super();
+  }
+  override get textContent(): string {
+    return this.data;
+  }
+  override set textContent(text: string) {
+    this.data = text;
+  }
+  override cloneNode(): FakeText {
+    return new FakeText(this.data);
+  }
+}
+
+/**
+ * The three writes compiled Solid makes to `style`, over ONE declaration map: `setProperty` and
+ * `removeProperty` (`setStyleProperty`, `solid-js/web`'s `web.js:302`, which is what the compiler
+ * emits per dynamic entry of a `style={{ … }}` prop) and `cssText` (its `style()` runtime, for a
+ * whole-object or string prop). It RECORDS: `<Form>`, `<Stack>`, `<Grid>` and `<Container>` each
+ * set a custom property, so `style = {}` killed every one of them inside `mount`, and a no-op that
+ * only stopped the crash would leave "the component set `--form-gap`" untestable instead — the
+ * same shape of hole one layer down.
+ */
+export class FakeStyle {
+  /** Declaration order, as `CSSStyleDeclaration` enumerates. */
+  readonly properties = new Map<string, string>();
+
+  setProperty(name: string, value: string): void {
+    this.properties.set(name, String(value));
+  }
+
+  /** The old value, as the DOM's does — Solid ignores it, a test asserting a removal need not. */
+  removeProperty(name: string): string {
+    const previous = this.properties.get(name) ?? '';
+    this.properties.delete(name);
+    return previous;
+  }
+
+  getPropertyValue(name: string): string {
+    return this.properties.get(name) ?? '';
+  }
+
+  get cssText(): string {
+    return [...this.properties].map(([name, value]) => `${name}: ${value};`).join(' ');
+  }
+
+  /** A declaration with no `:` is dropped rather than stored, which is also how Solid's own reset
+   *  lands: `style()` assigns `undefined` here to clear, and the DOM parses that to nothing. */
+  set cssText(text: string) {
+    this.properties.clear();
+    for (const declaration of String(text).split(';')) {
+      const at = declaration.indexOf(':');
+      if (at > 0) {
+        this.properties.set(declaration.slice(0, at).trim(), declaration.slice(at + 1).trim());
+      }
+    }
+  }
+}
+
+/**
+ * Backed by the element's `class` ATTRIBUTE rather than a list of its own: `classList.toggle` is
+ * emitted inline by the compiler for `classList={{ … }}` while `class` goes through `className`,
+ * and two representations would let one element answer a test two ways. `toggle` is the call Solid
+ * makes and `add` was the one this stood in for — the double implemented the method nothing calls.
+ */
+export class FakeClassList {
+  constructor(private readonly element: FakeElement) {}
+
+  private get names(): string[] {
+    return this.element.className.split(/\s+/).filter((name) => name.length > 0);
+  }
+
+  private write(names: readonly string[]): void {
+    this.element.className = names.join(' ');
+  }
+
+  add(...names: readonly string[]): void {
+    this.write([...this.names, ...names.filter((name) => !this.contains(name))]);
+  }
+
+  remove(...names: readonly string[]): void {
+    this.write(this.names.filter((name) => !names.includes(name)));
+  }
+
+  contains(name: string): boolean {
+    return this.names.includes(name);
+  }
+
+  toggle(name: string, force?: boolean): boolean {
+    const next = force ?? !this.contains(name);
+    if (next) this.add(name);
+    else this.remove(name);
+    return next;
+  }
+}
+
+export class FakeElement extends FakeNode {
+  readonly attributes = new Map<string, string>();
+  readonly listeners = new Map<string, (event: unknown) => void>();
+  /** Plain object, so `delete el.dataset.theme` behaves as the DOM's `DOMStringMap` does. */
+  readonly dataset: Record<string, string> = {};
+  readonly classList: FakeClassList = new FakeClassList(this);
+  readonly style = new FakeStyle();
+  /** Properties, not attributes: Solid assigns both of these straight onto the node. */
+  value = '';
+  checked = false;
+  constructor(readonly tagName: string) {
+    super();
+  }
+  get nodeName(): string {
+    return this.tagName.toUpperCase();
+  }
+  /** `_$className` assigns the PROPERTY, never the attribute — class assertions read this. */
+  get className(): string {
+    return this.attributes.get('class') ?? '';
+  }
+  set className(value: string) {
+    this.attributes.set('class', String(value));
+  }
+  /**
+   * `style` is the declaration map wearing an attribute's name, in all four calls. Both spellings
+   * are Solid's own: the compiler bakes a STATIC style entry into the template's `style=` attribute
+   * — which `parseHtml` sets here — and clears a whole-object prop through `removeAttribute`
+   * (`setAttribute(node, 'style')` with no value, `web.js:237`), while every dynamic entry goes to
+   * `style.setProperty`. Two stores would let one element answer `getAttribute('style')` and
+   * `style.getPropertyValue` differently.
+   */
+  setAttribute(name: string, value: string): void {
+    if (name === 'style') this.style.cssText = String(value);
+    else this.attributes.set(name, String(value));
+  }
+  getAttribute(name: string): string | null {
+    if (name === 'style') return this.style.properties.size === 0 ? null : this.style.cssText;
+    return this.attributes.get(name) ?? null;
+  }
+  hasAttribute(name: string): boolean {
+    return name === 'style' ? this.style.properties.size > 0 : this.attributes.has(name);
+  }
+  removeAttribute(name: string): void {
+    if (name === 'style') this.style.properties.clear();
+    else this.attributes.delete(name);
+  }
+  addEventListener(name: string, fn: (event: unknown) => void): void {
+    this.listeners.set(name, fn);
+  }
+  removeEventListener(name: string): void {
+    this.listeners.delete(name);
+  }
+  override cloneNode(deep?: boolean): FakeElement {
+    const copy = new FakeElement(this.tagName);
+    for (const [name, value] of this.attributes) copy.attributes.set(name, value);
+    // The declarations too, or a template's static `style=` survives the parse and dies at the
+    // `importNode` every compiled island mounts through.
+    for (const [name, value] of this.style.properties) copy.style.properties.set(name, value);
+    if (deep === true) for (const child of this.children) copy.appendChild(child.cloneNode(true));
+    return copy;
+  }
+  /**
+   * A tag name or `[attr="value"]`, anywhere in the subtree — the two shapes an island test asks
+   * for. Anything richer would be a CSS engine, which is a DOM library by another name.
+   *
+   * DESCENDANTS only, never `this`: the DOM's own `querySelector` does not match the element it is
+   * called on, and a host `<div>` answering `find('div')` reports the container the test built
+   * instead of the markup the island rendered into it.
+   */
+  querySelectorAll(selector: string): readonly FakeElement[] {
+    const attribute = ATTRIBUTE_SELECTOR.exec(selector);
+    const found: FakeElement[] = [];
+    const walk = (node: FakeNode): void => {
+      for (const child of node.children) {
+        if (child instanceof FakeElement && matches(child, selector, attribute)) found.push(child);
+        walk(child);
+      }
+    };
+    walk(this);
+    return found;
+  }
+  querySelector(selector: string): FakeElement | null {
+    return this.querySelectorAll(selector)[0] ?? null;
+  }
+}
+
+const matches = (
+  node: FakeElement,
+  selector: string,
+  attribute: RegExpExecArray | null,
+): boolean =>
+  attribute === null
+    ? node.tagName === selector
+    : node.getAttribute(attribute[1] as string) === attribute[2];
+
+export class FakeTemplate extends FakeElement {
+  content: FakeNode = new FakeNode();
+  constructor() {
+    super('template');
+  }
+  set innerHTML(html: string) {
+    this.content = parseHtml(html);
+  }
+}
+
+const VOID_TAGS = new Set(['br', 'hr', 'img', 'input', 'meta', 'link']);
+const TOKEN =
+  /<(\/?)([a-zA-Z][\w-]*)((?:\s+[^\s=/>]+(?:=(?:"[^"]*"|'[^']*'|[^\s>]+))?)*)\s*(\/?)>|([^<]+)/g;
+const ATTRIBUTE = /([^\s=/>]+)(?:=(?:"([^"]*)"|'([^']*)'|([^\s>]+)))?/g;
+
+/** Only what `babel-preset-solid` emits into a template: tags, static attributes and text. */
+export function parseHtml(html: string): FakeNode {
+  const root = new FakeNode();
+  const open: FakeNode[] = [root];
+  for (const match of html.matchAll(TOKEN)) {
+    const parent = open[open.length - 1] as FakeNode;
+    if (match[5] !== undefined) {
+      parent.appendChild(new FakeText(match[5]));
+      continue;
+    }
+    if (match[1] === '/') {
+      if (open.length > 1) open.pop();
+      continue;
+    }
+    const element = new FakeElement(match[2] as string);
+    for (const attr of (match[3] ?? '').matchAll(ATTRIBUTE)) {
+      if (attr[1] !== undefined) element.setAttribute(attr[1], attr[2] ?? attr[3] ?? attr[4] ?? '');
+    }
+    parent.appendChild(element);
+    if (match[4] !== '/' && !VOID_TAGS.has(element.tagName)) open.push(element);
+  }
+  return root;
+}
+
+export interface IslandDocument {
+  readonly documentElement: FakeElement;
+  readonly globals: Readonly<Record<string, unknown>>;
+}
+
+/**
+ * A fresh `<html>` and the globals a compiled island reads, built per mount rather than once per
+ * module: `document.documentElement.dataset.theme` is state one island writes and the next would
+ * otherwise inherit.
+ */
+export function createIslandDocument(): IslandDocument {
+  const documentElement = new FakeElement('html');
+  const document = {
+    documentElement,
+    createElement: (tag: string): FakeElement =>
+      tag === 'template' ? new FakeTemplate() : new FakeElement(tag),
+    createElementNS: (_ns: string, tag: string): FakeElement => new FakeElement(tag),
+    createTextNode: (text: string): FakeText => new FakeText(text),
+    createComment: (): FakeText => new FakeText(''),
+    importNode: (node: FakeNode, deep?: boolean): FakeNode => node.cloneNode(deep),
+    // The document's listeners are the documentElement's, because this DOM has no bubbling at all
+    // and a no-op here made a whole shape of component undrivable: `@ultimat3/ui`'s Menu, Popover
+    // and focus trap each close on an Escape registered on `document`, never on their own node, so
+    // a test could mount one and never shut it. `fire(mounted.documentElement, 'keydown', …)`
+    // reaches them through the surface `MountedIsland` already exposes.
+    addEventListener: (name: string, fn: (event: unknown) => void): void =>
+      documentElement.addEventListener(name, fn),
+    removeEventListener: (name: string): void => documentElement.removeEventListener(name),
+  };
+  return {
+    documentElement,
+    globals: {
+      // Solid's event delegation reads `window` before it reads anything else.
+      window: globalThis,
+      Element: FakeElement,
+      SVGElement: FakeElement,
+      Node: FakeNode,
+      Text: FakeText,
+      document,
+    },
+  };
+}
+
+/** The delegated handler Solid parks on the node as `$$click`, or a listener it attached with
+ *  `addEventListener` — a compiled island uses one or the other and a driver must accept both. */
+export function handlerFor(
+  element: FakeElement,
+  type: string,
+): ((event: unknown) => void) | undefined {
+  const delegated = (element as unknown as Record<string, unknown>)[`$$${type}`];
+  if (typeof delegated === 'function') return delegated as (event: unknown) => void;
+  return element.listeners.get(type);
+}

package/src/live-node.ts

@@ -17,7 +17,7 @@ import type {
   UpgradeTarget,
   WsData,
   WsLike,
-} from '@ultimat3/realtime';
+} from '@ultimat3/realtime/server';
 import { liveNodeUnavailable, upgradeRefused } from './errors';
 
 /** Every frame this end received, in order, already parsed. */
@@ -121,7 +121,7 @@ let sequence = 0;
 export async function createLiveNode(options: LiveNodeOptions = {}): Promise<LiveNodeHandle> {
   const core = await import('@ultimat3/core');
   const query = await import('@ultimat3/query');
-  const realtime = await import('@ultimat3/realtime');
+  const realtime = await import('@ultimat3/realtime/server');
 
   const buildId = options.buildId ?? 'test-build';
   const transport = new realtime.InProcessTransport();

package/src/live-replicator.ts

@@ -14,7 +14,8 @@
 // still decides what a real node reads, and this is never in that decision.
 
 import type { RowBulkChange, RowChange, RowObserver } from '@ultimat3/entity';
-import type { ChangeEvent, ChangeOp, LiveQueryRegistry, Row } from '@ultimat3/realtime';
+import type { Row } from '@ultimat3/realtime';
+import type { ChangeEvent, ChangeOp, LiveQueryRegistry } from '@ultimat3/realtime/server';
 
 /** What a caller does with a change nobody could deliver. */
 export interface LiveReplicatorOptions {