npm - @ultimat3/render - Versions diffs - 1.0.0 - Mend

@ultimat3/render 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (19) hide show

package/LICENSE ADDED Viewed

@@ -0,0 +1,21 @@
+MIT License
+Copyright (c) 2026 developerz.ai
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md ADDED Viewed

@@ -0,0 +1,149 @@
+# 🖼 @ultimat3/render
+The `route` primitive and the five render modes.
+| Mode | Behavior | Use |
+|---|---|---|
+| `static` | built once, served as a file | marketing, docs |
+| `isr` | static + background regen on tag/TTL | catalogs, profiles |
+| `ssr` | per-request full render | fresh SEO pages |
+| `stream` | static shell flushed instantly, holes streamed | **default for app pages** |
+| `spa` | shell only, client fetches | dashboards behind auth |
+```ts
+export const config = defineRoute({
+  render:     'isr',                  // static | isr | ssr | stream | spa
+  revalidate: { tags: [tag.post] },
+  prerender:  () => db.posts.slugs(),
+  offline:    'precache',             // precache | runtime | network-only
+  hydrate:    'visible',              // idle | visible | interaction | never
+  budget:     { js: '40kb', lcp: 2000 },
+  meta:       ({ post }) => ({ title: post.title, description: post.excerpt,
+                               og: { image: post.cover }, ld: ld.Article(post) }),
+});
+```
+## `offline`, `hydrate` and `meta` are required by the type
+Not by a lint rule, not by a doc — by `RouteDefinition`. Axiom 3 lives in the type system:
+a route that forgets its offline strategy or its `<head>` does not compile. `defineRoute`
+re-checks the same three at runtime (`X_ROUTE_OFFLINE_MISSING`, `X_ROUTE_META_MISSING`) for
+JS callers and generators.
+## `defineRoute` returns a descriptor, not the object you passed
+Two fields come back narrower than they went in, so nothing downstream branches on shape:
+| Field | The declaration accepts | The descriptor always is |
+|---|---|---|
+| `meta` | `(data) => RouteMeta \| Promise<RouteMeta>` | `(data) => Promise<RouteMeta>` |
+| `budget` | omitted, or a `RouteBudget` | a `RouteBudget` — `{}` when undeclared |
+```ts
+const meta = await config.meta({ post });   // always. sync or async declaration, one call
+const js = config.budget.js ?? null;        // never config.budget?.js
+```
+No author is forced to write `async`, and a `meta` that throws synchronously comes back as
+a rejection, so one `catch` covers both. The budget's *fields* stay optional:
+`budget.js === undefined` still means "declared no JS budget", which is exactly what fails
+a hydrating `site/` route below.
+## Mode invariants, checked at registration
+| Mode | Invariant | Error if violated |
+|---|---|---|
+| `static` | no per-request state — no `policy`, no `revalidate` | `X_ROUTE_MODE_INVALID` |
+| `isr` | needs a trigger: `revalidate.tags` or `revalidate.ttl` | `X_ROUTE_MODE_INVALID` |
+| `ssr` | cannot be prerendered | `X_ROUTE_MODE_INVALID` |
+| `stream` | at least one `<Suspense>` boundary | `X_ROUTE_MODE_INVALID` |
+| `spa` | requires a `policy` (authed dashboards only) | `X_ROUTE_MODE_INVALID` |
+Plus surface rules: `site/` allows `static | isr | ssr`, `app/` allows `stream | spa | ssr`,
+`api/` renders nothing, and a `site/` route that opts into hydration without a `budget.js`
+is a build error.
+## The route table is the single source of route truth
+`registry.ts` maps file paths to URLs and `describeRoutes()` projects the table into a
+sorted, JSON-safe descriptor list. Every downstream generator reads that one table.
+| File | URL |
+|---|---|
+| `site/page.tsx` | `/` |
+| `site/pricing/page.tsx` | `/pricing` |
+| `site/(marketing)/about/page.tsx` | `/about` |
+| `site/blog/[slug]/page.tsx` | `/blog/:slug` |
+| `site/docs/[...path]/page.tsx` | `/docs/*path` |
+| `app/dashboard/page.tsx` | `/dashboard` |
+| `api/posts/route.ts` | `/api/posts` |
+The URL is the **directory** path under the surface; the filename names the kind of file, never a
+URL segment. One spelling per surface — `page.tsx` under `site/` and `app/`, `route.ts` under
+`api/` — and `registerRoute` refuses anything else with `X_ROUTE_FILE_INVALID`. `index.tsx` is not
+a page. Two spellings would make "is this file a route?" undecidable for the module scan, the
+boundary walk, `sw.js` and the author reading the folder; one spelling also co-locates
+`page.tsx` + `page.module.scss` + `page.test.ts`, and gives `[slug]/` its own stylesheet.
+Consumers: `x.manifest.json`, the `/_x` routes panel, `sitemap.xml`, `sw.js`
+(`@ultimat3/pwa` takes descriptors as data — tier 4 packages never import each other).
+## `site/` cannot import `app/` — build error, resolved transitively
+```
+X_SURFACE_BOUNDARY: site/ imported app/
+  cause: site/pricing/page.tsx → shared/ui/button.tsx → app/charts/sparkline.tsx
+  fix:   x fix boundary site/pricing/page.tsx   (or move sparkline out of shared/ui)
+```
+The failure this prevents, in order:
+1. Someone puts `<Button>` in `shared/ui/` — correct, both surfaces need buttons.
+2. A dashboard needs a button with an inline trend line, so `<Sparkline>` joins the same
+   file and pulls in the charting library.
+3. `site/pricing` imports `<Button>`.
+4. The highest-intent page in the product now ships chart.js. Nothing broke, nothing
+   warned, LCP regressed 900ms, discovered a quarter later by a Lighthouse audit nobody
+   scheduled.
+The import that costs you is three hops from the file anyone reviewed, so
+`checkSurfaceBoundary()` walks the whole value-import graph. `import type` edges are erased
+at build time and therefore never carry the boundary. `shared/` is a leaf; `app/ → api/` is
+types-only.
+## Public API
+| Export | Owns |
+|---|---|
+| `defineRoute` | the `route` primitive |
+| `MODE_SPECS`, `assertModeShape`, `assertModeInvariants` | the mode invariant table |
+| `registerRoute`, `describeRoutes`, `matchRoute`, `routePathFromFile` | the route table |
+| `checkSurfaceBoundary`, `assertSurfaceBoundary`, `surfaceOf` | the hard boundary |
+| `renderStatic`, `enumeratePrerender` | build-time render, content hashing |
+| `createIsrController`, `invalidateAndRevalidate` | SWR + single-flight + tag triggers |
+| `renderSsr`, `streamResult`, `renderSpa` | the per-request modes |
+| `emitIslandAttributes`, `hydrateRuntime` | the four hydration strategies |
+| `graphFor`, `checkBudget`, `assertBudget` | two bundle graphs, per-route budgets |
+| `createRouter` | the vendored client router |
+| `mergeHead`, `renderHead`, `themeScript` | `<head>` merge + the one inlined script |
+## Notes
+- **ISR** serves stale instantly, regenerates single-flight (a burst renders once), and
+  registers each rendered page in `@ultimat3/cache`'s invalidation graph as an
+  `isr-route` dependent of its `revalidate.tags`. So
+  `action({ cache: { invalidates: [tag.post] } })` reaches ISR in the same hop as memo,
+  LRU, Redis and the CDN, and regenerates exactly the dependent pages — nobody lists
+  pages by hand, so nobody forgets one. `controller.attach()` installs it as the
+  framework's `Revalidator`.
+- **`stream`** flushes the shell first, then reveals holes in completion order with a
+  ~200-byte inline script. Solid's compiled templates and signals mean the shell costs zero
+  hydration work, so streaming buys TTFB *and* TBT here, not just TTFB.
+- **`hydrate: 'interaction'`** replays the event that woke the island; without replay the
+  first click on a cold island is silently lost.
+- **`hydrate: 'never'`** emits no attributes beyond the marker and no runtime — the `site/`
+  0kb default is mechanical, not aspirational.
+- **The client router is vendored** rather than depending on a moving SolidStart alpha. It
+  imports no `solid-js`: reactive primitives and the DOM host are injected.
+- `@ultimat3/http`'s `html()` / `stream()` turn a `RenderResult` into a `Response`; render
+  never constructs one.

package/package.json ADDED Viewed

@@ -0,0 +1,37 @@
+{
+  "name": "@ultimat3/render",
+  "version": "1.0.0",
+  "description": "The route primitive and the five render modes: static, isr, ssr, stream, spa.",
+  "license": "MIT",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/developerz-ai/ultimate.git",
+    "directory": "packages/render"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "files": [
+    "src",
+    "!src/**/*.test.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "bun": ">=1.3.0"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "test": "bun test"
+  },
+  "dependencies": {
+    "@ultimat3/cache": "1.0.0",
+    "@ultimat3/core": "1.0.0",
+    "@ultimat3/seo": "1.0.0"
+  }
+}

package/src/errors.ts ADDED Viewed

@@ -0,0 +1,167 @@
+/**
+ * Render's error codes. Every route failure is a stable code + cause + exact fix
+ * (axiom 4), identical in the terminal, the browser overlay and `--json`.
+ */
+import { registerErrorCodes, UltimateError } from '@ultimat3/core';
+export const RENDER_ERROR_CODES = [
+  'X_ROUTE_MODE_INVALID',
+  'X_ROUTE_OFFLINE_MISSING',
+  'X_ROUTE_META_MISSING',
+  'X_ROUTE_UNNORMALIZED',
+  'X_ROUTE_DUPLICATE',
+  'X_ROUTE_FILE_INVALID',
+  'X_SURFACE_BOUNDARY',
+  'X_BUDGET_EXCEEDED',
+  'X_PRERENDER_FAILED',
+] as const;
+export type RenderErrorCode = (typeof RENDER_ERROR_CODES)[number];
+export const RENDER_ERROR_TITLES: Readonly<Record<RenderErrorCode, string>> = {
+  X_ROUTE_MODE_INVALID: 'render mode not allowed on this surface',
+  X_ROUTE_OFFLINE_MISSING: "the route's offline strategy is missing or contradictory",
+  X_ROUTE_META_MISSING: 'required metadata missing',
+  X_ROUTE_UNNORMALIZED: 'a route was registered without defineRoute',
+  X_ROUTE_DUPLICATE: 'two route files resolve to one URL',
+  X_ROUTE_FILE_INVALID: 'a route file is not named for its surface',
+  X_SURFACE_BOUNDARY: 'a surface imported across the hard boundary',
+  X_BUDGET_EXCEEDED: 'a route blew its JS or LCP budget',
+  X_PRERENDER_FAILED: 'a prerendered path threw during build',
+};
+// Titles must be registered for `format()` to render the contract's first line. Every code above is
+// owned here and none is borrowed, so the call is unconditional: a second package claiming one has
+// to fail as X_ERROR_CODE_DUPLICATE, not quietly keep whichever title was registered first.
+registerErrorCodes(
+  Object.fromEntries(Object.entries(RENDER_ERROR_TITLES).map(([code, title]) => [code, { title }])),
+);
+const docsFor = (code: RenderErrorCode): string => `https://ultimate.dev/errors/${code}`;
+/** A render mode's invariant was violated at registration (see `modes.ts`). */
+export class RouteModeInvalidError extends UltimateError {
+  static readonly code = 'X_ROUTE_MODE_INVALID' as const;
+  constructor(cause: string, fix: string) {
+    super({
+      code: RouteModeInvalidError.code,
+      cause,
+      fix,
+      docs: docsFor(RouteModeInvalidError.code),
+    });
+  }
+}
+/** `offline` is required by the type; this catches JS callers that bypass it. */
+export class RouteOfflineMissingError extends UltimateError {
+  static readonly code = 'X_ROUTE_OFFLINE_MISSING' as const;
+  constructor(cause: string, fix: string) {
+    super({
+      code: RouteOfflineMissingError.code,
+      cause,
+      fix,
+      docs: docsFor(RouteOfflineMissingError.code),
+    });
+  }
+}
+/** `meta` is required by the type; this catches JS callers that bypass it. */
+export class RouteMetaMissingError extends UltimateError {
+  static readonly code = 'X_ROUTE_META_MISSING' as const;
+  constructor(cause: string, fix: string) {
+    super({
+      code: RouteMetaMissingError.code,
+      cause,
+      fix,
+      docs: docsFor(RouteMetaMissingError.code),
+    });
+  }
+}
+/**
+ * The route table holds descriptors, never declarations. `defineRoute` is the one normalizer, so
+ * a raw declaration reaching the registry means `budget` and `meta` are whatever the author wrote
+ * — and every reader downstream (`describeRoutes`, `sw.js`, the sitemap) assumes they are not.
+ */
+export class RouteUnnormalizedError extends UltimateError {
+  static readonly code = 'X_ROUTE_UNNORMALIZED' as const;
+  constructor(cause: string, fix: string) {
+    super({
+      code: RouteUnnormalizedError.code,
+      cause,
+      fix,
+      docs: docsFor(RouteUnnormalizedError.code),
+    });
+  }
+}
+/** Two files claim the same URL — the route table must stay a function of the path. */
+export class RouteDuplicateError extends UltimateError {
+  static readonly code = 'X_ROUTE_DUPLICATE' as const;
+  constructor(cause: string, fix: string) {
+    super({
+      code: RouteDuplicateError.code,
+      cause,
+      fix,
+      docs: docsFor(RouteDuplicateError.code),
+    });
+  }
+}
+/**
+ * A route file is not named for its surface. One spelling per surface — `page.tsx` under `site/`
+ * and `app/`, `route.ts` under `api/` — because the URL is the *directory* path, and a second
+ * spelling makes "is this file a route?" undecidable for every reader that has to answer it:
+ * the module scan, the boundary walk, `sw.js`, and the author looking at the folder.
+ */
+export class RouteFileInvalidError extends UltimateError {
+  static readonly code = 'X_ROUTE_FILE_INVALID' as const;
+  constructor(cause: string, fix: string) {
+    super({
+      code: RouteFileInvalidError.code,
+      cause,
+      fix,
+      docs: docsFor(RouteFileInvalidError.code),
+    });
+  }
+}
+/** A surface imported across the hard boundary (`site/` → `app/`, `shared/` → anything). */
+export class SurfaceBoundaryError extends UltimateError {
+  static readonly code = 'X_SURFACE_BOUNDARY' as const;
+  constructor(cause: string, fix: string) {
+    super({
+      code: SurfaceBoundaryError.code,
+      cause,
+      fix,
+      docs: docsFor(SurfaceBoundaryError.code),
+    });
+  }
+}
+/** A route's measured JS/LCP exceeded its declared `budget`. */
+export class BudgetExceededError extends UltimateError {
+  static readonly code = 'X_BUDGET_EXCEEDED' as const;
+  constructor(cause: string, fix: string) {
+    super({
+      code: BudgetExceededError.code,
+      cause,
+      fix,
+      docs: docsFor(BudgetExceededError.code),
+    });
+  }
+}
+/** `prerender()` threw, returned a non-enumeration, or produced unusable params. */
+export class PrerenderFailedError extends UltimateError {
+  static readonly code = 'X_PRERENDER_FAILED' as const;
+  constructor(cause: string, fix: string) {
+    super({
+      code: PrerenderFailedError.code,
+      cause,
+      fix,
+      docs: docsFor(PrerenderFailedError.code),
+    });
+  }
+}

package/src/head-seo.ts ADDED Viewed

@@ -0,0 +1,46 @@
+// Single responsibility: the one adapter between `@ultimat3/seo`'s tag vocabulary and this
+// package's `HeadRenderers` seam. `head.ts` stays injection-only so it is testable without a
+// catalog; every caller that renders a real document — `x dev`, `x build`, the server entry —
+// binds the seam here instead of writing a fourth private converter.
+import type { RenderMetaOptions, RouteMeta, HeadTag as SeoHeadTag } from '@ultimat3/seo';
+import { renderMeta } from '@ultimat3/seo';
+import type { HeadRenderers, HeadTag } from './head';
+/** Attributes that identify a tag for dedupe, read in this order. */
+const IDENTITY: Readonly<Record<SeoHeadTag['tag'], readonly string[]>> = {
+  title: [],
+  meta: ['name', 'property', 'http-equiv', 'charset', 'media'],
+  link: ['rel', 'hreflang', 'sizes'],
+  script: ['type'],
+};
+/**
+ * `<meta name="description">` → `meta:description`. Scripts also carry their position: a page
+ * with three JSON-LD nodes emits three tags with identical attributes, and keying them alike
+ * would collapse the graph down to its last node.
+ */
+export function headTagKey(tag: SeoHeadTag, index: number): string {
+  const identity = IDENTITY[tag.tag]
+    .map((name) => tag.attrs[name])
+    .filter((value): value is string => value !== undefined);
+  return [tag.tag, ...identity, ...(tag.tag === 'script' ? [String(index)] : [])].join(':');
+}
+export function toHeadTag(tag: SeoHeadTag, index: number): HeadTag {
+  return {
+    kind: tag.tag,
+    key: headTagKey(tag, index),
+    attrs: tag.attrs,
+    ...(tag.text === undefined ? {} : { content: tag.text }),
+  };
+}
+/**
+ * `HeadRenderers` backed by `@ultimat3/seo`. There is no `renderLd` half on purpose:
+ * `renderMeta` already emits `meta.ld` as JSON-LD scripts, and a second source for the same
+ * tags is exactly how a document ends up with two copies of its graph.
+ */
+export function seoRenderers(options: RenderMetaOptions = {}): HeadRenderers {
+  return { renderMeta: (meta: RouteMeta) => renderMeta(meta, options).map(toHeadTag) };
+}

package/src/head.ts ADDED Viewed

@@ -0,0 +1,137 @@
+/**
+ * `<head>` management. Merges `@ultimat3/seo`'s output with per-route overrides, deduped
+ * by key so the last writer wins deterministically, and owns the one inlined script the
+ * framework allows on a 0kb `site/` route: the theme flip.
+ *
+ * The seo renderers are injected rather than imported so render stays testable without a
+ * catalog and so the tag vocabulary keeps exactly one owner (`@ultimat3/seo`).
+ */
+import type { RouteMeta } from '@ultimat3/seo';
+import { BudgetExceededError } from './errors';
+export type HeadTagKind = 'title' | 'base' | 'meta' | 'link' | 'script' | 'style';
+export interface HeadTag {
+  readonly kind: HeadTagKind;
+  /** Dedupe key. `title`, `meta:description`, `link:canonical`, `script:theme`. */
+  readonly key: string;
+  readonly attrs?: Readonly<Record<string, string | boolean>>;
+  /** Text content for `title`, `script`, `style`. */
+  readonly content?: string;
+}
+export type MetaRenderer = (meta: RouteMeta) => readonly HeadTag[];
+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. */
+  readonly renderLd?: LdRenderer;
+}
+const KIND_ORDER: readonly HeadTagKind[] = ['base', 'title', 'meta', 'link', 'style', 'script'];
+/**
+ * Later sources win per key. Order is by kind, then by first-seen position within the
+ * kind — stable output matters because the shell's bytes are content-hashed.
+ */
+export function mergeHead(...sources: readonly (readonly HeadTag[])[]): readonly HeadTag[] {
+  const byKey = new Map<string, HeadTag>();
+  const order: string[] = [];
+  for (const source of sources) {
+    for (const tag of source) {
+      if (!byKey.has(tag.key)) order.push(tag.key);
+      byKey.set(tag.key, tag);
+    }
+  }
+  const merged = order
+    .map((key) => byKey.get(key))
+    .filter((tag): tag is HeadTag => tag !== undefined);
+  return merged.sort((a, b) => KIND_ORDER.indexOf(a.kind) - KIND_ORDER.indexOf(b.kind));
+}
+/** Build the head for a route from its `meta` output plus explicit overrides. */
+export function headFromMeta(
+  meta: RouteMeta,
+  renderers: HeadRenderers,
+  overrides: readonly HeadTag[] = [],
+): readonly HeadTag[] {
+  const seoTags = renderers.renderMeta(meta);
+  const ld = renderers.renderLd?.(meta) ?? null;
+  const ldTags: readonly HeadTag[] =
+    ld === null
+      ? []
+      : [
+          {
+            kind: 'script',
+            key: 'script:ld+json',
+            attrs: { type: 'application/ld+json' },
+            content: ld,
+          },
+        ];
+  return mergeHead(seoTags, ldTags, overrides);
+}
+const VOID_KINDS = new Set<HeadTagKind>(['meta', 'link', 'base']);
+export function renderHead(tags: readonly HeadTag[]): string {
+  return tags.map(renderTag).join('');
+}
+function renderTag(tag: HeadTag): string {
+  const attrs = Object.entries(tag.attrs ?? {})
+    .map(([name, value]) =>
+      value === true ? ` ${name}` : ` ${name}="${escapeAttr(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}>`;
+}
+function escapeAttr(value: string): string {
+  return value.replace(/&/g, '&amp;').replace(/"/g, '&quot;').replace(/</g, '&lt;');
+}
+function escapeText(value: string): string {
+  return value.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+}
+export interface ThemeScriptOptions {
+  /** Attribute the tokens key off. Never a class, never a raw colour. */
+  readonly attribute?: string;
+  readonly storageKey?: string;
+  /** Hard cap; a theme script that grows past this is no longer "one inlined script". */
+  readonly maxBytes?: number;
+}
+export const THEME_SCRIPT_MAX_BYTES = 512;
+/**
+ * The injection point for the no-flash theme flip. It sets a semantic attribute and
+ * nothing else — every colour is a token, so the whole scheme swap is one attribute.
+ * Returns a `HeadTag` so it participates in dedupe like any other tag.
+ */
+export function themeScript(options: ThemeScriptOptions = {}): HeadTag {
+  const attribute = options.attribute ?? 'data-theme';
+  const storageKey = options.storageKey ?? 'x-theme';
+  const source =
+    `try{var t=localStorage.getItem("${storageKey}")||` +
+    `(matchMedia("(prefers-color-scheme: dark)").matches?"dark":"light");` +
+    `document.documentElement.setAttribute("${attribute}",t)}catch(e){}`;
+  const bytes = new TextEncoder().encode(source).byteLength;
+  const cap = options.maxBytes ?? THEME_SCRIPT_MAX_BYTES;
+  if (bytes > cap) {
+    throw new BudgetExceededError(
+      `the inlined theme script is ${bytes}b, over its ${cap}b cap — the only script a ` +
+        '0kb site/ route is allowed to ship',
+      'shrink the theme script, or raise maxBytes deliberately in the head config',
+    );
+  }
+  return { kind: 'script', key: 'script:theme', content: source };
+}

package/src/hydrate.ts ADDED Viewed

@@ -0,0 +1,121 @@
+/**
+ * The four hydration strategies, emitted as a per-island directive. `never` emits no
+ * script tag and no runtime at all — that is what keeps the `site/` baseline at 0kb.
+ * `interaction` replays the event that triggered the load, so a click during the fetch is
+ * answered instead of swallowed.
+ */
+import type { HydrateStrategy } from './route';
+export interface IslandDirective {
+  readonly islandId: string;
+  readonly strategy: HydrateStrategy;
+  /** Build-id-immutable module URL for this island's chunk. */
+  readonly entry: string;
+  /** Serialized props; must be JSON. */
+  readonly props?: Readonly<Record<string, unknown>>;
+  /** Events replayed for `interaction`. */
+  readonly events?: readonly string[];
+  /** `rootMargin` for `visible`. */
+  readonly rootMargin?: string;
+}
+export const DEFAULT_REPLAY_EVENTS = ['click', 'input', 'change', 'submit', 'keydown'] as const;
+/**
+ * The island's markup wrapper. `never` gets attributes only, so the HTML is inert and the
+ * runtime below is never emitted for that island.
+ */
+export function emitIslandAttributes(directive: IslandDirective): string {
+  const attrs = [`data-x-island="${directive.islandId}"`, `data-x-hydrate="${directive.strategy}"`];
+  if (directive.strategy !== 'never') {
+    attrs.push(`data-x-entry="${directive.entry}"`);
+    if (directive.rootMargin !== undefined) {
+      attrs.push(`data-x-margin="${directive.rootMargin}"`);
+    }
+    if (directive.events !== undefined && directive.events.length > 0) {
+      attrs.push(`data-x-events="${directive.events.join(' ')}"`);
+    }
+  }
+  return attrs.join(' ');
+}
+/** Props travel as a typed JSON script tag, never as an attribute (quoting hazards). */
+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>`
+  );
+}
+/** Strategies that need runtime support. `never` is absent by construction. */
+export function requiredStrategies(
+  directives: readonly IslandDirective[],
+): ReadonlySet<Exclude<HydrateStrategy, 'never'>> {
+  const set = new Set<Exclude<HydrateStrategy, 'never'>>();
+  for (const directive of directives) {
+    if (directive.strategy !== 'never') set.add(directive.strategy);
+  }
+  return set;
+}
+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;
+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)})}
+function each(s,f){Array.prototype.forEach.call(document.querySelectorAll(s),f)}
+`.trim();
+const RUNTIME_IDLE = `
+each('[data-x-hydrate="idle"]',function(el){
+var go=function(){boot(el)};
+if('requestIdleCallback'in window)requestIdleCallback(go,{timeout:2000});else setTimeout(go,1)})
+`.trim();
+const RUNTIME_VISIBLE = `
+each('[data-x-hydrate="visible"]',function(el){
+var io=new IntersectionObserver(function(es){es.forEach(function(en){
+if(en.isIntersecting){io.disconnect();boot(el)}})},{rootMargin:el.getAttribute('data-x-margin')||'200px'});
+io.observe(el)})
+`.trim();
+// Event replay: the listener is registered before the chunk exists, records the event that
+// woke the island, and re-dispatches it once mounted. Without this, the first click on a
+// cold island is silently lost — the failure users read as "the button does nothing".
+const RUNTIME_INTERACTION = `
+each('[data-x-hydrate="interaction"]',function(el){
+var evs=(el.getAttribute('data-x-events')||'click').split(' ');
+var q=[],done=false;
+var on=function(ev){if(done)return;q.push(ev);
+boot(el).then(function(){done=true;evs.forEach(function(n){el.removeEventListener(n,on,true)});
+q.forEach(function(ev){var c=new ev.constructor(ev.type,ev);ev.target.dispatchEvent(c)});q=[]})};
+evs.forEach(function(n){el.addEventListener(n,on,true)})})
+`.trim();
+const RUNTIME_PARTS: Readonly<Record<Exclude<HydrateStrategy, 'never'>, string>> = {
+  idle: RUNTIME_IDLE,
+  visible: RUNTIME_VISIBLE,
+  interaction: RUNTIME_INTERACTION,
+};
+/**
+ * Emit only the runtime the page's islands actually use. A page of `never` islands gets
+ * the empty string — an unused strategy must not cost a byte.
+ */
+export function hydrateRuntime(directives: readonly IslandDirective[]): string {
+  const needed = requiredStrategies(directives);
+  if (needed.size === 0) return '';
+  const parts = (['idle', 'visible', 'interaction'] as const)
+    .filter((strategy) => needed.has(strategy))
+    .map((strategy) => RUNTIME_PARTS[strategy]);
+  return `<script type="module">${RUNTIME_PRELUDE}\n${parts.join('\n')}</script>`;
+}
+/** Rough emitted size of the hydration runtime for a page, for the budget check. */
+export function hydrateRuntimeBytes(directives: readonly IslandDirective[]): number {
+  return new TextEncoder().encode(hydrateRuntime(directives)).byteLength;
+}