@ultimat3/testing 22.15.0 → 23.0.0

package/src/island-state-mount.ts

@@ -0,0 +1,129 @@
+// One declared island STATE, mounted: the lookup every island test hand-rolled, and the suite
+// form that owns the `beforeAll` / `afterAll` a mount needs because it installs a process-global
+// `document`. The props a test asserts on are the props `x shot --island` photographs, so the
+// picture and the test cannot be of two different components.
+
+import { afterAll, beforeAll, describe } from 'bun:test';
+import { assert } from '@ultimat3/core';
+import type {
+  IslandBuilder,
+  IslandBundleLike,
+  MountedIsland,
+  MountIslandOptions,
+} from './fixture-island';
+import { mountIsland } from './fixture-island';
+import { IslandStateUnknownError } from './island-state-errors';
+import type { IslandStatesManifest } from './island-states';
+import type { TestOptions } from './test-types';
+import { testName } from './test-types';
+
+/** What a state's mount takes: `mountIsland`'s options, minus what the manifest already says. */
+export type IslandStateMountOptions = Omit<MountIslandOptions, 'file' | 'props'>;
+
+/** The suite form's: the mount's own, plus the deadline of the `beforeAll` that runs it. */
+export interface IslandStateSuiteOptions extends IslandStateMountOptions, TestOptions {}
+
+/**
+ * The deadline a block's mount gets when it names none. The first mount in a file pays the island
+ * build — a Babel pass and a browser bundle, seconds not milliseconds — and Bun's 5 s default is
+ * what a cold CI runner misses.
+ */
+export const ISLAND_MOUNT_TIMEOUT_MS = 60_000;
+
+/**
+ * Bundles already built in this process, per builder, by `<root>\0<island>`. A file with three
+ * states used to build its island three times; the source cannot change between two mounts of one
+ * test run, so the second is a lookup. A build that REJECTS is forgotten, so the next mount
+ * reports its own failure rather than a cached one.
+ */
+const bundles = new WeakMap<IslandBuilder, Map<string, Promise<IslandBundleLike>>>();
+
+const buildOnce =
+  (build: IslandBuilder): IslandBuilder =>
+  (root, options) => {
+    const built = bundles.get(build) ?? new Map<string, Promise<IslandBundleLike>>();
+    bundles.set(build, built);
+    const key = `${root}\0${options?.only ?? ''}`;
+    const known = built.get(key);
+    if (known !== undefined) return known;
+    const pending = build(root, options);
+    built.set(key, pending);
+    pending.catch(() => built.delete(key));
+    return pending;
+  };
+
+/**
+ * Mount one state the manifest declares. `using island = await mountIslandState(states, 'idle',
+ * { build: buildIslands, root })` inside one test — `using` owns the teardown. A file asserting
+ * several things about one state uses `describeIslandState`, which owns it for the block.
+ */
+export async function mountIslandState(
+  manifest: IslandStatesManifest,
+  id: string,
+  options: IslandStateMountOptions,
+): Promise<MountedIsland> {
+  const state = manifest.states.find((one) => one.id === id);
+  if (state === undefined) {
+    throw new IslandStateUnknownError({
+      island: manifest.island,
+      id,
+      known: manifest.states.map((one) => one.id),
+    });
+  }
+  return mountIsland({
+    ...options,
+    build: buildOnce(options.build),
+    file: manifest.island,
+    props: state.props,
+  });
+}
+
+/**
+ * One block per declared state: mounted before its first test, disposed after its last, with the
+ * island built once per file. `body` is handed an ACCESSOR, for `describeApp`'s reason — the
+ * block is declared at module scope and the mount does not exist until `beforeAll` has run:
+ *
+ * ```ts
+ * describeIslandState(counterStates, 'idle', { build: buildIslands, root }, (island) => {
+ *   test('a click reaches the DOM', () => {
+ *     expect(island().fire('button', 'click')).toBe(true);
+ *   });
+ * });
+ * ```
+ *
+ * Calls `describe`, so it goes at declaration scope. The block is named for the `unit` step — an
+ * island test is `<name>.island.test.ts`, which that step owns.
+ */
+export function describeIslandState(
+  manifest: IslandStatesManifest,
+  id: string,
+  options: IslandStateSuiteOptions,
+  body: (island: () => MountedIsland) => void,
+): void {
+  const { timeoutMs, ...mount } = options;
+  describe(testName('unit', `the ${manifest.name} island, ${id}`), () => {
+    let mounted: MountedIsland | undefined;
+    let over = false;
+    beforeAll(async () => {
+      const island = await mountIslandState(manifest, id, mount);
+      // A mount that outlived its deadline lands after `afterAll` has already run: disposed here,
+      // or its fake `document` is every later block's.
+      if (over) island[Symbol.dispose]();
+      else mounted = island;
+    }, timeoutMs ?? ISLAND_MOUNT_TIMEOUT_MS);
+    // Bun runs `afterAll` whether or not the mount resolved, so this reads what is there.
+    afterAll(() => {
+      over = true;
+      mounted?.[Symbol.dispose]();
+      mounted = undefined;
+    });
+    body(() => {
+      assert(
+        mounted !== undefined,
+        `the ${manifest.name} island's "${id}" state is not mounted — its mount failed, or the accessor was called outside this block's tests`,
+        'call the accessor inside a test of this describeIslandState block; a failed mount is reported above this line, by its own error',
+      );
+      return mounted;
+    });
+  });
+}

package/src/local-tx.ts

@@ -0,0 +1,87 @@
+// A mutator's `local()` half, run in a unit test: a `LocalTx` over rows held in memory, with the
+// semantics of the page's record store. The twin under test is the app's; this is only the store
+// it writes into, so a test asserts on rows and holds no cast and no hand-rolled table.
+
+import type { LocalTable, LocalTx } from '@ultimat3/action';
+
+/** `{ <table>: { <key>: <row> } }` — what the store holds, as a test seeds it and reads it back. */
+export type LocalRows<TRow extends object = object> = Readonly<
+  Record<string, Readonly<Record<string, TRow>>>
+>;
+
+export interface MemoryLocalTx {
+  /** What `mutator.local(tx, input)` is handed. `tx.<table>` and `tx.table('<name>')` are one table. */
+  readonly tx: LocalTx;
+  /** What a table holds now, by key — after however many applications. `{}` for one never seen. */
+  rows<TRow extends object = object>(table: string): Readonly<Record<string, TRow>>;
+}
+
+/** `undefined` in a patch means "leave it alone", exactly as the record store reads it. */
+const definedOf = (columns: object): Record<string, unknown> =>
+  Object.fromEntries(Object.entries(columns).filter(([, value]) => value !== undefined));
+
+/**
+ * A client store for one test. Keyed, exactly like the real one: the browser holds no entity
+ * schema, so a row is addressed by the key its server twin answers under, never by a column.
+ *
+ * | Call | Does |
+ * |---|---|
+ * | `insert(key, row)` | stores the row under the key |
+ * | `upsert(key, row)` | merges over what is held; an `undefined` field leaves the column alone |
+ * | `update(key, patch)` | changed fields, or a function of the held row. A NO-OP for a key the table does not hold — a twin must not invent a row |
+ * | `delete(key)` | removes it |
+ */
+export function memoryLocalTx(seed: LocalRows = {}): MemoryLocalTx {
+  const tables = new Map<string, Map<string, object>>();
+  const held = (name: string): Map<string, object> => {
+    const existing = tables.get(name);
+    if (existing !== undefined) return existing;
+    const created = new Map<string, object>();
+    tables.set(name, created);
+    return created;
+  };
+  // Frozen on the way in, as the record store freezes: a twin that mutated a row in place would
+  // pass here and corrupt the synced truth it was handed in a browser.
+  const stored = (row: object): object => Object.freeze({ ...row });
+  for (const [name, rows] of Object.entries(seed)) {
+    for (const [key, row] of Object.entries(rows)) held(name).set(key, stored(row));
+  }
+
+  // The one widening in this file: the store holds rows of whatever shape a test seeded, and a
+  // table is read back as the shape its caller names — the same door `tx.table<TRow>()` is.
+  const table = <TRow extends object>(name: string): LocalTable<TRow> => {
+    const rows = held(name) as Map<string, TRow>;
+    return {
+      get: (key) => rows.get(key),
+      all: () => [...rows.values()],
+      insert: (key, row) => {
+        rows.set(key, stored(row) as TRow);
+      },
+      upsert: (key, row) => {
+        rows.set(key, stored({ ...rows.get(key), ...definedOf(row) }) as TRow);
+      },
+      update: (key, patch) => {
+        const current = rows.get(key);
+        if (current === undefined) return;
+        const changed = typeof patch === 'function' ? patch(current) : patch;
+        rows.set(key, stored({ ...current, ...definedOf(changed) }) as TRow);
+      },
+      delete: (key) => {
+        rows.delete(key);
+      },
+    };
+  };
+
+  const tx = new Proxy({} as LocalTx, {
+    get: (_target, property) => {
+      if (typeof property !== 'string') return undefined;
+      return property === 'table' ? table : table(property);
+    },
+  });
+
+  return {
+    tx,
+    rows: <TRow extends object = object>(name: string): Readonly<Record<string, TRow>> =>
+      Object.fromEntries(tables.get(name) ?? []) as Record<string, TRow>,
+  };
+}

package/src/matcher-row.ts

@@ -0,0 +1,93 @@
+// Single responsibility: equality over a repository ROW, own properties included. `@ultimat3/entity`
+// answers a `.sealed()` column as a server-only property — own, readable by name, not enumerable —
+// and `toEqual` walks enumerable properties only: `expect(row).toEqual({ …, password })` fails with
+// an EMPTY diff (both sides print alike), and `toEqual(otherRow)` cannot see a wrong secret at all.
+// `toEqualRow` compares what the row HOLDS, and names what differs without printing a secret.
+
+import { describeValue, renderCauseValue } from '@ultimat3/core';
+import type { MatcherResult } from './matcher-result';
+
+const isPlain = (value: unknown): value is Record<string, unknown> => {
+  if (typeof value !== 'object' || value === null) return false;
+  const proto: unknown = Object.getPrototypeOf(value);
+  return proto === Object.prototype || proto === null;
+};
+
+/**
+ * `value` with every own property of every plain object in it made enumerable — the form
+ * `Bun.deepEquals` can compare. A `Date`, a `Map` or a class instance is left as it is: equality
+ * already knows them, and none of them is a row. `seen` maps an object to its copy, so a cycle
+ * comes back as a cycle instead of a stack overflow.
+ */
+const reveal = (value: unknown, seen: Map<object, unknown>): unknown => {
+  if (Array.isArray(value)) {
+    const known = seen.get(value);
+    if (known !== undefined) return known;
+    const out: unknown[] = [];
+    seen.set(value, out);
+    for (const item of value) out.push(reveal(item, seen));
+    return out;
+  }
+  if (!isPlain(value)) return value;
+  const known = seen.get(value);
+  if (known !== undefined) return known;
+  const out: Record<string, unknown> = {};
+  seen.set(value, out);
+  for (const key of Object.getOwnPropertyNames(value)) {
+    // `defineProperty`, never assignment: a key named `__proto__` must stay a key.
+    Object.defineProperty(out, key, {
+      value: reveal(value[key], seen),
+      enumerable: true,
+      writable: true,
+      configurable: true,
+    });
+  }
+  return out;
+};
+
+const same = (received: unknown, expected: unknown): boolean =>
+  Bun.deepEquals(reveal(received, new Map()), reveal(expected, new Map()));
+
+const serverOnly = (row: unknown, key: string): boolean =>
+  isPlain(row) && Object.getOwnPropertyDescriptor(row, key)?.enumerable === false;
+
+/**
+ * One line per top-level property that differs. A server-only property is NAMED and nothing more —
+ * not its value and not its length: the message lands in a CI log, and that property is a secret.
+ */
+const differences = (received: unknown, expected: unknown): readonly string[] => {
+  if (!isPlain(received) || !isPlain(expected)) {
+    return [`received ${describeValue(received)}, expected ${describeValue(expected)}`];
+  }
+  const keys = new Set([
+    ...Object.getOwnPropertyNames(received),
+    ...Object.getOwnPropertyNames(expected),
+  ]);
+  const lines: string[] = [];
+  for (const key of keys) {
+    if (same(received[key], expected[key])) continue;
+    if (!serverOnly(received, key) && !serverOnly(expected, key)) {
+      lines.push(
+        `${key}: received ${renderCauseValue(received[key])}, expected ${renderCauseValue(expected[key])}`,
+      );
+    } else if (!Object.hasOwn(expected, key)) {
+      lines.push(`${key} (server-only): the row holds one and the expected value names none`);
+    } else if (!Object.hasOwn(received, key)) {
+      lines.push(`${key} (server-only): the expected value holds one and the row has none`);
+    } else {
+      lines.push(`${key} (server-only): differs — a server-only value is never printed`);
+    }
+  }
+  return lines;
+};
+
+export function rowEquality(received: unknown, expected: unknown): MatcherResult {
+  const pass = same(received, expected);
+  return {
+    pass,
+    message: () =>
+      pass
+        ? 'expected the row not to equal the given one, own non-enumerable properties included'
+        : `expected the row to equal the given one, own non-enumerable properties included — ${differences(received, expected).join('; ')}`,
+  };
+}

package/src/matcher-surface.ts

@@ -24,6 +24,13 @@ export interface UltimateMatchers<T> {
   toBeWithinBudget(limit: number): T;
   toRejectInput(input: unknown): Promise<T>;
   toAcceptInput(input: unknown): Promise<T>;
+  /**
+   * `toEqual` for a repository ROW. A `.sealed()` column is an own property a row does not
+   * ENUMERATE, so `toEqual({ …, password })` fails with an empty diff and `toEqual(otherRow)`
+   * cannot see a wrong secret. This compares every own property, and its message names what
+   * differs — a server-only property by shape, never by value.
+   */
+  toEqualRow(expected: unknown): T;
   /**
    * The one matcher that WAITS. Retries `isVisible()` to a budget — 5000ms every 100ms unless
    * narrowed — and `.not.toBeVisible()` waits for the element to GO rather than inverting one look.

package/src/matchers.ts

@@ -12,6 +12,7 @@ import {
   TestPolicyExpectedError,
 } from './matcher-receiver-errors';
 import type { MatcherResult } from './matcher-result';
+import { rowEquality } from './matcher-row';
 import type { UltimateMatchers } from './matcher-surface';
 import type { VisibleOptions } from './matcher-visible';
 import { assertVisibilityProbe, visibilityResult } from './matcher-visible';
@@ -296,6 +297,11 @@ const implementations: ExpectExtendMatchers<UltimateMatchers<unknown>> = {
     );
   },
 
+  // Any receiver is comparable, so there is nothing to refuse: a non-row simply is not equal.
+  toEqualRow(received: unknown, expected: unknown) {
+    return rowEquality(received, expected);
+  },
+
   toAcceptInput(received: unknown, input: unknown) {
     const schema = assertStandardSchema(received);
     return hasIssues(schema, input).then((rejected) =>

package/src/per-test-reset.ts

@@ -0,0 +1,43 @@
+// What every test starts from, put back by the preload before each one — the per-TEST half of
+// isolation, beside `file-boundary.ts`'s per-file half. Today one thing: the jobs event bus, which
+// STORES what it is handed, so an answer one test published resumed the next test's waiting run.
+
+import { beforeEach } from 'bun:test';
+import type { resetEventBus } from '@ultimat3/jobs';
+
+let installed = false;
+
+/**
+ * The module that holds the ambient bus, when something in this process has loaded it — and only
+ * then. A test that never touched `@ultimat3/jobs` has no bus to reset, and loading the package to
+ * reset one would put the jobs graph into every `packages/core` test.
+ */
+function loadedEventsModule(): string | undefined {
+  // Resolved once per process: every test asks, and the answer is a path that does not move.
+  eventsPath ??= Bun.resolveSync('@ultimat3/jobs', import.meta.dir).replace(
+    /index\.ts$/,
+    'events.ts',
+  );
+  return eventsPath in require.cache ? eventsPath : undefined;
+}
+
+let eventsPath: string | undefined;
+
+/** Before each test: a fresh ambient event bus, when the jobs package is loaded at all. */
+export async function resetPerTestState(): Promise<void> {
+  const events = loadedEventsModule();
+  if (events === undefined) return;
+  // Already evaluated — this import answers from the module registry, the same instance.
+  const loaded = (await import(events)) as { readonly resetEventBus: typeof resetEventBus };
+  loaded.resetEventBus();
+}
+
+/**
+ * Called by the app preload (`./preload`), once per process. In a preload, `beforeEach` runs
+ * before every test of every file; idempotent so a second caller cannot register it twice.
+ */
+export function installPerTestReset(): void {
+  if (installed) return;
+  installed = true;
+  beforeEach(resetPerTestState);
+}

package/src/preload.ts

@@ -5,6 +5,8 @@
 //   [test]
 //   preload = ["@ultimat3/testing/preload"]
 
+// A green run prints the reporter and nothing else: the process logger's lines go to a sink.
+import './quiet-logs';
 import { installDeterminism } from './determinism';
 import { registerFrameworkFixtures } from './framework-fixtures';
 import './matchers';
@@ -12,8 +14,15 @@ import { installAppJsxLoader } from './app-jsx-loader';
 import { onFileBoundary } from './file-boundary';
 import { disposeLiveIslands } from './fixture-island';
 import { releasePluginsAfterIsolatedFile } from './isolated-plugins';
+import { installPerTestReset } from './per-test-reset';
 import { installRegistryLeakGuard } from './registry-leak-guard';
 import { sealNetwork } from './sealed-network';
+import { installTestSealKey } from './test-seal-key';
+
+// `.secrets.key` is gitignored and CI names no `ULTIMATE_SECRETS_KEY`: without a key every test
+// over a `.sealed()` column is `X_SEAL_KEY_MISSING` on a fresh clone. A throwaway one, only in a
+// test process (`NODE_ENV=test`) and only when the app supplied none — see the file.
+installTestSealKey();
 
 const seed = Number.parseInt(Bun.env['ULTIMATE_TEST_SEED'] ?? '', 10);
 const now = Bun.env['ULTIMATE_TEST_NOW'];
@@ -40,6 +49,10 @@ installRegistryLeakGuard();
 // back to what the first file saw.
 onFileBoundary(disposeLiveIslands);
 
+// And per TEST: the jobs event bus stores what it is handed, so one test's published answer
+// resumed the next test's waiting run (`per-test-reset.ts`).
+installPerTestReset();
+
 // A shared worker only (an isolated file is a fresh registry anyway): the app's
 // `defineApi({ pathStyle })` evaluates once per worker, in whichever file first imports it, and
 // must not be refused because an EARLIER file derived action paths under the default style.

package/src/quiet-logs.ts

@@ -0,0 +1,56 @@
+// Single responsibility: where the process logger's lines go under `bun test`. Both preloads
+// import this FIRST, before anything that loads `@ultimat3/core`.
+//
+//   LOG_LEVEL unset            a green run prints the reporter and nothing else: every line is dropped
+//   LOG_LEVEL=info (or lower)  the escape hatch — `LOG_LEVEL=info bun test <file>` prints them
+//   LOG_LEVEL=warn (or higher) the terminal shows that level and above
+//
+// The third row is a FILTER ON THE TERMINAL, never the logger's own threshold. Core reads
+// `LOG_LEVEL` once, when it is first imported, so `LOG_LEVEL=error bun test` used to raise the
+// process logger itself to `error` — and a test that installs a sink to assert on an `info` audit
+// line collected nothing and failed for an environment variable. The level is therefore pinned at
+// `info` for the one moment core loads, and what the author named decides what is PRINTED.
+//
+// A test that asserts on log output hands `createLogger({ level, writer })` its own writer, or
+// installs its own `setLogSink` and restores the previous one. Never `process.stdout`.
+
+import type { LogLevel } from '@ultimat3/core';
+
+/** The levels above `info`, least severe first: the ones a named `LOG_LEVEL` must not cost a sink. */
+const ABOVE_INFO = ['warn', 'error', 'fatal', 'silent'] as const satisfies readonly LogLevel[];
+
+export type LogRouting =
+  | { readonly lines: 'dropped' }
+  | { readonly lines: 'printed' }
+  | { readonly lines: 'filtered'; readonly from: (typeof ABOVE_INFO)[number] };
+
+/**
+ * What a named `LOG_LEVEL` means for a test process. `info` and below are core's own to print, at
+ * the level named — asking for `debug` is asking for more lines, and a collecting sink is handed
+ * them too. Anything core would not read as a level is `info` there, so it is `printed` here.
+ */
+export function logRouting(named: string | undefined): LogRouting {
+  if (named === undefined || named === '') return { lines: 'dropped' };
+  const from = ABOVE_INFO.find((level) => level === named);
+  return from === undefined ? { lines: 'printed' } : { lines: 'filtered', from };
+}
+
+const named = Bun.env['LOG_LEVEL'];
+const routing = logRouting(named);
+
+// Core's `logger` is built at module init from this variable, so the pin goes in before the
+// import and the author's value goes back after it: a child this process spawns inherits what
+// was named, never the pin. A dynamic import, because a static one is hoisted above this line.
+if (routing.lines === 'filtered') Bun.env['LOG_LEVEL'] = 'info';
+const { setLogSink } = await import('@ultimat3/core');
+
+if (routing.lines === 'dropped') {
+  setLogSink(() => undefined);
+} else if (routing.lines === 'filtered') {
+  Bun.env['LOG_LEVEL'] = routing.from;
+  const shown = new Set<LogLevel>(ABOVE_INFO.slice(ABOVE_INFO.indexOf(routing.from)));
+  // Core's own split: `error` and above to stderr, the rest to stdout.
+  setLogSink((line, level) => {
+    if (shown.has(level)) (level === 'warn' ? process.stdout : process.stderr).write(`${line}\n`);
+  });
+}

package/src/render-view.ts

@@ -0,0 +1,118 @@
+// What the server renders, for a unit test: `renderView` for one component, `renderRoute` for a
+// whole route module — its `load`, its `meta` and its page, resolved the way a request resolves
+// them. No browser, no server, no cast: a test asserts on markup and on visible text.
+
+import type { Actor } from '@ultimat3/core';
+import { assert, createContext, runWithContext } from '@ultimat3/core';
+import type { IslandDirective, RouteConfig, RouteParams } from '@ultimat3/render';
+
+/** What a component rendered. */
+export interface RenderedView {
+  /** The markup, exactly as the document would carry it. */
+  readonly html: string;
+  /**
+   * What a reader sees: tags, scripts and styles removed, entities decoded, whitespace collapsed
+   * to single spaces. Compare it with `t('<key>')` — the markup escapes what the catalog does not.
+   */
+  readonly text: string;
+}
+
+/** What a route rendered for one request. */
+export interface RenderedRoute<TData> extends RenderedView {
+  /** What `load` resolved — the one object `meta` and the page were both given. */
+  readonly data: TData;
+  readonly meta: Awaited<ReturnType<RouteConfig<TData>['meta']>>;
+  /** The islands this render emitted, in order. Empty on a page that ships no JavaScript. */
+  readonly islands: readonly IslandDirective[];
+}
+
+/**
+ * A route file's exports, passed whole: `import * as page from './page'`. Only `config` is typed —
+ * the page component is found among the rest by the rule the router finds it by.
+ */
+export interface RouteModule<TData> {
+  readonly config: RouteConfig<TData>;
+  /** Everything else the file exports — the page among it. Open, so a literal module typechecks. */
+  readonly [exported: string]: unknown;
+}
+
+export interface RouteRequest {
+  /** Absolute, as a request's is. Its search string becomes the page's `query`. */
+  readonly url?: string;
+  readonly params?: RouteParams;
+  /** Who is asking. `load` and the page run inside a request context holding this actor. */
+  readonly actor?: Actor;
+}
+
+const DEFAULT_URL = 'http://localhost/';
+
+const SCRIPT_OR_STYLE = /<(script|style)\b[^>]*>[\s\S]*?<\/\1>/g;
+
+/**
+ * `&amp;` last: decoding it first would turn the text `&amp;lt;` — an author's literal `&lt;` —
+ * into `<`, a character the page never showed.
+ */
+const visibleText = (html: string): string =>
+  html
+    .replace(SCRIPT_OR_STYLE, ' ')
+    .replace(/<[^>]*>/g, ' ')
+    .replaceAll('&lt;', '<')
+    .replaceAll('&gt;', '>')
+    .replaceAll('&amp;', '&')
+    .replace(/\s+/g, ' ')
+    .trim();
+
+const viewOf = (html: string): RenderedView => ({ html, text: visibleText(html) });
+
+/**
+ * Render one component with the props a page would hand it. The props are the component's own
+ * type, so a renamed prop is a compile error in the test rather than an `undefined` in the markup.
+ *
+ * No island collector: a component that renders an `island()` belongs to a route, which is where
+ * its hydration timing comes from — render it through `renderRoute`.
+ */
+export async function renderView<Props>(
+  component: (props: Props) => unknown,
+  props: Props,
+): Promise<RenderedView> {
+  const { renderToHtml } = await import('@ultimat3/render/server');
+  return viewOf(await renderToHtml(component(props)));
+}
+
+/**
+ * Render a route module the way a request does: `load` once, `meta` and the page on that same
+ * data, islands collected under the route's own `hydrate`. Pass the module whole —
+ * `import * as page from './page'` — so the page is found by the rule the router finds it by.
+ */
+export async function renderRoute<TData>(
+  module: RouteModule<TData>,
+  request: RouteRequest = {},
+): Promise<RenderedRoute<TData>> {
+  const render = await import('@ultimat3/render');
+  const { renderToHtml } = await import('@ultimat3/render/server');
+  const { config } = module;
+  // A copy typed by its own shape: the page is one of the exports `RouteModule` does not name.
+  const exported: Readonly<Record<string, unknown>> = { ...module };
+  const component = render.pageComponentOf(exported);
+  assert(
+    component !== undefined,
+    'renderRoute was handed a route module that exports no page component',
+    "export the page beside `config` — `export function Page()` — and pass the module whole: import * as page from './page'",
+  );
+  const url = request.url ?? DEFAULT_URL;
+  const ctx = { params: request.params ?? {}, url };
+  const islands = render.createIslandCollector({ file: url, hydrate: config.hydrate });
+
+  const run = async (): Promise<RenderedRoute<TData>> => {
+    const data = await render.routeDataFor(config, ctx);
+    const meta = await config.meta(render.metaContextFor(ctx, data));
+    const query = Object.fromEntries(new URL(url).searchParams);
+    const html = await renderToHtml(component({ data, params: ctx.params, url, query }), {
+      islands,
+    });
+    return { ...viewOf(html), data, meta, islands: islands.directives };
+  };
+
+  if (request.actor === undefined) return run();
+  return runWithContext(createContext({ actor: request.actor }), run);
+}

package/src/test-seal-key.ts

@@ -0,0 +1,51 @@
+// Single responsibility: the master key a TEST process seals under when the app handed it none.
+// `.secrets.key` is gitignored and CI has no `ULTIMATE_SECRETS_KEY`, so without this every test
+// over an entity with a `.sealed()` column is `X_SEAL_KEY_MISSING` on a fresh clone. The preload
+// is the one caller; the key itself is not exported, from this module or from the package.
+
+import { findMasterKey, SECRETS_KEY_ENV } from '@ultimat3/core';
+
+/**
+ * Public by construction — it is in the package on npm — so it protects nothing and must never
+ * seal a real row. 64 hex characters, which is all `parseMasterKey` asks of a key.
+ */
+const TEST_SEAL_KEY = '7e57'.repeat(16);
+
+type EnvRecord = Record<string, string | undefined>;
+
+export interface TestSealKeySource {
+  /** The app root a `.secrets.key` would sit in. Defaults to the working directory. */
+  readonly root?: string;
+  /** Read for the mode and the key, and written to. Defaults to `process.env`. */
+  readonly env?: EnvRecord;
+}
+
+/**
+ * Installs the throwaway key, and answers whether it did. Two refusals, both silent because both
+ * are the correct outcome rather than a mistake to report:
+ *
+ * - **Not a test process.** `bun test` sets `NODE_ENV=test`; anything else — a server that
+ *   imported the preload, `NODE_ENV=production` — gets no key, so a sealed write there is still
+ *   `X_SEAL_KEY_MISSING` and never a row sealed under a key the whole world holds.
+ * - **A key is already there**, in the variable or in `.secrets.key`. The app's own key wins: a
+ *   suite that reads the committed `secrets.enc.json` needs the key that sealed it.
+ */
+export function installTestSealKey(source: TestSealKeySource = {}): boolean {
+  const env = source.env ?? (process.env as EnvRecord);
+  const added = testSealKeyEnv({ ...source, env });
+  Object.assign(env, added);
+  return SECRETS_KEY_ENV in added;
+}
+
+/**
+ * The same decision as a value: the variable to ADD to a child's environment, or nothing. For a
+ * harness that spawns the app under test (`startE2eApp`) — the child is a server, not a `bun test`
+ * process, so it can never install a key for itself, and it must not be able to. The rule is still
+ * judged in THIS process: only a test process hands the key down.
+ */
+export function testSealKeyEnv(source: TestSealKeySource = {}): Readonly<Record<string, string>> {
+  const env = source.env ?? (process.env as EnvRecord);
+  if (env['NODE_ENV'] !== 'test') return {};
+  if (findMasterKey(source.root ?? process.cwd(), env) !== undefined) return {};
+  return { [SECRETS_KEY_ENV]: TEST_SEAL_KEY };
+}