@junejs/server 0.0.20 → 0.0.22

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@junejs/server",
-  "version": "0.0.20",
+  "version": "0.0.22",
   "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.20",
-    "@junejs/db": "0.0.20",
+    "@junejs/core": "0.0.22",
+    "@junejs/db": "0.0.22",
     "marked": "^18.0.5",
     "rolldown": "^1.1.0",
     "lightningcss": "^1.27.0"

package/src/adapter.ts

@@ -268,3 +268,69 @@ export function vercel(opts?: { runtime?: "node" | "edge"; regions?: string[] })
     },
   };
 }
+
+// Deno Deploy target. The SAME portable bundle as workers/vercel (edge-light →
+// react-dom server.edge.js, which Deno's web-standard runtime runs); the entry
+// wraps the pipeline in `Deno.serve(withDenoAssets(...))`. Deno Deploy has no CDN,
+// so the handler serves /_june/* from the co-located assets/ dir itself (like
+// vercel()'s split, but in-process). `june build` produces dist/{worker.js,assets}
+// and `deployctl deploy` ships the dir — no Build Output tree to construct.
+//
+// db: turso() works (libsql over HTTPS, env-driven). sqlite()/d1() are
+// Cloudflare-only; validate() rejects them.
+export function deno(opts?: { org?: string; app?: string }): JuneAdapter {
+  return {
+    name: "deno",
+    capabilities: { runtime: "edge", persistentConnections: true, assets: "server" },
+    // "deno" first (a dep may ship a Deno-specific build); else edge-light →
+    // server.edge.js (Web Streams + fetch, which Deno has).
+    conditions: ["deno", "edge-light", "edge", "import", "default"],
+
+    validate({ config }) {
+      const kind = config.resources?.db?.kind;
+      if (kind && kind !== "turso") {
+        throw new Error(
+          `deno(): the '${kind}' db isn't supported on Deno Deploy (D1 is Cloudflare-only).\n` +
+            "  Use turso() (libsql over HTTPS) for a Deno db, or deploy to Workers.",
+        );
+      }
+    },
+
+    entry() {
+      // The `export default { fetch }` Web Standard export — what `deno serve` (and
+      // Deno Deploy's runtime) invokes, and the same shape vercel()'s Node runtime
+      // uses. (A top-level `Deno.serve()` only works under `deno run`, not the
+      // platform.) No env glue: withDenoAssets reads Deno.env itself.
+      return {
+        imports: [`import { withDenoAssets } from "@junejs/server/worker";`],
+        wrap: (pipelineVar) => `export default { fetch: withDenoAssets(${pipelineVar}) };`,
+      };
+    },
+
+    async emit({ outDir }) {
+      // The bundle (worker.js + chunks) and assets/ already sit in outDir. The
+      // deno.json declares the Deno Deploy target (org/app) + the runtime block.
+      // `type: "dynamic"` is REQUIRED — it's the tag that tells EA "run this
+      // entrypoint as a server" (the `{ fetch }` export `deno serve` runs). Omit
+      // it and EA falls back to framework auto-detection ("internally optimized"),
+      // finds nothing, and the revision dies with "No runtime entrypoint provided".
+      // (The other arm is `type: "static"` + cwd/spa for a prebuilt SPA.) Source
+      // config takes precedence over the dashboard, so the deploy is reproducible.
+      // org/app come from deno({ org, app }) — without them, `deno deploy` prompts.
+      await writeFile(
+        join(outDir, "deno.json"),
+        JSON.stringify(
+          {
+            deploy: {
+              ...(opts?.org ? { org: opts.org } : {}),
+              ...(opts?.app ? { app: opts.app } : {}),
+              runtime: { type: "dynamic", entrypoint: "worker.js" },
+            },
+          },
+          null,
+          2,
+        ) + "\n",
+      );
+    },
+  };
+}

package/src/app.ts

@@ -18,8 +18,8 @@ import { resolveAgent, resolveSpeculationRules, type JuneConfig } from "@junejs/
 import type { DocumentConfig } from "@junejs/core/document";
 import { runWithTrace, type RequestTrace } from "@junejs/core/instrumentation";
 
-import { findExtraFile, listRoutes, matchRouteTree, resolveNotFound, routeFiles, type SegmentMatch } from "./router";
-import { createPipeline, type ExtraHandler, type LayoutComponent, type Pipeline, type Resolved } from "./pipeline";
+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 { memoizeResources } from "./resources";
 import { findClientEntry, bundleClientToString, CLIENT_SCRIPT_URL } from "./client-bundle";
 import { findGlobalCss, processCssCached, STYLES_URL } from "./css";
@@ -140,7 +140,7 @@ export function createApp({ appDir: appDirInput, config = {} }: CreateAppOptions
       }
     }
     let extra: ExtraHandler | undefined;
-    const extraFile = findExtraFile(appDir);
+    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;
@@ -153,10 +153,16 @@ export function createApp({ appDir: appDirInput, config = {} }: CreateAppOptions
       earlyHints: config.earlyHints,
       resources,
       notFoundComponent,
-      resolve: async (pathname): Promise<Resolved | null> => {
+      resolve: async (pathname) => {
         const match = await matchRouteTree(appDir, pathname, { pageConvention: true });
         if (!match) return null;
         const mod = await import(pathToFileURL(match.file).href);
+        // Resource route (route.*): the default export is the Response handler.
+        if (isResourceFile(match.file)) {
+          const handler = (mod as { default?: unknown }).default;
+          if (typeof handler !== "function") return null;
+          return { handler: handler as ResourceHandler, params: match.params };
+        }
         const def = routeFromModule(mod);
         if (!def) return null;
         return {
@@ -164,7 +170,7 @@ export function createApp({ appDir: appDirInput, config = {} }: CreateAppOptions
           params: match.params,
           chain: await loadChain(match.segments),
           loading: await nearestLoading(match.segments),
-        };
+        } satisfies Resolved;
       },
     });
   }

package/src/build.ts

@@ -31,8 +31,8 @@ import { workers, type JuneAdapter, type ResourcePlan } from "./adapter";
 import type { DocumentConfig } from "@junejs/core/document";
 import { collection } from "./content";
 import { createWorker, type WorkerManifest } from "./worker";
-import { findExtraFile } from "./router";
-import type { ExtraHandler, LayoutComponent, LoadingComponent } from "./pipeline";
+import { findMiddlewareFile } from "./router";
+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";
 import { buildModuleCss, rolldownCssModulesPlugin, registerCssModules } from "./css-modules";
@@ -51,6 +51,7 @@ type RouteEntry = {
   path: string;
   file: string;
   dynamic: boolean;
+  resource?: boolean; // a route.* resource route (raw-Response handler), not a page
   layouts: string[];
   loading?: string; // nearest loading.tsx up the tree → streaming Suspense fallback
 };
@@ -87,7 +88,9 @@ export async function scanRoutes(
     }
     const ext = e.name.match(/\.[^.]+$/)?.[0] ?? "";
     if (!ROUTE_EXTS.includes(ext)) continue;
-    if (!PAGE_BASENAMES.has(basename(e.name, ext))) continue;
+    const base = basename(e.name, ext);
+    const resource = base === "route";
+    if (!PAGE_BASENAMES.has(base) && !resource) continue;
     const relDir = relative(appDir, dir);
     const segments = relDir === "" ? [] : relDir.split(sep).filter((s) => !isRouteGroup(s));
     const path = "/" + segments.join("/");
@@ -95,6 +98,7 @@ export async function scanRoutes(
       path: path === "/" ? "/" : path,
       file: full,
       dynamic: /\[.+\]/.test(path),
+      resource,
       layouts: chain,
       loading: nearestLoading,
     });
@@ -197,11 +201,18 @@ export async function buildManifest(appRoot: string): Promise<WorkerManifest> {
 
   const routes: Record<string, BrandedRoute> = {};
   const dynamicRoutes: Array<{ pattern: string; def: BrandedRoute }> = [];
+  const resourceRoutes: Array<{ pattern: string; handler: ResourceHandler }> = [];
   const layoutChains: Record<string, LayoutComponent[]> = {};
   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 = await componentsFor(r.layouts);
@@ -217,7 +228,7 @@ export async function buildManifest(appRoot: string): Promise<WorkerManifest> {
   }
 
   let extra: ExtraHandler | undefined;
-  const extraFile = findExtraFile(appDir);
+  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;
@@ -226,6 +237,7 @@ export async function buildManifest(appRoot: string): Promise<WorkerManifest> {
   return {
     routes,
     dynamicRoutes,
+    resourceRoutes,
     layoutChains,
     loadings,
     document: frozen.document,
@@ -350,15 +362,26 @@ export async function juneBuild(
   };
   const chains: string[] = [];
   const loadings: string[] = [];
+  const resources: string[] = [];
   routes.forEach((r, i) => {
+    // Resource route (route.*): the default export IS the handler — import it
+    // directly (no routeFromModule, no layout chain).
+    if (r.resource) {
+      imports.push(`import h${i} from ${JSON.stringify(importPath(genDir, r.file))};`);
+      resources.push(`    { pattern: ${JSON.stringify(r.path)}, handler: h${i} },`);
+      return;
+    }
     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(", ")}],`);
     if (r.loading) loadings.push(`    ${JSON.stringify(r.path)}: ${loadingId(r.loading)},`);
   });
+  const resourceRoutesField = resources.length
+    ? `\n  resourceRoutes: [\n${resources.join("\n")}\n  ],`
+    : "";
 
-  const builtExtraFile = findExtraFile(appDir);
+  const builtExtraFile = findMiddlewareFile(appDir);
   if (builtExtraFile) {
     imports.push(`import extra from ${JSON.stringify(importPath(genDir, builtExtraFile))};`);
   }
@@ -418,7 +441,7 @@ ${statics.join("\n")}
   },
   dynamicRoutes: [
 ${dynamics.join("\n")}
-  ],
+  ],${resourceRoutesField}
   layoutChains: {
 ${chains.join("\n")}
   },
@@ -487,10 +510,11 @@ ${adapterEntry.wrap("pipeline")}
     const def = manifest.routes[r.path];
     if (!def || !def.prerender) continue;
     const stem = r.path === "/" ? "index" : r.path.slice(1);
-    // The homepage's projection requests are `/.md` / `/.json` (negotiate strips
-    // the ext back to `/`); withAssets serves them for `Accept: text/markdown`.
-    const mdReq = r.path === "/" ? "/.md" : `${r.path}.md`;
-    const jsonReq = r.path === "/" ? "/.json" : `${r.path}.json`;
+    // The homepage's projection requests are `/index.md` / `/index.json` (negotiate
+    // treats `/index` as the alias for `/`); these become the `index.md` /
+    // `index.json` assets the worker serves at the same intuitive paths.
+    const mdReq = r.path === "/" ? "/index.md" : `${r.path}.md`;
+    const jsonReq = r.path === "/" ? "/index.json" : `${r.path}.json`;
     const targets: Array<[string, string]> = [
       [r.path, `${stem}.html`],
       [mdReq, `${stem}.md`],

package/src/deploy.ts

@@ -52,7 +52,7 @@ export async function juneDeploy(appRoot: string, options: DeployOptions = {}):
   // fallback. workers() is the default when neither names one.
   const adapterName = (cfg.deploy?.adapter as { name?: string } | undefined)?.name;
   const target = adapterName ?? cfg.deploy?.target ?? "workers";
-  if (target !== "workers" && target !== "vercel") {
+  if (target !== "workers" && target !== "vercel" && target !== "deno") {
     throw new Error(`unknown deploy target: ${target}`);
   }
 
@@ -62,9 +62,75 @@ export async function juneDeploy(appRoot: string, options: DeployOptions = {}):
   }
 
   const run = options.runCli ?? spawnCli;
-  return target === "vercel"
-    ? deployVercel(appRoot, options, run)
-    : deployWorkers(appRoot, cfg, options, run);
+  if (target === "vercel") return deployVercel(appRoot, options, run);
+  if (target === "deno") return deployDeno(appRoot, cfg, options, run);
+  return deployWorkers(appRoot, cfg, options, run);
+}
+
+// --- Deno Deploy: `deno deploy` ships the built dir (worker.js + assets/) -------
+// ONE-TIME app provisioning (the trap): the app must be created in DYNAMIC mode
+// with worker.js as the entrypoint, or Deno Deploy auto-detects a framework
+// ("internally optimized"), finds none, and every build dies with "No runtime
+// entrypoint provided". The emitted deno.json's deploy.runtime.type="dynamic"
+// only takes precedence AFTER a successful source-config build — a chicken-and-egg
+// the first build can't satisfy. So provision once with the config forced:
+//   deno deploy create --org=<org> --app=<app> --source=local \
+//     --do-not-use-detected-build-config --runtime-mode=dynamic --entrypoint=worker.js
+// After that, plain `deno deploy` re-uses the stuck-free config on every ship.
+const DENO_CREATE_HINT =
+  "first deploy? provision the app in dynamic mode (auto-detect won't find an entrypoint):\n" +
+  "  deno deploy create --org=<org> --app=<app> --source=local \\\n" +
+  "    --do-not-use-detected-build-config --runtime-mode=dynamic --entrypoint=worker.js";
+
+async function deployDeno(
+  appRoot: string,
+  cfg: Awaited<ReturnType<typeof loadJuneConfig>>,
+  options: DeployOptions,
+  run: CliRun,
+): Promise<DeployResult> {
+  const dist = join(appRoot, "dist");
+  if (!existsSync(join(dist, "worker.js"))) {
+    throw new Error(`no built bundle (expected ${join(dist, "worker.js")}) — run june build first`);
+  }
+  if (options.dryRun) {
+    console.log(`dry-run: built ${dist} (skipping deno deploy)`);
+    return { url: null, dryRun: true, configPath: dist, migrated: [] };
+  }
+  if (!process.env.DENO_DEPLOY_TOKEN) {
+    console.log(
+      "note: DENO_DEPLOY_TOKEN not set — `deno deploy` will use its own login\n" +
+        "      (run `deno deploy login` once, or export the token).",
+    );
+  }
+  // Deno Deploy (the current platform; Classic + deployctl retire 2026-07-20). The
+  // emitted deno.json carries deploy.{org,app,runtime}, so `deno deploy` ships dist/
+  // (worker.js + chunks + assets/) with no extra flags onto an already-provisioned
+  // app. --prod targets production (default is a preview). Auth from DENO_DEPLOY_TOKEN.
+  const args = ["deno", "deploy"];
+  if (options.prod) args.push("--prod");
+
+  const { stdout, stderr, exitCode } = await run(args, dist);
+  if (stdout.trim()) console.log(stdout.trimEnd());
+  if (exitCode !== 0) {
+    const out = stderr + stdout;
+    if (/token|login|unauthorized|forbidden|organization was not found|app.*not found/i.test(out)) {
+      throw new Error(
+        "Deno Deploy auth/org failed — set DENO_DEPLOY_TOKEN (or `deno deploy login`) and the\n" +
+          "  org/app in deno({ org, app }).\n  " +
+          DENO_CREATE_HINT +
+          "\n" +
+          stderr.trim(),
+      );
+    }
+    if (/no runtime entrypoint|build config/i.test(out)) {
+      throw new Error("Deno Deploy build failed — " + DENO_CREATE_HINT + "\n" + stderr.trim());
+    }
+    throw new Error(`deno deploy failed (exit ${exitCode})\n${stderr.trim()}`);
+  }
+  // EA serves on *.deno.net (the prod alias <app>.<org>.deno.net + the per-revision
+  // preview); Classic used *.deno.dev. Match both so the URL is always surfaced.
+  const url = stdout.match(/https:\/\/\S+\.deno\.(net|dev)\S*/)?.[0] ?? null;
+  return { url, dryRun: false, configPath: dist, migrated: [] };
 }
 
 // --- Vercel: upload the prebuilt Build Output (.vercel/output/) ---------------

package/src/host.ts

@@ -49,7 +49,7 @@ export interface JuneHost {
   // this with the in-isolate dual-graph loader; the seam stays for the fallback.
   spawnModule(entry: string, args: string[], opts: { conditions?: string[] }): SpawnedModule;
   // Open a LOCAL SQLite database — the internal primitive the `sqlite()` db
-  // adapter builds on (docs/data-layer.md: openDb is demoted from the
+  // adapter builds on (docs/data-layer-boundary.md: openDb is demoted from the
   // user-facing API to a host primitive; apps declare `resources.db` instead).
   openDb(path: string): Promise<JuneDb>;
 }

package/src/index.ts

@@ -4,6 +4,7 @@
 export {
   workers,
   vercel,
+  deno,
   type JuneAdapter,
   type AdapterCapabilities,
   type ResourcePlan,

package/src/kv.ts

@@ -1,4 +1,4 @@
-// `kv` resource adapters. The kv resource IS the cache (docs/data-layer
+// `kv` resource adapters. The kv resource IS the cache (docs/data-layer-boundary
 // .md: "reframe cache as the kv resource — it already is one"): these wrap
 // @junejs/core/cache's CacheStore (memory / redis) as the simpler JuneKv contract,
 // so there is ONE key-value system, surfaced both as cache() and as ambient kv.

package/src/negotiate.ts

@@ -43,6 +43,19 @@ export function negotiate(url: URL, request: Request): Negotiated {
     }
   }
 
+  // "/index" is the conventional alias for the home route "/": the home page's
+  // projections live at the intuitive `/index.md` / `/index.json` (and plain
+  // `/index` serves the home view), matching the build's `index.md` / `index.json`
+  // assets.
+  if (pathname === "/index") {
+    pathname = "/";
+  } else if (target && pathname === "/") {
+    // 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;
+  }
+
   if (!target) {
     const accept = request.headers.get("accept") ?? "";
     for (const [re, t] of ACCEPT_TARGET) {

package/src/pipeline.ts

@@ -56,9 +56,19 @@ export type Resolved = {
   loading?: React.ComponentType;
 };
 
+// A RESOURCE route (app/**/route.*): a handler returning a raw Response — binary,
+// custom content-type, webhook — resolved by the SAME matcher (params from the
+// path), so it lives in the route table instead of a hand-rolled url branch.
+export type ResourceHandler = (
+  request: Request,
+  ctx: RouteContext,
+) => Response | Promise<Response>;
+export type ResolvedResource = { handler: ResourceHandler; params: Record<string, string> };
+
 // The one thing dev and worker do differently: turn a clean pathname into a
 // matched route. Dev walks the filesystem; the worker reads the frozen manifest.
-export type RouteResolver = (pathname: string) => Promise<Resolved | null>;
+// A match is either a page (Resolved) or a resource route (ResolvedResource).
+export type RouteResolver = (pathname: string) => Promise<Resolved | ResolvedResource | null>;
 
 export type PipelineConfig = {
   docConfig: DocumentConfig;
@@ -80,10 +90,18 @@ export type PipelineConfig = {
   extra?: ExtraHandler;
 };
 
-export type ExtraHandler = (
+// app/_middleware.* default export. Runs after the agent surface, before route
+// resolution; return null to pass through, a Response to short-circuit.
+//   ⚠ Don't authorize here — authorization is the single defineAction
+//     run(input, ctx) gate; a check here is a second, ungoverned path.
+//   ⚠ It runs BEFORE routes, so over-broad url matching shadows a page. For a
+//     custom endpoint (binary, webhook) prefer a route.* resource route.
+export type MiddlewareHandler = (
   request: Request,
   url: URL,
 ) => Promise<Response | null> | Response | null;
+/** @deprecated the former name (app/_extra); use {@link MiddlewareHandler}. */
+export type ExtraHandler = MiddlewareHandler;
 
 export type Pipeline = { fetch(request: Request): Promise<Response> };
 
@@ -379,6 +397,10 @@ export function createPipeline(cfg: PipelineConfig): Pipeline {
         target,
         speculative,
       };
+
+      // Resource route (route.*): a raw-Response handler — no projection, no doc
+      // shell. It's matched like any route, so it can't shadow a page.
+      if ("handler" in resolved) return resolved.handler(request, ctx);
       // Streaming Suspense: a view request on a route with loading.tsx AND
       // static metadata flushes the shell + fallback before load() resolves.
       // (data-derived metadata can't stream — the <head> needs the title.)

package/src/router.ts

@@ -31,14 +31,27 @@ export type RouteTreeMatch = {
 
 const routeExtensions = new Set([".tsx", ".jsx", ".ts", ".js"]);
 
-// app/_extra.* — the pre-route escape hatch (a `_` file, so never a route).
-// Dev and the build look it up through this ONE helper so the conventions
-// cannot drift.
-export function findExtraFile(appDir: string): string | null {
+// app/_middleware.* — the pre-route middleware seam (a `_` file, so never a
+// route): runs after the agent surface, before route resolution. Return null to
+// pass; return a Response to short-circuit. Two cautions (see MiddlewareHandler):
+// don't authorize here (that's the single run(input, ctx) gate), and because it
+// runs BEFORE routes, over-broad matching can shadow a page. For a custom
+// endpoint (binary, webhook), prefer a route.* resource route instead.
+// `_extra` is the deprecated former name (warned + still honored for one cycle).
+// Dev and the build look it up through this ONE helper so the conventions can't
+// drift.
+export function findMiddlewareFile(appDir: string): string | null {
   for (const ext of routeExtensions) {
-    const f = join(appDir, `_extra${ext}`);
+    const f = join(appDir, `_middleware${ext}`);
     if (existsSync(f)) return f;
   }
+  for (const ext of routeExtensions) {
+    const f = join(appDir, `_extra${ext}`);
+    if (existsSync(f)) {
+      console.warn("[june] app/_extra is deprecated — rename it to app/_middleware.");
+      return f;
+    }
+  }
   return null;
 }
 
@@ -58,6 +71,14 @@ function isPageFile(file: string) {
   return base === "page" || base === "index";
 }
 
+// app/**/route.* — a RESOURCE route: a handler returning a raw Response (binary,
+// custom content-type, webhook), not a React page. It's a first-class route (in
+// the route table, params from the path, resolved by the SAME matcher), so it
+// can't shadow pages by accident and doesn't need hand-rolled url matching.
+export function isResourceFile(file: string): boolean {
+  return baseName(file) === "route";
+}
+
 // Special (never-a-route) files that shape the segment tree.
 const SPECIAL_FILES = new Set(["layout", "loading", "error", "not-found"]);
 
@@ -118,7 +139,7 @@ function routePath(appDir: string, file: string) {
   // Route groups shape the filesystem, not the URL.
   const parts = withoutExtension.split("/").filter((p) => !isRouteGroup(p));
 
-  if (parts.at(-1) === "page" || parts.at(-1) === "index") {
+  if (parts.at(-1) === "page" || parts.at(-1) === "index" || parts.at(-1) === "route") {
     parts.pop();
   }
 
@@ -146,9 +167,12 @@ export async function matchRouteTree(
     const entries = await listDir(dir);
     const segments = [...chain, segmentAt(dir, entries)];
 
-    // Terminal: URL consumed → find the page in this dir.
+    // Terminal: URL consumed → find the page (or resource route) in this dir.
     if (rest.length === 0) {
-      const page = fileFor(entries, dir, "page") ?? fileFor(entries, dir, "index");
+      const page =
+        fileFor(entries, dir, "page") ??
+        fileFor(entries, dir, "index") ??
+        fileFor(entries, dir, "route");
       if (page) return { file: page, params, segments };
     } else if (!options.pageConvention) {
       // Legacy flat convention: a non-special leaf FILE names the final segment
@@ -251,17 +275,19 @@ export async function routeFiles(
     if (!routeExtensions.has(file.match(/\.[^.]+$/)?.[0] ?? "")) return false;
     if (isSpecialFile(file)) return false;
     if (file.split(sep).some((p) => p.startsWith("_"))) return false;
-    if (options.pageConvention && !isPageFile(file)) return false;
+    if (options.pageConvention && !isPageFile(file) && !isResourceFile(file)) return false;
     return true;
   });
 }
 
-// All route paths under appDir (for sitemap / llms.txt / api-catalog).
+// All PAGE route paths under appDir (for sitemap / llms.txt / api-catalog).
+// Resource routes (route.*) are excluded — they're machine endpoints (og images,
+// webhooks), not pages, so they don't belong in the human/agent sitemap.
 export async function listRoutes(
   appDir: string,
   options: MatchOptions = {},
 ): Promise<string[]> {
-  const files = await routeFiles(appDir, options);
+  const files = (await routeFiles(appDir, options)).filter((file) => !isResourceFile(file));
   return [...new Set(files.map((file) => routePath(appDir, file)))].sort();
 }
 

package/src/worker.ts

@@ -16,13 +16,16 @@ import type { AgentConfig } from "@junejs/core/config";
 import type { DocumentConfig } from "@junejs/core/document";
 import type { Resources } from "@junejs/core/resources";
 
-import { createPipeline, type ExtraHandler, type LayoutComponent, type LoadingComponent, type Resolved } from "./pipeline";
+import { createPipeline, type ExtraHandler, type LayoutComponent, type LoadingComponent, type Resolved, type ResolvedResource, type ResourceHandler } from "./pipeline";
 
 export type WorkerManifest = {
   // Static paths → route definitions ("/", "/users", ...).
   routes: Record<string, BrandedRoute>;
   // 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.
+  resourceRoutes?: Array<{ pattern: string; handler: ResourceHandler }>;
   // 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[]>;
@@ -93,6 +96,11 @@ export function createWorker(
     def: d.def,
     pattern: d.pattern,
   }));
+  const resources = (manifest.resourceRoutes ?? []).map((r) => ({
+    ...compilePattern(r.pattern),
+    handler: r.handler,
+    pattern: r.pattern,
+  }));
   const routeList = [
     ...Object.keys(manifest.routes),
     ...(manifest.dynamicRoutes ?? []).map((d) => d.pattern),
@@ -116,7 +124,7 @@ export function createWorker(
     notFoundComponent: manifest.notFound,
     extra: manifest.extra,
     resources: provider ? () => provider(currentEnv) : undefined,
-    resolve: async (pathname): Promise<Resolved | null> => {
+    resolve: async (pathname): Promise<Resolved | ResolvedResource | null> => {
       const staticDef = manifest.routes[pathname];
       if (staticDef)
         return { def: staticDef, params: {}, chain: chainFor(pathname), loading: loadingFor(pathname) };
@@ -134,6 +142,19 @@ export function createWorker(
           return { def: d.def, params, chain: chainFor(d.pattern), loading: loadingFor(d.pattern) };
         }
       }
+      // Resource routes after pages (so a page is never shadowed by one).
+      for (const r of resources) {
+        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 };
+        }
+      }
       return null;
     },
   });
@@ -215,3 +236,54 @@ export function withAssets(
     },
   };
 }
+
+// The Deno-target twin of withAssets. Deno Deploy has NO CDN / asset binding, so
+// the handler serves the hashed framework assets (/_june/*) from the bundle's
+// co-located assets/ dir and falls through to the pipeline for everything else —
+// the same split vercel() gets from the CDN, but in-process. The deno() adapter
+// bakes `export default { fetch: withDenoAssets(pipeline) }` into the entry (the
+// Web Standard handler `deno serve` / Deno Deploy runs). Deno globals are
+// referenced only inside the body, so non-Deno bundles tree-shake this out.
+declare const Deno: {
+  readFile(path: string | URL): Promise<Uint8Array>;
+};
+
+const ASSET_CONTENT_TYPES: Record<string, string> = {
+  css: "text/css; charset=utf-8",
+  js: "text/javascript; charset=utf-8",
+  json: "application/json; charset=utf-8",
+  map: "application/json; charset=utf-8",
+  svg: "image/svg+xml",
+  png: "image/png",
+  jpg: "image/jpeg",
+  jpeg: "image/jpeg",
+  webp: "image/webp",
+  avif: "image/avif",
+  ico: "image/x-icon",
+  woff2: "font/woff2",
+  woff: "font/woff",
+};
+
+export function withDenoAssets(pipeline: FetchPipeline): (request: Request) => Promise<Response> {
+  return async (request) => {
+    const url = new URL(request.url);
+    if (request.method === "GET" && url.pathname.startsWith("/_june/")) {
+      try {
+        const file = await Deno.readFile(new URL(`./assets${url.pathname}`, import.meta.url));
+        const ext = url.pathname.split(".").pop()?.toLowerCase() ?? "";
+        return new Response(file as BodyInit, {
+          headers: {
+            "content-type": ASSET_CONTENT_TYPES[ext] ?? "application/octet-stream",
+            "cache-control": "public, max-age=31536000, immutable",
+          },
+        });
+      } catch {
+        /* not on disk → fall through (the pipeline 404s) */
+      }
+    }
+    // No env arg: Deno has no platform bindings (unlike D1/KV on workers); env-
+    // driven resources (turso) read process.env / Deno.env themselves. Keeps the
+    // function off the --allow-env permission too.
+    return pipeline.fetch(request);
+  };
+}