@ultimat3/render 1.2.0 → 2.0.0

package/src/island-props.ts

@@ -0,0 +1,144 @@
+/**
+ * What an island may close over: nothing but declared, JSON-safe, budgeted props.
+ * An island is named by specifier, so it cannot capture a scope — the only way the server
+ * reaches the browser is this bag, and every rule here is about what must not travel.
+ */
+
+import { IslandPropsInvalidError } from './errors';
+import type { JsxProps } from './jsx';
+
+export type JsonValue =
+  | string
+  | number
+  | boolean
+  | null
+  | readonly JsonValue[]
+  | { readonly [key: string]: JsonValue };
+
+export type IslandProps = Readonly<Record<string, JsonValue>>;
+
+/**
+ * Props ship inside the HTML of every response, so they are page weight the `budget` never sees
+ * as JS. A cap turns "I passed the whole row" into a number and a fix instead of a slow page.
+ */
+export const ISLAND_PROPS_MAX_BYTES = 4096;
+
+/** JSX keys that are markup, not data: they stay on the server and never serialize. */
+const SERVER_ONLY_KEYS = new Set(['children']);
+
+/**
+ * Names the value the way an author can act on it. `[object Object]` is not an instruction;
+ * "a Date at props.at" is.
+ */
+function describeValue(value: unknown): string {
+  if (value === undefined) return 'undefined';
+  if (typeof value === 'function') return 'a function';
+  if (typeof value === 'bigint') return 'a bigint';
+  if (typeof value === 'symbol') return 'a symbol';
+  if (value instanceof Date) return 'a Date';
+  if (value instanceof Map || value instanceof Set) return `a ${value.constructor.name}`;
+  if (typeof value === 'number' && !Number.isFinite(value)) return String(value);
+  if (typeof value === 'object' && value !== null) {
+    const proto: unknown = Object.getPrototypeOf(value);
+    if (proto !== Object.prototype && proto !== null) {
+      return `an instance of ${(value as { constructor?: { name?: string } }).constructor?.name ?? 'a class'}`;
+    }
+  }
+  return `a ${typeof value}`;
+}
+
+/**
+ * A structural walk rather than a `JSON.stringify` round-trip: stringify drops a function and a
+ * `undefined` silently, which is the exact footgun — the prop the author meant to pass arrives
+ * missing in the browser and the island renders an empty state nobody can reproduce on the server.
+ */
+function assertJsonSafe(value: unknown, path: string, seen: Set<object>, file: string): JsonValue {
+  if (value === null) return null;
+  if (typeof value === 'string' || typeof value === 'boolean') return value;
+  if (typeof value === 'number' && Number.isFinite(value)) return value;
+
+  if (Array.isArray(value)) {
+    guardCycle(value, path, seen, file);
+    const out = value.map((item, index) => assertJsonSafe(item, `${path}[${index}]`, seen, file));
+    seen.delete(value);
+    return out;
+  }
+
+  if (isPlainObject(value)) {
+    guardCycle(value, path, seen, file);
+    const out: Record<string, JsonValue> = {};
+    for (const [key, item] of Object.entries(value)) {
+      out[key] = assertJsonSafe(item, `${path}.${key}`, seen, file);
+    }
+    seen.delete(value);
+    return out;
+  }
+
+  throw new IslandPropsInvalidError(
+    `${path} is ${describeValue(value)}, which cannot cross the server/client boundary — ` +
+      'an island receives JSON and nothing else',
+    `pass a plain JSON value at ${path} in ${file} (an id, not the row; a string, not a Date), ` +
+      'or fetch it inside the island',
+  );
+}
+
+function isPlainObject(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;
+}
+
+function guardCycle(value: object, path: string, seen: Set<object>, file: string): void {
+  if (!seen.has(value)) {
+    seen.add(value);
+    return;
+  }
+  throw new IslandPropsInvalidError(
+    `${path} closes a cycle, so it can never be serialized for the browser`,
+    `break the cycle at ${path} in ${file} — pass ids instead of linked objects`,
+  );
+}
+
+/**
+ * The one gate between a page's scope and an island's props. Undeclared keys are refused by
+ * name because `<Modal {…row} />` is how a password hash reaches the browser, and the error that
+ * lists the columns is the one that stops it.
+ */
+export function checkIslandProps(
+  props: JsxProps,
+  declared: readonly string[],
+  file: string,
+  moduleId: string,
+): IslandProps {
+  const allowed = new Set(declared);
+  const passed = Object.keys(props).filter((key) => !SERVER_ONLY_KEYS.has(key));
+  const undeclared = passed.filter((key) => !allowed.has(key));
+
+  if (undeclared.length > 0) {
+    throw new IslandPropsInvalidError(
+      `${file} passes ${undeclared.map((key) => `\`${key}\``).join(', ')} to the ${moduleId} ` +
+        `island, which declares ${declared.length === 0 ? 'no props' : declared.join(', ')} — ` +
+        'an island receives exactly what it declared, so a spread row cannot leak a column',
+      `add ${undeclared.map((key) => `'${key}'`).join(', ')} to props: [] on the island() call, ` +
+        `or stop passing ${undeclared.length === 1 ? 'it' : 'them'} in ${file}`,
+    );
+  }
+
+  const bag: Record<string, JsonValue> = {};
+  const seen = new Set<object>();
+  for (const key of passed) {
+    bag[key] = assertJsonSafe(props[key], `props.${key}`, seen, file);
+  }
+
+  const bytes = new TextEncoder().encode(JSON.stringify(bag)).byteLength;
+  if (bytes > ISLAND_PROPS_MAX_BYTES) {
+    throw new IslandPropsInvalidError(
+      `the ${moduleId} island in ${file} carries ${bytes} bytes of props (cap ` +
+        `${ISLAND_PROPS_MAX_BYTES}), and every one of them ships inside the HTML on every request`,
+      `pass an id in ${file} and fetch the rest inside the island, or raise the cap deliberately ` +
+        'by splitting the island',
+    );
+  }
+
+  return bag;
+}

package/src/island.ts

@@ -0,0 +1,218 @@
+/**
+ * The island: one interactive component on an otherwise static page.
+ *
+ * Declared by module SPECIFIER, never by import — a string cannot close over a database handle,
+ * and there is no import edge for a bundler to follow, so a static page's graph stays the page's
+ * graph (axiom 6). WHEN it wakes is the route's `hydrate`, never a second declaration here.
+ */
+
+import { IslandInvalidError } from './errors';
+import type { JsonValue } from './island-props';
+import type { JsxProps } from './jsx';
+
+/**
+ * One spelling, like `page.tsx` and `route.ts`: a file is a client entry if and only if its name
+ * says so. That is what makes "what ships JS?" answerable by `grep` and by the bundler, without
+ * opening a file or following an import.
+ */
+export const ISLAND_EXTENSION = '.island.tsx';
+
+/** Registered globally so two copies of this module agree on what an island node is. */
+export const ISLAND_NODE: unique symbol = Symbol.for('ultimate.render.island') as never;
+
+/** Characters that would break out of the `data-x-entry` attribute the specifier lands in. */
+const UNSAFE_SPECIFIER = /["'`<>\s\\]/;
+
+/** The same test the resolver's output has to pass: one rule, applied at both ends of the seam. */
+export function isEmittableSpecifier(value: string): boolean {
+  return value.length > 0 && !UNSAFE_SPECIFIER.test(value);
+}
+
+export interface IslandDeclaration<TKeys extends readonly string[] = readonly string[]> {
+  /** Relative specifier of the client entry, e.g. `./contact-modal.island.tsx`. */
+  readonly src: string;
+  /** The exact prop names this island accepts. Anything else is a build failure. */
+  readonly props?: TKeys;
+  /** The wrapper element. `span` for an island inside a line of text. */
+  readonly tag?: string;
+  /** Events replayed for `hydrate: 'interaction'`. */
+  readonly events?: readonly string[];
+  /** `rootMargin` for `hydrate: 'visible'`. */
+  readonly rootMargin?: string;
+}
+
+/** The normalized declaration. `island()` is the one normalizer, as `defineRoute` is for routes. */
+export interface IslandSpec {
+  /** Stable, derived from `src`: the unit a bundle is measured in and a budget counts. */
+  readonly moduleId: string;
+  readonly src: string;
+  readonly propKeys: readonly string[];
+  readonly tag: string;
+  readonly events?: readonly string[];
+  readonly rootMargin?: string;
+}
+
+/**
+ * An island node is a branded ARRAY, and that is not decoration.
+ *
+ * An app types its JSX with `jsxImportSource: solid-js`, whose `JSX.Element` is a type ALIAS —
+ * `Node | ArrayElement | (string & {}) | number | boolean | null | undefined` — so it can neither
+ * be augmented nor satisfied by a plain object. A component returning one is TS2786 at every
+ * `<ContactSales />`, which is how a feature whose whole point is "a contact modal on an otherwise
+ * static page" shipped usable only through `h(Modal, …)`. `ArrayElement` is the union's one
+ * object-shaped member, so being an array is what makes the island an ordinary JSX child.
+ *
+ * The array is empty and stays empty — the shell is `props.children`, walked by `render-html.ts`,
+ * and `never[]` is the honest element type for an array nothing is ever pushed into. It also keeps
+ * render free of `solid-js`: the constraint is satisfied structurally, not by importing the union.
+ * `type-pins.tsx` is what holds the claim to a build error.
+ */
+export interface IslandNode extends Array<never> {
+  readonly [ISLAND_NODE]: true;
+  readonly spec: IslandSpec;
+  readonly props: JsxProps;
+}
+
+/**
+ * Tested BEFORE `Array.isArray` by every walker, since an island node is now both. `render-html.ts`
+ * is the one that matters: the array branch would render an empty shell and drop the island.
+ */
+export function isIslandNode(value: unknown): value is IslandNode {
+  return typeof value === 'object' && value !== null && ISLAND_NODE in value;
+}
+
+/** Declared props are JSON, plus the server-only children that become the island's shell. */
+export type IslandComponent<TKeys extends readonly string[]> = (
+  props: Readonly<Record<TKeys[number], JsonValue>> & { readonly children?: unknown },
+) => IslandNode;
+
+/**
+ * `./contact-modal.island.tsx` → `contact-modal`; `../shared/search.island.tsx` → `shared-search`.
+ * Derived from the path rather than hashed so the id in the HTML, the budget report and the
+ * manifest is the one an author can find on disk.
+ */
+export function islandModuleId(src: string): string {
+  return src
+    .slice(0, -ISLAND_EXTENSION.length)
+    .replace(/^(?:\.\.?\/)+/, '')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+}
+
+/**
+ * Islands declared since the last `defineRoute` drained this list — the seam that lets a page
+ * declaring an island hydrate without saying so twice.
+ *
+ * Ambient, and deliberately not the thing `island-collector.ts` refuses to be: that one is about
+ * a RENDER, where two concurrent requests would bill one page for the other's JS. This one is
+ * about a MODULE, evaluated once, on one thread, before any request exists — and `src` is resolved
+ * relative to the route file (`island-bundle.ts`), so an `island()` call is a route-module-local
+ * declaration by construction. `defineRoute` empties it, so nothing accumulates.
+ */
+const declaredIslands: IslandSpec[] = [];
+
+/**
+ * Called by `defineRoute` alone. Returns what this module declared and resets the list.
+ *
+ * Package-internal on purpose — reachable from `./island`, absent from `src/index.ts`. An app that
+ * could call this between its `island()` and its `defineRoute` would silently drain the
+ * declarations the route derives `hydrate`, `budget.js` and `entry.islands` from, and get a page
+ * that renders an island nothing boots. Machinery is not API, and a public export is semver-locked
+ * the moment it ships.
+ */
+export function drainDeclaredIslands(): readonly IslandSpec[] {
+  if (declaredIslands.length === 0) return [];
+  const drained = [...declaredIslands];
+  declaredIslands.length = 0;
+  return drained;
+}
+
+/**
+ * Whether this exact spec is still waiting to be drained — which is decidable, and is the whole
+ * difference between the two causes of `X_ISLAND_NOT_HYDRATED`. A spec still pending at RENDER
+ * time was declared where no `defineRoute` could see it (below the route, or outside a route
+ * module); a spec already drained means the route reached `'never'` because an author wrote it.
+ *
+ * Identity, not equality: `island()` pushes the object it closes over, so the spec reaching the
+ * collector is the same one, and two islands with identical fields never collide.
+ */
+export function islandNeverDrained(spec: IslandSpec): boolean {
+  return declaredIslands.includes(spec);
+}
+
+/** Test seam: the list is process-global because the module cache it mirrors is too. */
+export function clearDeclaredIslands(): void {
+  declaredIslands.length = 0;
+}
+
+/**
+ * Declare an island. Runs at the page module's scope, so a bad declaration fails when the route
+ * is loaded — at build time for `static`, and before the first request for every other mode.
+ *
+ * Declare it ABOVE `defineRoute`, which is where JavaScript already puts a `const` a page uses:
+ * that is what lets the route derive `hydrate` and its JS budget instead of asking for both. An
+ * island declared below the route still renders — and still fails loudly, as
+ * `X_ISLAND_NOT_HYDRATED`, rather than shipping markup nothing boots.
+ */
+export function island<const TKeys extends readonly string[] = []>(
+  declaration: IslandDeclaration<TKeys>,
+): IslandComponent<TKeys> {
+  const spec = normalizeIsland(declaration);
+  declaredIslands.push(spec);
+  return (props) => islandNode(spec, props as JsxProps);
+}
+
+/** The one constructor. `Object.assign` over an array is what gives the node both identities. */
+function islandNode(spec: IslandSpec, props: JsxProps): IslandNode {
+  return Object.assign([] as never[], { [ISLAND_NODE]: true as const, spec, props });
+}
+
+function normalizeIsland(declaration: IslandDeclaration): IslandSpec {
+  const src = declaration.src;
+  if (typeof src !== 'string' || src.length === 0) {
+    throw new IslandInvalidError(
+      'island() was given no src, so there is no module for the browser to import',
+      `pass src: './<name>${ISLAND_EXTENSION}' — the client entry, as a specifier, never an import`,
+    );
+  }
+  if (src.includes('://')) {
+    throw new IslandInvalidError(
+      `island src ${JSON.stringify(src)} is a remote URL, so it is outside the bundle graph and ` +
+        'outside the route budget that has to count it',
+      `vendor the module into the app and pass src: './<name>${ISLAND_EXTENSION}'`,
+    );
+  }
+  if (UNSAFE_SPECIFIER.test(src)) {
+    throw new IslandInvalidError(
+      `island src ${JSON.stringify(src)} contains a character that cannot appear in the ` +
+        'data-x-entry attribute it is emitted into',
+      `rename the module to a plain path and pass src: './<name>${ISLAND_EXTENSION}'`,
+    );
+  }
+  if (!src.endsWith(ISLAND_EXTENSION)) {
+    const stem = src.replace(/\.[jt]sx?$/, '');
+    throw new IslandInvalidError(
+      `island src ${JSON.stringify(src)} is not an island file: a module ships to the browser ` +
+        `only if its name says so, and ${ISLAND_EXTENSION} is the one spelling that says it`,
+      `git mv -- ${src} ${stem}${ISLAND_EXTENSION}, then pass src: '${stem}${ISLAND_EXTENSION}'`,
+    );
+  }
+
+  const moduleId = islandModuleId(src);
+  if (moduleId.length === 0) {
+    throw new IslandInvalidError(
+      `island src ${JSON.stringify(src)} has no name left once ${ISLAND_EXTENSION} is removed`,
+      `name the module: src: './<name>${ISLAND_EXTENSION}'`,
+    );
+  }
+
+  return {
+    moduleId,
+    src,
+    propKeys: declaration.props ?? [],
+    tag: declaration.tag ?? 'div',
+    ...(declaration.events === undefined ? {} : { events: declaration.events }),
+    ...(declaration.rootMargin === undefined ? {} : { rootMargin: declaration.rootMargin }),
+  };
+}

package/src/islands.ts

@@ -74,7 +74,14 @@ export function routeJsBytes(
   directives: readonly IslandDirective[] = [],
 ): RouteBytes {
   const graph = graphFor(entry.surface, islands);
-  const onRoute = graph.islands.filter((island) => entry.islands.includes(island.id));
+  // Two sources, unioned: `entry.islands` is what registration declared, and the directives are
+  // what the page actually rendered. Reading only the first is how the runtime bytes of an island
+  // could be charged while its chunk was not — a budget that counts the wrapper and not the code.
+  const onRoute = graph.islands.filter(
+    (island) =>
+      entry.islands.includes(island.id) ||
+      directives.some((directive) => (directive.moduleId ?? directive.islandId) === island.id),
+  );
   const islandBytes = onRoute.reduce((sum, island) => sum + island.bytes, 0);
   const runtimeBytes = directives.length > 0 ? hydrateRuntimeBytes(directives) : 0;
   const baseline = islandBytes === 0 && runtimeBytes === 0 ? 0 : graph.baselineBytes;

package/src/jsx.ts

@@ -0,0 +1,46 @@
+/**
+ * The server JSX factory. `h` builds an inert node — no DOM, no reactivity, no `solid-js` — so a
+ * page component stays a pure function from props to a tree, and `render-html.ts` is the only
+ * thing that decides what a tree means. This is what the `.tsx` loader compiles every element to.
+ */
+
+/** Registered on the global symbol registry: two copies of this module must agree on a node. */
+export const JSX_NODE: unique symbol = Symbol.for('ultimate.render.jsx') as never;
+
+export type JsxProps = Readonly<Record<string, unknown>>;
+
+/** A component is any function of props. Async is allowed: `render-html.ts` awaits it. */
+export type JsxComponent = (props: JsxProps) => unknown;
+
+export interface JsxNode {
+  readonly [JSX_NODE]: true;
+  /** A lowercase string is an element; a function is a component. */
+  readonly type: string | JsxComponent;
+  readonly props: JsxProps;
+}
+
+export function isJsxNode(value: unknown): value is JsxNode {
+  return typeof value === 'object' && value !== null && JSX_NODE in value;
+}
+
+/**
+ * Children live in `props.children`, the shape Solid and every JSX author already writes — so a
+ * component reading `props.children` behaves the same whether its children came from the classic
+ * factory's rest arguments or from an explicit `children` prop.
+ */
+export function h(
+  type: string | JsxComponent,
+  props: JsxProps | null,
+  ...children: readonly unknown[]
+): JsxNode {
+  const base = props ?? {};
+  if (children.length === 0) return { [JSX_NODE]: true, type, props: base };
+  return {
+    [JSX_NODE]: true,
+    type,
+    props: { ...base, children: children.length === 1 ? children[0] : children },
+  };
+}
+
+/** `<>…</>`. A fragment is its children and nothing else — no wrapper element in the output. */
+export const Fragment: JsxComponent = (props) => (props as { children?: unknown }).children;

package/src/modes.ts

@@ -14,10 +14,15 @@ import { SURFACE_SPECS, surfaceAllows } from './surfaces';
 export const RENDER_MODES = ['static', 'isr', 'ssr', 'stream', 'spa'] as const;
 
 /**
- * Everything about a route except its `meta`. Mode invariants never read metadata, and
- * omitting it keeps these checks free of the route's data generic.
+ * Everything about a route except the two keys carrying its data generic. Mode invariants never
+ * read metadata and never load anything, and omitting both keeps these checks free of `TData`.
+ *
+ * Not a convenience — a requirement. Both are function-typed *properties*, so they are checked
+ * contravariantly: keeping either here makes `RouteConfig<TData>` unassignable to `RouteShape`
+ * for every `TData` other than the default, and `assertModeShape(config)` stops compiling inside
+ * `defineRoute` itself. Same variance trap that `Invariant.holds` hit in `@ultimat3/entity`.
  */
-export type RouteShape = Omit<RouteConfig, 'meta'>;
+export type RouteShape = Omit<RouteConfig, 'meta' | 'load'>;
 
 export interface ModeSpec {
   readonly mode: RenderMode;
@@ -206,3 +211,23 @@ export function assertModeInvariants(config: RouteShape, ctx: ModeCheckContext):
 export function defaultHydrate(surface: Surface): HydrateStrategy {
   return surface === 'site' ? 'never' : 'idle';
 }
+
+/**
+ * What an island route may spend ABOVE its surface's baseline when it declares no `budget.js`.
+ *
+ * A number, not "unlimited", because the guard means nothing otherwise — and 4kb because that is
+ * roughly twice what the reference app's real island costs (875 B of chunk plus a 1,019 B runtime),
+ * which is enough for a second small island and not enough to hide a library. A declared
+ * `budget.js` still wins, and exceeding this one still fails with the island named.
+ */
+export const DEFAULT_ISLAND_JS_BYTES = 4096;
+
+/**
+ * The derived ceiling for a route whose hydration came from an island. Relative to the surface
+ * baseline, never absolute: `site/` starts at 0kb and `app/` at 14kb, so one number would be
+ * either a ceiling `app/` fails on arrival or one `site/` can never reach.
+ */
+export function defaultIslandBudget(surface: Surface): string {
+  const bytes = SURFACE_SPECS[surface].jsBaselineBytes + DEFAULT_ISLAND_JS_BYTES;
+  return `${bytes / 1024}kb`;
+}

package/src/module-loader.ts

@@ -0,0 +1,144 @@
+/**
+ * The two loaders that make an app's source runnable: `.tsx` → the server JSX factory, and
+ * `.scss` → CSS plus a class-name map. Both are Bun runtime plugins, so `x dev`, `x build` and
+ * `bun test` all load a component the same way and there is no separate "bundled" behaviour.
+ */
+
+import { compileStylesheet, isGlobalStylesheet } from './css-modules';
+import { PrerenderFailedError } from './errors';
+import type { Surface } from './surfaces';
+import { surfaceOf } from './surfaces';
+
+/**
+ * Why a transform at all: `tsconfig.json` says `jsx: 'preserve'`, which makes Bun fall back to the
+ * CLASSIC React factory and ignore `jsxImportSource` entirely — every `.tsx` in an Ultimate app
+ * compiles to `React.createElement` against a global that does not exist. `jsxImportSource` stays
+ * pointed at `solid-js` because that is where the JSX *type* namespace lives (`class`, not
+ * `className`); the *runtime* factory is the framework's, and an app never configures one.
+ */
+const JSX_FACTORY = '__xh';
+const JSX_FRAGMENT = '__xFragment';
+
+/** No newline: the prelude shares line 1 with the file's own first line, so stack traces still point at it. */
+const JSX_PRELUDE = `import { h as ${JSX_FACTORY}, Fragment as ${JSX_FRAGMENT} } from '@ultimat3/render';`;
+
+const transpiler = new Bun.Transpiler({
+  loader: 'tsx',
+  tsconfig: {
+    compilerOptions: {
+      jsx: 'react',
+      jsxFactory: JSX_FACTORY,
+      jsxFragmentFactory: JSX_FRAGMENT,
+    },
+  } as never,
+});
+
+export interface Stylesheet {
+  /** Absolute path of the source file. */
+  readonly file: string;
+  /** The surface that owns it, or `null` for a package stylesheet shared by both graphs. */
+  readonly surface: Surface | null;
+  /** A plain (non-module) stylesheet: the tokens and the reset, which the cascade needs first. */
+  readonly global: boolean;
+  readonly css: string;
+}
+
+const stylesheets = new Map<string, Stylesheet>();
+
+export function registeredStylesheets(): readonly Stylesheet[] {
+  return [...stylesheets.values()];
+}
+
+/** Test seam: the registry is process-global because the module cache it mirrors is too. */
+export function clearStylesheets(): void {
+  stylesheets.clear();
+}
+
+/**
+ * The CSS a document on `surface` must carry: the global layer first, then the modules, each group
+ * in load order. A `site/` page never receives `app/` CSS — that is axiom 6 applied to bytes the
+ * browser parses, not just bytes it executes.
+ *
+ * `shared/` is carried by both graphs by definition — it is the one directory both surfaces import
+ * from, and it is where an app's own global stylesheet lives. Filtering it out (which this did)
+ * meant an app could put its tokens in the one place the convention names and have every document
+ * silently drop them.
+ *
+ * Globals sort ahead of modules rather than riding load order: the reset styles bare elements at
+ * the lowest specificity there is, so a reset that happened to register after a module rule wins
+ * ties it must lose. Insertion order alone made that depend on which page a request hit first.
+ */
+export function stylesFor(surface: Surface | null): string {
+  const carried = [...stylesheets.values()].filter(
+    (sheet) => sheet.surface === null || sheet.surface === 'shared' || sheet.surface === surface,
+  );
+  return [...carried.filter((sheet) => sheet.global), ...carried.filter((sheet) => !sheet.global)]
+    .map((sheet) => sheet.css)
+    .join('');
+}
+
+/**
+ * `.tsx` source → JS calling the server factory. Exported so the transform is testable as a pure
+ * function: the plugin below is the six lines of glue that hand it a file.
+ */
+export function transformTsx(source: string): string {
+  // No newline between: the prelude shares line 1 with the file's own first line, so every stack
+  // trace and every reported error still points at the line the author wrote.
+  return JSX_PRELUDE + transpiler.transformSync(source);
+}
+
+/**
+ * `.scss` source → the module body an `import styles from …` receives, registering the CSS.
+ *
+ * Keyed by absolute path, which is what makes the global layer emit ONCE however many app modules
+ * import it. Sass dedupes `@use` within a single compilation, and every file here is its own
+ * compilation — so a token file `@use`d by twenty `page.module.scss` would inline its `:root` block
+ * twenty times. One file, imported for its side effect, is the shape that cannot do that.
+ */
+export function loadStylesheet(path: string, source: string): string {
+  const compiled = compileStylesheet(path, source);
+  if (compiled.css.length > 0) {
+    stylesheets.set(path, {
+      file: path,
+      surface: surfaceOf(path),
+      global: isGlobalStylesheet(path),
+      css: compiled.css,
+    });
+  }
+  return `export default ${JSON.stringify(compiled.classes)};`;
+}
+
+let installed = false;
+
+/**
+ * Idempotent: importing `@ultimat3/render` from anywhere installs it once, which is the only
+ * placement that covers `x dev`, `x build`, the production `server.ts` and `bun test` without each
+ * of them remembering to. A plugin only affects modules loaded AFTER it, and every route module is.
+ */
+export function installRenderLoader(): void {
+  if (installed) return;
+  installed = true;
+
+  Bun.plugin({
+    name: 'ultimate-render',
+    setup(build): void {
+      build.onLoad({ filter: /\.tsx$/ }, async ({ path }) => ({
+        contents: transformTsx(await Bun.file(path).text()),
+        loader: 'js',
+      }));
+
+      build.onLoad({ filter: /\.(?:s?css)$/ }, async ({ path }) => {
+        const source = await Bun.file(path).text();
+        try {
+          return { contents: loadStylesheet(path, source), loader: 'js' };
+        } catch (error) {
+          if (error instanceof PrerenderFailedError) throw error;
+          throw new PrerenderFailedError(
+            `${path} could not be loaded: ${error instanceof Error ? error.message : String(error)}`,
+            `open ${path} and fix the stylesheet it @use-s`,
+          );
+        }
+      });
+    },
+  });
+}