@junejs/server 0.0.7 → 0.0.9

package/package.json

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

package/src/app.ts

@@ -13,7 +13,7 @@ import { dirname, resolve } from "node:path";
 import { pathToFileURL } from "node:url";
 import type { ComponentType } from "react";
 
-import { isRouteDefinition } from "@junejs/core/route";
+import { routeFromModule } from "@junejs/core/route";
 import { resolveAgent, resolveSpeculationRules, type JuneConfig } from "@junejs/core/config";
 import type { DocumentConfig } from "@junejs/core/document";
 import { runWithTrace, type RequestTrace } from "@junejs/core/instrumentation";
@@ -117,9 +117,10 @@ export function createApp({ appDir: appDirInput, config = {} }: CreateAppOptions
       resolve: async (pathname): Promise<Resolved | null> => {
         const match = await matchRouteTree(appDir, pathname, { pageConvention: true });
         if (!match) return null;
-        const mod = (await import(pathToFileURL(match.file).href)) as { default?: unknown };
-        if (!isRouteDefinition(mod.default)) return null;
-        return { def: mod.default, params: match.params, chain: await loadChain(match.segments) };
+        const mod = await import(pathToFileURL(match.file).href);
+        const def = routeFromModule(mod);
+        if (!def) return null;
+        return { def, params: match.params, chain: await loadChain(match.segments) };
       },
     });
   }

package/src/build.ts

@@ -24,7 +24,8 @@ import { pathToFileURL } from "node:url";
 
 import { loadJuneConfig } from "./config-loader";
 import { resolveAgent, resolveSpeculationRules } from "@junejs/core/config";
-import { isRouteDefinition, type BrandedRoute } from "@junejs/core/route";
+import { buildLinkHeader } from "@junejs/core/discovery";
+import { routeFromModule, type BrandedRoute } from "@junejs/core/route";
 import type { DocumentConfig } from "@junejs/core/document";
 import { collection } from "./content";
 import { createWorker, type WorkerManifest } from "./worker";
@@ -171,14 +172,15 @@ export async function buildManifest(appRoot: string): Promise<WorkerManifest> {
   const layoutChains: Record<string, LayoutComponent[]> = {};
 
   for (const r of scanned) {
-    const mod = (await import(pathToFileURL(r.file).href)) as { default?: unknown };
-    if (!isRouteDefinition(mod.default)) continue;
+    const mod = await import(pathToFileURL(r.file).href);
+    const def = routeFromModule(mod);
+    if (!def) continue;
     const chain = await componentsFor(r.layouts);
     if (r.dynamic) {
-      dynamicRoutes.push({ pattern: r.path, def: mod.default });
+      dynamicRoutes.push({ pattern: r.path, def });
       layoutChains[r.path] = chain;
     } else {
-      routes[r.path] = mod.default;
+      routes[r.path] = def;
       layoutChains[r.path] = chain;
     }
   }
@@ -224,7 +226,13 @@ export async function juneBuild(
   const frozen = await freezeConfig(appRoot);
 
   // ---- generated entry -----------------------------------------------------
-  const imports: string[] = [`import { createWorker } from "@junejs/server/worker";`];
+  // Routes are namespace-imported and adapted with routeFromModule, so the
+  // multi-export page shape (default view + named loader/json/md) and the legacy
+  // route({}) default export both work.
+  const imports: string[] = [
+    `import { createWorker } from "@junejs/server/worker";`,
+    `import { routeFromModule } from "@junejs/core/route";`,
+  ];
   const statics: string[] = [];
   const dynamics: string[] = [];
   const layoutIds = new Map<string, string>();
@@ -239,9 +247,9 @@ export async function juneBuild(
   };
   const chains: string[] = [];
   routes.forEach((r, i) => {
-    imports.push(`import r${i} from ${JSON.stringify(importPath(genDir, r.file))};`);
-    if (r.dynamic) dynamics.push(`    { pattern: ${JSON.stringify(r.path)}, def: r${i} },`);
-    else statics.push(`    ${JSON.stringify(r.path)}: r${i},`);
+    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(", ")}],`);
   });
 
@@ -250,10 +258,17 @@ export async function juneBuild(
     imports.push(`import extra from ${JSON.stringify(importPath(genDir, builtExtraFile))};`);
   }
 
+  // The deployed worker runs first (wrangler assets.run_worker_first) and wraps
+  // the pipeline with withAssets — so prerendered pages, served from the ASSETS
+  // binding, still get the Link header + Accept:markdown negotiation the asset
+  // layer can't do. The Link header is frozen here from the same builder the
+  // pipeline uses, so the static and dynamic surfaces advertise identically.
+  const linkHeader = buildLinkHeader(frozen.agent);
   const entry = `// AUTO-GENERATED by \`june build\` — do not edit. Regenerate: june build .
+import { withAssets } from "@junejs/server/worker";
 ${imports.join("\n")}
 
-export default createWorker({
+const pipeline = createWorker({
   routes: {
 ${statics.join("\n")}
   },
@@ -267,6 +282,8 @@ ${chains.join("\n")}
   agent: ${JSON.stringify(frozen.agent)},
   earlyHints: ${JSON.stringify(frozen.earlyHints)},${builtExtraFile ? "\n  extra," : ""}
 });
+
+export default withAssets(pipeline, { link: ${JSON.stringify(linkHeader)} });
 `;
   const entryFile = join(genDir, "worker-entry.tsx");
   await writeFile(entryFile, entry);
@@ -310,11 +327,15 @@ ${chains.join("\n")}
     const def = manifest.routes[r.path];
     if (!def || !def.prerender) continue;
     const stem = r.path === "/" ? "index" : r.path.slice(1);
-    const targets: Array<[string, string]> = [[r.path, `${stem}.html`]];
-    if (r.path !== "/") {
-      targets.push([`${r.path}.md`, `${stem}.md`]);
-      if (typeof def.json === "function") targets.push([`${r.path}.json`, `${stem}.json`]);
-    }
+    // 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`;
+    const targets: Array<[string, string]> = [
+      [r.path, `${stem}.html`],
+      [mdReq, `${stem}.md`],
+    ];
+    if (typeof def.json === "function") targets.push([jsonReq, `${stem}.json`]);
     for (const [reqPath, file] of targets) {
       const res = await worker.fetch(new Request(`https://prerender.june${reqPath}`));
       if (!res.ok) throw new Error(`prerender ${reqPath} → ${res.status}`);
@@ -341,15 +362,30 @@ ${chains.join("\n")}
     const pkg = existsSync(pkgPath)
       ? (JSON.parse(await Bun.file(pkgPath).text()) as { name?: string })
       : {};
+    const deployCfg = (await loadJuneConfig(appRoot)).deploy;
     await writeFile(
       join(outDir, "wrangler.jsonc"),
       JSON.stringify(
         {
-          name: (pkg.name ?? basename(appRoot)).replace(/[^a-z0-9-]/gi, "-").toLowerCase(),
+          name:
+            deployCfg?.name ??
+            (pkg.name ?? basename(appRoot)).replace(/[^a-z0-9-]/gi, "-").toLowerCase(),
           main: "./worker.js",
           compatibility_date: "2025-01-01",
           compatibility_flags: ["nodejs_compat"],
-          ...(hasAssets ? { assets: { directory: "./assets" } } : {}),
+          // run_worker_first: the worker wraps asset serving (withAssets) so
+          // prerendered pages still get Link headers + Accept:markdown
+          // negotiation. The ASSETS binding lets the worker serve the static
+          // files itself.
+          ...(hasAssets
+            ? { assets: { directory: "./assets", binding: "ASSETS", run_worker_first: true } }
+            : {}),
+          // config deploy.domain → a Workers custom domain; without it the
+          // generated file regenerating on every build would silently drop a
+          // hand-attached domain.
+          ...(deployCfg?.domain
+            ? { routes: [{ pattern: deployCfg.domain, custom_domain: true }] }
+            : {}),
         },
         null,
         2,

package/src/db.ts

@@ -3,15 +3,28 @@
 // by the host, injected onto RouteContext as `ctx.db`. The framework depends on
 // the JuneDb contract; these adapters (and Juno on top) are swappable.
 
+import { mkdirSync } from "node:fs";
+import { dirname } from "node:path";
+
 import type { DbFactory, JuneDb, RunResult } from "@junejs/core/resources";
 
 import { host } from "./host";
 
-// Local SQLite — the zero-config dev default (embedded file or :memory:). Built
-// on the demoted host.openDb primitive (the sync bun:/node: driver wrapped async).
+// Local SQLite — the zero-config dev default. A persistent FILE, not :memory:,
+// on purpose: `june dev` restarts the process on every save (the watch
+// supervisor), so an in-memory default would evaporate your dev data at each
+// edit. A file also makes the dev db inspectable with the sqlite3 every
+// machine already has (`sqlite3 .june/dev.sqlite`). Pass ":memory:" explicitly
+// for ephemerality.
 export function sqlite(opts: { path?: string } = {}): DbFactory {
-  const path = opts.path ?? ":memory:";
-  return { kind: "sqlite", open: () => host.openDb(path) };
+  const path = opts.path ?? ".june/dev.sqlite";
+  return {
+    kind: "sqlite",
+    open: () => {
+      if (path !== ":memory:") mkdirSync(dirname(path), { recursive: true });
+      return host.openDb(path);
+    },
+  };
 }
 
 // --- D1 (Cloudflare) — the third openDb impl (rebuild-plan Phase 5) ----------

package/src/negotiate.ts

@@ -10,12 +10,10 @@ import type { RenderTarget } from "@junejs/core/route";
 
 const EXT_TARGET: Record<string, RenderTarget> = {
   ".json": "json",
-  ".agent": "agent",
   ".md": "md",
 };
 
 const ACCEPT_TARGET: Array<[test: RegExp, target: RenderTarget]> = [
-  [/application\/vnd\.june-agent\+json/, "agent"],
   [/text\/markdown/, "md"],
   [/application\/json/, "json"],
 ];

package/src/pipeline.ts

@@ -18,14 +18,12 @@ import React from "react";
 import { renderToReadableStream } from "react-dom/server";
 
 import {
-  resolveProjection,
   type BrandedRoute,
   type Metadata,
   type RenderTarget,
   type RouteContext,
 } from "@junejs/core/route";
 import { Document, type DocumentConfig } from "@junejs/core/document";
-import { isResourceManifest } from "@junejs/core/agent";
 import {
   apiCatalog,
   buildLinkHeader,
@@ -34,7 +32,7 @@ import {
   robotsTxt,
   sitemapXml,
 } from "@junejs/core/discovery";
-import { mcpHandler } from "@junejs/core/mcp";
+import { mcpHandler, mcpTools } from "@junejs/core/mcp";
 import type { AgentConfig } from "@junejs/core/config";
 import type { Resources } from "@junejs/core/resources";
 
@@ -95,6 +93,23 @@ function text(body: string, contentType: string, init?: ResponseInit) {
   return new Response(body, { ...init, headers });
 }
 
+// The default favicon: the site name's first character in a rounded square —
+// a plain SVG string, so it needs no fonts, no rasterizer, and works for CJK
+// names as readily as latin ones. Served at /favicon.svg AND /favicon.ico
+// (browsers respect the svg content-type), so no June app 404s its icon.
+function letterFavicon(siteName: string | undefined): Response {
+  const first = (siteName ?? "").trim().charAt(0) || "•";
+  const letter = first.toUpperCase().replace(/[<>&"']/g, "");
+  return text(
+    `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64">` +
+      `<rect width="64" height="64" rx="12" fill="#1d1d1f"/>` +
+      `<text x="32" y="32" dy=".36em" text-anchor="middle" font-family="ui-sans-serif, system-ui, sans-serif" font-size="34" font-weight="600" fill="#fbfbf8">${letter || "•"}</text>` +
+      `</svg>\n`,
+    "image/svg+xml",
+    { headers: { "cache-control": "public, max-age=86400" } },
+  );
+}
+
 export function createPipeline(cfg: PipelineConfig): Pipeline {
   const { docConfig, agent } = cfg;
   const NotFound = cfg.notFoundComponent ?? DefaultNotFound;
@@ -118,8 +133,13 @@ export function createPipeline(cfg: PipelineConfig): Pipeline {
       (acc, L) => React.createElement(L, null, acc),
       node,
     );
+    // WebMCP: register the app's actions as browser tools. Computed per render
+    // from the live registry (stable after warmup), gated on agent.webmcp + mcp
+    // (execute proxies to /mcp). No actions → no script → page stays zero-JS.
+    const webmcpTools = agent.webmcp && agent.mcp ? mcpTools() : null;
+    const config: DocumentConfig = webmcpTools?.length ? { ...docConfig, webmcpTools } : docConfig;
     const stream = await renderToReadableStream(
-      React.createElement(Document, { config: docConfig, metadata, children: wrapped }),
+      React.createElement(Document, { config, metadata, children: wrapped }),
     );
     await stream.allReady; // fully resolved markup (no streamed Suspense fallbacks)
     const html = "<!doctype html>\n" + (await new Response(stream).text());
@@ -145,9 +165,18 @@ export function createPipeline(cfg: PipelineConfig): Pipeline {
   }
 
   async function renderMarkdown(def: BrandedRoute, data: unknown, ctx: RouteContext): Promise<Response> {
-    if (def.md) return text(await def.md(data, ctx), "text/markdown; charset=utf-8");
-    const payload = def.json ? await def.json(data, ctx) : data;
-    return text("```json\n" + JSON.stringify(payload, null, 2) + "\n```\n", "text/markdown; charset=utf-8");
+    // md fn → custom; absent → derive from the json projection (loader data when
+    // json is also absent). md/json === false is handled as 404 by the caller.
+    const jsonData =
+      typeof def.json === "function" ? await def.json(data, ctx) : def.json === false ? null : data;
+    const body =
+      typeof def.md === "function"
+        ? await def.md(data, ctx)
+        : "```json\n" + JSON.stringify(jsonData, null, 2) + "\n```\n";
+    // x-markdown-tokens: a rough estimate (~4 chars/token) agents use to budget.
+    return text(body, "text/markdown; charset=utf-8", {
+      headers: { "x-markdown-tokens": String(Math.ceil(body.length / 4)) },
+    });
   }
 
   async function renderProjection(
@@ -157,21 +186,17 @@ export function createPipeline(cfg: PipelineConfig): Pipeline {
     ctx: RouteContext,
   ): Promise<Response> {
     const { def, chain } = resolved;
-    if (target === "md") return renderMarkdown(def, data, ctx);
+    // A projection declared `false` is disabled → 404 (and absent from discovery).
+    if (def[target] === false) return notFoundResponse(target, ctx.url.pathname);
 
-    switch (resolveProjection(def, target)) {
-      case "json":
-        return Response.json(await def.json!(data, ctx));
-      case "agent": {
-        const out = await def.agent!(data, ctx);
-        const body = isResourceManifest(out) ? out.toManifest() : out;
-        return text(JSON.stringify(body), "application/vnd.june-agent+json");
-      }
-      default: {
-        const node = def.view ? def.view(data, ctx) : null;
-        return renderDocument(node, resolveMeta(def, data, ctx), 200, chain);
-      }
+    if (target === "md") return renderMarkdown(def, data, ctx);
+    if (target === "json") {
+      // Convention: a json() fn customizes; absent → serialize the loader data.
+      const payload = typeof def.json === "function" ? await def.json(data, ctx) : data;
+      return Response.json(payload);
     }
+    const node = def.view ? def.view(data, ctx) : null;
+    return renderDocument(node, resolveMeta(def, data, ctx), 200, chain);
   }
 
   async function discovery(url: URL): Promise<Response | null> {
@@ -219,6 +244,15 @@ export function createPipeline(cfg: PipelineConfig): Pipeline {
         if (out) return out;
       }
 
+      // --- default favicon (after extra so an app can override it) ----------
+      if (
+        request.method === "GET" &&
+        !docConfig.site.icon &&
+        (url.pathname === "/favicon.svg" || url.pathname === "/favicon.ico")
+      ) {
+        return letterFavicon(docConfig.site.name);
+      }
+
       // --- routes ----------------------------------------------------------
       const { target, pathname, speculative } = negotiate(url, request);
       const resolved = await cfg.resolve(pathname);

package/src/router.ts

@@ -67,8 +67,12 @@ function isSpecialFile(file: string) {
 
 const isRouteGroup = (name: string) => /^\(.+\)$/.test(name);
 const isParamDir = (name: string) => /^\[([A-Za-z_][A-Za-z0-9_]*)\]$/.test(name);
+// [[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 paramName = (name: string) => name.replace(/^\[+(\.\.\.)?|\]+$/g, "");
 
 type DirEntry = { name: string; dir: boolean };
 
@@ -164,7 +168,16 @@ export async function matchRouteTree(
       if (hit) return hit;
     }
 
-    if (rest.length === 0) return null;
+    if (rest.length === 0) {
+      // Optional segments match ABSENCE too: descend without consuming and
+      // without setting the param.
+      for (const e of entries) {
+        if (!e.dir || !(isOptionalDir(e.name) || isOptionalCatchAllDir(e.name))) continue;
+        const hit = await descend(join(dir, e.name), [], params, segments);
+        if (hit) return hit;
+      }
+      return null;
+    }
     const [head, ...tail] = rest as [string, ...string[]];
 
     // 1) exact static dir
@@ -173,9 +186,9 @@ export async function matchRouteTree(
       const hit = await descend(join(dir, head), tail, params, segments);
       if (hit) return hit;
     }
-    // 2) [param] dirs
+    // 2) [param] and [[param]] dirs consume one segment
     for (const e of entries) {
-      if (!e.dir || !isParamDir(e.name)) continue;
+      if (!e.dir || !(isParamDir(e.name) || isOptionalDir(e.name))) continue;
       const hit = await descend(
         join(dir, e.name),
         tail,
@@ -184,9 +197,9 @@ export async function matchRouteTree(
       );
       if (hit) return hit;
     }
-    // 3) [...catchAll] dirs consume everything remaining
+    // 3) [...catchAll] and [[...catchAll]] dirs consume everything remaining
     for (const e of entries) {
-      if (!e.dir || !isCatchAllDir(e.name)) continue;
+      if (!e.dir || !(isCatchAllDir(e.name) || isOptionalCatchAllDir(e.name))) continue;
       const hit = await descend(
         join(dir, e.name),
         [],

package/src/worker.ts

@@ -41,26 +41,45 @@ export type WorkerManifest = {
 
 type Compiled = { regex: RegExp; names: string[]; def: BrandedRoute; pattern: string };
 
-// "/posts/[slug]" | "/docs/[...path]" → matcher
+// "/posts/[slug]" | "/docs/[...path]" | "/notes/[[tag]]" → matcher. Optional
+// segments ([[x]], [[...x]]) wrap slash + capture together so absence matches;
+// a pattern of ONLY optional segments must also match the bare "/".
 function compilePattern(pattern: string): { regex: RegExp; names: string[] } {
   const names: string[] = [];
-  const source = pattern
-    .split("/")
-    .map((seg) => {
-      const ca = seg.match(/^\[\.\.\.(\w+)\]$/);
-      if (ca) {
-        names.push(ca[1]!);
-        return "(.+)";
-      }
-      const p = seg.match(/^\[(\w+)\]$/);
-      if (p) {
-        names.push(p[1]!);
-        return "([^/]+)";
-      }
-      return seg.replace(/[.*+?^${}()|\\]/g, "\\$&");
-    })
-    .join("/");
-  return { regex: new RegExp(`^${source}$`), names };
+  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 += "/([^/]+)";
+      allOptional = false;
+      continue;
+    }
+    source += "/" + seg.replace(/[.*+?^${}()|\\]/g, "\\$&");
+    allOptional = false;
+  }
+  if (source === "") return { regex: /^\/$/, names };
+  return { regex: new RegExp(allOptional ? `^(?:${source}|/)$` : `^${source}$`), names };
 }
 
 export function createWorker(manifest: WorkerManifest): { fetch(request: Request): Promise<Response> } {
@@ -91,7 +110,14 @@ export function createWorker(manifest: WorkerManifest): { fetch(request: Request
       for (const d of dynamic) {
         const m = pathname.match(d.regex);
         if (m) {
-          const params = Object.fromEntries(d.names.map((n, i) => [n, decodeURIComponent(m[i + 1]!)]));
+          // 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)]];
+            }),
+          );
           return { def: d.def, params, chain: chainFor(d.pattern) };
         }
       }
@@ -99,3 +125,65 @@ export function createWorker(manifest: WorkerManifest): { fetch(request: Request
     },
   });
 }
+
+// --- the deployed worker's outermost layer (run_worker_first) ---------------
+// Prerendered pages are served as static ASSETS, which bypass the pipeline —
+// so the agent-ready signals the asset layer can't produce get added HERE:
+//   1. `Accept: text/markdown` on a page → the prerendered `.md` asset.
+//   2. a `Link` header on every HTML response (RFC 8288/9727 discovery).
+//   3. `x-markdown-tokens` on markdown responses.
+// Static assets are served by the ASSETS binding (no re-render); only genuinely
+// dynamic routes reach the pipeline. With no ASSETS binding (no prerender), this
+// is a transparent pass-through to the pipeline.
+type AssetEnv = { ASSETS?: { fetch(request: Request): Promise<Response> } };
+type FetchPipeline = { fetch(request: Request): Promise<Response> };
+
+const estimateTokens = (s: string) => String(Math.ceil(s.length / 4));
+
+export function withAssets(
+  pipeline: FetchPipeline,
+  opts: { link?: string | null } = {},
+): { fetch(request: Request, env?: AssetEnv): Promise<Response> } {
+  return {
+    async fetch(request, env) {
+      const assets = env?.ASSETS;
+      const url = new URL(request.url);
+      const isPagePath = !/\.[a-z0-9]+$/i.test(url.pathname); // no file extension
+      const accept = request.headers.get("accept") ?? "";
+
+      // 1. Markdown content negotiation on a page path → prerendered .md asset.
+      if (assets && request.method === "GET" && isPagePath && /text\/markdown/.test(accept)) {
+        const base = url.pathname === "/" ? "/index" : url.pathname.replace(/\/+$/, "");
+        const mdUrl = new URL(url);
+        mdUrl.pathname = `${base}.md`;
+        const a = await assets.fetch(new Request(mdUrl.toString(), { headers: request.headers }));
+        if (a.ok) {
+          const body = await a.text();
+          const headers = new Headers(a.headers);
+          headers.set("content-type", "text/markdown; charset=utf-8");
+          headers.set("x-markdown-tokens", estimateTokens(body));
+          if (opts.link) headers.set("link", opts.link);
+          return new Response(body, { status: 200, headers });
+        }
+        // no prerendered .md → fall through; a dynamic route renders it below.
+      }
+
+      // 2. Static assets (prerendered HTML/.md/.json, /client.js) served direct.
+      if (assets) {
+        const a = await assets.fetch(request);
+        if (a.status !== 404) {
+          const ct = a.headers.get("content-type") ?? "";
+          if (opts.link && ct.includes("text/html") && !a.headers.has("link")) {
+            const headers = new Headers(a.headers);
+            headers.set("link", opts.link);
+            return new Response(a.body, { status: a.status, headers });
+          }
+          return a;
+        }
+      }
+
+      // 3. Dynamic routes → the render pipeline (already sets Link + negotiates).
+      return pipeline.fetch(request);
+    },
+  };
+}