@junejs/server 0.1.3 → 0.2.0

package/src/favicon.ts

@@ -0,0 +1,325 @@
+// The default PNG icons: apple-touch-icon.png (180), icon.png (32), and a real
+// favicon.ico — the site name's first character on the same dark square as the
+// SVG favicon the pipeline serves. Build + dev host only (resvg-wasm, node:fs);
+// the worker never imports this, it serves the files `june build` wrote.
+//
+// A rasterizer has no browser fonts, so each icon picks a font for the script
+// of its character:
+//   Latin / Greek / Cyrillic caps, digits → Inter caps, bundled (offline, deterministic)
+//   Han → the Noto Sans CJK face for site.lang, via CLDR likely subtags:
+//         zh → SC, zh-TW / zh-Hant → TC, zh-HK / zh-MO / yue → HK, ja → JP, ko → KR;
+//         a lang with no Han signal (en) → SC, CLDR's default for Han
+//   kana → Noto Sans JP · Hangul → Noto Sans KR · emoji → Noto Emoji
+//   Arabic, Devanagari, Thai, … → that script's Noto Sans face
+// Non-bundled faces come from Google Fonts subset to that ONE character (a few
+// KB), cached on disk, so only the first build touches the network. Any miss
+// (offline, unknown script, a glyph the font lacks) draws the square without a
+// character, and never fails the build.
+import { createHash } from "node:crypto";
+import { existsSync, lstatSync } from "node:fs";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { createRequire } from "node:module";
+import { join } from "node:path";
+
+import type { DocumentConfig } from "@junejs/core/document";
+
+import { iconLetter } from "./icon-letter";
+
+type Site = DocumentConfig["site"];
+
+export const ICON_BG = "#1d1d1f";
+export const ICON_FG = "#fbfbf8";
+
+// Filenames the icons are served at (from the app root), and the public/ files
+// that mean the app brings its own icon — then June generates none.
+export const GENERATED_ICONS = ["apple-touch-icon.png", "icon.png", "favicon.ico", "icon-192.png", "icon-512.png"] as const;
+export type GeneratedIconFile = (typeof GENERATED_ICONS)[number];
+// The app's own main icon, in preference order: the first one present becomes
+// the page's favicon link (so none of them is ever silently unreferenced).
+const PRIMARY_ICON_FILES = ["favicon.svg", "icon.svg", "favicon.png", "icon.png", "favicon.ico"];
+const CUSTOM_ICON_FILES = [...PRIMARY_ICON_FILES, "apple-touch-icon.png"];
+const MANIFEST_FILES = ["manifest.webmanifest", "manifest.json", "site.webmanifest"];
+
+// `inPublic` for resolveIcons over an app's public/ dir. A symlinked public/ is
+// ignored, as the build and dev server ignore it.
+export function publicFileCheck(publicDir: string): (file: string) => boolean {
+  let real = false;
+  try {
+    real = lstatSync(publicDir).isDirectory();
+  } catch {
+    /* no public/ */
+  }
+  return (file) => real && existsSync(join(publicDir, file));
+}
+
+// Which icons the document links, and whether June generates them. `inPublic`
+// answers whether public/<file> exists. Generated when the app has no icon of
+// its own. Otherwise every icon file it has is linked: the first of
+// PRIMARY_ICON_FILES as the favicon (site.icon still wins in the document),
+// plus icon.png and apple-touch-icon.png when present.
+//
+// The web manifest: the app's own public/manifest.webmanifest (or
+// manifest.json) is linked whenever present. Otherwise June generates one only
+// alongside its own icons — an app with custom icons may have no 192/512 PNGs
+// for a manifest to point at.
+export function resolveIcons(
+  site: Site,
+  inPublic: (file: string) => boolean,
+): { generate: boolean; icons: NonNullable<DocumentConfig["icons"]> } {
+  const ownManifest = MANIFEST_FILES.find(inPublic);
+  const custom = Boolean(site.icon) || CUSTOM_ICON_FILES.some(inPublic);
+  if (!custom) {
+    return {
+      generate: true,
+      icons: {
+        png: "/icon.png",
+        appleTouch: "/apple-touch-icon.png",
+        manifest: ownManifest ? `/${ownManifest}` : "/manifest.webmanifest",
+        generated: !ownManifest,
+      },
+    };
+  }
+  const primary = PRIMARY_ICON_FILES.find(inPublic);
+  return {
+    generate: false,
+    icons: {
+      primary: primary ? `/${primary}` : undefined,
+      png: inPublic("icon.png") ? "/icon.png" : undefined,
+      appleTouch: inPublic("apple-touch-icon.png") ? "/apple-touch-icon.png" : undefined,
+      manifest: ownManifest ? `/${ownManifest}` : undefined,
+    },
+  };
+}
+
+const is = (re: RegExp) => (ch: string) => re.test(ch);
+const isBundled = is(/^[\p{Script=Latin}\p{Script=Greek}\p{Script=Cyrillic}0-9•]/u);
+const isEmoji = is(/^\p{Extended_Pictographic}/u);
+const isKana = is(/^[\p{Script=Hiragana}\p{Script=Katakana}]/u);
+const isHangul = is(/^\p{Script=Hangul}/u);
+const isHan = is(/^\p{Script=Han}/u);
+
+// Scripts with a Noto Sans face on Google Fonts, by Unicode script name.
+const NOTO_SCRIPTS = [
+  "Arabic", "Armenian", "Bengali", "Devanagari", "Ethiopic", "Georgian", "Gujarati", "Gurmukhi",
+  "Hebrew", "Kannada", "Khmer", "Lao", "Malayalam", "Myanmar", "Sinhala", "Tamil", "Telugu", "Thai",
+] as const;
+const NOTO_SCRIPT_RES = NOTO_SCRIPTS.map((s) => [s, new RegExp(`^\\p{Script=${s}}`, "u")] as const);
+
+// The Noto Sans CJK face whose Han glyph forms match `lang`. Resolved through
+// CLDR likely subtags (Intl.Locale#maximize) instead of a hand-picked region.
+export function hanFamily(lang: string | undefined): string {
+  let loc: Intl.Locale;
+  try {
+    loc = new Intl.Locale(lang || "und").maximize();
+  } catch {
+    return "Noto Sans SC";
+  }
+  if (loc.script === "Jpan") return "Noto Sans JP";
+  if (loc.script === "Kore") return "Noto Sans KR";
+  if (loc.script === "Hant") return loc.region === "HK" || loc.region === "MO" ? "Noto Sans HK" : "Noto Sans TC";
+  return "Noto Sans SC"; // Hans, or a language with no Han signal — CLDR's und-Hani is zh-Hans
+}
+
+// The Google Fonts family for a character; null = the bundled Inter caps;
+// undefined = no known face (draw the square alone).
+export function iconFamily(ch: string, lang: string | undefined): string | null | undefined {
+  if (!ch) return undefined;
+  if (isBundled(ch)) return null;
+  if (isEmoji(ch)) return "Noto Emoji";
+  if (isKana(ch)) return "Noto Sans JP";
+  if (isHangul(ch)) return "Noto Sans KR";
+  if (isHan(ch)) return hanFamily(lang);
+  const script = NOTO_SCRIPT_RES.find(([, re]) => re.test(ch))?.[0];
+  return script ? `Noto Sans ${script}` : undefined;
+}
+
+// Fetches a font subset: resolves to the TTF bytes, or null on any failure.
+export type FontFetcher = (family: string, text: string) => Promise<Uint8Array | null>;
+
+// A legacy Safari UA makes Google Fonts answer with TTF (resvg reads TTF/OTF,
+// not woff2) — the same trick @junejs/og uses.
+const LEGACY_UA =
+  "Mozilla/5.0 (Macintosh; U; Intel Mac OS X 10_6_8) AppleWebKit/533.21.1 (KHTML, like Gecko) Version/5.0.5 Safari/533.21.1";
+
+// Google Fonts, subset to `text`, cached under cacheDir by request URL so a
+// rebuild never refetches. timeoutMs bounds each request (offline builds fall
+// back quickly instead of hanging).
+export function googleFontFetcher(
+  cacheDir: string,
+  opts: { fetch?: typeof fetch; timeoutMs?: number } = {},
+): FontFetcher {
+  const doFetch = opts.fetch ?? fetch;
+  const timeoutMs = opts.timeoutMs ?? 3000;
+  return async (family, text) => {
+    const cssUrl = `https://fonts.googleapis.com/css2?family=${encodeURIComponent(family)}:wght@600&text=${encodeURIComponent(text)}`;
+    const file = join(cacheDir, createHash("sha256").update(cssUrl).digest("hex").slice(0, 32) + ".ttf");
+    try {
+      return new Uint8Array(await readFile(file));
+    } catch {
+      /* not cached */
+    }
+    try {
+      const signal = AbortSignal.timeout(timeoutMs);
+      const cssRes = await doFetch(cssUrl, { headers: { "User-Agent": LEGACY_UA }, signal });
+      if (!cssRes.ok) return null;
+      const url = (await cssRes.text()).match(/src: url\((.+?)\)/)?.[1];
+      if (!url) return null;
+      const fontRes = await doFetch(url, { signal });
+      if (!fontRes.ok) return null;
+      const bytes = new Uint8Array(await fontRes.arrayBuffer());
+      await mkdir(cacheDir, { recursive: true });
+      await writeFile(file, bytes);
+      return bytes;
+    } catch {
+      return null;
+    }
+  };
+}
+
+type ResvgModule = typeof import("@resvg/resvg-wasm");
+let resvgReady: Promise<ResvgModule> | undefined;
+function loadResvg(): Promise<ResvgModule> {
+  return (resvgReady ??= (async () => {
+    const mod = await import("@resvg/resvg-wasm");
+    const wasmPath = createRequire(import.meta.url).resolve("@resvg/resvg-wasm/index_bg.wasm");
+    await mod.initWasm(await readFile(wasmPath));
+    return mod;
+  })());
+}
+
+let bundledFont: Promise<Uint8Array> | undefined;
+const loadBundledFont = () =>
+  (bundledFont ??= readFile(new URL("../assets/icon-latin.ttf", import.meta.url)).then((b) => new Uint8Array(b)));
+const BUNDLED_FAMILY = "Inter";
+
+const escapeXml = (s: string) => s.replace(/[<>&"']/g, (c) => `&#${c.charCodeAt(0)};`);
+
+// Where the glyph goes on the 64×64 square: font size + origin, from its INK
+// box — not its em box — so every script sits optically centred at one size.
+// A probe render measures the ink; cap height and a CJK ideograph both come out
+// INK_H tall, and a wide glyph is held to INK_W. The ink box's corners stay
+// within 0.4 of the size from the centre, which is the maskable-icon safe zone,
+// so the manifest can mark the full-bleed art "maskable" (pinned in a test).
+const PROBE = 1000;
+export const INK_H = 28;
+export const INK_W = 40;
+type Placement = { family: string; font: Uint8Array; size: number; x: number; y: number };
+
+function inkBox(resvg: ResvgModule, ch: string, family: string, font: Uint8Array) {
+  const probe =
+    `<svg xmlns="http://www.w3.org/2000/svg" width="${PROBE}" height="${PROBE}">` +
+    `<text x="${PROBE / 2}" y="${PROBE * 0.7}" font-family="${family}" font-size="${PROBE * 0.6}">${escapeXml(ch)}</text></svg>`;
+  const r = new resvg.Resvg(probe, { font: { fontBuffers: [font], loadSystemFonts: false, defaultFontFamily: family } });
+  const bbox = r.getBBox();
+  const box = bbox && bbox.width > 0 && bbox.height > 0 ? { x: bbox.x, y: bbox.y, width: bbox.width, height: bbox.height } : null;
+  bbox?.free();
+  r.free();
+  return box;
+}
+
+// A private-use code point no subset font maps: whatever it draws is .notdef.
+const NOTDEF_PROBE = "";
+
+function place(resvg: ResvgModule, ch: string, family: string, font: Uint8Array): Placement | null {
+  const bbox = inkBox(resvg, ch, family, font);
+  if (!bbox) return null;
+  // A font without the glyph draws .notdef (tofu), which HAS ink — so compare
+  // with the font's own .notdef box. The same box means a missing glyph.
+  const notdef = inkBox(resvg, NOTDEF_PROBE, family, font);
+  if (notdef && notdef.x === bbox.x && notdef.y === bbox.y && notdef.width === bbox.width && notdef.height === bbox.height) {
+    return null;
+  }
+  const scale = Math.min(INK_H / bbox.height, INK_W / bbox.width);
+  const cx = bbox.x + bbox.width / 2 - PROBE / 2;
+  const cy = bbox.y + bbox.height / 2 - PROBE * 0.7;
+  return { family, font, size: PROBE * 0.6 * scale, x: 32 - cx * scale, y: 32 - cy * scale };
+}
+
+// The icon as SVG on a 64 grid. rounded=false for apple-touch-icon: iOS masks
+// the corners itself and wants a full-bleed square.
+function iconSvg(ch: string, p: Placement | null, rounded: boolean): string {
+  const glyph = p
+    ? `<text x="${p.x.toFixed(2)}" y="${p.y.toFixed(2)}" font-family="${p.family}" font-size="${p.size.toFixed(2)}" fill="${ICON_FG}">${escapeXml(ch)}</text>`
+    : "";
+  return (
+    `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" width="64" height="64">` +
+    `<rect width="64" height="64"${rounded ? ` rx="12"` : ""} fill="${ICON_BG}"/>${glyph}</svg>`
+  );
+}
+
+// A single-image .ico whose entry is a PNG (valid since Windows Vista; every
+// current browser reads it).
+export function pngToIco(png: Uint8Array, size: number): Uint8Array<ArrayBuffer> {
+  const out = new Uint8Array(22 + png.length);
+  const v = new DataView(out.buffer);
+  v.setUint16(2, 1, true); // type: icon
+  v.setUint16(4, 1, true); // one image
+  out[6] = size >= 256 ? 0 : size; // width
+  out[7] = size >= 256 ? 0 : size; // height
+  v.setUint16(10, 1, true); // colour planes
+  v.setUint16(12, 32, true); // bits per pixel
+  v.setUint32(14, png.length, true);
+  v.setUint32(18, 22, true); // image data offset
+  out.set(png, 22);
+  return out;
+}
+
+export type GeneratedIcons = {
+  "apple-touch-icon.png": Uint8Array<ArrayBuffer>;
+  "icon.png": Uint8Array<ArrayBuffer>;
+  "favicon.ico": Uint8Array<ArrayBuffer>;
+  // The web manifest's icons (Android home screen). Full-bleed like the apple
+  // icon: the glyph's ink stays inside the maskable safe zone (a centred circle
+  // of radius 0.4), so one image serves "any" and "maskable".
+  "icon-192.png": Uint8Array<ArrayBuffer>;
+  "icon-512.png": Uint8Array<ArrayBuffer>;
+  // What was drawn, for the build log and tests: the character and its font
+  // family, or family null when the square went out without one.
+  letter: string;
+  family: string | null;
+};
+
+export async function renderIcons(opts: {
+  site: Site;
+  fetchFont: FontFetcher;
+  warn?: (msg: string) => void;
+}): Promise<GeneratedIcons> {
+  const resvg = await loadResvg();
+  const ch = iconLetter(opts.site.name);
+  const family = iconFamily(ch, opts.site.lang);
+  let placement: Placement | null = null;
+  if (family === null) {
+    placement = place(resvg, ch, BUNDLED_FAMILY, await loadBundledFont());
+  } else if (family !== undefined) {
+    const font = await opts.fetchFont(family, ch);
+    if (font) placement = place(resvg, ch, family, font);
+  }
+  if (ch && !placement) {
+    opts.warn?.(
+      `[june] default icon: no font for "${ch}"${family ? ` (${family} unavailable — offline?)` : ""}; ` +
+        `drew the square without it. Set site.icon or add public/icon.png to use your own.`,
+    );
+  }
+  const fonts = placement ? [placement.font] : [];
+  const render = (size: number, rounded: boolean) => {
+    const r = new resvg.Resvg(iconSvg(ch, placement, rounded), {
+      fitTo: { mode: "width", value: size },
+      font: { fontBuffers: fonts, loadSystemFonts: false, defaultFontFamily: placement?.family ?? BUNDLED_FAMILY },
+    });
+    const image = r.render();
+    const png = image.asPng() as Uint8Array<ArrayBuffer>; // a JS-owned copy, not a view into wasm memory
+    image.free();
+    r.free();
+    return png;
+  };
+  const icon32 = render(32, true);
+  return {
+    "apple-touch-icon.png": render(180, false),
+    "icon.png": icon32,
+    "favicon.ico": pngToIco(icon32, 32),
+    "icon-192.png": render(192, false),
+    "icon-512.png": render(512, false),
+    letter: ch,
+    family: placement?.family ?? null,
+  };
+}

package/src/host.ts

@@ -42,7 +42,8 @@ export interface JuneHost {
   readonly name: "bun" | "node";
   serve(
     handler: (req: Request) => Promise<Response>,
-    opts: { port: number; earlyHints?: () => string[] },
+    // hostname: the address to bind. Absent = all interfaces (production, containers).
+    opts: { port: number; hostname?: string; earlyHints?: () => string[] },
   ): ServeHandle;
   // Spawn a module in a child runtime (the react-server Flight renderer, which
   // must run under a different module-resolution condition). Phase 4 supersedes
@@ -63,7 +64,7 @@ function bunHost(): JuneHost {
       // idleTimeout 0: Bun's 10s default kills quiet long-lived responses —
       // the dev live-reload SSE most visibly (the browser then reconnects,
       // reads it as a server restart, and reloads the page every 10s).
-      const server = Bun.serve({ port: opts.port, fetch: handler, idleTimeout: 0 });
+      const server = Bun.serve({ port: opts.port, hostname: opts.hostname, fetch: handler, idleTimeout: 0 });
       return { port: server.port ?? opts.port, stop: (force) => void server.stop(force) };
     },
     spawnModule(entry, args, opts) {
@@ -125,7 +126,7 @@ function nodeHost(): JuneHost {
           res.end("Internal Server Error");
         }
       });
-      server.listen(opts.port);
+      server.listen(opts.port, opts.hostname);
       return {
         get port() {
           const addr = server.address();

package/src/icon-letter.ts

@@ -0,0 +1,14 @@
+// The default icon's character — shared by the worker's SVG favicon
+// (pipeline.ts) and the build's PNG icons (favicon.ts), so both draw the same
+// one. Worker-safe: no node:* imports.
+
+// The name's first grapheme, uppercased. A grapheme — not charAt(0) — so an
+// emoji, a flag, or a character outside the BMP stays whole instead of
+// becoming half a surrogate pair. "" when the name has none.
+export function iconLetter(name: string | undefined): string {
+  const trimmed = (name ?? "").trim();
+  if (!trimmed) return "";
+  const first = new Intl.Segmenter(undefined, { granularity: "grapheme" }).segment(trimmed)[Symbol.iterator]().next()
+    .value?.segment;
+  return (first ?? "").toUpperCase();
+}

package/src/index.ts

@@ -81,6 +81,20 @@ export {
   type Resolved,
   type LayoutComponent,
 } from "./pipeline";
+// Connection auth helpers — turn an authenticated principal into a per-call
+// bearer token for an outbound connection (provider/mcp/openapi). The auth
+// INTEGRATION lives in the host layer by design, so these sit here (not in pure
+// @junejs/core). Generic + overridable; the Better Auth variant is structural
+// (adds no dependency).
+export {
+  linkedAccountAuth,
+  betterAuthAccessToken,
+  betterAuthAccountTokenStore,
+  type AccountTokenStore,
+  type LinkedAccountAuthOptions,
+  type ConnectionAuth,
+  type BetterAuthLike,
+} from "./connection-auth";
 export { createApp, type JuneApp, type CreateAppOptions } from "./app";
 export { createWorker, type WorkerManifest } from "./worker";
 export {
@@ -91,6 +105,14 @@ export {
   freezeConfig,
   type BuildResult,
 } from "./build";
+export {
+  generateAgentModule,
+  findAgentDir,
+  scanAgentDir,
+  emitAgentModule,
+  AGENT_MODULE_FILE,
+  type AgentDirScan,
+} from "./agent-compile";
 export { juneDeploy, type DeployResult } from "./deploy";
 export { migrateD1, wranglerD1, resolveD1Database, type D1Exec } from "./d1-migrate";
 export { startDevServer, type DevServer, type DevServerOptions } from "./dev";

package/src/isolate-local.ts

@@ -0,0 +1,33 @@
+// isolate-local.ts — read @junejs/db's `isolateLocal` WITHOUT a named import.
+//
+// Same hazard core-version.ts exists for: a NAMED import of an export the
+// resolved copy doesn't have dies at module LINK time with an unhelpful
+// SyntaxError, before any of our own diagnostics can run. `isolateLocal` is new
+// in @junejs/db 0.1.0-dev.2, and a version range cannot save us here — the
+// floor has to stay satisfiable by the workspace's own db (which is the very
+// version that lacks it), and `bun pm pack` rewrites a `workspace:*` dep to
+// whatever version it resolves, which can be OLDER still.
+//
+// So: namespace import + optional read, with a local fallback. Unlike the core
+// runtime contract, this one does NOT warrant throwing — isolate-scoped
+// memoization is a lifetime optimization, not a correctness contract. The
+// fallback memoizes in this module instance, so callers keep their cache; the
+// only thing lost against an older db is sharing one value across DUPLICATE
+// copies of the module (workspace symlinks), which costs a missed cache hit,
+// never a wrong answer.
+import * as juneDb from "@junejs/db";
+
+export type IsolateLocal = <T>(key: string | symbol, make: () => T) => T;
+
+// Exported for tests: the ambient read below can only ever see the workspace's
+// own (matching) db, so the degraded path needs a direct handle to be provable.
+export function makeIsolateLocalFallback(): IsolateLocal {
+  const values = new Map<string | symbol, unknown>();
+  return <T>(key: string | symbol, make: () => T): T => {
+    if (!values.has(key)) values.set(key, make());
+    return values.get(key) as T;
+  };
+}
+
+export const isolateLocal: IsolateLocal =
+  (juneDb as { isolateLocal?: IsolateLocal }).isolateLocal ?? makeIsolateLocalFallback();

package/src/llms-links.ts

@@ -0,0 +1,96 @@
+// /llms.txt links, collected from the routes themselves. Each route may export
+// `llms` (see LlmsEntry in @junejs/core/route): a static route defaults to one link
+// under "Pages" built from its static metadata; a dynamic route — a [param]
+// template an agent can't fetch — lists each real page it serves, or is skipped.
+// Links point at the markdown projection (<path>.md) unless the route turned md off,
+// so an agent reads the page rather than its HTML (llmstxt.org's recommendation).
+import type { LlmsLink, SitemapPage } from "@junejs/core/discovery";
+import type { LlmsEntry } from "@junejs/core/route";
+
+import type { RouteResolver } from "./pipeline";
+
+const DEFAULT_SECTION = "Pages";
+
+const mdPath = (path: string) => (path === "/" ? "/index.md" : `${path.replace(/\/+$/, "")}.md`);
+
+export async function collectLlmsLinks(origin: string, routes: string[], resolve: RouteResolver): Promise<LlmsLink[]> {
+  const links: LlmsLink[] = [];
+  const seen = new Set<string>();
+  for (const route of routes) {
+    // A dynamic template resolves against its own pattern ("/docs/[slug]" matches
+    // /docs/:slug), which is all we need: the route definition, not its data.
+    const resolved = await resolve(route);
+    if (!resolved || !("def" in resolved)) continue; // resource routes have no page to list
+    const { def } = resolved;
+    if (def.llms === false) continue;
+
+    const dynamic = route.includes("[");
+    const declared = typeof def.llms === "function" ? await def.llms() : def.llms;
+    const entries: LlmsEntry[] = declared ? (Array.isArray(declared) ? declared : [declared]) : dynamic ? [] : [{}];
+    // Static metadata only: a metadata FUNCTION needs loader data we don't run here.
+    const meta = typeof def.metadata === "object" ? def.metadata : undefined;
+
+    for (const entry of entries) {
+      const path = entry.path ?? (dynamic ? undefined : route);
+      if (!path) continue; // a dynamic entry must name its page
+      const url = origin + (def.md === false ? path : mdPath(path));
+      // dedupe on the FINAL url: "/a" and "/a/" both render /a.md, so they're one page
+      if (seen.has(url)) continue;
+      seen.add(url);
+      const own = path === route; // the route's own page → its metadata describes it
+      links.push({
+        title: entry.title ?? (own ? meta?.title : undefined) ?? path,
+        url,
+        description: entry.description ?? (own ? meta?.description : undefined),
+        section: entry.section ?? DEFAULT_SECTION,
+        optional: entry.optional === true,
+      });
+    }
+  }
+  return links;
+}
+
+// /sitemap.xml pages, enumerated like /llms.txt. A static route is one page; a
+// dynamic route lists its real pages via its `llms` entries (their `lastModified`
+// becomes <lastmod>) — the runtime-safe hook /llms.txt already runs. A route
+// that names none stays out: a [param] template isn't a URL. Resource routes
+// (route.*) are machine endpoints, not pages. `llms = false` keeps a static
+// route listed (its URL is known without entries); on a dynamic route it leaves
+// no entries, so its pages drop out of the runtime sitemap too.
+// `staticPaths` join in only when opts.staticPaths is set — the static() build's
+// prerender, the one place the route contract runs them. Even then they're
+// skipped under i18n: they arrive locale-prefixed, while the sitemap derives
+// each page's locale variants from its canonical path.
+export async function collectSitemapPages(
+  routes: string[],
+  resolve: RouteResolver,
+  opts: { i18n?: boolean; staticPaths?: boolean } = {},
+): Promise<SitemapPage[]> {
+  const pages = new Map<string, SitemapPage>();
+  const add = (path: string, lastModified?: string | Date) => {
+    const key = path === "/" ? "/" : path.replace(/\/+$/, "");
+    const prev = pages.get(key);
+    if (!prev) pages.set(key, lastModified ? { path: key, lastModified } : { path: key });
+    else if (lastModified && !prev.lastModified) prev.lastModified = lastModified;
+  };
+  for (const route of routes) {
+    const resolved = await resolve(route);
+    if (!resolved || !("def" in resolved)) continue;
+    const { def } = resolved;
+    const dynamic = route.includes("[");
+    const declared = def.llms ? (typeof def.llms === "function" ? await def.llms() : def.llms) : undefined;
+    const entries: LlmsEntry[] = declared ? (Array.isArray(declared) ? declared : [declared]) : [];
+    // A static route is exactly one URL — its own. An entry naming another path
+    // (an llms.txt pointer elsewhere) is not a page this route serves.
+    if (!dynamic) {
+      add(route, entries.find((e) => (e.path ?? route) === route)?.lastModified);
+      continue;
+    }
+    for (const e of entries) if (e.path) add(e.path, e.lastModified);
+    if (opts.staticPaths && !opts.i18n && def.staticPaths) {
+      const sp = typeof def.staticPaths === "function" ? await def.staticPaths() : def.staticPaths;
+      for (const p of sp) add(p);
+    }
+  }
+  return [...pages.values()];
+}

package/src/manifest.ts

@@ -0,0 +1,130 @@
+// The FREEZE, in-process: import route modules + layouts, build the manifest a
+// createWorker() can run immediately. Extracted from build.ts; used by
+// prerender and by the parity test (its render path is identical to the
+// Rolldown-bundled worker).
+
+import { existsSync } from "node:fs";
+import { basename, join } from "node:path";
+import { pathToFileURL } from "node:url";
+
+import { routeFromModule, type BrandedRoute } from "@junejs/core/route";
+import { freezeConfig } from "./config-freeze";
+import type { ExtraHandler, LayoutComponent, LoadingComponent, ResourceHandler } from "./pipeline";
+import { scanAppRoutes } from "./route-scan";
+import { findMiddlewareFile } from "./router";
+import { resolveBoundary } from "./segment";
+import type { WorkerManifest } from "./worker";
+
+export type ImportedLayout = { component: LayoutComponent; boundary: boolean };
+export async function importLayout(file: string): Promise<ImportedLayout | null> {
+  const mod = (await import(pathToFileURL(file).href)) as {
+    default?: LayoutComponent;
+    segmentBoundary?: unknown;
+  };
+  return typeof mod.default === "function"
+    ? { component: mod.default, boundary: mod.segmentBoundary === true }
+    : null;
+}
+
+export async function buildManifest(appRoot: string): Promise<WorkerManifest> {
+  const appDir = join(appRoot, "app");
+  const frozen = await freezeConfig(appRoot);
+  const scanned = await scanAppRoutes(appRoot);
+
+  const layoutCache = new Map<string, ImportedLayout | null>();
+  const loadCached = async (f: string): Promise<ImportedLayout | null> => {
+    if (!layoutCache.has(f)) layoutCache.set(f, await importLayout(f));
+    return layoutCache.get(f) ?? null;
+  };
+  // The chain (root→leaf) + boundary index + shell key, via the SHARED resolver
+  // (the one place the deepest-wins rule lives), so the frozen manifest and the
+  // dev resolver can't drift — the parity contract.
+  const componentsFor = async (
+    files: string[],
+  ): Promise<{ chain: LayoutComponent[]; boundaryIndex: number | null; key: string | null }> => {
+    const items = [];
+    for (const f of files) {
+      const c = await loadCached(f);
+      items.push({ file: f, entry: c?.component ?? null, boundary: !!c?.boundary });
+    }
+    return resolveBoundary(items);
+  };
+
+  const loadingCache = new Map<string, LoadingComponent | null>();
+  const loadingFor = async (file?: string): Promise<LoadingComponent | undefined> => {
+    if (!file) return undefined;
+    if (!loadingCache.has(file)) {
+      const loaded = await importLayout(file);
+      loadingCache.set(file, loaded ? (loaded.component as LoadingComponent) : null);
+    }
+    return loadingCache.get(file) ?? undefined;
+  };
+
+  const routes: Record<string, BrandedRoute> = {};
+  const dynamicRoutes: Array<{ pattern: string; def: BrandedRoute }> = [];
+  const resourceRoutes: Array<{ pattern: string; handler: ResourceHandler }> = [];
+  const generatedRoutes = scanned.filter((r) => r.generated).map((r) => r.path);
+  const layoutChains: Record<string, LayoutComponent[]> = {};
+  const layoutBoundaries: Record<string, { index: number; key: string }> = {};
+  const loadings: Record<string, LoadingComponent> = {};
+
+  for (const r of scanned) {
+    const mod = await import(pathToFileURL(r.file).href);
+    // Resource route (route.*): the default export is the Response handler.
+    if (r.resource) {
+      const handler = (mod as { default?: unknown }).default;
+      if (typeof handler === "function") resourceRoutes.push({ pattern: r.path, handler: handler as ResourceHandler });
+      continue;
+    }
+    const def = routeFromModule(mod);
+    if (!def) continue;
+    const { chain, boundaryIndex, key } = await componentsFor(r.layouts);
+    const loading = await loadingFor(r.loading);
+    if (r.dynamic) {
+      dynamicRoutes.push({ pattern: r.path, def });
+      layoutChains[r.path] = chain;
+    } else {
+      routes[r.path] = def;
+      layoutChains[r.path] = chain;
+    }
+    if (boundaryIndex !== null && key !== null) layoutBoundaries[r.path] = { index: boundaryIndex, key };
+    if (loading) loadings[r.path] = loading;
+  }
+
+  let extra: ExtraHandler | undefined;
+  const extraFile = findMiddlewareFile(appDir);
+  if (extraFile) {
+    const mod = (await import(pathToFileURL(extraFile).href)) as { default?: unknown };
+    if (typeof mod.default === "function") extra = mod.default as ExtraHandler;
+  }
+
+  // The durable agent's DO address (createWorker routes the chat endpoint by
+  // it). Set whenever an agent/ directory exists — the surface is inert without
+  // an env.AGENT binding, so in-process consumers (prerender, the parity test)
+  // are unaffected.
+  let agentName: string | undefined;
+  const agentDir = join(appDir, frozen.agent.runtime.dir);
+  if (frozen.agent.runtime.enabled && existsSync(agentDir)) {
+    const cfgFile = join(agentDir, "agent.ts");
+    const cfg = existsSync(cfgFile)
+      ? ((await import(pathToFileURL(cfgFile).href)).default as { name?: string } | undefined)
+      : undefined;
+    agentName = cfg?.name ?? basename(agentDir);
+  }
+
+  return {
+    routes,
+    dynamicRoutes,
+    resourceRoutes,
+    ...(generatedRoutes.length ? { generatedRoutes } : {}),
+    layoutChains,
+    layoutBoundaries,
+    loadings,
+    document: frozen.document,
+    agent: frozen.agent,
+    agentName,
+    i18n: frozen.i18n,
+    earlyHints: frozen.earlyHints,
+    extra,
+  };
+}