@ultimat3/render 1.2.0 → 3.0.0

package/src/head.ts

@@ -9,6 +9,8 @@
 
 import type { RouteMeta } from '@ultimat3/seo';
 import { BudgetExceededError } from './errors';
+// `html.ts` is this package's one escaper — a second one is how a character ends up missing.
+import { escapeAttribute, escapeJsonContent, escapeRawTextContent, escapeText } from './html';
 
 export type HeadTagKind = 'title' | 'base' | 'meta' | 'link' | 'script' | 'style';
 
@@ -27,7 +29,13 @@ export type LdRenderer = (meta: RouteMeta) => string | null;
 export interface HeadRenderers {
   /** `@ultimat3/seo`'s `renderMeta`, adapted to `HeadTag[]`. */
   readonly renderMeta: MetaRenderer;
-  /** `@ultimat3/seo`'s `renderLd`, returning the JSON-LD body or null. */
+  /**
+   * A host's own JSON-LD body, or null. Deliberately unbound by `seoRenderers()` — `renderMeta`
+   * already emits `meta.ld` as one script per node, and a second source for the same tags is how
+   * a document ends up with two copies of its graph. It never was `@ultimat3/seo`'s `renderLd`
+   * either: that took nodes and returned a `HeadTag`, so it could not satisfy this signature. It
+   * was deleted in 1.3.0 for being that second source.
+   */
   readonly renderLd?: LdRenderer;
 }
 
@@ -53,12 +61,35 @@ export function mergeHead(...sources: readonly (readonly HeadTag[])[]): readonly
 }
 
 /** Build the head for a route from its `meta` output plus explicit overrides. */
+/**
+ * The tags every HTML document needs and no route should have to declare. Merged FIRST, so a
+ * route that sets one of these keys still wins.
+ *
+ * Absent until now, and the omission was not cosmetic: with no `viewport`, a phone lays the page
+ * out at ~980px and scales it down, so every deployed Ultimate app rendered zoomed-out on mobile
+ * whatever its CSS said. `color-scheme` is the other half of the token layer's dark mode — without
+ * it the browser paints its own form controls and scrollbars light under a dark page.
+ */
+export const documentBaseline = (): readonly HeadTag[] => [
+  { kind: 'meta', key: 'meta:charset', attrs: { charset: 'utf-8' } },
+  {
+    kind: 'meta',
+    key: 'meta:viewport',
+    attrs: { name: 'viewport', content: 'width=device-width, initial-scale=1' },
+  },
+  {
+    kind: 'meta',
+    key: 'meta:color-scheme',
+    attrs: { name: 'color-scheme', content: 'light dark' },
+  },
+];
+
 export function headFromMeta(
   meta: RouteMeta,
   renderers: HeadRenderers,
   overrides: readonly HeadTag[] = [],
 ): readonly HeadTag[] {
-  const seoTags = renderers.renderMeta(meta);
+  const seoTags = [...documentBaseline(), ...renderers.renderMeta(meta)];
   const ld = renderers.renderLd?.(meta) ?? null;
   const ldTags: readonly HeadTag[] =
     ld === null
@@ -83,21 +114,40 @@ export function renderHead(tags: readonly HeadTag[]): string {
 function renderTag(tag: HeadTag): string {
   const attrs = Object.entries(tag.attrs ?? {})
     .map(([name, value]) =>
-      value === true ? ` ${name}` : ` ${name}="${escapeAttr(String(value))}"`,
+      value === true ? ` ${name}` : ` ${name}="${escapeAttribute(String(value))}"`,
     )
     .join('');
   if (VOID_KINDS.has(tag.kind)) return `<${tag.kind}${attrs}>`;
   const raw = tag.content ?? '';
-  const isRaw = tag.kind === 'script' || tag.kind === 'style';
-  return `<${tag.kind}${attrs}>${isRaw ? raw : escapeText(raw)}</${tag.kind}>`;
+  return `<${tag.kind}${attrs}>${contentOf(tag, raw)}</${tag.kind}>`;
 }
 
-function escapeAttr(value: string): string {
-  return value.replace(/&/g, '&amp;').replace(/"/g, '&quot;').replace(/</g, '&lt;');
+/**
+ * Three contexts, three rules, and the one that was missing was the one attacker text reaches.
+ * `script`/`style` are raw text (`escapeRawTextContent`); a JSON-carrying script is data, so it
+ * takes the total JSON rule; everything else is HTML text, where a character reference IS decoded.
+ * `content` was emitted VERBATIM for script and style until `As of 2026-08`, which made any string
+ * reaching `meta.ld` — a title, a product name, a bio — able to close the element.
+ */
+function contentOf(tag: HeadTag, raw: string): string {
+  if (tag.kind !== 'script' && tag.kind !== 'style') return escapeText(raw);
+  return carriesJson(tag) ? escapeJsonContent(raw) : escapeRawTextContent(raw);
 }
 
-function escapeText(value: string): string {
-  return value.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+/**
+ * `application/ld+json`, `application/json`, any `…+json`: the body is data, not code.
+ *
+ * The MIME parameter is cut before the suffix test, because a real document writes
+ * `type="application/ld+json; charset=utf-8"` and that does not end in `json` — so the block built
+ * from route data, which is the path attacker text takes, silently took the raw-text escaper
+ * instead of the total one. `</` is escaped either way, so this was a weakened boundary rather than
+ * a break-out; the JSON rule is total on purpose, and a `charset` is not a reason to leave it.
+ */
+function carriesJson(tag: HeadTag): boolean {
+  const declared = tag.attrs?.['type'];
+  if (typeof declared !== 'string') return false;
+  const [type = ''] = declared.split(';');
+  return type.trim().toLowerCase().endsWith('json');
 }
 
 export interface ThemeScriptOptions {

package/src/html.ts

@@ -0,0 +1,141 @@
+/**
+ * HTML text and attribute serialization for the server renderer. Escaping lives here and only
+ * here: a second escaper is how one of them ends up missing a character, and a missing character
+ * in an attribute is an injection.
+ */
+
+import { safeUrl, URL_ATTRIBUTES } from '@ultimat3/core';
+import type { JsxProps } from './jsx';
+
+/** Elements that never carry children, so the writer must not emit a closing tag. */
+export const VOID_ELEMENTS: ReadonlySet<string> = new Set([
+  'area',
+  'base',
+  'br',
+  'col',
+  'embed',
+  'hr',
+  'img',
+  'input',
+  'link',
+  'meta',
+  'param',
+  'source',
+  'track',
+  'wbr',
+]);
+
+export function escapeText(value: string): string {
+  return value.replaceAll('&', '&amp;').replaceAll('<', '&lt;').replaceAll('>', '&gt;');
+}
+
+export function escapeAttribute(value: string): string {
+  return escapeText(value).replaceAll('"', '&quot;');
+}
+
+/**
+ * `<script>` and `<style>` hold RAW TEXT: a character reference is not decoded inside them, so
+ * `escapeText` there would ship `&lt;` to a JS or CSS parser and corrupt the code without closing
+ * the hole. What actually ends the element is `</` followed by its tag name, and — inside a script
+ * only — `<!--` switches the tokenizer into the escaped state where the element's own `</script>`
+ * no longer closes it and the rest of the document becomes script text.
+ *
+ * So the two sequences are made unwritable instead. `\/` and `\!` are the identity escape in a JS
+ * string, a JS regex, a CSS string and a CSS url(), which is where a `</` in authored code lives;
+ * outside a string neither `</` nor `<!--` is valid code in either language.
+ */
+export function escapeRawTextContent(value: string): string {
+  return value.replaceAll('</', '<\\/').replaceAll('<!--', '<\\!--');
+}
+
+/**
+ * The same element, when its content is JSON rather than code — `application/ld+json`, which is
+ * built from route data and is therefore the path attacker text takes. JSON gets the total rule:
+ * `<` is the same character to `JSON.parse`, so nothing survives that could spell `</script`
+ * or `<!--`, and the body stays byte-for-byte valid JSON.
+ *
+ * Safe by construction because `<`, `>`, `&`, U+2028 and U+2029 can only occur INSIDE a JSON
+ * string — no JSON structural token contains one — so every replacement lands where `\u` means
+ * an escape. U+2028/U+2029 are legal in a JSON string and illegal in a JS one, and this content
+ * is read back by both.
+ */
+export function escapeJsonContent(json: string): string {
+  return json
+    .replaceAll('<', '\\u003c')
+    .replaceAll('>', '\\u003e')
+    .replaceAll('&', '\\u0026')
+    .replaceAll('\u2028', '\\u2028')
+    .replaceAll('\u2029', '\\u2029');
+}
+
+/**
+ * JSX prop name → attribute name. Solid authors write the HTML spelling (`class`, `for`), but the
+ * React spellings compile too, and an author who writes one and gets no attribute has a bug with
+ * no error message.
+ */
+const ATTRIBUTE_ALIASES: Readonly<Record<string, string>> = {
+  className: 'class',
+  htmlFor: 'for',
+};
+
+/** Props the tree consumes rather than emits. `innerHTML` is emitted as content, not an attribute. */
+const NON_ATTRIBUTES: ReadonlySet<string> = new Set([
+  'children',
+  'ref',
+  'key',
+  'innerHTML',
+  'textContent',
+]);
+
+const cssProperty = (name: string): string =>
+  name.startsWith('--') ? name : name.replace(/[A-Z]/g, (letter) => `-${letter.toLowerCase()}`);
+
+/** `{ marginTop: '1rem' }` → `margin-top:1rem`. A string style passes through untouched. */
+export function styleValue(value: unknown): string | null {
+  if (typeof value === 'string') return value;
+  if (typeof value !== 'object' || value === null) return null;
+  const parts = Object.entries(value as Record<string, unknown>)
+    .filter(([, item]) => item !== undefined && item !== null && item !== false)
+    .map(([name, item]) => `${cssProperty(name)}:${String(item)}`);
+  return parts.length === 0 ? null : parts.join(';');
+}
+
+/**
+ * One prop → one attribute string, or `null` when it emits nothing. Event handlers are dropped
+ * rather than stringified: the server has no listeners, and `onclick="function(){…}"` would ship
+ * a broken inline handler that looks like it works.
+ */
+export function attributePair(name: string, value: unknown): string | null {
+  if (NON_ATTRIBUTES.has(name)) return null;
+  if (value === undefined || value === null || value === false) return null;
+  if (typeof value === 'function') return null;
+  if (name.startsWith('on') && name.length > 2) return null;
+
+  const attribute = ATTRIBUTE_ALIASES[name] ?? name;
+  if (value === true) return attribute;
+  if (attribute === 'style') {
+    const style = styleValue(value);
+    return style === null ? null : `style="${escapeAttribute(style)}"`;
+  }
+  const text = String(value);
+  // Escaping makes a value inert inside the quotes; it cannot make a SCHEME inert, because
+  // `href="javascript:alert(1)"` never leaves them. One choke point for both, here, because this
+  // module is the single place injection is prevented and an href off a database row is the shape
+  // every app writes. A refused URL emits no attribute at all — an anchor with no `href` is inert
+  // and still renders its text, where a blanked one is a live link nobody checked.
+  if (URL_ATTRIBUTES.includes(attribute.toLowerCase())) {
+    const url = safeUrl(text, attribute.toLowerCase());
+    if (url === null) return null;
+    return `${attribute}="${escapeAttribute(url)}"`;
+  }
+  return `${attribute}="${escapeAttribute(text)}"`;
+}
+
+export function renderAttributes(props: JsxProps): string {
+  const parts: string[] = [];
+  for (const [name, value] of Object.entries(props)) {
+    const pair = attributePair(name, value);
+    if (pair !== null) parts.push(pair);
+  }
+  return parts.length === 0 ? '' : ` ${parts.join(' ')}`;
+}

package/src/hydrate.ts

@@ -5,10 +5,17 @@
  * answered instead of swallowed.
  */
 
+import { escapeJsonContent } from './html';
 import type { HydrateStrategy } from './route';
 
 export interface IslandDirective {
+  /** Unique per INSTANCE: two of the same island on a page need two prop bags to find. */
   readonly islandId: string;
+  /**
+   * The client entry this instance came from — the unit a bundle is measured in and a budget
+   * counts. Optional only because it arrived after `islandId`; `island()` always sets it.
+   */
+  readonly moduleId?: string;
   readonly strategy: HydrateStrategy;
   /** Build-id-immutable module URL for this island's chunk. */
   readonly entry: string;
@@ -40,12 +47,16 @@ export function emitIslandAttributes(directive: IslandDirective): string {
   return attrs.join(' ');
 }
 
-/** Props travel as a typed JSON script tag, never as an attribute (quoting hazards). */
+/**
+ * Props travel as a typed JSON script tag, never as an attribute (quoting hazards). The body is
+ * escaped by `html.ts`'s one JSON escaper — this file had its own partial copy, and a second
+ * escaper is how one of them ends up missing a character.
+ */
 export function emitIslandProps(directive: IslandDirective): string {
   if (directive.props === undefined || directive.strategy === 'never') return '';
   return (
     `<script type="application/json" data-x-props="${directive.islandId}">` +
-    `${JSON.stringify(directive.props).replace(/</g, '\\u003c')}</script>`
+    `${escapeJsonContent(JSON.stringify(directive.props))}</script>`
   );
 }
 
@@ -60,13 +71,18 @@ export function requiredStrategies(
   return set;
 }
 
+// `el.__x` holds the boot PROMISE, not a boolean flag: it is still "already booting" for the
+// once-only guard, and a second caller now waits for the same mount instead of being handed a
+// resolved promise. As a flag, a second click during the chunk's load short-circuited to
+// `Promise.resolve()`, and the interaction runtime flushed its replay queue into an island that
+// had not mounted — the events went to nothing and the listeners were already removed.
 const RUNTIME_PRELUDE = `
 var Q={};
 function boot(el){var e=el.getAttribute('data-x-entry');
-if(!e||el.__x)return Promise.resolve();el.__x=1;
+if(!e)return Promise.resolve();if(el.__x)return el.__x;
 var p=document.querySelector('script[data-x-props="'+el.getAttribute('data-x-island')+'"]');
 var props=p?JSON.parse(p.textContent||'{}'):{};
-return import(e).then(function(m){return m.mount(el,props)})}
+return el.__x=import(e).then(function(m){return m.mount(el,props)})}
 function each(s,f){Array.prototype.forEach.call(document.querySelectorAll(s),f)}
 `.trim();
 

package/src/index.ts

@@ -1,13 +1,29 @@
 /** Public API of `@ultimat3/render`: the `route` primitive, the five modes, the table. */
 
+import { installRenderLoader } from './module-loader';
+
+// A side effect on import, deliberately: a Bun plugin only transforms modules loaded AFTER it, and
+// every consumer that will ever load a `.tsx` route or a `.scss` module imports this package first
+// (an app's route file imports `defineRoute` from here before it imports anything else it owns).
+// Any later hook — `x dev`, `x build`, `server.ts` — would each have to remember, which is four
+// places one fact can be wrong instead of none.
+installRenderLoader();
+
+export type { CompiledStylesheet } from './css-modules';
+export { compileStylesheet, isCssModule, isGlobalStylesheet, scopeClasses } from './css-modules';
 export type { RenderErrorCode } from './errors';
 export {
   BudgetExceededError,
+  IslandInvalidError,
+  IslandNotHydratedError,
+  IslandPropsInvalidError,
   PrerenderFailedError,
   RENDER_ERROR_CODES,
   RENDER_ERROR_TITLES,
   RouteDuplicateError,
   RouteFileInvalidError,
+  RouteLoadFailedError,
+  RouteLoadInvalidError,
   RouteMetaMissingError,
   RouteModeInvalidError,
   RouteOfflineMissingError,
@@ -22,6 +38,7 @@ export type {
   ThemeScriptOptions,
 } from './head';
 export {
+  documentBaseline,
   headFromMeta,
   mergeHead,
   renderHead,
@@ -38,6 +55,19 @@ export {
   hydrateRuntimeBytes,
   requiredStrategies,
 } from './hydrate';
+export type { IslandComponent, IslandDeclaration, IslandNode, IslandSpec } from './island';
+export {
+  ISLAND_EXTENSION,
+  ISLAND_NODE,
+  isEmittableSpecifier,
+  isIslandNode,
+  island,
+  islandModuleId,
+} from './island';
+export type { IslandCollector, IslandCollectorInput } from './island-collector';
+export { createIslandCollector, islandModuleIds } from './island-collector';
+export type { IslandProps, JsonValue } from './island-props';
+export { checkIslandProps, ISLAND_PROPS_MAX_BYTES } from './island-props';
 export type { BudgetReport, BundleGraph, GraphName, Island, RouteBytes } from './islands';
 export {
   assertBudget,
@@ -48,14 +78,27 @@ export {
   parseByteBudget,
   routeJsBytes,
 } from './islands';
+export type { JsxComponent, JsxNode, JsxProps } from './jsx';
+export { Fragment, h, isJsxNode, JSX_NODE } from './jsx';
 export type { ModeCheckContext, ModeSpec, RouteShape } from './modes';
 export {
   assertModeInvariants,
   assertModeShape,
+  DEFAULT_ISLAND_JS_BYTES,
   defaultHydrate,
+  defaultIslandBudget,
   MODE_SPECS,
   RENDER_MODES,
 } from './modes';
+export type { Stylesheet } from './module-loader';
+export {
+  clearStylesheets,
+  installRenderLoader,
+  loadStylesheet,
+  registeredStylesheets,
+  stylesFor,
+  transformTsx,
+} from './module-loader';
 export type {
   CompiledPattern,
   RegisterRouteInput,
@@ -75,6 +118,8 @@ export {
   routeFor,
   routePathFromFile,
 } from './registry';
+export type { RenderHtmlOptions } from './render-html';
+export { renderComponent, renderToHtml } from './render-html';
 export type {
   IsrController,
   IsrControllerOptions,
@@ -83,10 +128,11 @@ export type {
   IsrServeResult,
   IsrState,
   IsrStore,
+  MemoryIsrStoreOptions,
 } from './render-isr';
-
 export {
   createIsrController,
+  DEFAULT_ISR_MAX_ENTRIES,
   invalidateAndRevalidate,
   memoryIsrStore,
   parseTtlMs,
@@ -108,6 +154,7 @@ export {
 export type { StreamHole, StreamOptions, StreamPlan } from './render-stream';
 export {
   collectStream,
+  DEFAULT_HOLE_TIMEOUT_MS,
   holeId,
   holeMarker,
   REVEAL_SCRIPT,
@@ -117,6 +164,7 @@ export {
 } from './render-stream';
 export type {
   HydrateStrategy,
+  LoadRequirement,
   OfflineStrategy,
   PrerenderFn,
   RenderMode,
@@ -124,20 +172,28 @@ export type {
   RevalidateConfig,
   RouteBudget,
   RouteConfig,
+  RouteContext,
   RouteData,
   RouteDefinition,
   RouteGuard,
+  RouteLoadAsyncFn,
+  RouteLoadFn,
   RouteMetaAsyncFn,
+  RouteMetaContext,
   RouteMetaFn,
   RouteParams,
 } from './route';
 export {
+  DEFAULT_ISLAND_HYDRATE,
   defineRoute,
   HYDRATE_STRATEGIES,
   isRouteConfig,
   OFFLINE_STRATEGIES,
   tagKeys,
 } from './route';
+export type { RouteComponent } from './route-component';
+export { pageComponentOf } from './route-component';
+export { metaContextFor, routeDataFor } from './route-data';
 export type {
   NavigateOptions,
   NavigationGuard,

package/src/island-collector.ts

@@ -0,0 +1,148 @@
+/**
+ * What one render pulled in. The collector is where an island's timing, its budget and its
+ * failure to have either come from the ROUTE rather than from the island — so `hydrate` stays the
+ * one place a route says it ships JavaScript, and the directives stay a per-render fact.
+ */
+
+import { IslandInvalidError, IslandNotHydratedError } from './errors';
+import type { IslandDirective } from './hydrate';
+import { DEFAULT_REPLAY_EVENTS } from './hydrate';
+import type { IslandSpec } from './island';
+import { isEmittableSpecifier, islandNeverDrained } from './island';
+import type { IslandProps } from './island-props';
+import { checkIslandProps } from './island-props';
+import type { JsxProps } from './jsx';
+import type { HydrateStrategy } from './route';
+
+/** The distinct client entries a rendered page pulled in — one per module, however many instances. */
+export function islandModuleIds(directives: readonly IslandDirective[]): readonly string[] {
+  const ids = new Set<string>();
+  for (const directive of directives) ids.add(directive.moduleId ?? directive.islandId);
+  return [...ids];
+}
+
+export interface IslandCollectorInput {
+  /** The route file, so every failure names the file an author has to open. */
+  readonly file: string;
+  /** The route's `hydrate`. The island inherits it; it never declares one of its own. */
+  readonly hydrate: HydrateStrategy;
+  /** Specifier → built chunk URL. Identity in dev and in tests; the build supplies the real one. */
+  readonly resolve?: (src: string) => string;
+}
+
+/**
+ * Collects what a single render pulled in. Per render, never module-global: two requests render
+ * different params and a shared collector would bill one page for the other's islands.
+ */
+export interface IslandCollector {
+  readonly file: string;
+  readonly hydrate: HydrateStrategy;
+  readonly directives: readonly IslandDirective[];
+  /** Called by the tree walker once per island instance. Returns what the markup is built from. */
+  record(spec: IslandSpec, props: JsxProps): IslandDirective;
+}
+
+export function createIslandCollector(input: IslandCollectorInput): IslandCollector {
+  const directives: IslandDirective[] = [];
+  const entries = new Map<string, string>();
+  const resolve = input.resolve ?? ((src: string) => src);
+  const strategy = input.hydrate;
+
+  return {
+    file: input.file,
+    hydrate: strategy,
+    get directives(): readonly IslandDirective[] {
+      return directives;
+    },
+    record(spec: IslandSpec, props: JsxProps): IslandDirective {
+      assertHydrates(strategy, spec, input.file);
+
+      const entry = resolve(spec.src);
+      assertEntry(entry, spec, input.file);
+      const claimed = entries.get(spec.moduleId);
+      if (claimed !== undefined && claimed !== entry) {
+        throw new IslandInvalidError(
+          `two islands on ${input.file} both resolve to the id ${spec.moduleId} (${claimed} and ` +
+            `${entry}), so their props would be handed to whichever the browser found first`,
+          `rename one of the modules — the id is its filename, so two islands need two names`,
+        );
+      }
+      entries.set(spec.moduleId, entry);
+
+      const bag = checkIslandProps(props, spec.propKeys, input.file, spec.moduleId);
+      const instance = directives.filter((d) => d.moduleId === spec.moduleId).length + 1;
+      const directive = buildDirective(spec, strategy, entry, `${spec.moduleId}-${instance}`, bag);
+      directives.push(directive);
+      return directive;
+    },
+  };
+}
+
+function buildDirective(
+  spec: IslandSpec,
+  strategy: HydrateStrategy,
+  entry: string,
+  islandId: string,
+  props: IslandProps,
+): IslandDirective {
+  // Replay defaults to every event a shell can receive: losing the first keystroke in a search box
+  // is the same failure as losing the first click, and only the declaration knows which shell it is.
+  const events = strategy === 'interaction' ? (spec.events ?? DEFAULT_REPLAY_EVENTS) : spec.events;
+  return {
+    islandId,
+    moduleId: spec.moduleId,
+    strategy,
+    entry,
+    ...(Object.keys(props).length === 0 ? {} : { props }),
+    ...(events === undefined ? {} : { events }),
+    ...(spec.rootMargin === undefined ? {} : { rootMargin: spec.rootMargin }),
+  };
+}
+
+/**
+ * An island on a route that ships no JS is a button that does nothing — and it is also how the
+ * budget stops meaning anything, because `hydrate: 'never'` is what excuses a `site/` route from
+ * declaring `budget.js` at all.
+ *
+ * Still reachable with `hydrate` derived, and for exactly two reasons — so the `fix:` names ONE.
+ * `islandNeverDrained` is what tells them apart: a spec still pending at render time was declared
+ * where no `defineRoute` could see it, and a spec already drained means an author wrote `'never'`.
+ * Offering both edits would make half the instruction wrong for every reader, and leave working
+ * out which half is theirs as the reader's job — which is the opposite of axiom 4.
+ */
+function assertHydrates(strategy: HydrateStrategy, spec: IslandSpec, file: string): void {
+  if (strategy !== 'never') return;
+  // Only on the failure path: the happy path returned above and never touches the list.
+  const undrained = islandNeverDrained(spec);
+  const cause = undrained
+    ? `no defineRoute in that module drained the ${spec.moduleId} declaration and the route ` +
+      "derived hydrate: 'never'"
+    : `the route declares hydrate: 'never'`;
+  throw new IslandNotHydratedError(
+    `${file} renders the ${spec.moduleId} island but ${cause}, so the browser would receive its ` +
+      'markup and never the JavaScript that makes it do anything',
+    undrained
+      ? `move the island() call for ${spec.moduleId} above defineRoute in ${file} — a page that ` +
+          'declares an island hydrates on its own'
+      : `remove hydrate: 'never' from ${file} — a page that declares an island hydrates on its own`,
+  );
+}
+
+function assertEntry(entry: string, spec: IslandSpec, file: string): void {
+  if (isEmittableSpecifier(entry)) return;
+  throw new IslandInvalidError(
+    `the resolver returned ${JSON.stringify(entry)} for the ${spec.moduleId} island in ${file}, ` +
+      'which cannot be emitted as a module URL',
+    'fix the resolve() passed to createIslandCollector — it must return a plain URL path',
+  );
+}
+
+/** Thrown from the walker when an island is rendered with nothing to boot it. */
+export function islandWithoutCollector(spec: IslandSpec): IslandNotHydratedError {
+  return new IslandNotHydratedError(
+    `the ${spec.moduleId} island was rendered outside a render that collects islands, so no ` +
+      'hydration runtime is emitted and its chunk is never requested',
+    'render the page through renderToHtml(tree, { islands: createIslandCollector({ file, ' +
+      'hydrate }) }) so the island is counted, booted and budgeted',
+  );
+}