@ultimat3/testing 19.1.2 → 19.2.0

package/CLAUDE.md

@@ -74,6 +74,9 @@ is its own entry point and not part of the barrel.
 | `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 |
+| The selector grammar is SMALL and REFUSES, `As of 2026-09-05` | `island-selector.ts`: compounds of tag, `#id`, `.class`, `[attr]`, `[attr="value"]`, joined by a space (descendant) or `>` (child), matched right to left as CSS matches. Until then it was one regex — `[attr="value"]` or a bare tag — and a selector outside it MATCHED NOTHING: `find('[data-role="list"] button')` read as a tag with a space in it and answered `null`, so a virtualized list could be addressed one element at a time or not at all. Outside the grammar is `X_TEST_ISLAND_SELECTOR_UNSUPPORTED` with the offset, never an empty answer. No `,`, no `+`/`~`, no pseudo-classes: each is a CSS engine's worth of edge cases, and the rule above about a DOM library holds |
+| The box is 0 until a test writes it | `clientHeight`, `scrollTop`, `scrollHeight` and the rest are plain writable numbers, default 0, and `getBoundingClientRect()` derives from the offset box. This DOM lays nothing out, so any other number is a fact the harness invented — and `undefined`, which they were, turns a windowed list's `Math.ceil(height / row)` into `NaN` rows with no throw near the cause. `size:` on `mountIsland` writes the HOST's box before `mount` (the one element that exists then); `mounted.resize` writes everything the island created, after |
+| `ResizeObserver` records and never fires on its own | `island-observers.ts`, one registry PER DOCUMENT. `observe` fires nothing: a browser's initial notification lands at the next rendering opportunity, after `mount` returned, and here that opportunity is `mounted.resize(el, { width, height })` — which writes `client*` and `offset*`, delivers a spec-shaped entry to every observer of THAT element and no other, and answers whether one ran, for `fire`'s reason. `disconnect` leaves the registry, so `mounted.observing(el)` after an island's cleanup is the assertion that its `onCleanup` disconnected. `IntersectionObserver` is the same class of gap and is not modelled — no shipped island reads one |
 | 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 |
 | A states file is PURE DATA, and it is enforced | `defineIslandStates` declares the states an island can be photographed in — error, empty, over-quota, read-only — in a sibling file (`settings.island.states.ts`) that may not import the component, JSX or `solid-js`. Three consumers read that file and only one of them has a browser: the command that takes the pictures (which must know the complete expected list BEFORE a browser exists, or "produced nothing and exited 0" reads as success), the harness page, and `island-states-guard.test.ts`. `assertIslandStatesPure` is the static rule — `X_TEST_ISLAND_STATES_NOT_PURE` — because a module that imports Solid still evaluates perfectly well under Bun, so nothing dynamic can catch it |
@@ -122,8 +125,8 @@ 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 —
+`fixture-island.ts`, `island-dom.ts`, `island-selector.ts` and `island-observers.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

@@ -23,6 +23,8 @@ frozen clock. Never let a test reach the network unmocked — it fails by design
 | `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 |
+| `island-selector.ts` | the selector grammar `find`/`all` read — compounds and two combinators — and the refusal for the rest |
+| `island-observers.ts` | `ResizeObserver`, recording; `deliverResize` is the test's hand on the browser's layout |
 | `island-states.ts` | the vocabulary: what a photographable island STATE is. Types and constants, importing nothing |
 | `define-island-states.ts` | `defineIslandStates()` — one manifest, validated and frozen, with every default resolved |
 | `island-states-check.ts` | the rules a declaration must satisfy, as pure functions answering a fault |
@@ -301,6 +303,65 @@ removed.
 `island[Symbol.dispose]()` in an `afterAll`. Left installed it hands a fake `document` to every
 later FILE in the run.
 
+### Selectors
+
+`find`, `all`, `text`, `fire`, `resize`, `scroll` and `observing` take one grammar, `As of
+2026-09-05`: a **compound** of a tag, `#id`, `.class`, `[attr]` and `[attr="value"]`
+(`li[data-role="row"].odd`), joined by the **descendant** combinator (a space) and the **child**
+combinator (`>`). Matching is CSS's — right to left, `>` means the direct parent, a space means any
+ancestor, and a descendant walk backtracks — so `[data-role="scroller"] > ul > li button` finds
+the buttons in the rows and not the one in the toolbar.
+
+Anything else — a pseudo-class, a comma, `+`/`~`, an unquoted attribute value — throws
+`X_TEST_ISLAND_SELECTOR_UNSUPPORTED` naming the offset it stopped at. It used to match nothing,
+which failed the assertion after it on the wrong question.
+
+### Layout: the box, the scroll offset, `ResizeObserver`
+
+This DOM lays nothing out, so every box field is **0 until a test writes it**: `clientWidth`,
+`clientHeight`, `offsetWidth`, `offsetHeight`, `scrollWidth`, `scrollHeight`, `scrollTop` and
+`scrollLeft` are plain writable numbers on every element, `getBoundingClientRect()` derives from
+the offset box at the origin, and `scrollTo({ top })` / `scrollTo(left, top)` write the offset and
+run the element's `scroll` listener. A virtualized list — rows sliced by `scrollTop / rowHeight`,
+a window sized by `clientHeight` — is testable end to end:
+
+```ts
+import { buildIslands } from '@ultimat3/cli';
+import { expect, mountIsland } from '@ultimat3/testing';
+
+declare const root: string; // the app root, as above
+using island = await mountIsland({
+  build: buildIslands,
+  root,
+  file: 'apps/web/app/fleet/session-list.island.tsx',
+  props: { rows: 3 },
+  size: { height: 640 },
+});
+
+// The host is the one element that exists BEFORE mount; `size:` is its box then.
+// Everything the island creates starts at 0 and is laid out afterwards, by you:
+expect(island.resize('[data-role="scroller"]', { height: 100, width: 300 })).toBe(true);
+expect(island.all('[data-role="scroller"] li')).toHaveLength(3);
+
+expect(island.scroll('[data-role="scroller"]', { top: 80 })).toBe(true);
+expect(island.text('[data-role="scroller"] li')).toBe('row 3');
+```
+
+`ResizeObserver` is a constructor for the life of the mount, so an island's
+`typeof ResizeObserver === 'function'` guard takes the browser's branch. It **records** — `observe`,
+`unobserve`, `disconnect` — and fires nothing on its own: the browser's initial notification lands
+after `mount` returns, at the next rendering opportunity, and here that opportunity is your
+`island.resize(target, { width, height })`. It writes the size onto the element (`client*` and
+`offset*` together) and delivers one spec-shaped entry — `target`, `contentRect`, `borderBoxSize`,
+`contentBoxSize`, `devicePixelContentBoxSize` — to every observer watching **that** element, and
+answers whether any did, for `fire`'s reason. `island.observing(target)` is the teardown
+assertion: an `onCleanup` that forgot `disconnect()` still answers `true` after the island's
+cleanup ran. The registry is per document, so nothing an earlier mount observed survives into the
+next.
+
+Not modelled: `IntersectionObserver`. Same class of gap for an infinite-scroll sentinel; it is not
+here yet because no island the framework ships reads one.
+
 ## Declaring the states an island can be photographed in
 
 A reviewer can click their way to most of a component. They cannot click their way to *the account
@@ -403,7 +464,8 @@ fails on a page that simply has not painted yet.
 
 `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` `X_TEST_ISLAND_STATES_EMPTY`
+`X_TEST_ISLAND_NOT_BUILT` `X_TEST_ISLAND_NO_MOUNT` `X_TEST_ISLAND_SELECTOR_UNSUPPORTED`
+`X_TEST_ISLAND_STATES_EMPTY`
 `X_TEST_ISLAND_STATES_NOT_PURE` `X_TEST_ISLAND_STATES_MISSING_FILE` `X_TEST_ISLAND_STATES_UNKNOWN`
 `X_TEST_ISLAND_STATES_AMBIGUOUS` `X_TEST_ISLAND_STATE_ID_INVALID` `X_TEST_ISLAND_STATE_DUPLICATE`
 `X_TEST_ISLAND_STATE_JSON_INVALID` `X_TEST_ISLAND_STATE_CLOCK_INVALID`

package/package.json

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

package/src/errors.ts

@@ -30,6 +30,8 @@ export const TESTING_ERROR_CODES = [
   'X_TEST_LIVE_NODE_UPGRADE_REFUSED',
   'X_TEST_ISLAND_NOT_BUILT',
   'X_TEST_ISLAND_NO_MOUNT',
+  // Declared here and thrown from `island-selector.ts`, for the reason the states codes below are.
+  'X_TEST_ISLAND_SELECTOR_UNSUPPORTED',
   // Declared here and thrown from `island-state-errors.ts`: one file has one job and this
   // catalogue is at its ceiling, so the classes moved and the registration did not.
   'X_TEST_ISLAND_STATES_EMPTY',
@@ -65,6 +67,7 @@ export const TESTING_ERROR_TITLES: Readonly<Record<TestingErrorCode, string>> =
   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',
+  X_TEST_ISLAND_SELECTOR_UNSUPPORTED: "a selector is outside the island DOM's grammar",
   X_TEST_ISLAND_STATES_EMPTY: 'an island state manifest declares no states',
   X_TEST_ISLAND_STATES_NOT_PURE:
     'an island states file imports the component, a renderer or a sibling module',

package/src/fixture-island.ts

@@ -8,6 +8,8 @@ import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { islandMountMissing, islandNotBuilt } from './errors';
 import { createIslandDocument, FakeElement, handlerFor, parseHtml } from './island-dom';
+import type { ResizeInput } from './island-observers';
+import { deliverResize } from './island-observers';
 
 /** 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. */
@@ -47,6 +49,12 @@ export interface MountIslandOptions {
   readonly shell?: string;
   /** Anything the micro-DOM does not supply — `fetch` above all. Merged over the DOM globals. */
   readonly globals?: Readonly<Record<string, unknown>>;
+  /**
+   * The host element's box BEFORE `mount` runs — the one element that exists then, laid out by
+   * the server-rendered page around it. Everything the island creates starts at 0 and is sized
+   * after mount through `resize`, which is the order a browser's `ResizeObserver` delivers in.
+   */
+  readonly size?: ResizeInput;
 }
 
 export interface MountedIsland extends Disposable {
@@ -70,6 +78,20 @@ export interface MountedIsland extends Disposable {
     type: string,
     event?: Readonly<Record<string, unknown>>,
   ): boolean;
+  /**
+   * The browser's layout, in the test's hand: write the box onto the element and deliver an entry
+   * to every `ResizeObserver` the island has watching THAT element. Answers whether one ran, for
+   * `fire`'s reason — an element nothing observes and an island that never observed are otherwise
+   * the same silence, and the second is the bug.
+   */
+  resize(target: string | FakeElement | null | undefined, size: ResizeInput): boolean;
+  /** Move the element's scroll offset and run its `scroll` listener. Answers whether one ran. */
+  scroll(
+    target: string | FakeElement | null | undefined,
+    to: { top?: number; left?: number },
+  ): boolean;
+  /** Whether any live `ResizeObserver` is watching the element — `false` once it disconnected. */
+  observing(target: string | FakeElement | null | undefined): boolean;
 }
 
 /**
@@ -201,13 +223,16 @@ export async function mountIsland(options: MountIslandOptions): Promise<MountedI
     );
   }
 
-  const { documentElement, globals } = createIslandDocument();
+  const { documentElement, globals, resizeObservers } = 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');
+    // Before the shell and before `mount`: nothing observes the host yet, so this is a write and
+    // never a notification.
+    if (options.size !== undefined) deliverResize(resizeObservers, el, options.size);
     if (options.shell !== undefined) {
       for (const child of [...parseHtml(options.shell).children]) el.appendChild(child);
     }
@@ -216,6 +241,8 @@ export async function mountIsland(options: MountIslandOptions): Promise<MountedI
     // — 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 resolve = (target: string | FakeElement | null | undefined): FakeElement | null =>
+      typeof target === 'string' ? el.querySelector(target) : (target ?? null);
     return {
       code: chunk.code,
       el,
@@ -224,12 +251,26 @@ export async function mountIsland(options: MountIslandOptions): Promise<MountedI
       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);
+        const node = resolve(target);
+        const handler = node === null ? undefined : handlerFor(node, type);
         if (handler === undefined) return false;
         handler({ currentTarget: node, target: node, ...event });
         return true;
       },
+      resize: (target, size) => {
+        const node = resolve(target);
+        return node === null ? false : deliverResize(resizeObservers, node, size);
+      },
+      scroll: (target, to) => {
+        const node = resolve(target);
+        if (node === null || handlerFor(node, 'scroll') === undefined) return false;
+        node.scrollTo(to);
+        return true;
+      },
+      observing: (target) => {
+        const node = resolve(target);
+        return node !== null && [...resizeObservers].some((each) => each.targets.has(node));
+      },
       [Symbol.dispose]: restore,
     };
   } catch (error) {

package/src/index.ts

@@ -119,6 +119,7 @@ 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 { FakeResizeObserverEntry, ResizeInput, ResizeRect } from './island-observers';
 export type { IslandAddress, IslandShotTarget } from './island-shot-targets';
 export {
   isIslandTheme,

package/src/island-dom.ts

@@ -2,9 +2,13 @@
 // `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.
+//
+// Two neighbours at the 500-line ceiling: `island-selector.ts` is the selector grammar `find`
+// and `all` read, and `island-observers.ts` is the `ResizeObserver` an island measures with.
 
-/** `[data-role="preview"]` — the one selector shape a mounted island is queried by. */
-const ATTRIBUTE_SELECTOR = /^\[([\w-]+)="([^"]*)"\]$/;
+import type { FakeResizeObserver } from './island-observers';
+import { createResizeObservers, rectOf } from './island-observers';
+import { matchesSelector, parseSelector } from './island-selector';
 
 /**
  * A node belongs to ONE parent, and the DOM enforces that by moving it: every attach detaches the
@@ -256,19 +260,57 @@ export class FakeElement extends FakeNode {
     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.
+   * The box, as a test set it. Every field is 0 until something writes it: this DOM lays nothing
+   * out, and a number invented here would be a fact the harness made up. An island reads them the
+   * way a virtualized list does — `clientHeight` for the window, `scrollTop` in a scroll handler,
+   * `scrollHeight` to know the whole — and a stub without them answered `undefined`, which
+   * `Math.floor` turns into `NaN` rows with no throw to point at it. Plain writable fields, so a
+   * test sets `list.clientHeight = 400` directly, or through `mounted.resize`, which also notifies
+   * the island's `ResizeObserver`.
+   */
+  clientWidth = 0;
+  clientHeight = 0;
+  offsetWidth = 0;
+  offsetHeight = 0;
+  scrollWidth = 0;
+  scrollHeight = 0;
+  scrollTop = 0;
+  scrollLeft = 0;
+  /** Derived from the offset box: no layout, so an element is always at the origin. */
+  getBoundingClientRect(): ReturnType<typeof rectOf> {
+    return rectOf(this.offsetWidth, this.offsetHeight);
+  }
+  /**
+   * Both spellings the DOM takes — `scrollTo({ top })` and `scrollTo(left, top)` — writing the
+   * offsets and running the island's `scroll` listener, which is how a virtualized list learns its
+   * window moved. `scroll` is not in Solid's delegated set, so `onScroll` compiles to
+   * `addEventListener('scroll', …)` and only that listener is looked for.
+   */
+  scrollTo(options: { top?: number; left?: number } | number, top?: number): void {
+    if (typeof options === 'number') {
+      this.scrollLeft = options;
+      if (top !== undefined) this.scrollTop = top;
+    } else {
+      if (options.left !== undefined) this.scrollLeft = options.left;
+      if (options.top !== undefined) this.scrollTop = options.top;
+    }
+    this.listeners.get('scroll')?.({ currentTarget: this, target: this });
+  }
+  /**
+   * A compound of tag, `#id`, `.class`, `[attr]` and `[attr="value"]`, joined by the descendant
+   * and child combinators — `island-selector.ts` — anywhere in the subtree. Anything richer throws
+   * `X_TEST_ISLAND_SELECTOR_UNSUPPORTED` rather than matching nothing.
    *
    * 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 parsed = parseSelector(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);
+        if (child instanceof FakeElement && matchesSelector(child, parsed)) found.push(child);
         walk(child);
       }
     };
@@ -280,15 +322,6 @@ export class FakeElement extends FakeNode {
   }
 }
 
-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() {
@@ -331,6 +364,8 @@ export function parseHtml(html: string): FakeNode {
 export interface IslandDocument {
   readonly documentElement: FakeElement;
   readonly globals: Readonly<Record<string, unknown>>;
+  /** Every `ResizeObserver` this document's island constructed and has not disconnected. */
+  readonly resizeObservers: Set<FakeResizeObserver<FakeElement>>;
 }
 
 /**
@@ -340,6 +375,9 @@ export interface IslandDocument {
  */
 export function createIslandDocument(): IslandDocument {
   const documentElement = new FakeElement('html');
+  // Per document, for the reason the document itself is: an observer the last mount's island
+  // never disconnected must not hear the next mount's `resize`.
+  const { registry: resizeObservers, ResizeObserver } = createResizeObservers<FakeElement>();
   const document = {
     documentElement,
     createElement: (tag: string): FakeElement =>
@@ -359,6 +397,7 @@ export function createIslandDocument(): IslandDocument {
   };
   return {
     documentElement,
+    resizeObservers,
     globals: {
       // Solid's event delegation reads `window` before it reads anything else.
       window: globalThis,
@@ -367,6 +406,9 @@ export function createIslandDocument(): IslandDocument {
       Node: FakeNode,
       Text: FakeText,
       document,
+      // A constructor, so an island's `typeof ResizeObserver === 'function'` guard takes the
+      // branch a browser takes. `window.ResizeObserver` resolves through `globalThis` above.
+      ResizeObserver,
     },
   };
 }

package/src/island-observers.ts

@@ -0,0 +1,158 @@
+// `ResizeObserver`, as much of it as a compiled island calls and a test can drive. Split out of
+// `island-dom.ts` at the 500-line ceiling.
+//
+// `bun test` has no `ResizeObserver` at all, so an island that measures its box — a virtualized
+// list sizing its window, a terminal computing rows and columns — either guarded the constructor
+// and took a fallback path no browser takes, or threw `ResizeObserver is not defined` inside
+// `mount`. Neither is the island a browser runs. The stub RECORDS: `observe`, `unobserve` and
+// `disconnect` keep a set per observer, and `deliverResize` is the test's hand on the browser's
+// layout — it calls every observer watching THAT element, and no other, with an entry shaped the
+// way the spec shapes one.
+//
+// `observe()` fires nothing. A browser delivers an initial notification at the next rendering
+// opportunity, which is after `mount` has returned; here that opportunity is the test's own
+// `mounted.resize(...)`, made when the test decides what the layout is. A stub that fired inside
+// `observe` would re-enter the island mid-`mount` from a place no browser does.
+
+/** The size a test hands an element — either axis alone is fine; the other keeps its value. */
+export interface ResizeInput {
+  readonly width?: number;
+  readonly height?: number;
+}
+
+/** The size fields `deliverResize` writes, so an island's own `clientHeight` read agrees with
+ *  the entry it was handed. Structural, so this module imports no DOM class. */
+export interface SizedElement {
+  clientWidth: number;
+  clientHeight: number;
+  offsetWidth: number;
+  offsetHeight: number;
+}
+
+/** `DOMRectReadOnly`, as the spec's `contentRect` — every member, because an island may read any. */
+export interface ResizeRect {
+  readonly x: number;
+  readonly y: number;
+  readonly top: number;
+  readonly left: number;
+  readonly width: number;
+  readonly height: number;
+  readonly right: number;
+  readonly bottom: number;
+}
+
+export const rectOf = (width: number, height: number): ResizeRect => ({
+  x: 0,
+  y: 0,
+  top: 0,
+  left: 0,
+  width,
+  height,
+  right: width,
+  bottom: height,
+});
+
+/** One entry of the list a `ResizeObserver` callback receives. All three box lists are the same
+ *  box: this DOM has no padding or border to tell them apart by. */
+export interface FakeResizeObserverEntry<TElement extends object> {
+  readonly target: TElement;
+  readonly contentRect: ResizeRect;
+  readonly borderBoxSize: readonly { readonly inlineSize: number; readonly blockSize: number }[];
+  readonly contentBoxSize: readonly { readonly inlineSize: number; readonly blockSize: number }[];
+  readonly devicePixelContentBoxSize: readonly {
+    readonly inlineSize: number;
+    readonly blockSize: number;
+  }[];
+}
+
+export type ResizeCallback<TElement extends object> = (
+  entries: readonly FakeResizeObserverEntry<TElement>[],
+  observer: FakeResizeObserver<TElement>,
+) => void;
+
+export class FakeResizeObserver<TElement extends object = object> {
+  readonly targets = new Set<TElement>();
+  constructor(
+    private readonly registry: Set<FakeResizeObserver<TElement>>,
+    private readonly callback: ResizeCallback<TElement>,
+  ) {
+    registry.add(this);
+  }
+  observe(target: TElement): void {
+    this.targets.add(target);
+  }
+  unobserve(target: TElement): void {
+    this.targets.delete(target);
+  }
+  /** Out of the registry too: an observer an island disconnected in `onCleanup` is gone, and a
+   *  later `resize` must not reach it — that is the assertion a teardown test makes. */
+  disconnect(): void {
+    this.targets.clear();
+    this.registry.delete(this);
+  }
+  deliver(target: TElement, rect: ResizeRect): void {
+    const box = [{ inlineSize: rect.width, blockSize: rect.height }];
+    this.callback(
+      [
+        {
+          target,
+          contentRect: rect,
+          borderBoxSize: box,
+          contentBoxSize: box,
+          devicePixelContentBoxSize: box,
+        },
+      ],
+      this,
+    );
+  }
+}
+
+/**
+ * The per-document registry and the constructor an island sees as `ResizeObserver`. Per DOCUMENT,
+ * never module scope: an observer one mount left behind must not receive the next mount's resize,
+ * and `createIslandDocument` is built fresh per mount for exactly that class of state.
+ */
+export function createResizeObservers<TElement extends object>(): {
+  readonly registry: Set<FakeResizeObserver<TElement>>;
+  readonly ResizeObserver: new (callback: ResizeCallback<TElement>) => FakeResizeObserver<TElement>;
+} {
+  const registry = new Set<FakeResizeObserver<TElement>>();
+  const ResizeObserver = class extends FakeResizeObserver<TElement> {
+    constructor(callback: ResizeCallback<TElement>) {
+      super(registry, callback);
+    }
+  };
+  return { registry, ResizeObserver };
+}
+
+/**
+ * Write the size onto the element and notify every observer watching it. Answers whether ANY
+ * observer ran, for `fire`'s reason: an element nothing observes and an island that never called
+ * `observe` are the same silence otherwise, and the second is the bug.
+ *
+ * Both `client*` and `offset*` move together. This DOM lays nothing out, so the two are one number
+ * — an island reading either after a resize sees the size the entry carried.
+ */
+export function deliverResize<TElement extends SizedElement>(
+  registry: ReadonlySet<FakeResizeObserver<TElement>>,
+  target: TElement,
+  size: ResizeInput,
+): boolean {
+  if (size.width !== undefined) {
+    target.clientWidth = size.width;
+    target.offsetWidth = size.width;
+  }
+  if (size.height !== undefined) {
+    target.clientHeight = size.height;
+    target.offsetHeight = size.height;
+  }
+  const rect = rectOf(target.clientWidth, target.clientHeight);
+  let delivered = false;
+  // A copy: a callback that disconnects its observer mutates the registry under the walk.
+  for (const observer of [...registry]) {
+    if (!observer.targets.has(target)) continue;
+    observer.deliver(target, rect);
+    delivered = true;
+  }
+  return delivered;
+}

package/src/island-selector.ts

@@ -0,0 +1,174 @@
+// The selector grammar the island micro-DOM answers, and the refusal for everything outside it.
+//
+// Split out of `island-dom.ts` at the 500-line ceiling. Until `As of 2026-09-05` the whole grammar
+// was one regex — `[data-role="preview"]` or a bare tag — and a selector outside it was not
+// refused, it MATCHED NOTHING: `find('[data-role="list"] button')` read as a tag named
+// `[data-role="list"] button`, answered `null`, and the assertion after it failed on the wrong
+// question. A virtualized list — rows inside a scroller inside a panel — cannot be addressed one
+// element at a time, which is what the app that measured this was left doing.
+//
+// Small on purpose: compounds of tag, `#id`, `.class`, `[attr]` and `[attr="value"]`, joined by the
+// descendant (whitespace) and child (`>`) combinators. No `,`, no sibling combinators, no
+// pseudo-classes — each is a CSS engine's worth of edge cases, and a DOM library may not be added.
+// Anything else throws `X_TEST_ISLAND_SELECTOR_UNSUPPORTED` naming the fragment, because a
+// selector silently matching nothing is the hole this file replaces.
+
+import { UltimateError } from '@ultimat3/core';
+
+/** The element surface the matcher reads. Structural, so this module imports no DOM class. */
+export interface SelectableElement {
+  readonly tagName: string;
+  /** Whatever the tree's parent type is — a fragment root without a tag is not an element. */
+  readonly parentNode: object | null;
+  getAttribute(name: string): string | null;
+}
+
+const isSelectable = (node: object): node is SelectableElement =>
+  typeof (node as { tagName?: unknown }).tagName === 'string' &&
+  typeof (node as { getAttribute?: unknown }).getAttribute === 'function';
+
+/** `tag`, `#id`, `.class`, `[attr]`, `[attr="v"]`, `[attr='v']` — one simple selector each. */
+const SIMPLE = /\*|[a-zA-Z][\w-]*|#[\w-]+|\.[\w-]+|\[([\w-]+)(?:=(?:"([^"]*)"|'([^']*)'))?\]/y;
+
+interface Compound {
+  readonly tag: string | undefined;
+  readonly id: string | undefined;
+  readonly classes: readonly string[];
+  readonly attributes: readonly { readonly name: string; readonly value: string | undefined }[];
+}
+
+/** `descendant` is whitespace, `child` is `>`. The first compound has no combinator before it. */
+type Combinator = 'descendant' | 'child';
+
+interface Step {
+  readonly combinator: Combinator;
+  readonly compound: Compound;
+}
+
+export interface ParsedSelector {
+  readonly source: string;
+  readonly steps: readonly Step[];
+}
+
+/** The grammar, in the words the fix line prints. One string, so the two can never disagree. */
+export const SELECTOR_GRAMMAR =
+  'a tag, #id, .class, [attr] or [attr="value"], compounded (li[data-role="row"]) and joined by a ' +
+  'space (descendant) or > (child)';
+
+export class IslandSelectorUnsupportedError extends UltimateError {
+  constructor(input: { selector: string; at: number }) {
+    const fragment = input.selector.slice(input.at, input.at + 12);
+    super({
+      code: 'X_TEST_ISLAND_SELECTOR_UNSUPPORTED',
+      cause: `${JSON.stringify(input.selector)} is not in the island DOM's selector grammar — the part it cannot read starts at ${JSON.stringify(fragment)} (offset ${input.at})`,
+      fix: `spell the selector as ${SELECTOR_GRAMMAR}; a pseudo-class, a comma or a sibling combinator needs a browser test`,
+    });
+  }
+}
+
+const parseCompound = (selector: string, from: number): { compound: Compound; end: number } => {
+  let tag: string | undefined;
+  let id: string | undefined;
+  const classes: string[] = [];
+  const attributes: { name: string; value: string | undefined }[] = [];
+  let at = from;
+  for (;;) {
+    SIMPLE.lastIndex = at;
+    const match = SIMPLE.exec(selector);
+    if (match === null) break;
+    const token = match[0];
+    if (token === '*') {
+      /* universal: matches every element */
+    } else if (token.startsWith('#')) id = token.slice(1);
+    else if (token.startsWith('.')) classes.push(token.slice(1));
+    else if (token.startsWith('[')) {
+      attributes.push({ name: match[1] as string, value: match[2] ?? match[3] });
+    } else if (tag === undefined && at === from) tag = token;
+    // A tag AFTER an id, class or attribute is two compounds with no combinator between them,
+    // which is not a selector: `[a]li` is refused rather than read as `[a] li`.
+    else break;
+    at += token.length;
+  }
+  if (at === from) throw new IslandSelectorUnsupportedError({ selector, at: from });
+  return { compound: { tag, id, classes, attributes }, end: at };
+};
+
+/**
+ * Left to right into steps; matched right to left by `matchesSelector`. Throws at the first
+ * character the grammar does not cover, with its offset — a refusal a reader can act on, where
+ * "matched nothing" is one they have to guess at.
+ */
+export function parseSelector(selector: string): ParsedSelector {
+  const steps: Step[] = [];
+  let at = 0;
+  let combinator: Combinator = 'descendant';
+  const skipSpaces = (): void => {
+    while (selector[at] === ' ' || selector[at] === '\t' || selector[at] === '\n') at += 1;
+  };
+  skipSpaces();
+  if (at === selector.length) throw new IslandSelectorUnsupportedError({ selector, at: 0 });
+  for (;;) {
+    const { compound, end } = parseCompound(selector, at);
+    steps.push({ combinator, compound });
+    at = end;
+    const beforeSpaces = at;
+    skipSpaces();
+    if (at === selector.length) return { source: selector, steps };
+    if (selector[at] === '>') {
+      combinator = 'child';
+      at += 1;
+      skipSpaces();
+    } else if (at > beforeSpaces) combinator = 'descendant';
+    // No whitespace and no `>` between two tokens the compound parser stopped on: `[a]li`,
+    // `li:first-child`, `a, b`, `a + b` — every one of them a shape this grammar does not read.
+    else throw new IslandSelectorUnsupportedError({ selector, at });
+  }
+}
+
+const classesOf = (element: SelectableElement): readonly string[] =>
+  (element.getAttribute('class') ?? '').split(/\s+/).filter((name) => name.length > 0);
+
+const matchesCompound = (element: SelectableElement, compound: Compound): boolean => {
+  if (compound.tag !== undefined && compound.tag !== element.tagName) return false;
+  if (compound.id !== undefined && element.getAttribute('id') !== compound.id) return false;
+  if (compound.classes.length > 0) {
+    const own = classesOf(element);
+    if (!compound.classes.every((name) => own.includes(name))) return false;
+  }
+  for (const { name, value } of compound.attributes) {
+    const actual = element.getAttribute(name);
+    if (value === undefined ? actual === null : actual !== value) return false;
+  }
+  return true;
+};
+
+/** The element's parent when it is an element — a document or fragment root has no `tagName`. */
+const parentElement = (element: SelectableElement): SelectableElement | null => {
+  const parent = element.parentNode;
+  return parent !== null && isSelectable(parent) ? parent : null;
+};
+
+/**
+ * Right to left, as CSS matches: the LAST compound is the element itself, and each earlier one
+ * names its parent (`>`) or some ancestor (a space) — with backtracking over ancestors, so
+ * `a b c` matches a `c` under a `b` under an `a` at any depth, and `a > b` does NOT match `b`'s
+ * grandchildren. Ancestors ABOVE the element `querySelectorAll` was called on count, which is also
+ * the DOM's rule: `host.querySelectorAll('div p')` finds a `p` whose `div` is the host itself.
+ */
+export function matchesSelector(element: SelectableElement, parsed: ParsedSelector): boolean {
+  const matchesAt = (candidate: SelectableElement, index: number): boolean => {
+    const step = parsed.steps[index] as Step;
+    if (!matchesCompound(candidate, step.compound)) return false;
+    if (index === 0) return true;
+    const next = index - 1;
+    if (step.combinator === 'child') {
+      const parent = parentElement(candidate);
+      return parent !== null && matchesAt(parent, next);
+    }
+    for (let up = parentElement(candidate); up !== null; up = parentElement(up)) {
+      if (matchesAt(up, next)) return true;
+    }
+    return false;
+  };
+  return matchesAt(element, parsed.steps.length - 1);
+}