@junejs/server 0.1.2 → 0.1.3

package/dist/build.d.ts

@@ -15,6 +15,7 @@ type RouteEntry = {
   file: string;
   dynamic: boolean;
   resource?: boolean;
+  generated?: boolean;
   layouts: string[];
   loading?: string;
 };

package/dist/build.js

@@ -193,7 +193,11 @@ async function buildManifest(appRoot) {
 	const appRoutes = await scanRoutes(appDir);
 	const frameworkRoutes = existsSync(juneRoutesDir) ? await scanRoutes(juneRoutesDir) : [];
 	const appPaths = new Set(appRoutes.map((r) => r.path));
-	const scanned = [...appRoutes, ...frameworkRoutes.filter((r) => !appPaths.has(r.path))].sort((a, b) => a.path.localeCompare(b.path));
+	const scanned = [...appRoutes, ...frameworkRoutes.filter((r) => !appPaths.has(r.path)).map((r) => ({
+		...r,
+		generated: true
+	}))].sort((a, b) => a.path.localeCompare(b.path));
+	const generatedRoutes = scanned.filter((r) => r.generated).map((r) => r.path);
 	const layoutCache = /* @__PURE__ */ new Map();
 	const loadCached = async (f) => {
 		if (!layoutCache.has(f)) layoutCache.set(f, await importLayout(f));
@@ -266,6 +270,7 @@ async function buildManifest(appRoot) {
 		routes,
 		dynamicRoutes,
 		resourceRoutes,
+		...generatedRoutes.length ? { generatedRoutes } : {},
 		layoutChains,
 		layoutBoundaries,
 		loadings,
@@ -304,7 +309,10 @@ async function juneBuild(appRoot, options = {}) {
 	const appRoutes2 = await scanRoutes(appDir);
 	const frameworkRoutes2 = existsSync(juneRoutesDir2) ? await scanRoutes(juneRoutesDir2) : [];
 	const appPaths2 = new Set(appRoutes2.map((r) => r.path));
-	const routes = [...appRoutes2, ...frameworkRoutes2.filter((r) => !appPaths2.has(r.path))].sort((a, b) => a.path.localeCompare(b.path));
+	const routes = [...appRoutes2, ...frameworkRoutes2.filter((r) => !appPaths2.has(r.path)).map((r) => ({
+		...r,
+		generated: true
+	}))].sort((a, b) => a.path.localeCompare(b.path));
 	if (routes.length === 0) throw new Error(`no page.* routes found under ${appDir} or .june/routes/`);
 	const frozen = await freezeConfig(appRoot);
 	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).");
@@ -392,6 +400,8 @@ async function juneBuild(appRoot, options = {}) {
 		if (r.loading) loadings.push(`    ${JSON.stringify(r.path)}: ${loadingId(r.loading)},`);
 	});
 	const resourceRoutesField = resources.length ? `\n  resourceRoutes: [\n${resources.join("\n")}\n  ],` : "";
+	const generatedPaths = routes.filter((r) => r.generated).map((r) => r.path);
+	const generatedRoutesField = generatedPaths.length ? `\n  generatedRoutes: ${JSON.stringify(generatedPaths)},` : "";
 	const layoutBoundariesField = boundaries.length ? `\n  layoutBoundaries: {\n${boundaries.join("\n")}\n  },` : "";
 	const builtExtraFile = findMiddlewareFile(appDir);
 	if (builtExtraFile) imports.push(`import extra from ${JSON.stringify(importPath(genDir, builtExtraFile))};`);
@@ -427,7 +437,7 @@ ${statics.join("\n")}
   },
   dynamicRoutes: [
 ${dynamics.join("\n")}
-  ],${resourceRoutesField}
+  ],${resourceRoutesField}${generatedRoutesField}
   layoutChains: {
 ${chains.join("\n")}
   },${layoutBoundariesField}

package/dist/route-rank.d.ts

@@ -0,0 +1,11 @@
+//#region src/route-rank.d.ts
+type SegmentKind = "static" | "param" | "optional" | "catchAll" | "optionalCatchAll";
+declare function parseSegment(segment: string): {
+  kind: SegmentKind;
+  name?: string;
+};
+declare function segmentRank(segment: string): number;
+declare function compareSegments(a: string, b: string): number;
+declare function compareRoutePatterns(a: string, b: string): number;
+//#endregion
+export { SegmentKind, compareRoutePatterns, compareSegments, parseSegment, segmentRank };

package/dist/route-rank.js

@@ -0,0 +1,38 @@
+//#region src/route-rank.ts
+const DYNAMIC = /^\[(\[)?(\.\.\.)?([A-Za-z_][A-Za-z0-9_]*)\](\])?$/;
+function parseSegment(segment) {
+	const m = segment.match(DYNAMIC);
+	if (!m || !!m[1] !== !!m[4]) return { kind: "static" };
+	const optional = !!m[1];
+	return {
+		kind: !!m[2] ? optional ? "optionalCatchAll" : "catchAll" : optional ? "optional" : "param",
+		name: m[3]
+	};
+}
+const RANK = {
+	static: 0,
+	param: 1,
+	optional: 2,
+	catchAll: 3,
+	optionalCatchAll: 4
+};
+function segmentRank(segment) {
+	return RANK[parseSegment(segment).kind];
+}
+function compareSegments(a, b) {
+	return segmentRank(a) - segmentRank(b) || (a < b ? -1 : a > b ? 1 : 0);
+}
+function compareRoutePatterns(a, b) {
+	const as = a.split("/").filter(Boolean);
+	const bs = b.split("/").filter(Boolean);
+	for (let i = 0; i < Math.max(as.length, bs.length); i++) {
+		const x = as[i];
+		const y = bs[i];
+		if (x === void 0) return -1;
+		if (y === void 0) return 1;
+		if (x !== y) return compareSegments(x, y);
+	}
+	return 0;
+}
+//#endregion
+export { compareRoutePatterns, compareSegments, parseSegment, segmentRank };

package/dist/router.js

@@ -1,3 +1,4 @@
+import { compareSegments, parseSegment } from "./route-rank.js";
 import { existsSync } from "node:fs";
 import { readdir } from "node:fs/promises";
 import { join, relative, sep } from "node:path";
@@ -42,11 +43,11 @@ function isSpecialFile(file) {
 	return SPECIAL_FILES.has(baseName(file));
 }
 const isRouteGroup = (name) => /^\(.+\)$/.test(name);
-const isParamDir = (name) => /^\[([A-Za-z_][A-Za-z0-9_]*)\]$/.test(name);
-const isOptionalDir = (name) => /^\[\[([A-Za-z_][A-Za-z0-9_]*)\]\]$/.test(name);
-const isOptionalCatchAllDir = (name) => /^\[\[\.\.\.([A-Za-z_][A-Za-z0-9_]*)\]\]$/.test(name);
-const isCatchAllDir = (name) => /^\[\.\.\.([A-Za-z_][A-Za-z0-9_]*)\]$/.test(name);
-const paramName = (name) => name.replace(/^\[+(\.\.\.)?|\]+$/g, "");
+const isParamDir = (name) => parseSegment(name).kind === "param";
+const isOptionalDir = (name) => parseSegment(name).kind === "optional";
+const isOptionalCatchAllDir = (name) => parseSegment(name).kind === "optionalCatchAll";
+const isCatchAllDir = (name) => parseSegment(name).kind === "catchAll";
+const paramName = (name) => parseSegment(name).name;
 async function listDir(dir) {
 	return (await readdir(dir, { withFileTypes: true }).catch(() => [])).filter((e) => !e.name.startsWith("_") && !e.name.startsWith(".")).map((e) => ({
 		name: e.name,
@@ -85,7 +86,7 @@ function routePath(appDir, file) {
 async function matchRouteTree(appDir, pathname, options = {}) {
 	const urlSegments = pathname.split("/").filter(Boolean).map(decodeURIComponent);
 	async function descend(dir, rest, params, chain) {
-		const entries = await listDir(dir);
+		const entries = (await listDir(dir)).sort((a, b) => compareSegments(a.name, b.name));
 		const segments = [...chain, segmentAt(dir, entries)];
 		if (rest.length === 0) {
 			const page = fileFor(entries, dir, "page") ?? fileFor(entries, dir, "index") ?? fileFor(entries, dir, "route");

package/dist/worker.d.ts

@@ -16,6 +16,7 @@ type WorkerManifest = {
     pattern: string;
     handler: ResourceHandler;
   }>;
+  generatedRoutes?: string[];
   layoutChains?: Record<string, LayoutComponent[]>;
   layoutBoundaries?: Record<string, {
     index: number;

package/dist/worker.js

@@ -1,4 +1,5 @@
 import { durableAgentSurface } from "./agent-durable.js";
+import { compareRoutePatterns, parseSegment } from "./route-rank.js";
 import { createPipeline } from "./pipeline.js";
 import { RESERVED_PREFIX, contentTypeFor, safeRelativePath } from "./static-files.js";
 //#region src/worker.ts
@@ -7,34 +8,16 @@ function compilePattern(pattern) {
 	let source = "";
 	let allOptional = true;
 	for (const seg of pattern.split("/").filter(Boolean)) {
-		const oca = seg.match(/^\[\[\.\.\.(\w+)\]\]$/);
-		if (oca) {
-			names.push(oca[1]);
-			source += "(?:/(.+))?";
-			continue;
-		}
-		const ca = seg.match(/^\[\.\.\.(\w+)\]$/);
-		if (ca) {
-			names.push(ca[1]);
-			source += "/(.+)";
-			allOptional = false;
-			continue;
-		}
-		const op = seg.match(/^\[\[(\w+)\]\]$/);
-		if (op) {
-			names.push(op[1]);
-			source += "(?:/([^/]+))?";
-			continue;
-		}
-		const p = seg.match(/^\[(\w+)\]$/);
-		if (p) {
-			names.push(p[1]);
-			source += "/([^/]+)";
+		const { kind, name } = parseSegment(seg);
+		if (name) names.push(name);
+		if (kind === "optionalCatchAll") source += "(?:/(.+))?";
+		else if (kind === "optional") source += "(?:/([^/]+))?";
+		else {
+			if (kind === "catchAll") source += "/(.+)";
+			else if (kind === "param") source += "/([^/]+)";
+			else source += "/" + seg.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 			allOptional = false;
-			continue;
 		}
-		source += "/" + seg.replace(/[.*+?^${}()|\\]/g, "\\$&");
-		allOptional = false;
 	}
 	if (source === "") return {
 		regex: /^\/$/,
@@ -46,20 +29,42 @@ function compilePattern(pattern) {
 	};
 }
 function createWorker(manifest) {
-	const dynamic = (manifest.dynamicRoutes ?? []).map((d) => ({
-		...compilePattern(d.pattern),
-		def: d.def,
-		pattern: d.pattern
-	}));
-	const resources = (manifest.resourceRoutes ?? []).map((r) => ({
-		...compilePattern(r.pattern),
-		handler: r.handler,
-		pattern: r.pattern
-	}));
+	const generated = new Set(manifest.generatedRoutes ?? []);
+	const row = (pattern) => ({
+		...compilePattern(pattern),
+		pattern,
+		generated: generated.has(pattern)
+	});
+	const table = [
+		...Object.entries(manifest.routes).map(([pattern, def]) => ({
+			...row(pattern),
+			def
+		})),
+		...(manifest.dynamicRoutes ?? []).map((d) => ({
+			...row(d.pattern),
+			def: d.def
+		})),
+		...(manifest.resourceRoutes ?? []).map((r) => ({
+			...row(r.pattern),
+			handler: r.handler
+		}))
+	];
+	table.sort((a, b) => Number(a.generated) - Number(b.generated) || compareRoutePatterns(a.pattern, b.pattern) || Number(!!a.handler) - Number(!!b.handler));
 	const routeList = [...Object.keys(manifest.routes), ...(manifest.dynamicRoutes ?? []).map((d) => d.pattern)].sort();
 	const chainFor = (key) => manifest.layoutChains?.[key] ?? [];
 	const loadingFor = (key) => manifest.loadings?.[key];
 	const boundaryFor = (key) => manifest.layoutBoundaries?.[key] ?? null;
+	const resolvedPage = (def, key, params) => {
+		const b = boundaryFor(key);
+		return {
+			def,
+			params,
+			chain: chainFor(key),
+			boundaryIndex: b?.index ?? null,
+			boundaryKey: b?.key ?? null,
+			loading: loadingFor(key)
+		};
+	};
 	let currentEnv;
 	const provider = manifest.resources;
 	const servicesProvider = manifest.services;
@@ -85,47 +90,18 @@ function createWorker(manifest) {
 		services: servicesProvider ? () => (servicesCache ??= { v: servicesProvider(currentEnv) }).v : void 0,
 		resolve: async (pathname) => {
 			const staticDef = manifest.routes[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) {
-					const params = Object.fromEntries(d.names.flatMap((n, i) => {
-						const v = m[i + 1];
-						return v === void 0 ? [] : [[n, decodeURIComponent(v)]];
-					}));
-					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)
-					};
-				}
-			}
-			for (const r of resources) {
+			if (staticDef && !generated.has(pathname)) return resolvedPage(staticDef, pathname, {});
+			for (const r of table) {
 				const m = pathname.match(r.regex);
-				if (m) {
-					const params = Object.fromEntries(r.names.flatMap((n, i) => {
-						const v = m[i + 1];
-						return v === void 0 ? [] : [[n, decodeURIComponent(v)]];
-					}));
-					return {
-						handler: r.handler,
-						params
-					};
-				}
+				if (!m) continue;
+				const params = Object.fromEntries(r.names.flatMap((n, i) => {
+					const v = m[i + 1];
+					return v === void 0 ? [] : [[n, decodeURIComponent(v)]];
+				}));
+				return r.handler ? {
+					handler: r.handler,
+					params
+				} : resolvedPage(r.def, r.pattern, params);
 			}
 			return null;
 		}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@junejs/server",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "June host adapters + dev server. Host-coupled; depends on the pure @junejs/core contract layer.",
   "type": "module",
   "license": "MIT",

package/src/build.ts

@@ -60,6 +60,7 @@ type RouteEntry = {
   file: string;
   dynamic: boolean;
   resource?: boolean; // a route.* resource route (raw-Response handler), not a page
+  generated?: boolean; // scanned from .june/routes/ — ranks after every app/ route, as in dev
   layouts: string[];
   loading?: string; // nearest loading.tsx up the tree → streaming Suspense fallback
 };
@@ -372,8 +373,9 @@ export async function buildManifest(appRoot: string): Promise<WorkerManifest> {
   const appPaths = new Set(appRoutes.map((r) => r.path));
   const scanned = [
     ...appRoutes,
-    ...frameworkRoutes.filter((r) => !appPaths.has(r.path)),
+    ...frameworkRoutes.filter((r) => !appPaths.has(r.path)).map((r) => ({ ...r, generated: true })),
   ].sort((a, b) => a.path.localeCompare(b.path));
+  const generatedRoutes = scanned.filter((r) => r.generated).map((r) => r.path);
 
   const layoutCache = new Map<string, ImportedLayout | null>();
   const loadCached = async (f: string): Promise<ImportedLayout | null> => {
@@ -445,6 +447,7 @@ export async function buildManifest(appRoot: string): Promise<WorkerManifest> {
     routes,
     dynamicRoutes,
     resourceRoutes,
+    ...(generatedRoutes.length ? { generatedRoutes } : {}),
     layoutChains,
     layoutBoundaries,
     loadings,
@@ -493,7 +496,7 @@ export async function juneBuild(
   const appPaths2 = new Set(appRoutes2.map((r) => r.path));
   const routes = [
     ...appRoutes2,
-    ...frameworkRoutes2.filter((r) => !appPaths2.has(r.path)),
+    ...frameworkRoutes2.filter((r) => !appPaths2.has(r.path)).map((r) => ({ ...r, generated: true })),
   ].sort((a, b) => a.path.localeCompare(b.path));
   if (routes.length === 0) throw new Error(`no page.* routes found under ${appDir} or .june/routes/`);
 
@@ -650,6 +653,12 @@ export async function juneBuild(
   const resourceRoutesField = resources.length
     ? `\n  resourceRoutes: [\n${resources.join("\n")}\n  ],`
     : "";
+  // .june/routes/ patterns rank after every app/ route (dev falls back to them).
+  // Only emitted when there are some, so bundles without them stay byte-identical.
+  const generatedPaths = routes.filter((r) => r.generated).map((r) => r.path);
+  const generatedRoutesField = generatedPaths.length
+    ? `\n  generatedRoutes: ${JSON.stringify(generatedPaths)},`
+    : "";
   // Only emitted when some route declares a boundary, so boundary-less bundles
   // stay byte-identical (additive manifest field, like resources).
   const layoutBoundariesField = boundaries.length
@@ -733,7 +742,7 @@ ${statics.join("\n")}
   },
   dynamicRoutes: [
 ${dynamics.join("\n")}
-  ],${resourceRoutesField}
+  ],${resourceRoutesField}${generatedRoutesField}
   layoutChains: {
 ${chains.join("\n")}
   },${layoutBoundariesField}

package/src/route-rank.ts

@@ -0,0 +1,60 @@
+// Route precedence — the ONE ranking both resolvers use (#312). The dev matcher
+// (router.ts, matchRouteTree) walks the app tree trying each level's children in
+// this order; the built worker (worker.ts) cannot walk a tree, so it sorts its
+// flat route table with compareRoutePatterns and takes the first regex match.
+// For patterns that both match a URL, the depth-first walk and the sorted table
+// pick the same winner: the first segment where two patterns differ decides.
+//
+// Worker-safe: no node:* imports.
+
+export type SegmentKind = "static" | "param" | "optional" | "catchAll" | "optionalCatchAll";
+
+// The one segment grammar: a param name is an identifier ([A-Za-z_][A-Za-z0-9_]*).
+// Anything else in brackets (`[1]`, `[foo-bar]`, `[slug].png`) is a STATIC
+// segment named literally, in dev, in the ranking and in the worker's regex.
+const DYNAMIC = /^\[(\[)?(\.\.\.)?([A-Za-z_][A-Za-z0-9_]*)\](\])?$/;
+
+export function parseSegment(segment: string): { kind: SegmentKind; name?: string } {
+  const m = segment.match(DYNAMIC);
+  // Brackets must pair: `[[x]]` or `[x]`, never `[[x]` / `[x]]`.
+  if (!m || !!m[1] !== !!m[4]) return { kind: "static" };
+  const optional = !!m[1];
+  const catchAll = !!m[2];
+  const kind: SegmentKind = catchAll
+    ? optional ? "optionalCatchAll" : "catchAll"
+    : optional ? "optional" : "param";
+  return { kind, name: m[3] };
+}
+
+const RANK: Record<SegmentKind, number> = { static: 0, param: 1, optional: 2, catchAll: 3, optionalCatchAll: 4 };
+
+// Per-segment rank, most specific first: static, [param], [[param]], [...rest],
+// [[...rest]]. Optional sits after its required form, so `[slug]` answers
+// before `[[slug]]` when a segment is present.
+export function segmentRank(segment: string): number {
+  return RANK[parseSegment(segment).kind];
+}
+
+// Sibling order within one directory level: by rank, then by name so a tie
+// (two [param] dirs) resolves the same on every filesystem.
+export function compareSegments(a: string, b: string): number {
+  return segmentRank(a) - segmentRank(b) || (a < b ? -1 : a > b ? 1 : 0);
+}
+
+// Order two file-route patterns ("/docs/[[...path]]", "/feed.xml") by
+// precedence. The first differing segment decides; a pattern that ends there
+// beats one that continues, since only absent optional segments can follow a
+// match that already consumed the URL (dev checks a directory's own page before
+// descending into its optional children).
+export function compareRoutePatterns(a: string, b: string): number {
+  const as = a.split("/").filter(Boolean);
+  const bs = b.split("/").filter(Boolean);
+  for (let i = 0; i < Math.max(as.length, bs.length); i++) {
+    const x = as[i];
+    const y = bs[i];
+    if (x === undefined) return -1;
+    if (y === undefined) return 1;
+    if (x !== y) return compareSegments(x, y);
+  }
+  return 0;
+}

package/src/router.ts

@@ -6,6 +6,8 @@ import { existsSync } from "node:fs";
 import { readdir } from "node:fs/promises";
 import { join, relative, sep } from "node:path";
 
+import { compareSegments, parseSegment } from "./route-rank";
+
 export type RouteMatch = {
   file: string;
   params: Record<string, string>;
@@ -87,13 +89,13 @@ function isSpecialFile(file: string) {
 }
 
 const isRouteGroup = (name: string) => /^\(.+\)$/.test(name);
-const isParamDir = (name: string) => /^\[([A-Za-z_][A-Za-z0-9_]*)\]$/.test(name);
+const isParamDir = (name: string) => parseSegment(name).kind === "param";
 // [[slug]] / [[...slug]] — match like their required forms, and ALSO match the
 // segment being absent (the param is then simply missing from ctx.params).
-const isOptionalDir = (name: string) => /^\[\[([A-Za-z_][A-Za-z0-9_]*)\]\]$/.test(name);
-const isOptionalCatchAllDir = (name: string) => /^\[\[\.\.\.([A-Za-z_][A-Za-z0-9_]*)\]\]$/.test(name);
-const isCatchAllDir = (name: string) => /^\[\.\.\.([A-Za-z_][A-Za-z0-9_]*)\]$/.test(name);
-const paramName = (name: string) => name.replace(/^\[+(\.\.\.)?|\]+$/g, "");
+const isOptionalDir = (name: string) => parseSegment(name).kind === "optional";
+const isOptionalCatchAllDir = (name: string) => parseSegment(name).kind === "optionalCatchAll";
+const isCatchAllDir = (name: string) => parseSegment(name).kind === "catchAll";
+const paramName = (name: string) => parseSegment(name).name!;
 
 type DirEntry = { name: string; dir: boolean };
 
@@ -147,8 +149,10 @@ function routePath(appDir: string, file: string) {
 }
 
 // Recursive-descent matcher over the app directory. Priority at every level:
-// exact static segment > [param] > [...catchAll]; route groups `(name)` descend
-// without consuming a URL segment; `_`-prefixed entries never participate.
+// exact static segment > [param] > [...catchAll], required before optional, ties
+// by name (route-rank.ts — the built worker sorts its route table by the same
+// ranking); route groups `(name)` descend without consuming a URL segment;
+// `_`-prefixed entries never participate.
 // Returns the page file, accumulated params (catch-all joins with "/"), and the
 // chain of segments (with their special files) from the app root to the page.
 export async function matchRouteTree(
@@ -164,7 +168,8 @@ export async function matchRouteTree(
     params: Record<string, string>,
     chain: SegmentMatch[],
   ): Promise<RouteTreeMatch | null> {
-    const entries = await listDir(dir);
+    // Ranked, not readdir order, so the pick is the same on every filesystem.
+    const entries = (await listDir(dir)).sort((a, b) => compareSegments(a.name, b.name));
     const segments = [...chain, segmentAt(dir, entries)];
 
     // Terminal: URL consumed → find the page (or resource route) in this dir.

package/src/worker.ts

@@ -19,6 +19,7 @@ import type { Resources } from "@junejs/core/resources";
 
 import { createPipeline, type ExtraHandler, type LayoutComponent, type LoadingComponent, type Resolved, type ResolvedResource, type ResourceHandler } from "./pipeline";
 import { durableAgentSurface, type DurableObjectNamespace } from "./agent-durable";
+import { compareRoutePatterns, parseSegment } from "./route-rank";
 import { contentTypeFor, RESERVED_PREFIX, safeRelativePath } from "./static-files";
 
 export type WorkerManifest = {
@@ -27,8 +28,13 @@ export type WorkerManifest = {
   // Dynamic patterns in file-route syntax ("/posts/[slug]", "/docs/[...path]").
   dynamicRoutes?: Array<{ pattern: string; def: BrandedRoute }>;
   // Resource routes (app/**/route.*): a raw-Response handler keyed by its pattern
-  // (static or dynamic). Matched after pages, so a page never gets shadowed.
+  // (static or dynamic). Ranked with the pages by segment shape (route-rank.ts),
+  // exactly as `june dev` resolves; a page wins only at the SAME pattern.
   resourceRoutes?: Array<{ pattern: string; handler: ResourceHandler }>;
+  // Patterns scanned from .june/routes/ (framework-generated, e.g. Kura). Dev
+  // consults app/ first and falls back to .june/routes/, so every one of these
+  // ranks after every app/ route. Absent → all routes are app/ routes.
+  generatedRoutes?: string[];
   // 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[]>;
@@ -66,7 +72,13 @@ export type WorkerManifest = {
   services?: (env?: unknown) => unknown;
 };
 
-type Compiled = { regex: RegExp; names: string[]; def: BrandedRoute; pattern: string };
+// One row of the worker's route table: a page (def) or a resource route (handler).
+type Compiled = {
+  regex: RegExp;
+  names: string[];
+  pattern: string;
+  generated: boolean;
+} & ({ def: BrandedRoute; handler?: undefined } | { def?: undefined; handler: ResourceHandler });
 
 // "/posts/[slug]" | "/docs/[...path]" | "/notes/[[tag]]" → matcher. Optional
 // segments ([[x]], [[...x]]) wrap slash + capture together so absence matches;
@@ -76,34 +88,19 @@ function compilePattern(pattern: string): { regex: RegExp; names: string[] } {
   let source = "";
   let allOptional = true;
   for (const seg of pattern.split("/").filter(Boolean)) {
-    const oca = seg.match(/^\[\[\.\.\.(\w+)\]\]$/);
-    if (oca) {
-      names.push(oca[1]!);
-      source += "(?:/(.+))?";
-      continue;
-    }
-    const ca = seg.match(/^\[\.\.\.(\w+)\]$/);
-    if (ca) {
-      names.push(ca[1]!);
-      source += "/(.+)";
-      allOptional = false;
-      continue;
-    }
-    const op = seg.match(/^\[\[(\w+)\]\]$/);
-    if (op) {
-      names.push(op[1]!);
-      source += "(?:/([^/]+))?";
-      continue;
-    }
-    const p = seg.match(/^\[(\w+)\]$/);
-    if (p) {
-      names.push(p[1]!);
-      source += "/([^/]+)";
+    // Same grammar as the dev matcher (route-rank.ts parseSegment).
+    const { kind, name } = parseSegment(seg);
+    if (name) names.push(name);
+    if (kind === "optionalCatchAll") source += "(?:/(.+))?";
+    else if (kind === "optional") source += "(?:/([^/]+))?";
+    else {
+      if (kind === "catchAll") source += "/(.+)";
+      else if (kind === "param") source += "/([^/]+)";
+      // A static segment matches literally: escape every RegExp metacharacter,
+      // brackets included (`docs[v2`, `[slug].png` are static names).
+      else source += "/" + seg.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
       allOptional = false;
-      continue;
     }
-    source += "/" + seg.replace(/[.*+?^${}()|\\]/g, "\\$&");
-    allOptional = false;
   }
   if (source === "") return { regex: /^\/$/, names };
   return { regex: new RegExp(allOptional ? `^(?:${source}|/)$` : `^${source}$`), names };
@@ -112,16 +109,23 @@ function compilePattern(pattern: string): { regex: RegExp; names: string[] } {
 export function createWorker(
   manifest: WorkerManifest,
 ): { fetch(request: Request, env?: unknown): Promise<Response> } {
-  const dynamic: Compiled[] = (manifest.dynamicRoutes ?? []).map((d) => ({
-    ...compilePattern(d.pattern),
-    def: d.def,
-    pattern: d.pattern,
-  }));
-  const resources = (manifest.resourceRoutes ?? []).map((r) => ({
-    ...compilePattern(r.pattern),
-    handler: r.handler,
-    pattern: r.pattern,
-  }));
+  // Pages and resource routes in ONE table, ordered the way `june dev` resolves
+  // (#312): app/ before .june/routes/, then segment shape (static > [param] >
+  // [...catchAll], required before optional), then a page before a resource
+  // route at the same pattern. The kind of route never outranks the shape.
+  const generated = new Set(manifest.generatedRoutes ?? []);
+  const row = (pattern: string) => ({ ...compilePattern(pattern), pattern, generated: generated.has(pattern) });
+  const table: Compiled[] = [
+    ...Object.entries(manifest.routes).map(([pattern, def]) => ({ ...row(pattern), def })),
+    ...(manifest.dynamicRoutes ?? []).map((d) => ({ ...row(d.pattern), def: d.def })),
+    ...(manifest.resourceRoutes ?? []).map((r) => ({ ...row(r.pattern), handler: r.handler })),
+  ];
+  table.sort(
+    (a, b) =>
+      Number(a.generated) - Number(b.generated) ||
+      compareRoutePatterns(a.pattern, b.pattern) ||
+      Number(!!a.handler) - Number(!!b.handler),
+  );
   const routeList = [
     ...Object.keys(manifest.routes),
     ...(manifest.dynamicRoutes ?? []).map((d) => d.pattern),
@@ -131,6 +135,17 @@ export function createWorker(
   const loadingFor = (key: string): LoadingComponent | undefined => manifest.loadings?.[key];
   const boundaryFor = (key: string): { index: number; key: string } | null =>
     manifest.layoutBoundaries?.[key] ?? null;
+  const resolvedPage = (def: BrandedRoute, key: string, params: Record<string, string>): Resolved => {
+    const b = boundaryFor(key);
+    return {
+      def,
+      params,
+      chain: chainFor(key),
+      boundaryIndex: b?.index ?? null,
+      boundaryKey: b?.key ?? null,
+      loading: loadingFor(key),
+    };
+  };
 
   // 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
@@ -172,52 +187,21 @@ export function createWorker(
     resources: provider ? () => provider(currentEnv) : undefined,
     services: servicesProvider ? () => (servicesCache ??= { v: servicesProvider(currentEnv) }).v : undefined,
     resolve: async (pathname): Promise<Resolved | ResolvedResource | null> => {
+      // Fast path: an app/ static page outranks every other route for its path.
       const staticDef = manifest.routes[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) {
-          // Optional segments leave their capture undefined — the param is
-          // then absent, matching the dev matcher's semantics.
-          const params = Object.fromEntries(
-            d.names.flatMap((n, i) => {
-              const v = m[i + 1];
-              return v === undefined ? [] : [[n, decodeURIComponent(v)]];
-            }),
-          );
-          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).
-      for (const r of resources) {
+      if (staticDef && !generated.has(pathname)) return resolvedPage(staticDef, pathname, {});
+      for (const r of table) {
         const m = pathname.match(r.regex);
-        if (m) {
-          const params = Object.fromEntries(
-            r.names.flatMap((n, i) => {
-              const v = m[i + 1];
-              return v === undefined ? [] : [[n, decodeURIComponent(v)]];
-            }),
-          );
-          return { handler: r.handler, params };
-        }
+        if (!m) continue;
+        // Optional segments leave their capture undefined — the param is
+        // then absent, matching the dev matcher's semantics.
+        const params = Object.fromEntries(
+          r.names.flatMap((n, i) => {
+            const v = m[i + 1];
+            return v === undefined ? [] : [[n, decodeURIComponent(v)]];
+          }),
+        );
+        return r.handler ? { handler: r.handler, params } : resolvedPage(r.def, r.pattern, params);
       }
       return null;
     },