@junejs/server 0.0.22 → 0.0.25

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@junejs/server",
-  "version": "0.0.22",
+  "version": "0.0.25",
   "description": "June host adapters + dev server. Host-coupled; depends on the pure @junejs/core contract layer.",
   "type": "module",
   "license": "MIT",
@@ -30,8 +30,8 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@junejs/core": "0.0.22",
-    "@junejs/db": "0.0.22",
+    "@junejs/core": "0.0.25",
+    "@junejs/db": "0.0.25",
     "marked": "^18.0.5",
     "rolldown": "^1.1.0",
     "lightningcss": "^1.27.0"

package/src/app.ts

@@ -20,6 +20,7 @@ import { runWithTrace, type RequestTrace } from "@junejs/core/instrumentation";
 
 import { findMiddlewareFile, isResourceFile, listRoutes, matchRouteTree, resolveNotFound, routeFiles, type SegmentMatch } from "./router";
 import { createPipeline, type ExtraHandler, type LayoutComponent, type Pipeline, type Resolved, type ResourceHandler } from "./pipeline";
+import { resolveBoundary } from "./segment";
 import { memoizeResources } from "./resources";
 import { findClientEntry, bundleClientToString, CLIENT_SCRIPT_URL } from "./client-bundle";
 import { findGlobalCss, processCssCached, STYLES_URL } from "./css";
@@ -39,15 +40,25 @@ export type JuneApp = {
   earlyHints(): string[];
 };
 
-// Import a layout file's default export as a layout component (memoized).
-const layoutCache = new Map<string, LayoutComponent>();
-async function loadLayout(file: string): Promise<LayoutComponent | null> {
+// Import a layout file's default export as a layout component (memoized), plus
+// its static `segmentBoundary` flag — read from the module export WITHOUT
+// rendering the component, which is what lets the server slice the chain for a
+// segment-scoped fragment without paying the shell's render cost.
+type LoadedLayout = { component: LayoutComponent; boundary: boolean };
+const layoutCache = new Map<string, LoadedLayout | null>();
+async function loadLayout(file: string): Promise<LoadedLayout | null> {
   const cached = layoutCache.get(file);
-  if (cached) return cached;
-  const mod = (await import(pathToFileURL(file).href)) as { default?: LayoutComponent };
-  if (typeof mod.default !== "function") return null;
-  layoutCache.set(file, mod.default);
-  return mod.default;
+  if (cached !== undefined) return cached;
+  const mod = (await import(pathToFileURL(file).href)) as {
+    default?: LayoutComponent;
+    segmentBoundary?: unknown;
+  };
+  const result: LoadedLayout | null =
+    typeof mod.default === "function"
+      ? { component: mod.default, boundary: mod.segmentBoundary === true }
+      : null;
+  layoutCache.set(file, result);
+  return result;
 }
 
 // The nearest loading.tsx up the segment chain (deepest wins) → the streaming
@@ -64,14 +75,20 @@ async function nearestLoading(segments: SegmentMatch[]): Promise<React.Component
   return mod.default;
 }
 
-async function loadChain(segments: SegmentMatch[]): Promise<LayoutComponent[]> {
-  const chain: LayoutComponent[] = [];
+// The layout chain (root→leaf) plus the segment boundary, via the shared
+// resolver (the one place the deepest-wins rule + shell key live, so dev and the
+// frozen manifest can't drift).
+async function loadChain(
+  segments: SegmentMatch[],
+): Promise<{ chain: LayoutComponent[]; boundaryIndex: number | null; boundaryKey: string | null }> {
+  const items = [];
   for (const seg of segments) {
     if (!seg.layout) continue;
     const L = await loadLayout(seg.layout);
-    if (L) chain.push(L);
+    items.push({ file: seg.layout, entry: L?.component ?? null, boundary: !!L?.boundary });
   }
-  return chain;
+  const { chain, boundaryIndex, key } = resolveBoundary(items);
+  return { chain, boundaryIndex, boundaryKey: key };
 }
 
 export function createApp({ appDir: appDirInput, config = {} }: CreateAppOptions): JuneApp {
@@ -149,6 +166,7 @@ export function createApp({ appDir: appDirInput, config = {} }: CreateAppOptions
       extra,
       docConfig,
       agent,
+      i18n: config.i18n,
       routeList: routePaths,
       earlyHints: config.earlyHints,
       resources,
@@ -165,10 +183,13 @@ export function createApp({ appDir: appDirInput, config = {} }: CreateAppOptions
         }
         const def = routeFromModule(mod);
         if (!def) return null;
+        const { chain, boundaryIndex, boundaryKey } = await loadChain(match.segments);
         return {
           def,
           params: match.params,
-          chain: await loadChain(match.segments),
+          chain,
+          boundaryIndex,
+          boundaryKey,
           loading: await nearestLoading(match.segments),
         } satisfies Resolved;
       },

package/src/build.ts

@@ -29,9 +29,10 @@ import { buildLinkHeader } from "@junejs/core/discovery";
 import { routeFromModule, type BrandedRoute } from "@junejs/core/route";
 import { workers, type JuneAdapter, type ResourcePlan } from "./adapter";
 import type { DocumentConfig } from "@junejs/core/document";
-import { collection } from "./content";
+import { generateContentModule } from "./content";
 import { createWorker, type WorkerManifest } from "./worker";
 import { findMiddlewareFile } from "./router";
+import { resolveBoundary } from "./segment";
 import type { ExtraHandler, LayoutComponent, LoadingComponent, ResourceHandler } from "./pipeline";
 import { findClientEntry, bundleClientToFile, CLIENT_SCRIPT_URL } from "./client-bundle";
 import { cssTargets, findGlobalCss, minifyCss, processCss, STYLES_URL } from "./css";
@@ -112,29 +113,11 @@ export async function scanRoutes(
 export async function generateContent(appRoot: string): Promise<string[]> {
   const contentDir = join(appRoot, "content");
   if (!existsSync(contentDir)) return [];
-  const dirs = (await readdir(contentDir, { withFileTypes: true })).filter((e) => e.isDirectory());
-  if (dirs.length === 0) return [];
-
-  let out =
-    "// AUTO-GENERATED by `june build` — edit content/**/*.md, not this file.\n" +
-    "export type ContentEntry = { slug: string; data: Record<string, string | string[]>; body: string; original: string; html: string };\n";
-  const names: string[] = [];
-  for (const d of dirs) {
-    const entries = collection(join(contentDir, d.name)).map(({ slug, data, body, original, html }) => ({
-      slug,
-      data,
-      body,
-      original,
-      html,
-    }));
-    const constName = d.name.replace(/[^A-Za-z0-9]/g, "_").toUpperCase();
-    // Singular finder name: posts → post, otherwise <name>Entry.
-    const finder = d.name.endsWith("s") ? d.name.slice(0, -1) : `${d.name}Entry`;
-    out += `export const ${constName}: ContentEntry[] = ${JSON.stringify(entries, null, 2)};\n`;
-    out += `export const ${finder} = (slug: string): ContentEntry | null => ${constName}.find((p) => p.slug === slug) ?? null;\n`;
-    names.push(d.name);
-  }
-  await writeFile(join(appRoot, "app", "_content.ts"), out);
+  // Emission (incl. the per-locale layout) lives in ./content so it's pure and
+  // unit-testable; this stays the thin fs wrapper.
+  const { code, names } = generateContentModule(contentDir);
+  if (names.length === 0) return [];
+  await writeFile(join(appRoot, "app", "_content.ts"), code);
   return names;
 }
 
@@ -142,6 +125,7 @@ export async function generateContent(appRoot: string): Promise<string[]> {
 export async function freezeConfig(appRoot: string): Promise<{
   document: DocumentConfig;
   agent: WorkerManifest["agent"];
+  i18n: WorkerManifest["i18n"];
   earlyHints: string[];
   buildExternal: string[];
 }> {
@@ -163,14 +147,24 @@ export async function freezeConfig(appRoot: string): Promise<{
       styles: hasCss ? STYLES_URL : null,
     },
     agent: resolveAgent(cfg.agent),
+    // Pass i18n through as-is: the in-process buildManifest keeps a resolveLocale
+    // hook (parity test), and the codegen JSON.stringify below drops the function
+    // (worker hook support is the codegen pass — see the manifest field comment).
+    i18n: cfg.i18n,
     earlyHints: cfg.earlyHints ?? [],
     buildExternal: cfg.build?.external ?? [],
   };
 }
 
-async function importLayout(file: string): Promise<LayoutComponent | null> {
-  const mod = (await import(pathToFileURL(file).href)) as { default?: LayoutComponent };
-  return typeof mod.default === "function" ? mod.default : null;
+type ImportedLayout = { component: LayoutComponent; boundary: boolean };
+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;
 }
 
 // The FREEZE, in-process: import route modules + layouts, build the manifest a
@@ -181,21 +175,32 @@ export async function buildManifest(appRoot: string): Promise<WorkerManifest> {
   const frozen = await freezeConfig(appRoot);
   const scanned = (await scanRoutes(appDir)).sort((a, b) => a.path.localeCompare(b.path));
 
-  const layoutCache = new Map<string, LayoutComponent | null>();
-  const componentsFor = async (files: string[]): Promise<LayoutComponent[]> => {
-    const chain: LayoutComponent[] = [];
+  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) {
-      if (!layoutCache.has(f)) layoutCache.set(f, await importLayout(f));
-      const c = layoutCache.get(f) ?? null;
-      if (c) chain.push(c);
+      const c = await loadCached(f);
+      items.push({ file: f, entry: c?.component ?? null, boundary: !!c?.boundary });
     }
-    return chain;
+    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)) loadingCache.set(file, await importLayout(file) as LoadingComponent | null);
+    if (!loadingCache.has(file)) {
+      const loaded = await importLayout(file);
+      loadingCache.set(file, loaded ? (loaded.component as LoadingComponent) : null);
+    }
     return loadingCache.get(file) ?? undefined;
   };
 
@@ -203,6 +208,7 @@ export async function buildManifest(appRoot: string): Promise<WorkerManifest> {
   const dynamicRoutes: Array<{ pattern: string; def: BrandedRoute }> = [];
   const resourceRoutes: Array<{ pattern: string; handler: ResourceHandler }> = [];
   const layoutChains: Record<string, LayoutComponent[]> = {};
+  const layoutBoundaries: Record<string, { index: number; key: string }> = {};
   const loadings: Record<string, LoadingComponent> = {};
 
   for (const r of scanned) {
@@ -215,7 +221,7 @@ export async function buildManifest(appRoot: string): Promise<WorkerManifest> {
     }
     const def = routeFromModule(mod);
     if (!def) continue;
-    const chain = await componentsFor(r.layouts);
+    const { chain, boundaryIndex, key } = await componentsFor(r.layouts);
     const loading = await loadingFor(r.loading);
     if (r.dynamic) {
       dynamicRoutes.push({ pattern: r.path, def });
@@ -224,6 +230,7 @@ export async function buildManifest(appRoot: string): Promise<WorkerManifest> {
       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;
   }
 
@@ -239,9 +246,11 @@ export async function buildManifest(appRoot: string): Promise<WorkerManifest> {
     dynamicRoutes,
     resourceRoutes,
     layoutChains,
+    layoutBoundaries,
     loadings,
     document: frozen.document,
     agent: frozen.agent,
+    i18n: frozen.i18n,
     earlyHints: frozen.earlyHints,
     extra,
   };
@@ -268,6 +277,15 @@ export async function juneBuild(
   if (routes.length === 0) throw new Error(`no page.* routes found under ${appDir}`);
 
   const frozen = await freezeConfig(appRoot);
+  // The locales table freezes into the worker as data; a resolveLocale hook is a
+  // function and won't survive JSON codegen. URL-pinned resolution + the built-in
+  // negotiation chain still work in the worker — only the hook is dev-only for now.
+  if (frozen.i18n?.resolveLocale) {
+    console.warn(
+      "[june build] i18n.resolveLocale is not yet wired into the built worker " +
+        "(URL-pinned + built-in negotiation work; the hook runs in dev only).",
+    );
+  }
   // The deploy adapter packages the portable build for its target (default:
   // built-in workers()). It contributes the entry's export wrapper + emits the
   // deploy config.
@@ -360,7 +378,17 @@ export async function juneBuild(
     }
     return id;
   };
+  // `segmentBoundary` is a STATIC export, so read each layout module here (no
+  // render) to know its boundary flag AND whether it loads at all — codegen then
+  // FILTERS null layouts and computes the boundary index/key through the SAME
+  // shared resolver the dev/manifest paths use, so all three agree by
+  // construction (not by a fragile "indices happen to line up" assumption).
+  const layoutInfo = new Map<string, ImportedLayout | null>();
+  for (const f of new Set(routes.flatMap((r) => (r.resource ? [] : r.layouts)))) {
+    layoutInfo.set(f, await importLayout(f));
+  }
   const chains: string[] = [];
+  const boundaries: string[] = [];
   const loadings: string[] = [];
   const resources: string[] = [];
   routes.forEach((r, i) => {
@@ -374,12 +402,28 @@ export async function juneBuild(
     imports.push(`import * as r${i} from ${JSON.stringify(importPath(genDir, r.file))};`);
     if (r.dynamic) dynamics.push(`    { pattern: ${JSON.stringify(r.path)}, def: routeFromModule(r${i}) },`);
     else statics.push(`    ${JSON.stringify(r.path)}: routeFromModule(r${i}),`);
-    chains.push(`    ${JSON.stringify(r.path)}: [${r.layouts.map(layoutId).join(", ")}],`);
+    // entry = the emitted layout id (null layouts filtered out, so layoutId — and
+    // its import — is only emitted for real layouts), matching the runtime chain.
+    const { chain, boundaryIndex, key } = resolveBoundary(
+      r.layouts.map((f) => {
+        const info = layoutInfo.get(f) ?? null;
+        return { file: f, entry: info ? layoutId(f) : null, boundary: !!info?.boundary };
+      }),
+    );
+    chains.push(`    ${JSON.stringify(r.path)}: [${chain.join(", ")}],`);
+    if (boundaryIndex !== null && key !== null) {
+      boundaries.push(`    ${JSON.stringify(r.path)}: { index: ${boundaryIndex}, key: ${JSON.stringify(key)} },`);
+    }
     if (r.loading) loadings.push(`    ${JSON.stringify(r.path)}: ${loadingId(r.loading)},`);
   });
   const resourceRoutesField = resources.length
     ? `\n  resourceRoutes: [\n${resources.join("\n")}\n  ],`
     : "";
+  // Only emitted when some route declares a boundary, so boundary-less bundles
+  // stay byte-identical (additive manifest field, like resources).
+  const layoutBoundariesField = boundaries.length
+    ? `\n  layoutBoundaries: {\n${boundaries.join("\n")}\n  },`
+    : "";
 
   const builtExtraFile = findMiddlewareFile(appDir);
   if (builtExtraFile) {
@@ -444,12 +488,12 @@ ${dynamics.join("\n")}
   ],${resourceRoutesField}
   layoutChains: {
 ${chains.join("\n")}
-  },
+  },${layoutBoundariesField}
   loadings: {
 ${loadings.join("\n")}
   },
   document: ${JSON.stringify(frozen.document, null, 2).replace(/\n/g, "\n  ")},
-  agent: ${JSON.stringify(frozen.agent)},
+  agent: ${JSON.stringify(frozen.agent)},${frozen.i18n ? `\n  i18n: ${JSON.stringify(frozen.i18n)},` : ""}
   earlyHints: ${JSON.stringify(frozen.earlyHints)},${builtExtraFile ? "\n  extra," : ""}${resourcesField}
 });
 

package/src/content.ts

@@ -9,7 +9,7 @@
 // The last line is the differentiator: other frameworks' "markdown output" is
 // a lossy HTML→md conversion; June's .md projection IS the authored source.
 // Agents read exactly what the author wrote (frontmatter included).
-import { readdirSync, readFileSync, statSync } from "node:fs";
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
 import { join } from "node:path";
 import { marked } from "marked";
 
@@ -24,6 +24,9 @@ export type ContentEntry = {
   original: string;
   /** The body rendered to HTML (marked). */
   html: string;
+  /** The locale this entry was authored in — set for files under a `<locale>/`
+   *  subdir, undefined for the flat (default-locale) files. */
+  locale?: string;
 };
 
 // Minimal frontmatter: `key: value` lines between --- fences; `[a, b]` lists
@@ -56,7 +59,7 @@ function parseFrontmatter(raw: string): { data: ContentEntry["data"]; body: stri
 // mtime-keyed memo: correct under dev edits, free in production.
 const memo = new Map<string, { mtime: number; entry: ContentEntry }>();
 
-function loadEntry(file: string, slug: string): ContentEntry {
+function loadEntry(file: string, slug: string, locale?: string): ContentEntry {
   const mtime = statSync(file).mtimeMs;
   const hit = memo.get(file);
   if (hit && hit.mtime === mtime) return hit.entry;
@@ -69,34 +72,164 @@ function loadEntry(file: string, slug: string): ContentEntry {
     body,
     original,
     html: marked.parse(body, { async: false }) as string,
+    ...(locale ? { locale } : {}),
   };
   memo.set(file, { mtime, entry });
   return entry;
 }
 
-/** All entries in a content directory, newest-first by `date` (then slug). */
-export function collection(dir: string): ContentEntry[] {
-  const entries = readdirSync(dir)
-    .filter((f) => f.endsWith(".md") || f.endsWith(".mdx"))
-    .map((f) => loadEntry(join(dir, f), f.replace(/\.(md|mdx)$/, "")));
-  return entries.sort((a, b) => {
-    const da = String(a.data.date ?? "");
-    const db = String(b.data.date ?? "");
-    return db.localeCompare(da) || a.slug.localeCompare(b.slug);
-  });
+const isMd = (f: string) => f.endsWith(".md") || f.endsWith(".mdx");
+const slugOf = (f: string) => f.replace(/\.(md|mdx)$/, "");
+const byDate = (a: ContentEntry, b: ContentEntry) =>
+  String(b.data.date ?? "").localeCompare(String(a.data.date ?? "")) ||
+  a.slug.localeCompare(b.slug);
+
+// Per-locale content layout: flat `<dir>/*.md` are the DEFAULT-locale entries
+// (today's behavior, zero migration); each `<dir>/<locale>/*.md` subdir holds
+// that locale's variants. Isomorphic to the routing default (unprefixed) vs
+// locale (prefixed) split. A single-locale collection has no subdirs → `byLocale`
+// is empty and everything below collapses to the flat path.
+export type ScannedCollection = {
+  default: ContentEntry[];
+  byLocale: Record<string, ContentEntry[]>;
+};
+
+// BCP-47-shaped tag (language + optional script/region/variant subtags). Used to
+// decide whether a subdir is a locale bucket WITHOUT the i18n config: it accepts
+// `de`, `fr`, `zh-TW`, `pt-BR` and rejects `images`, `drafts`, `assets` — so a
+// stray folder can't become a phantom locale. Pass `knownLocales` for exact,
+// config-driven validation (the stronger check once the locale set is threaded in).
+const LOCALE_DIR = /^[a-z]{2,3}(-[A-Za-z0-9]{2,8})*$/;
+function isLocaleDir(name: string, known?: readonly string[]): boolean {
+  return known ? known.includes(name) : LOCALE_DIR.test(name);
 }
 
-/** One entry by slug, or null. */
-export function entry(dir: string, slug: string): ContentEntry | null {
-  // Guard the slug — it comes from the URL.
-  if (!/^[A-Za-z0-9._-]+$/.test(slug)) return null;
+export function scanCollection(dir: string, knownLocales?: readonly string[]): ScannedCollection {
+  const def: ContentEntry[] = [];
+  const byLocale: Record<string, ContentEntry[]> = {};
+  for (const ent of readdirSync(dir, { withFileTypes: true })) {
+    if (ent.isDirectory()) {
+      // Only a configured locale (or, without a list, a BCP-47-shaped name) is a
+      // locale bucket — a stray content/<col>/images/ is NOT a phantom "images".
+      if (!isLocaleDir(ent.name, knownLocales)) continue;
+      const locale = ent.name;
+      const sub = join(dir, locale);
+      byLocale[locale] = readdirSync(sub)
+        .filter(isMd)
+        .map((f) => loadEntry(join(sub, f), slugOf(f), locale))
+        .sort(byDate);
+    } else if (isMd(ent.name)) {
+      def.push(loadEntry(join(dir, ent.name), slugOf(ent.name)));
+    }
+  }
+  def.sort(byDate);
+  return { default: def, byLocale };
+}
+
+/** All entries in a content directory, newest-first by `date` (then slug). With
+ *  a `locale`, each entry is its locale variant when present, else the default
+ *  (so a reader sees the whole collection, localized where available). */
+export function collection(dir: string, locale?: string): ContentEntry[] {
+  const { default: def, byLocale } = scanCollection(dir);
+  if (!locale || !byLocale[locale]) return def;
+  const variants = new Map(byLocale[locale].map((e) => [e.slug, e]));
+  return def.map((e) => variants.get(e.slug) ?? e).sort(byDate);
+}
+
+// Probe `<dir>/<slug>.{md,mdx}`, tagging the result with `locale`. null if absent.
+function probe(dir: string, slug: string, locale?: string): ContentEntry | null {
   for (const ext of [".md", ".mdx"]) {
-    const file = join(dir, slug + ext);
     try {
-      return loadEntry(file, slug);
+      return loadEntry(join(dir, slug + ext), slug, locale);
     } catch {
       /* try next ext */
     }
   }
   return null;
 }
+
+/** One entry by slug, or null. With a `locale`, prefer `<dir>/<locale>/<slug>`,
+ *  falling back to the flat default (a dev-warn flags a partial translation).
+ *  `fallback: false` is STRICT — a missing variant returns null (so a route can
+ *  404 rather than serve default-language content). */
+export function entry(
+  dir: string,
+  slug: string,
+  locale?: string,
+  opts?: { fallback?: boolean },
+): ContentEntry | null {
+  // Guard the slug — it comes from the URL.
+  if (!/^[A-Za-z0-9._-]+$/.test(slug)) return null;
+  if (!locale) return probe(dir, slug);
+  const variant = probe(join(dir, locale), slug, locale);
+  if (variant) return variant;
+  if (opts?.fallback === false) return null; // strict — no default-language bleed
+  const fallback = probe(dir, slug);
+  // The locale is otherwise translated here, but not this slug → a gap worth a
+  // dev signal (silent in production builds, where NODE_ENV is baked).
+  if (fallback && existsSync(join(dir, locale))) {
+    console.warn(`[june content] ${slug}: no "${locale}" variant — served default`);
+  }
+  return fallback;
+}
+
+// Generate the frozen `app/_content.ts` module text from `content/<collection>/`.
+// The FREEZE that removes node:fs from the worker graph: routes import frozen
+// entries + finders instead of reading the filesystem at request time.
+//
+// Off by absence: a collection with no `<locale>/` subdirs emits EXACTLY today's
+// shape (`POSTS` array + `post(slug)` finder) — single-locale apps are unchanged.
+// A collection WITH locale subdirs additionally emits a slug→locale→entry map, a
+// locale-aware `post(slug, locale?)` finder (variant → flat default, dev-warn on a
+// partial-translation miss, tree-shaken in production), and a locale-merged
+// `posts(locale?)` lister.
+export function generateContentModule(
+  contentDir: string,
+  knownLocales?: readonly string[],
+): { code: string; names: string[] } {
+  const strip = (e: ContentEntry) => ({
+    slug: e.slug,
+    data: e.data,
+    body: e.body,
+    original: e.original,
+    html: e.html,
+    ...(e.locale ? { locale: e.locale } : {}),
+  });
+  const dirs = readdirSync(contentDir, { withFileTypes: true }).filter((e) => e.isDirectory());
+  const names: string[] = [];
+  let anyLocale = false;
+  let body = "";
+  for (const d of dirs) {
+    const { default: def, byLocale } = scanCollection(join(contentDir, d.name), knownLocales);
+    const CONST = d.name.replace(/[^A-Za-z0-9]/g, "_").toUpperCase();
+    // Singular finder name: posts → post, otherwise <name>Entry.
+    const finder = d.name.endsWith("s") ? d.name.slice(0, -1) : `${d.name}Entry`;
+    body += `export const ${CONST}: ContentEntry[] = ${JSON.stringify(def.map(strip), null, 2)};\n`;
+    if (Object.keys(byLocale).length === 0) {
+      body += `export const ${finder} = (slug: string): ContentEntry | null => ${CONST}.find((p) => p.slug === slug) ?? null;\n`;
+    } else {
+      anyLocale = true;
+      const map: Record<string, Record<string, unknown>> = {};
+      for (const [loc, entries] of Object.entries(byLocale)) {
+        for (const e of entries) (map[loc] ??= {})[e.slug] = strip(e);
+      }
+      body += `const ${CONST}_L: Record<string, Record<string, ContentEntry>> = ${JSON.stringify(map, null, 2)};\n`;
+      body +=
+        `export const ${finder} = (slug: string, locale?: string, opts?: { fallback?: boolean }): ContentEntry | null => {\n` +
+        `  const v = locale ? ${CONST}_L[locale]?.[slug] : undefined;\n` +
+        `  if (v) return v;\n` +
+        `  if (opts?.fallback === false) return null;\n` +
+        `  const d = ${CONST}.find((p) => p.slug === slug) ?? null;\n` +
+        `  if (process.env.NODE_ENV !== "production" && locale && ${CONST}_L[locale] && d) console.warn(\`[june content] ${d.name}/\${slug}: no "\${locale}" variant — served default\`);\n` +
+        `  return d;\n};\n`;
+      body += `export const ${d.name} = (locale?: string): ContentEntry[] => locale && ${CONST}_L[locale] ? ${CONST}.map((p) => ${CONST}_L[locale]![p.slug] ?? p) : ${CONST};\n`;
+    }
+    names.push(d.name);
+  }
+  const entryType = anyLocale
+    ? "export type ContentEntry = { slug: string; data: Record<string, string | string[]>; body: string; original: string; html: string; locale?: string };\n"
+    : "export type ContentEntry = { slug: string; data: Record<string, string | string[]>; body: string; original: string; html: string };\n";
+  const code =
+    "// AUTO-GENERATED by `june build` — edit content/**/*.md, not this file.\n" + entryType + body;
+  return { code, names };
+}

package/src/dev-reload.ts

@@ -18,6 +18,7 @@ const SCRIPT_PATH = "/__june/reload.js";
 const RELOAD_JS = `// june dev live-reload: reconnect-after-drop → reload; "css" event → hot-swap
 (() => {
   let dropped = false;
+  let es;
   const swapCss = () => {
     document.querySelectorAll('link[rel="stylesheet"]').forEach((old) => {
       const u = new URL(old.href);
@@ -33,7 +34,7 @@ const RELOAD_JS = `// june dev live-reload: reconnect-after-drop → reload; "cs
     });
   };
   const connect = () => {
-    const es = new EventSource(${JSON.stringify(EVENTS_PATH)});
+    es = new EventSource(${JSON.stringify(EVENTS_PATH)});
     es.addEventListener("open", () => {
       if (dropped) {
         // push-HMR: morph the freshly-restarted page in place (state survives);
@@ -58,6 +59,11 @@ const RELOAD_JS = `// june dev live-reload: reconnect-after-drop → reload; "cs
       }
     });
   };
+  // Release the SSE on navigation. In MPA mode every click is a full reload that
+  // opens a fresh EventSource; without this the old connection lingers and, since
+  // each held SSE consumes one of the browser's ~6 HTTP/1.1 slots per host, rapid
+  // navigation saturates them — further page loads stall (pending) / 503.
+  addEventListener("pagehide", () => { try { es && es.close(); } catch (e) {} });
   connect();
 })();
 `;

package/src/index.ts

@@ -50,6 +50,21 @@ export {
 } from "./router";
 export { installAsyncContext } from "./instrumentation";
 export { negotiate, type Negotiated } from "./negotiate";
+// Locale routing (Layer 1). The pure host-resolution layer lives in @junejs/core;
+// re-exported here so apps build locale links with `localeHref` off the ONE handle.
+export {
+  localeHref,
+  resolveRequestLocale,
+  matchPinnedLocale,
+  negotiateLocale,
+  parseAcceptLanguage,
+  localeDir,
+  dirForLang,
+  LOCALE_COOKIE,
+  type I18nConfig,
+  type LocaleConfig,
+  type LocaleMatch,
+} from "@junejs/core/i18n";
 export {
   createPipeline,
   type Pipeline,

package/src/negotiate.ts

@@ -11,7 +11,7 @@ import type { RenderTarget } from "@junejs/core/route";
 // The fragment media type + title header are the client-router wire protocol —
 // defined once in @junejs/core so the browser router and this negotiator share
 // the exact strings. Re-exported so existing server-side importers are unaffected.
-export { FRAGMENT_ACCEPT, TITLE_HEADER } from "@junejs/core/nav-protocol";
+export { FRAGMENT_ACCEPT, TITLE_HEADER, SEGMENT_HEADER } from "@junejs/core/nav-protocol";
 
 const EXT_TARGET: Record<string, RenderTarget> = {
   ".json": "json",
@@ -31,8 +31,13 @@ export type Negotiated = {
   speculative: boolean;
 };
 
-export function negotiate(url: URL, request: Request): Negotiated {
-  let pathname = url.pathname;
+// `basePath` overrides the pathname to negotiate (defaults to url.pathname). The
+// i18n step strips the locale prefix off the FRONT of url.pathname first and
+// passes the remainder here, so extension/Accept negotiation runs on the route
+// path, not the locale-prefixed one. url.pathname stays the raw request path.
+export function negotiate(url: URL, request: Request, basePath?: string): Negotiated {
+  const original = basePath ?? url.pathname;
+  let pathname = original;
   let target: RenderTarget | null = null;
 
   for (const [ext, t] of Object.entries(EXT_TARGET)) {
@@ -53,7 +58,7 @@ export function negotiate(url: URL, request: Request): Negotiated {
     // A bare projection on the root — `/.md`, `/.json` — is NOT a real URL (the
     // home surface is `/index.md`). Stripping the extension collapses it to "/",
     // so steer it back to the literal path: no route matches → 404.
-    pathname = url.pathname;
+    pathname = original;
   }
 
   if (!target) {

package/src/pipeline.ts

@@ -37,9 +37,31 @@ import { mcpHandler, mcpTools } from "@junejs/core/mcp";
 
 import { ensureScope, runInScope } from "@junejs/db";
 import type { AgentConfig } from "@junejs/core/config";
+import {
+  LOCALE_COOKIE,
+  localeAlternates,
+  localeDir,
+  matchPinnedLocale,
+  negotiateLocale,
+  type I18nConfig,
+  type LocaleAlternate,
+} from "@junejs/core/i18n";
 import type { Resources } from "@junejs/core/resources";
 
-import { negotiate, TITLE_HEADER } from "./negotiate";
+import { negotiate, TITLE_HEADER, SEGMENT_HEADER } from "./negotiate";
+
+// Minimal Cookie-header read for the locale negotiation chain (no dependency on
+// an auth/cookie integration — i18n must stand alone).
+function readCookie(request: Request, name: string): string | undefined {
+  const header = request.headers.get("cookie");
+  if (!header) return undefined;
+  for (const part of header.split(";")) {
+    const eq = part.indexOf("=");
+    if (eq === -1) continue;
+    if (part.slice(0, eq).trim() === name) return decodeURIComponent(part.slice(eq + 1).trim());
+  }
+  return undefined;
+}
 
 export type LayoutComponent = React.ComponentType<{ children: React.ReactNode }>;
 export type LoadingComponent = React.ComponentType;
@@ -54,6 +76,17 @@ export type Resolved = {
   // into streaming Suspense: the shell + this fallback flush before load()
   // resolves, then the view streams in.
   loading?: React.ComponentType;
+  // Segment-scoped fragments: the index in `chain` of the boundary layout (the
+  // one exporting `segmentBoundary` and rendering <JuneOutlet>), deepest wins.
+  // A soft-nav fragment then renders only chain.slice(boundaryIndex + 1) — the
+  // boundary layout's own markup (the persistent shell) is NOT re-rendered.
+  // null/undefined → whole-chain fragment (the default). Full documents always
+  // render the whole chain regardless, so a hard load is unaffected.
+  boundaryIndex?: number | null;
+  // The shell's identity key (which boundary layout owns it). Stamped on
+  // [data-june-root] (full load) and sent as the SEGMENT_HEADER (fragment) so the
+  // client morphs a fragment only into the shell it belongs to. Set iff boundaryIndex is.
+  boundaryKey?: string | null;
 };
 
 // A RESOURCE route (app/**/route.*): a handler returning a raw Response — binary,
@@ -73,6 +106,9 @@ export type RouteResolver = (pathname: string) => Promise<Resolved | ResolvedRes
 export type PipelineConfig = {
   docConfig: DocumentConfig;
   agent: AgentConfig;
+  // Locale routing config (june.config.ts `i18n`). Absent → no locale handling:
+  // the resolution step below never runs and ctx.locale stays undefined.
+  i18n?: I18nConfig;
   // The route list for discovery surfaces (sitemap / llms.txt). Async so dev can
   // re-scan the filesystem; the worker returns a frozen array.
   routeList: () => Promise<string[]> | string[];
@@ -171,11 +207,37 @@ export function createPipeline(cfg: PipelineConfig): Pipeline {
     return headers;
   }
 
+  // The document language + writing direction for one render. lang = the resolved
+  // locale (ctx.locale) when i18n is on, else the site.lang floor, else "en"; dir
+  // derives from it (a LocaleConfig.dir override wins). LTR → dir undefined, so
+  // single-locale pages stay byte-identical.
+  function langDir(locale: string | undefined): { lang: string; dir?: "ltr" | "rtl" } {
+    const lang = locale ?? docConfig.site.lang ?? "en";
+    return { lang, dir: localeDir(lang, cfg.i18n) };
+  }
+
+  // rel="alternate" hreflang links for this page's locale variants. Built from the
+  // locale-STRIPPED route path (so every locale's URL is generated correctly) and
+  // the current host (cross-origin locales come back absolute). undefined when
+  // i18n is off → single-locale pages emit no hreflang.
+  function alternatesFor(ctx: RouteContext): LocaleAlternate[] | undefined {
+    if (!cfg.i18n) return undefined;
+    const pinned = matchPinnedLocale(cfg.i18n, ctx.url.host, ctx.url.pathname);
+    const routePath = pinned ? pinned.pathname : ctx.url.pathname;
+    return localeAlternates(cfg.i18n, routePath, {
+      currentHost: ctx.url.host,
+      protocol: ctx.url.protocol.replace(":", ""),
+    });
+  }
+
   async function renderDocument(
     node: React.ReactNode,
     metadata: Metadata | undefined,
     status: number,
     chain: LayoutComponent[],
+    locale?: string,
+    boundaryKey?: string | null,
+    alternates?: LocaleAlternate[],
   ): Promise<Response> {
     // Wrap root→leaf: chain[0] is outermost.
     const wrapped = chain.reduceRight<React.ReactNode>(
@@ -183,7 +245,14 @@ export function createPipeline(cfg: PipelineConfig): Pipeline {
       node,
     );
     const stream = await renderToReadableStream(
-      React.createElement(Document, { config: docConfigForRender(), metadata, children: wrapped }),
+      React.createElement(Document, {
+        config: docConfigForRender(),
+        metadata,
+        children: wrapped,
+        shellKey: boundaryKey, // stamps data-june-shell on [data-june-root]
+        alternates,
+        ...langDir(locale),
+      }),
     );
     await stream.allReady; // fully resolved markup (no streamed Suspense fallbacks)
     // React 19 emits <!DOCTYPE html> itself for an <html> root — don't prepend a
@@ -201,8 +270,20 @@ export function createPipeline(cfg: PipelineConfig): Pipeline {
     node: React.ReactNode,
     metadata: Metadata | undefined,
     chain: LayoutComponent[],
+    boundaryIndex?: number | null,
+    boundaryKey?: string | null,
   ): Promise<Response> {
-    const wrapped = chain.reduceRight<React.ReactNode>(
+    // ONE gate: a fragment is segment-scoped iff it has both a boundary index AND
+    // a shell key. They always travel together (resolveBoundary returns both or
+    // neither), but tying the content-slice and the header to a single flag means
+    // a content-only body can never go out without its key (which would wipe the
+    // shell) nor a key without a content-only body.
+    const segmented = typeof boundaryIndex === "number" && boundaryKey != null;
+    // Segment-scoped renders ONLY the chain below the boundary layout (its
+    // children = the <JuneOutlet> contents on a full load), so the boundary
+    // layout's shell markup is never produced. Whole-chain wraps the entire chain.
+    const inside = segmented ? chain.slice(boundaryIndex! + 1) : chain;
+    const wrapped = inside.reduceRight<React.ReactNode>(
       (acc, L) => React.createElement(L, null, acc),
       node,
     );
@@ -212,6 +293,9 @@ export function createPipeline(cfg: PipelineConfig): Pipeline {
     const headers = new Headers({ "content-type": "text/html; charset=utf-8" });
     const title = typeof metadata?.title === "string" ? metadata.title : undefined;
     if (title) headers.set(TITLE_HEADER, title);
+    // The shell key tells the client which shell this content-only fragment is
+    // for; it morphs the outlet only when that matches the mounted shell.
+    if (segmented) headers.set(SEGMENT_HEADER, boundaryKey!);
     return new Response(html, { status: 200, headers });
   }
 
@@ -233,7 +317,7 @@ export function createPipeline(cfg: PipelineConfig): Pipeline {
     loadPromise: Promise<unknown>,
     ctx: RouteContext,
   ): Promise<Response> {
-    const { def, chain, loading: Loading } = resolved;
+    const { def, chain, loading: Loading, boundaryKey } = resolved;
     const leaf = React.createElement(StreamedView, { loadPromise, def, ctx });
     const boundary = React.createElement(
       Suspense,
@@ -246,7 +330,14 @@ export function createPipeline(cfg: PipelineConfig): Pipeline {
     );
     const metadata = typeof def.metadata === "object" ? def.metadata : undefined;
     const stream = await renderToReadableStream(
-      React.createElement(Document, { config: docConfigForRender(), metadata, children: wrapped }),
+      React.createElement(Document, {
+        config: docConfigForRender(),
+        metadata,
+        children: wrapped,
+        shellKey: boundaryKey, // stamps data-june-shell on [data-june-root]
+        alternates: alternatesFor(ctx),
+        ...langDir(ctx.locale),
+      }),
       { onError: (e: unknown) => console.error("[june] streaming render error:", e) },
     );
     // NO allReady — return the live stream (shell first). React 19 streams the
@@ -254,7 +345,11 @@ export function createPipeline(cfg: PipelineConfig): Pipeline {
     return new Response(stream, { status: 200, headers: htmlHeaders() });
   }
 
-  function notFoundResponse(target: RenderTarget, pathname: string): Promise<Response> | Response {
+  function notFoundResponse(
+    target: RenderTarget,
+    pathname: string,
+    locale?: string,
+  ): Promise<Response> | Response {
     // Data clients get a JSON 404; humans get the rendered NotFound document.
     return target !== "view"
       ? Response.json({ error: "Not Found", path: pathname }, { status: 404 })
@@ -263,6 +358,7 @@ export function createPipeline(cfg: PipelineConfig): Pipeline {
           { title: "Not found", robots: "noindex" },
           404,
           [],
+          locale,
         );
   }
 
@@ -293,15 +389,15 @@ export function createPipeline(cfg: PipelineConfig): Pipeline {
     data: unknown,
     ctx: RouteContext,
   ): Promise<Response> {
-    const { def, chain } = resolved;
+    const { def, chain, boundaryIndex, boundaryKey } = resolved;
     // A projection declared `false` is disabled → 404 (and absent from discovery).
     // "fragment" isn't a declarable projection (it's the view rendered without the
     // shell), so it's never disabled — exclude it from the check.
     if (target !== "fragment" && def[target] === false) {
-      return notFoundResponse(target, ctx.url.pathname);
+      return notFoundResponse(target, ctx.url.pathname, ctx.locale);
     }
 
-    const res = await renderTarget(target, def, data, ctx, chain);
+    const res = await renderTarget(target, def, data, ctx, chain, boundaryIndex, boundaryKey);
     // Every projection here is chosen by the Accept header at the SAME url (a full
     // page, its fragment, its .md and .json all live at the clean path). Without
     // Vary, a shared/browser cache can hand a soft-nav fragment to a real page
@@ -317,6 +413,8 @@ export function createPipeline(cfg: PipelineConfig): Pipeline {
     data: unknown,
     ctx: RouteContext,
     chain: LayoutComponent[],
+    boundaryIndex?: number | null,
+    boundaryKey?: string | null,
   ): Promise<Response> {
     if (target === "md") return renderMarkdown(def, data, ctx);
     if (target === "json") {
@@ -326,8 +424,11 @@ export function createPipeline(cfg: PipelineConfig): Pipeline {
     }
     const node = provideLoaderData(data, def.view ? def.view(data, ctx) : null);
     const meta = resolveMeta(def, data, ctx);
-    if (target === "fragment") return renderFragment(node, meta, chain);
-    return renderDocument(node, meta, 200, chain);
+    // Only the fragment projection narrows to a segment; the full document always
+    // renders the whole chain (a hard load of the URL is never segment-scoped) —
+    // but it stamps the shell key so the client knows which shell is mounted.
+    if (target === "fragment") return renderFragment(node, meta, chain, boundaryIndex, boundaryKey);
+    return renderDocument(node, meta, 200, chain, ctx.locale, boundaryKey, alternatesFor(ctx));
   }
 
   async function discovery(url: URL): Promise<Response | null> {
@@ -340,7 +441,10 @@ export function createPipeline(cfg: PipelineConfig): Pipeline {
       case "/robots.txt":
         return text(robotsTxt(url.origin), "text/plain; charset=utf-8");
       case "/sitemap.xml":
-        return text(sitemapXml(url.origin, await cfg.routeList()), "application/xml; charset=utf-8");
+        return text(
+          sitemapXml(url.origin, await cfg.routeList(), cfg.i18n),
+          "application/xml; charset=utf-8",
+        );
       case "/.well-known/api-catalog":
         return text(JSON.stringify(apiCatalog(url.origin, agent)), "application/linkset+json");
       case "/.well-known/mcp/server-card.json":
@@ -383,10 +487,35 @@ export function createPipeline(cfg: PipelineConfig): Pipeline {
         return letterFavicon(docConfig.site.name);
       }
 
+      // --- locale resolution (before routing) ------------------------------
+      // host/path → locale, stripping the locale prefix off the front so the
+      // router matches the bare route path. Only runs when `i18n` is configured.
+      let locale: string | undefined;
+      let routeBase = url.pathname;
+      if (cfg.i18n) {
+        const pinned = matchPinnedLocale(cfg.i18n, url.host, url.pathname);
+        if (pinned) {
+          locale = pinned.locale;
+          routeBase = pinned.pathname;
+        } else {
+          // Ambiguous (bare path on the default origin): the resolveLocale hook
+          // gets first say, then the built-in chain. The hook runs ONLY here —
+          // never when the URL already pinned the locale.
+          const override = cfg.i18n.resolveLocale?.({ url, headers: request.headers });
+          locale =
+            override && cfg.i18n.locales[override]
+              ? override
+              : negotiateLocale(cfg.i18n, {
+                  acceptLanguage: request.headers.get("accept-language"),
+                  cookie: readCookie(request, LOCALE_COOKIE),
+                });
+        }
+      }
+
       // --- routes ----------------------------------------------------------
-      const { target, pathname, speculative } = negotiate(url, request);
+      const { target, pathname, speculative } = negotiate(url, request, routeBase);
       const resolved = await cfg.resolve(pathname);
-      if (!resolved) return notFoundResponse(target, pathname);
+      if (!resolved) return notFoundResponse(target, pathname, locale);
 
       // ctx is identity/request only; db/kv/blob are ambient (read from the
       // request scope this whole handler runs inside — see runInScope below).
@@ -395,6 +524,7 @@ export function createPipeline(cfg: PipelineConfig): Pipeline {
         url,
         params: resolved.params,
         target,
+        locale,
         speculative,
       };
 
@@ -416,7 +546,7 @@ export function createPipeline(cfg: PipelineConfig): Pipeline {
         data = resolved.def.load ? await resolved.def.load(ctx) : undefined;
       } catch {
         // unknown slug etc. → 404 (segment error boundaries are a later milestone)
-        return notFoundResponse(target, pathname);
+        return notFoundResponse(target, pathname, locale);
       }
       return renderProjection(resolved, target, data, ctx);
   }

package/src/segment.ts

@@ -0,0 +1,60 @@
+// Segment-boundary resolution — the ONE place the "deepest segmentBoundary wins"
+// rule lives, shared by the dev resolver (app.ts), the build manifest, and the
+// codegen (build.ts). Single-sourcing it keeps dev / frozen-manifest / deployed
+// worker from drifting on the exact invariant the feature depends on.
+//
+// HOST-ONLY (uses node:crypto): runs in the dev server and at build time, never
+// in the worker request path — the worker reads the frozen key from the manifest.
+import { createHash } from "node:crypto";
+
+export const boundaryWarning = (file: string): string =>
+  `[june] multiple segmentBoundary layouts in one chain (${file}); using the deepest.`;
+
+// A stable key identifying a boundary layout (its persistent shell). Same file →
+// same key (a shell shared across routes); different file → different key (a
+// distinct shell), so the client can tell whether a soft-nav fragment belongs to
+// the shell currently mounted and hard-navigate when it doesn't. Consistency is
+// only needed WITHIN one running instance (dev server OR deployed worker), since
+// the key is compared between an outlet's host marker and a response header both
+// produced by that same instance — dev and prod need not agree.
+//
+// Memoized: the dev resolver runs per request, and the key is a pure function of
+// the path. 16 hex chars (64 bits) makes a same-instance collision between two
+// boundary layouts — which would morph one shell's content into another — beyond
+// reach without inflating the wire marker.
+const keyCache = new Map<string, string>();
+export function boundaryKey(file: string): string {
+  let key = keyCache.get(file);
+  if (key === undefined) {
+    key = createHash("sha256").update(file).digest("hex").slice(0, 16);
+    keyCache.set(file, key);
+  }
+  return key;
+}
+
+// Build the layout chain (root→leaf, null entries filtered) and locate the
+// boundary: the DEEPEST entry flagged `boundary`. The index is into the FILTERED
+// chain — every consumer filters identically, so the index always matches the
+// chain the worker actually renders. Generic over the entry type so codegen can
+// pass layout-id strings where dev/build pass component functions.
+export function resolveBoundary<C>(
+  items: Array<{ file: string; entry: C | null; boundary: boolean }>,
+): { chain: C[]; boundaryIndex: number | null; key: string | null } {
+  const chain: C[] = [];
+  let boundaryIndex: number | null = null;
+  let boundaryFile: string | null = null;
+  for (const it of items) {
+    if (it.entry == null) continue; // dropped layout — filtered consistently everywhere
+    if (it.boundary) {
+      if (boundaryIndex !== null) console.warn(boundaryWarning(it.file));
+      boundaryIndex = chain.length;
+      boundaryFile = it.file;
+    }
+    chain.push(it.entry);
+  }
+  return {
+    chain,
+    boundaryIndex,
+    key: boundaryFile === null ? null : boundaryKey(boundaryFile),
+  };
+}

package/src/worker.ts

@@ -14,6 +14,7 @@ import type React from "react";
 import type { BrandedRoute } from "@junejs/core/route";
 import type { AgentConfig } from "@junejs/core/config";
 import type { DocumentConfig } from "@junejs/core/document";
+import type { I18nConfig } from "@junejs/core/i18n";
 import type { Resources } from "@junejs/core/resources";
 
 import { createPipeline, type ExtraHandler, type LayoutComponent, type LoadingComponent, type Resolved, type ResolvedResource, type ResourceHandler } from "./pipeline";
@@ -29,10 +30,19 @@ export type WorkerManifest = {
   // Layout chains (root→leaf) keyed by route path / dynamic pattern. The build
   // freezes the same chain the dev server loads from app/layout.* files.
   layoutChains?: Record<string, LayoutComponent[]>;
+  // Segment boundary per route: the chain index of the deepest layout exporting
+  // `segmentBoundary` (renders <JuneOutlet>) plus the shell's identity `key`.
+  // Routes without one are absent → whole-chain fragment (the default). Frozen
+  // statically by the build.
+  layoutBoundaries?: Record<string, { index: number; key: string }>;
   // Nearest loading.tsx per route path → streaming Suspense fallback.
   loadings?: Record<string, LoadingComponent>;
   document: DocumentConfig;
   agent: AgentConfig;
+  // Locale routing config, frozen from june.config.ts `i18n`. The locales table
+  // is plain data; a `resolveLocale` hook survives the in-process freeze (parity
+  // test) but not JSON codegen — worker hook support lands with the codegen pass.
+  i18n?: I18nConfig;
   // Preload Link values (config earlyHints + auto font hints), frozen at build.
   earlyHints?: string[];
   htmlCacheControl?: string;
@@ -108,6 +118,8 @@ export function createWorker(
 
   const chainFor = (key: string): LayoutComponent[] => manifest.layoutChains?.[key] ?? [];
   const loadingFor = (key: string): LoadingComponent | undefined => manifest.loadings?.[key];
+  const boundaryFor = (key: string): { index: number; key: string } | null =>
+    manifest.layoutBoundaries?.[key] ?? null;
 
   // The worker's env (D1/KV/R2 bindings) arrives per fetch and is stable across
   // requests in an isolate; we capture the latest and hand it to the env-aware
@@ -118,6 +130,7 @@ export function createWorker(
   const pipeline = createPipeline({
     docConfig: manifest.document,
     agent: manifest.agent,
+    i18n: manifest.i18n,
     routeList: () => routeList,
     earlyHints: manifest.earlyHints,
     htmlCacheControl: manifest.htmlCacheControl,
@@ -126,8 +139,17 @@ export function createWorker(
     resources: provider ? () => provider(currentEnv) : undefined,
     resolve: async (pathname): Promise<Resolved | ResolvedResource | null> => {
       const staticDef = manifest.routes[pathname];
-      if (staticDef)
-        return { def: staticDef, params: {}, chain: chainFor(pathname), loading: loadingFor(pathname) };
+      if (staticDef) {
+        const b = boundaryFor(pathname);
+        return {
+          def: staticDef,
+          params: {},
+          chain: chainFor(pathname),
+          boundaryIndex: b?.index ?? null,
+          boundaryKey: b?.key ?? null,
+          loading: loadingFor(pathname),
+        };
+      }
       for (const d of dynamic) {
         const m = pathname.match(d.regex);
         if (m) {
@@ -139,7 +161,15 @@ export function createWorker(
               return v === undefined ? [] : [[n, decodeURIComponent(v)]];
             }),
           );
-          return { def: d.def, params, chain: chainFor(d.pattern), loading: loadingFor(d.pattern) };
+          const b = boundaryFor(d.pattern);
+          return {
+            def: d.def,
+            params,
+            chain: chainFor(d.pattern),
+            boundaryIndex: b?.index ?? null,
+            boundaryKey: b?.key ?? null,
+            loading: loadingFor(d.pattern),
+          };
         }
       }
       // Resource routes after pages (so a page is never shadowed by one).