@ultimat3/testing 19.3.1 → 19.3.2

package/CLAUDE.md

@@ -71,6 +71,7 @@ is its own entry point and not part of the barrel.
 | 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 |
 | `mountIsland` AWAITS `mount` | `IslandEntry['mount']` returns `unknown`, not `void`, and the call is awaited — the shipped runtime chains `import(e).then((m) => m.mount(el, props))` (`packages/render/src/hydrate.ts`) and only marks the element mounted when that settles, so an `async` mount is an ordinary island and `like.island.tsx` already is one. Typed `=> void` and called bare, the fixture returned before an island that opens a queue or a socket had rendered anything, so every assertion after it read an empty wrapper — and worse, the mount RESUMED after `restore()` had taken the fake `document` back out, failing with `document is not defined` inside whichever later test happened to be running. Not a breaking change: `IslandEntry` is module-private and an island module is matched structurally off an `unknown` import, so nothing implements it. |
+| Dispose STOPS the island, then restores the globals | `mountIsland` keeps what `mount` resolved to and, when it is a function, calls it in `[Symbol.dispose]` BEFORE `restore()` — the island's disposer clears an interval whose callback reads `document`, or removes a listener from it, and must find the `document` it was made against. Solid's `render` returns a disposer, so `return render(…)` is an island's whole side of it (`X_TEST_ISLAND_NO_MOUNT`'s fix line and `x g island`'s template both say so). Restoring the globals was the whole teardown until 2026-09-07, and an island that polled on an interval kept ticking after the DOM was gone: measured in ai-maxxing as `document is not defined` thrown into whichever later test was running and as one file's fetch stub receiving another file's POSTs. Once — `using` and an `afterAll` that also disposes by hand are both real — and a disposer that throws still hands the globals back in a `finally`; the throw is the test's to see |
 | The micro-DOM is the fixture's, once **for islands** | `island-dom.ts`. **"Once" is scoped to this job, and said so only from 2026-08-23**: `packages/ui/src/fake-dom.ts` is a second micro-DOM (201 lines, test-only, off that package's barrel) for a different one — focus, `activeElement`, `contains` and a `:not()` selector grammar for keyboard code, none of which parses a `<template>`. It is not a copy to collapse: `ui` is tier 4 and this package is tier 5, so `ui -> testing` is an upward import the boundary check refuses, and the merge would need the shared half moved down to a tier neither grammar belongs in. `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 |

package/README.md

@@ -303,6 +303,17 @@ removed.
 `island[Symbol.dispose]()` in an `afterAll`. Left installed it hands a fake `document` to every
 later FILE in the run.
 
+**Dispose also stops the island** (`As of 2026-09-07`): when `mount` returns a function, that is
+the island's disposer and dispose calls it — before the globals go back, so a disposer that
+removes a listener from `document` or clears an interval whose callback reads it finds the same
+`document` `mount` ran under. Solid's `render` already returns exactly that, so an island's whole
+side of the contract is `return render(() => <Counter {...props} />, el)` — and a disposed root
+runs every `onCleanup` inside it. Until this landed, restoring the globals was the whole of the
+teardown: an island whose `mount` polled on an interval kept ticking after the DOM was gone,
+which surfaced as `document is not defined` thrown into whichever later test happened to be
+running, and as one file's fetch stub receiving POSTs from another file's island. A `mount` that
+returns nothing disposes as it always did.
+
 ### Selectors
 
 `find`, `all`, `text`, `fire`, `resize`, `scroll` and `observing` take one grammar, `As of

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/testing",
-  "version": "19.3.1",
+  "version": "19.3.2",
   "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": "19.3.1",
-    "@ultimat3/core": "19.3.1",
-    "@ultimat3/db": "19.3.1",
-    "@ultimat3/entity": "19.3.1",
-    "@ultimat3/i18n": "19.3.1",
-    "@ultimat3/jobs": "19.3.1",
-    "@ultimat3/mail": "19.3.1",
-    "@ultimat3/policy": "19.3.1",
-    "@ultimat3/query": "19.3.1",
-    "@ultimat3/realtime": "19.3.1",
-    "@ultimat3/time": "19.3.1"
+    "@ultimat3/cache": "19.3.2",
+    "@ultimat3/core": "19.3.2",
+    "@ultimat3/db": "19.3.2",
+    "@ultimat3/entity": "19.3.2",
+    "@ultimat3/i18n": "19.3.2",
+    "@ultimat3/jobs": "19.3.2",
+    "@ultimat3/mail": "19.3.2",
+    "@ultimat3/policy": "19.3.2",
+    "@ultimat3/query": "19.3.2",
+    "@ultimat3/realtime": "19.3.2",
+    "@ultimat3/time": "19.3.2"
   }
 }

package/src/errors.ts

@@ -466,7 +466,7 @@ export class IslandMountMissingError extends UltimateError {
       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); }`,
+          : `in ${file} add: import { render } from 'solid-js/web'; export function mount(el: HTMLElement, props: Parameters<typeof ${component}>[0]): () => void { el.textContent = ''; return render(() => <${component} {...props} />, el); }`,
     });
   }
 }

package/src/fixture-island.ts

@@ -57,6 +57,10 @@ export interface MountIslandOptions {
   readonly size?: ResizeInput;
 }
 
+/**
+ * `Disposable`: dispose calls the disposer the island's `mount` returned (Solid's `render` answers
+ * one — `return render(…)`), then hands the process its globals back. Both, in that order.
+ */
 export interface MountedIsland extends Disposable {
   /** The chunk's source, for asserting on what did or did not reach the browser. */
   readonly code: string;
@@ -101,11 +105,19 @@ export interface MountedIsland extends Disposable {
  * opens a queue or a socket first is therefore an ordinary island (`like.island.tsx` is `async`),
  * and a fixture typed `=> void` could only ever call it and walk away. Widening, not narrowing: an
  * island module is matched structurally off an `unknown` import, so nothing implements this type.
+ *
+ * What `mount` answers, once awaited, is the island's DISPOSER when it is a function — the one
+ * way an island hands back what it started, and Solid's `render` already returns exactly that, so
+ * `return render(…)` is the whole of an island's side. The fixture calls it on dispose.
  */
 interface IslandEntry {
   readonly mount: (el: unknown, props: unknown) => unknown;
 }
 
+/** The island's disposer, when `mount` answered one — anything else is an island with nothing to stop. */
+const disposerOf = (returned: unknown): (() => void) | undefined =>
+  typeof returned === 'function' ? (returned as () => void) : undefined;
+
 /** `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 {
@@ -198,6 +210,13 @@ function installGlobals(values: Readonly<Record<string, unknown>>): () => void {
  * 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.
+ *
+ * Dispose is two things in one order: the island's own disposer first, then the globals back.
+ * Restoring the globals was the whole of it until 2026-09-07, so an island whose `mount` started
+ * an interval kept ticking after the DOM was gone — measured as `document is not defined` thrown
+ * into whichever later test was running, and as one file's fetch stub receiving POSTs from another
+ * file's island. The disposer runs while the fake `document` is still installed, because what it
+ * clears (a listener on `document`, an interval whose callback reads it) was made against that one.
  */
 export async function mountIsland(options: MountIslandOptions): Promise<MountedIsland> {
   // `only`, because this fixture has always KNOWN which island it wants and asked for all of them
@@ -240,7 +259,21 @@ export async function mountIsland(options: MountIslandOptions): Promise<MountedI
     // island's `mount` resumed AFTER the `restore()` below had taken the fake `document` back out
     // — so it failed with `document is not defined` inside whichever later test happened to be
     // running, with no thread back here.
-    await entry.mount(el, options.props);
+    const unmount = disposerOf(await entry.mount(el, options.props));
+    let disposed = false;
+    const dispose = (): void => {
+      // Once: `using` and an `afterAll` that also disposes by hand are both real, and Solid's own
+      // disposer is idempotent while an island's `clearInterval` wrapper need not be.
+      if (disposed) return;
+      disposed = true;
+      try {
+        unmount?.();
+      } finally {
+        // Whatever the disposer did — including throw, which is the test's to see — the process
+        // gets its globals back, or the fake `document` reaches every later file in the run.
+        restore();
+      }
+    };
     const resolve = (target: string | FakeElement | null | undefined): FakeElement | null =>
       typeof target === 'string' ? el.querySelector(target) : (target ?? null);
     return {
@@ -271,7 +304,7 @@ export async function mountIsland(options: MountIslandOptions): Promise<MountedI
         const node = resolve(target);
         return node !== null && [...resizeObservers].some((each) => each.targets.has(node));
       },
-      [Symbol.dispose]: restore,
+      [Symbol.dispose]: dispose,
     };
   } catch (error) {
     // A mount that throws restores the process before it rethrows: the alternative leaves every