@junejs/server 0.1.0-dev.5 → 0.1.0-dev.7

package/dist/adapter.d.ts

@@ -23,6 +23,7 @@ type AdapterEmitContext = {
   config: JuneConfig;
   plan: ResourcePlan;
   defaultName: string;
+  publicFiles?: string[];
 };
 interface JuneAdapter {
   readonly name: string;

package/dist/adapter.js

@@ -1,6 +1,6 @@
 import { existsSync } from "node:fs";
 import { copyFile, cp, mkdir, readdir, rm, writeFile } from "node:fs/promises";
-import { join } from "node:path";
+import { dirname, join } from "node:path";
 //#region src/adapter.ts
 function workers(opts) {
 	return {
@@ -78,7 +78,7 @@ function vercel(opts) {
 				wrap: (pipelineVar) => isEdge ? env + `export default (request) => ${pipelineVar}.fetch(request, __env);` : env + `export default { fetch: (request) => ${pipelineVar}.fetch(request, __env) };`
 			};
 		},
-		async emit({ appRoot, outDir, hasAssets }) {
+		async emit({ appRoot, outDir, hasAssets, publicFiles }) {
 			const out = join(appRoot, ".vercel", "output");
 			const fnDir = join(out, "functions", `${VERCEL_FUNCTION}.func`);
 			await rm(out, {
@@ -106,6 +106,13 @@ function vercel(opts) {
 				const src = join(outDir, "assets", "_june");
 				if (existsSync(src)) await cp(src, join(out, "static", "_june"), { recursive: true });
 			}
+			for (const rel of publicFiles ?? []) {
+				const from = join(outDir, "assets", rel);
+				if (!existsSync(from)) continue;
+				const to = join(out, "static", rel);
+				await mkdir(dirname(to), { recursive: true });
+				await copyFile(from, to);
+			}
 			await writeFile(join(out, "config.json"), JSON.stringify({
 				version: 3,
 				routes: [

package/dist/agent-discover.js

@@ -2,7 +2,7 @@ import { existsSync } from "node:fs";
 import { readFile, readdir } from "node:fs/promises";
 import { basename, extname, join } from "node:path";
 import { pathToFileURL } from "node:url";
-import { defineAgent } from "@junejs/core/agent-config";
+import { defineAgent, resolveChannel } from "@junejs/core/agent-config";
 import { connectAll } from "@junejs/core/connections";
 //#region src/agent-discover.ts
 async function scan(dir, ext) {
@@ -48,7 +48,7 @@ async function discoverAgent(dir) {
 	const channels = [];
 	for (const f of await scan(join(dir, "channels"), ".ts")) {
 		const mod = await import(pathToFileURL(f).href);
-		if (mod.default) channels.push(mod.default);
+		if (mod.default) channels.push(resolveChannel(mod.default, process.env));
 	}
 	const connectionDefs = [];
 	for (const f of await scan(join(dir, "connections"), ".ts")) {

package/dist/agent-durable.d.ts

@@ -1,4 +1,6 @@
+import { Channel, ChannelFactory } from "@junejs/core/agent-config";
 import { Model, Msg, SessionStore, Tool } from "@junejs/core/agent-runtime";
+import { Resources } from "@junejs/core/resources";
 //#region src/agent-durable.d.ts
 interface SqlStorageCursor<T = Record<string, unknown>> {
   toArray(): T[];
@@ -40,9 +42,13 @@ type DoAgentDef = {
   model: Model;
   tools: Tool[];
   instructions?: string;
+  resources?: Resources;
+  services?: unknown;
 };
 declare class AgentDurableObject {
   private session;
+  private readonly resources;
+  private readonly services;
   constructor(state: DurableObjectState, def: DoAgentDef);
   turn(input: {
     turnId?: string;
@@ -56,5 +62,11 @@ declare function durableAgentSurface(getNamespace: () => DurableObjectNamespace
   agentName: string;
   chatPath?: string;
 }): (req: Request) => Promise<Response | null>;
+declare function durableChannelSurface(getNamespace: () => DurableObjectNamespace | undefined, opts: {
+  agentName: string;
+  channels: (Channel | ChannelFactory)[];
+  env: unknown;
+  waitUntil?: (p: Promise<unknown>) => void;
+}): (req: Request) => Promise<Response | null>;
 //#endregion
-export { AgentDurableObject, DoAgentDef, DoSessionStore, DurableObjectNamespace, DurableObjectState, DurableObjectStub, DurableStorage, SqlStorage, SqlStorageCursor, durableAgentSurface, durableFetch };
+export { AgentDurableObject, DoAgentDef, DoSessionStore, DurableObjectNamespace, DurableObjectState, DurableObjectStub, DurableStorage, SqlStorage, SqlStorageCursor, durableAgentSurface, durableChannelSurface, durableFetch };

package/dist/agent-durable.js

@@ -1,4 +1,6 @@
+import { channelDispatch, resolveChannel } from "@junejs/core/agent-config";
 import { AgentSession, withSystem } from "@junejs/core/agent-runtime";
+import { ensureScope, runInScope } from "@junejs/db";
 //#region src/agent-durable.ts
 var DoSessionStore = class {
 	storage;
@@ -61,13 +63,21 @@ const crossDoUnsupported = { session() {
 } };
 var AgentDurableObject = class {
 	session;
+	resources;
+	services;
 	constructor(state, def) {
 		const store = new DoSessionStore(state.storage);
 		const model = def.instructions ? withSystem(def.model, def.instructions) : def.model;
+		this.resources = def.resources ?? {};
+		this.services = def.services;
 		this.session = new AgentSession(def.name ?? "agent", "self", store, new InProcBroadcaster(), model, def.tools, crossDoUnsupported);
 	}
-	turn(input) {
-		return this.session.turn(input);
+	async turn(input) {
+		await ensureScope();
+		return runInScope({
+			resources: this.resources,
+			services: this.services
+		}, () => this.session.turn(input));
 	}
 	transcript() {
 		return this.session.transcript();
@@ -102,5 +112,30 @@ function durableAgentSurface(getNamespace, opts) {
 		}));
 	};
 }
+function durableChannelSurface(getNamespace, opts) {
+	return channelDispatch(opts.channels.map((c) => resolveChannel(c, opts.env)), {
+		agent: {
+			name: opts.agentName,
+			instructions: "",
+			tools: [],
+			skills: [],
+			channels: [],
+			connections: []
+		},
+		waitUntil: opts.waitUntil,
+		run: async (message, o) => {
+			const namespace = getNamespace();
+			if (!namespace) throw new Error("durableChannelSurface: no Durable Object namespace bound (env.AGENT)");
+			const { text } = await (await durableFetch(namespace, opts.agentName, o?.session ?? "default", new Request("https://do/turn", {
+				method: "POST",
+				body: JSON.stringify({
+					userText: message,
+					turnId: o?.turnId
+				})
+			}))).json();
+			return text;
+		}
+	});
+}
 //#endregion
-export { AgentDurableObject, DoSessionStore, durableAgentSurface, durableFetch };
+export { AgentDurableObject, DoSessionStore, durableAgentSurface, durableChannelSurface, durableFetch };

package/dist/app.js

@@ -8,7 +8,9 @@ import { MODULE_STYLES_URL, buildModuleCss, registerCssModules } from "./css-mod
 import { CLIENT_SCRIPT_URL, bundleClientSplit, findClientEntry } from "./client-bundle.js";
 import { generateIslandRegistry } from "./island-registry.js";
 import { STYLES_URL, findGlobalCss, globalCssUsesTailwind, processCssCached } from "./css.js";
-import { existsSync } from "node:fs";
+import { contentTypeFor, safeRelativePath } from "./static-files.js";
+import { existsSync, lstatSync, realpathSync } from "node:fs";
+import { readFile } from "node:fs/promises";
 import { dirname, join, resolve } from "node:path";
 import { pathToFileURL } from "node:url";
 import { buildSystemPrompt } from "@junejs/core/agent-config";
@@ -62,6 +64,11 @@ function createApp({ appDir: appDirInput, config = {} }) {
 	const appDir = resolve(appDirInput);
 	const juneRoutesDir = join(dirname(appDir), ".june", "routes");
 	const hasJuneRoutes = existsSync(juneRoutesDir);
+	const publicDir = join(dirname(appDir), "public");
+	let publicRoot = null;
+	try {
+		if (lstatSync(publicDir).isDirectory()) publicRoot = realpathSync(publicDir);
+	} catch {}
 	const agent = resolveAgent(config.agent);
 	const speculation = config.speculation;
 	const clientEntry = findClientEntry(appDir) ?? findClientEntry(join(dirname(appDir), ".june", "routes"));
@@ -201,7 +208,34 @@ function createApp({ appDir: appDirInput, config = {} }) {
 					});
 				}
 			}
-			return runWithTrace(newTrace(), async () => (await getPipeline()).fetch(request));
+			const toPipeline = () => runWithTrace(newTrace(), async () => (await getPipeline()).fetch(request));
+			if (publicRoot !== null && (request.method === "GET" || request.method === "HEAD")) {
+				const rel = safeRelativePath(new URL(request.url).pathname);
+				if (rel !== null && rel.split("/")[0] !== "_june") {
+					const segments = rel.split("/");
+					const file = join(publicRoot, ...segments);
+					let stat;
+					try {
+						stat = lstatSync(file);
+					} catch {}
+					let real = null;
+					if (stat?.isFile()) try {
+						real = realpathSync(file);
+					} catch {}
+					if (real === file) {
+						const headers = {
+							"content-type": contentTypeFor(rel),
+							"cache-control": "public, max-age=0, must-revalidate"
+						};
+						if (request.method === "HEAD") return Promise.resolve(new Response(null, { headers: {
+							...headers,
+							"content-length": String(stat.size)
+						} }));
+						return readFile(file).then((buf) => new Response(buf, { headers }), () => toPipeline());
+					}
+				}
+			}
+			return toPipeline();
 		},
 		async warmup() {
 			const files = await routeFiles(appDir, { pageConvention: true });

package/dist/build.js

@@ -6,12 +6,13 @@ import { jsxTransform } from "./tsconfig-jsx.js";
 import { CLIENT_SCRIPT_URL, bundleClientToFile, findClientEntry } from "./client-bundle.js";
 import { generateIslandRegistry } from "./island-registry.js";
 import { STYLES_URL, cssTargets, findGlobalCss, globalCssUsesTailwind, minifyCss, processCss } from "./css.js";
+import { RESERVED_PREFIX } from "./static-files.js";
 import { findJuneConfigPath, loadJuneConfig } from "./config-loader.js";
 import { generateContentModule } from "./content.js";
 import { createWorker } from "./worker.js";
 import { buildRsc, findRscRoutes } from "./rsc-build.js";
-import { existsSync } from "node:fs";
-import { mkdir, readFile, readdir, rm, writeFile } from "node:fs/promises";
+import { existsSync, lstatSync } from "node:fs";
+import { copyFile, mkdir, readFile, readdir, rm, writeFile } from "node:fs/promises";
 import { basename, dirname, join, relative, resolve, sep } from "node:path";
 import { pathToFileURL } from "node:url";
 import { routeFromModule } from "@junejs/core/route";
@@ -279,6 +280,15 @@ function importPath(fromDir, file) {
 	const p = relative(fromDir, file).split(sep).join("/").replace(/\.[^.]+$/, "");
 	return p.startsWith(".") ? p : `./${p}`;
 }
+async function collectFiles(dir, base = dir) {
+	const out = [];
+	for (const entry of await readdir(dir, { withFileTypes: true })) {
+		const abs = join(dir, entry.name);
+		if (entry.isDirectory()) out.push(...await collectFiles(abs, base));
+		else if (entry.isFile()) out.push(relative(base, abs).split(sep).join("/"));
+	}
+	return out;
+}
 async function juneBuild(appRoot, options = {}) {
 	const appDir = join(appRoot, "app");
 	if (!existsSync(appDir)) throw new Error(`no app/ directory in ${appRoot} — is this a June app?`);
@@ -459,6 +469,26 @@ ${adapterEntry.wrap("pipeline")}
 	if (moduleCssAsset) manifest.document.moduleStyles = `/${moduleCssAsset}`;
 	const worker = createWorker(manifest);
 	let hasAssets = false;
+	const publicDir = join(appRoot, "public");
+	const publicFiles = [];
+	let publicIsDir = false;
+	try {
+		publicIsDir = lstatSync(publicDir).isDirectory();
+	} catch {}
+	if (existsSync(publicDir) && !publicIsDir) console.warn(`[june] public/ is not a real directory (symlink?) — skipped`);
+	if (publicIsDir) {
+		for (const rel of await collectFiles(publicDir)) {
+			if (rel.split("/")[0] === "_june") {
+				console.warn(`[june] public/${rel} ignored — ${RESERVED_PREFIX}/ is reserved for framework assets`);
+				continue;
+			}
+			const dest = join(assetsDir, rel);
+			await mkdir(dirname(dest), { recursive: true });
+			await copyFile(join(publicDir, ...rel.split("/")), dest);
+			publicFiles.push(rel);
+		}
+		if (publicFiles.length) hasAssets = true;
+	}
 	const isStatic = adapter.capabilities.runtime === "static";
 	const i18n = frozen.i18n;
 	const prerenderOne = async (reqPath, def) => {
@@ -536,7 +566,8 @@ ${adapterEntry.wrap("pipeline")}
 		linkHeader,
 		config: fullConfig,
 		plan,
-		defaultName
+		defaultName,
+		publicFiles
 	});
 	if (plan.db) console.log(`  ↳ d1 binding "${plan.db.binding}" emitted — set database_id in wrangler.jsonc (wrangler d1 create ${plan.db.databaseName})`);
 	return {

package/dist/index.d.ts

@@ -21,6 +21,6 @@ import { ResourceFlags, WorkerEnv, bindWorkerResources, memoizeResources } from
 import { MatchOptions, RouteMatch, RouteTreeMatch, SegmentMatch, listRoutes, matchRoute, matchRouteTree, resolveNotFound } from "./router.js";
 import { installAsyncContext } from "./instrumentation.js";
 import { Negotiated, negotiate } from "./negotiate.js";
-import { blob, db, kv } from "@junejs/db";
+import { blob, currentServices, db, kv } from "@junejs/db";
 import { I18nConfig, LOCALE_COOKIE, LocaleConfig, LocaleMatch, dirForLang, localeDir, localeHref, matchPinnedLocale, negotiateLocale, parseAcceptLanguage, resolveRequestLocale } from "@junejs/core/i18n";
-export { type AdapterCapabilities, type AdapterEmitContext, type AdapterEntry, type BuildResult, type ContentEntry, type CreateAppOptions, type D1Database, type D1Exec, type DeployResult, type DevServer, type DevServerOptions, type I18nConfig, type JuneAdapter, type JuneApp, type JuneDb, type JuneHost, LOCALE_COOKIE, type LayoutComponent, type LocaleConfig, type LocaleMatch, type MatchOptions, type MigrateResult, type Migration, type Negotiated, type Pipeline, type PipelineConfig, type R2Bucket, type Resolved, type ResourceFlags, type ResourcePlan, type RouteMatch, type RouteResolver, type RouteTreeMatch, type RunResult, type SegmentMatch, type ServeHandle, type SpawnedModule, type WorkerEnv, type WorkerManifest, bindWorkerResources, blob, blockedMessage, buildManifest, classify, collection, createApp, createPipeline, createWorker, d1, db, deno, dirForLang, entry, freezeConfig, generateContent, host, installAsyncContext, juneBuild, juneDeploy, kv, listRoutes, loadJuneConfig, localBlob, localeDir, localeHref, matchPinnedLocale, matchRoute, matchRouteTree, memoizeResources, memoryKv, migrate, migrateApp, migrateD1, mysql, negotiate, negotiateLocale, parseAcceptLanguage, postgres, r2, readMigrations, redisKv, resolveD1Database, resolveNotFound, resolveRequestLocale, scanRoutes, sqlite, startDevServer, staticSite, turso, typesApp, vercel, workers, wranglerD1 };
+export { type AdapterCapabilities, type AdapterEmitContext, type AdapterEntry, type BuildResult, type ContentEntry, type CreateAppOptions, type D1Database, type D1Exec, type DeployResult, type DevServer, type DevServerOptions, type I18nConfig, type JuneAdapter, type JuneApp, type JuneDb, type JuneHost, LOCALE_COOKIE, type LayoutComponent, type LocaleConfig, type LocaleMatch, type MatchOptions, type MigrateResult, type Migration, type Negotiated, type Pipeline, type PipelineConfig, type R2Bucket, type Resolved, type ResourceFlags, type ResourcePlan, type RouteMatch, type RouteResolver, type RouteTreeMatch, type RunResult, type SegmentMatch, type ServeHandle, type SpawnedModule, type WorkerEnv, type WorkerManifest, bindWorkerResources, blob, blockedMessage, buildManifest, classify, collection, createApp, createPipeline, createWorker, currentServices, d1, db, deno, dirForLang, entry, freezeConfig, generateContent, host, installAsyncContext, juneBuild, juneDeploy, kv, listRoutes, loadJuneConfig, localBlob, localeDir, localeHref, matchPinnedLocale, matchRoute, matchRouteTree, memoizeResources, memoryKv, migrate, migrateApp, migrateD1, mysql, negotiate, negotiateLocale, parseAcceptLanguage, postgres, r2, readMigrations, redisKv, resolveD1Database, resolveNotFound, resolveRequestLocale, scanRoutes, sqlite, startDevServer, staticSite, turso, typesApp, vercel, workers, wranglerD1 };

package/dist/index.js

@@ -21,6 +21,6 @@ import { installAsyncContext } from "./instrumentation.js";
 import { host } from "./host.js";
 import { startDevServer } from "./dev.js";
 import { memoryKv, redisKv } from "./kv.js";
-import { blob, db, kv } from "@junejs/db";
+import { blob, currentServices, db, kv } from "@junejs/db";
 import { LOCALE_COOKIE, dirForLang, localeDir, localeHref, matchPinnedLocale, negotiateLocale, parseAcceptLanguage, resolveRequestLocale } from "@junejs/core/i18n";
-export { LOCALE_COOKIE, bindWorkerResources, blob, blockedMessage, buildManifest, classify, collection, createApp, createPipeline, createWorker, d1, db, deno, dirForLang, entry, freezeConfig, generateContent, host, installAsyncContext, juneBuild, juneDeploy, kv, listRoutes, loadJuneConfig, localBlob, localeDir, localeHref, matchPinnedLocale, matchRoute, matchRouteTree, memoizeResources, memoryKv, migrate, migrateApp, migrateD1, mysql, negotiate, negotiateLocale, parseAcceptLanguage, postgres, r2, readMigrations, redisKv, resolveD1Database, resolveNotFound, resolveRequestLocale, scanRoutes, sqlite, startDevServer, staticSite, turso, typesApp, vercel, workers, wranglerD1 };
+export { LOCALE_COOKIE, bindWorkerResources, blob, blockedMessage, buildManifest, classify, collection, createApp, createPipeline, createWorker, currentServices, d1, db, deno, dirForLang, entry, freezeConfig, generateContent, host, installAsyncContext, juneBuild, juneDeploy, kv, listRoutes, loadJuneConfig, localBlob, localeDir, localeHref, matchPinnedLocale, matchRoute, matchRouteTree, memoizeResources, memoryKv, migrate, migrateApp, migrateD1, mysql, negotiate, negotiateLocale, parseAcceptLanguage, postgres, r2, readMigrations, redisKv, resolveD1Database, resolveNotFound, resolveRequestLocale, scanRoutes, sqlite, startDevServer, staticSite, turso, typesApp, vercel, workers, wranglerD1 };

package/dist/pipeline.js

@@ -1,11 +1,11 @@
 import { SEGMENT_HEADER, TITLE_HEADER, encodeTitle, negotiate } from "./negotiate.js";
+import { ensureScope, runInScope, setRequestLocale } from "@junejs/db";
 import { LoaderDataContext } from "@junejs/core/route";
 import React, { Suspense, use } from "react";
 import { renderToReadableStream } from "react-dom/server";
 import { Document } from "@junejs/core/document";
 import { apiCatalog, buildLinkHeader, llmsTxt, mcpServerCard, robotsTxt, sitemapXml } from "@junejs/core/discovery";
 import { mcpHandler, mcpTools } from "@junejs/core/mcp";
-import { ensureScope, runInScope, setRequestLocale } from "@junejs/db";
 import { LOCALE_COOKIE, localeAlternates, localeDir, matchPinnedLocale, negotiateLocale } from "@junejs/core/i18n";
 //#region src/pipeline.ts
 function readCookie(request, name) {

package/dist/static-files.d.ts

@@ -0,0 +1,6 @@
+//#region src/static-files.d.ts
+declare const RESERVED_PREFIX = "_june";
+declare function contentTypeFor(pathname: string): string;
+declare function safeRelativePath(pathname: string): string | null;
+//#endregion
+export { RESERVED_PREFIX, contentTypeFor, safeRelativePath };

package/dist/static-files.js

@@ -0,0 +1,56 @@
+//#region src/static-files.ts
+const RESERVED_PREFIX = "_june";
+const CONTENT_TYPES = {
+	html: "text/html; charset=utf-8",
+	css: "text/css; charset=utf-8",
+	js: "text/javascript; charset=utf-8",
+	mjs: "text/javascript; charset=utf-8",
+	json: "application/json; charset=utf-8",
+	map: "application/json; charset=utf-8",
+	xml: "application/xml; charset=utf-8",
+	txt: "text/plain; charset=utf-8",
+	md: "text/markdown; charset=utf-8",
+	csv: "text/csv; charset=utf-8",
+	webmanifest: "application/manifest+json",
+	svg: "image/svg+xml",
+	png: "image/png",
+	jpg: "image/jpeg",
+	jpeg: "image/jpeg",
+	gif: "image/gif",
+	webp: "image/webp",
+	avif: "image/avif",
+	ico: "image/x-icon",
+	bmp: "image/bmp",
+	woff2: "font/woff2",
+	woff: "font/woff",
+	ttf: "font/ttf",
+	otf: "font/otf",
+	mp4: "video/mp4",
+	webm: "video/webm",
+	mp3: "audio/mpeg",
+	ogg: "audio/ogg",
+	wav: "audio/wav",
+	wasm: "application/wasm",
+	pdf: "application/pdf",
+	zip: "application/zip"
+};
+function contentTypeFor(pathname) {
+	const dot = pathname.lastIndexOf(".");
+	if (dot === -1) return "application/octet-stream";
+	return CONTENT_TYPES[pathname.slice(dot + 1).toLowerCase()] ?? "application/octet-stream";
+}
+function safeRelativePath(pathname) {
+	let decoded;
+	try {
+		decoded = decodeURIComponent(pathname);
+	} catch {
+		return null;
+	}
+	if (decoded.includes("\0") || decoded.includes("\\")) return null;
+	const segments = decoded.split("/").filter((s) => s !== "" && s !== ".");
+	if (segments.length === 0) return null;
+	if (segments.some((s) => s === "..")) return null;
+	return segments.join("/");
+}
+//#endregion
+export { RESERVED_PREFIX, contentTypeFor, safeRelativePath };

package/dist/worker.js

@@ -1,5 +1,6 @@
 import { durableAgentSurface } from "./agent-durable.js";
 import { createPipeline } from "./pipeline.js";
+import { RESERVED_PREFIX, contentTypeFor, safeRelativePath } from "./static-files.js";
 //#region src/worker.ts
 function compilePattern(pattern) {
 	const names = [];
@@ -176,32 +177,33 @@ function withAssets(pipeline, opts = {}) {
 		return pipeline.fetch(request, env);
 	} };
 }
-const ASSET_CONTENT_TYPES = {
-	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"
-};
 function withDenoAssets(pipeline) {
 	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, { headers: {
-				"content-type": ASSET_CONTENT_TYPES[ext] ?? "application/octet-stream",
-				"cache-control": "public, max-age=31536000, immutable"
-			} });
-		} catch {}
+		const method = request.method;
+		if (method === "GET" || method === "HEAD") {
+			const url = new URL(request.url);
+			{
+				const rel = safeRelativePath(url.pathname);
+				if (rel !== null) try {
+					const assetUrl = new URL(`./assets/${rel.split("/").map(encodeURIComponent).join("/")}`, import.meta.url);
+					const immutable = rel.startsWith(`${RESERVED_PREFIX}/`);
+					const headers = {
+						"content-type": contentTypeFor(rel),
+						"cache-control": immutable ? "public, max-age=31536000, immutable" : "public, max-age=0, must-revalidate"
+					};
+					if (method === "HEAD") {
+						const info = await Deno.stat(assetUrl);
+						if (!info.isFile) throw new Error("not a file");
+						return new Response(null, { headers: {
+							...headers,
+							"content-length": String(info.size)
+						} });
+					}
+					const file = await Deno.readFile(assetUrl);
+					return new Response(file, { headers });
+				} catch {}
+			}
+		}
 		return pipeline.fetch(request);
 	};
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@junejs/server",
-  "version": "0.1.0-dev.5",
+  "version": "0.1.0-dev.7",
   "description": "June host adapters + dev server. Host-coupled; depends on the pure @junejs/core contract layer.",
   "type": "module",
   "license": "MIT",
@@ -125,8 +125,8 @@
     "build": "tsdown"
   },
   "dependencies": {
-    "@junejs/core": ">=0.1.0-dev.4",
-    "@junejs/db": ">=0.0.33-dev.1",
+    "@junejs/core": ">=0.1.0-dev.5",
+    "@junejs/db": ">=0.0.33-dev.2",
     "@momiji-rs/sparkdown": "^0.0.4",
     "lightningcss": "^1.27.0",
     "oxc-parser": "^0.137.0",

package/src/adapter.ts

@@ -8,7 +8,7 @@
 // are explicit `deploy: { adapter: vercel() }` from their own package.
 import { existsSync } from "node:fs";
 import { cp, copyFile, mkdir, readdir, rm, writeFile } from "node:fs/promises";
-import { basename, join } from "node:path";
+import { basename, dirname, join } from "node:path";
 
 import type { JuneConfig } from "@junejs/core/config";
 
@@ -49,6 +49,10 @@ export type AdapterEmitContext = {
   plan: ResourcePlan;
   // package.json name (or sanitized dir name) — the fallback worker/app name.
   defaultName: string;
+  // Verbatim public/ files (forward-slash paths relative to assets/), already
+  // copied into outDir/assets. Adapters that build a separate static tier (vercel)
+  // place these there; whole-assets targets (workers/static/deno) ignore it.
+  publicFiles?: string[];
 };
 
 export interface JuneAdapter {
@@ -214,7 +218,7 @@ export function vercel(opts?: { runtime?: "node" | "edge"; regions?: string[] })
       };
     },
 
-    async emit({ appRoot, outDir, hasAssets }) {
+    async emit({ appRoot, outDir, hasAssets, publicFiles }) {
       const out = join(appRoot, ".vercel", "output");
       const fnDir = join(out, "functions", `${VERCEL_FUNCTION}.func`);
       await rm(out, { recursive: true, force: true }); // clean — no stale outputs
@@ -249,11 +253,20 @@ export function vercel(opts?: { runtime?: "node" | "edge"; regions?: string[] })
         await writeFile(join(fnDir, "package.json"), JSON.stringify({ type: "module" }, null, 2) + "\n");
       }
 
-      // static: only the hashed framework assets under /_june/ (exact-path URLs)
+      // static: the hashed framework assets under /_june/ (exact-path URLs)...
       if (hasAssets) {
         const src = join(outDir, "assets", "_june");
         if (existsSync(src)) await cp(src, join(out, "static", "_june"), { recursive: true });
       }
+      // ...plus verbatim public/ files, served by the `filesystem` route handle
+      // below. Only these — prerendered page HTML stays on the SSR function.
+      for (const rel of publicFiles ?? []) {
+        const from = join(outDir, "assets", rel);
+        if (!existsSync(from)) continue;
+        const to = join(out, "static", rel);
+        await mkdir(dirname(to), { recursive: true });
+        await copyFile(from, to);
+      }
 
       await writeFile(
         join(out, "config.json"),

package/src/agent-discover.ts

@@ -21,7 +21,7 @@ import { basename, extname, join } from "node:path";
 import { pathToFileURL } from "node:url";
 
 import type { AnyAction } from "@junejs/core/agent";
-import { defineAgent, type AgentConfigFile, type AgentDefinition, type Channel, type Skill } from "@junejs/core/agent-config";
+import { defineAgent, resolveChannel, type AgentConfigFile, type AgentDefinition, type Channel, type ChannelFactory, type Skill } from "@junejs/core/agent-config";
 import { connectAll, type Connection } from "@junejs/core/connections";
 
 async function scan(dir: string, ext: string): Promise<string[]> {
@@ -79,10 +79,13 @@ export async function discoverAgent(dir: string): Promise<AgentDefinition> {
     skills.push(parseSkill(basename(f, ".md"), await readFile(f, "utf8")));
   }
 
+  // A channel module default-exports a Channel OR a `(env) => Channel` factory (the
+  // form workerd needs — secrets live in env, not at module scope). On native, env is
+  // process.env (present at load), so resolve here; the plain form stays supported.
   const channels: Channel[] = [];
   for (const f of await scan(join(dir, "channels"), ".ts")) {
     const mod = await import(pathToFileURL(f).href);
-    if (mod.default) channels.push(mod.default as Channel);
+    if (mod.default) channels.push(resolveChannel(mod.default as Channel | ChannelFactory, process.env));
   }
 
   // connections/*.ts — outbound: wire external MCP/OpenAPI servers, turning their

package/src/agent-durable.ts

@@ -25,6 +25,16 @@ import {
   type SessionStore,
   type Tool,
 } from "@junejs/core/agent-runtime";
+import type { Resources } from "@junejs/core/resources";
+import {
+  channelDispatch,
+  resolveChannel,
+  type AgentDefinition,
+  type Channel,
+  type ChannelContext,
+  type ChannelFactory,
+} from "@junejs/core/agent-config";
+import { ensureScope, runInScope } from "@junejs/db";
 
 // ── minimal structural Cloudflare surface (no @cloudflare/workers-types dep) ──
 export interface SqlStorageCursor<T = Record<string, unknown>> {
@@ -114,7 +124,26 @@ const crossDoUnsupported: Runtime = {
 
 // `instructions` (system prompt) is injected into the model per turn (withSystem),
 // so it need not be baked into `model` at construction — single-sourced on the def.
-export type DoAgentDef = { name?: string; model: Model; tools: Tool[]; instructions?: string };
+//
+// `resources` / `services` are the DI seam that closes the isolate gap: a DO is a
+// SEPARATE isolate from the Worker entry, reached by RPC, so the pipeline's request
+// scope (and its ambient `db`/`kv`/`blob`) never crosses into it. Instead the app
+// builds these from the DO's OWN env in the DO constructor (where env lives) and the
+// AgentDurableObject runs every turn inside a scope holding them — so a tool reads
+// ambient `db` (from `resources`) and app-defined services (via `currentServices()`)
+// exactly as a route loader does, with no module-global setter and no `env` on ctx.
+//   • resources — db/kv/blob handles bound from env (e.g. `{ db: d1(env.DB) }`).
+//   • services  — the app's own bag for things June doesn't model (Vectorize,
+//     Workers AI, a ledger writer, a retriever). Opaque here; the app types it at
+//     the `currentServices<T>()` read.
+export type DoAgentDef = {
+  name?: string;
+  model: Model;
+  tools: Tool[];
+  instructions?: string;
+  resources?: Resources;
+  services?: unknown;
+};
 
 // The agent runtime INSIDE a Durable Object. A plain class (constructor takes the
 // DO state) so this module needs no `cloudflare:workers` import. The app supplies
@@ -123,18 +152,36 @@ export type DoAgentDef = { name?: string; model: Model; tools: Tool[]; instructi
 // AgentDurableObject from `this.ctx` and forwards `fetch()`:
 //
 //   export class JuneAgentDO extends DurableObject {
-//     agent = new AgentDurableObject(this.ctx, { model, tools });
+//     agent = new AgentDurableObject(this.ctx, {
+//       model, tools,
+//       resources: { db: d1(this.env.DB) },   // ambient `db` inside tools
+//       services: makeServices(this.env),     // retriever, ledger writer, Vectorize…
+//     });
 //     fetch(req) { return this.agent.fetch(req); }
 //   }
 export class AgentDurableObject {
   private session: AgentSession;
+  // Built from the DO's env in the constructor (this isolate), shared across turns —
+  // env is stable per isolate, like bindWorkerResources memoizes per worker isolate.
+  private readonly resources: Resources;
+  private readonly services: unknown;
   constructor(state: DurableObjectState, def: DoAgentDef) {
     const store = new DoSessionStore(state.storage);
     const model = def.instructions ? withSystem(def.model, def.instructions) : def.model;
+    this.resources = def.resources ?? {};
+    this.services = def.services;
     this.session = new AgentSession(def.name ?? "agent", "self", store, new InProcBroadcaster(), model, def.tools, crossDoUnsupported);
   }
-  turn(input: { turnId?: string; userText: string }): Promise<string> {
-    return this.session.turn(input);
+  // Run the whole turn inside a request scope seeded from this DO's env, so ambient
+  // `db`/`kv`/`blob` and `currentServices()` resolve inside a tool exactly as in a
+  // route loader. `locals` is intentionally NOT set here: a fresh scope object per
+  // turn means a fresh (lazily-created) locals Map per turn, so per-turn state (e.g.
+  // Juno's batch-loader registry) can't leak across turns on a long-lived DO.
+  // ensureScope() lazily wires node:async_hooks (workerd via nodejs_compat), as the
+  // pipeline does; without it runInScope is a pass-through and ambient reads throw.
+  async turn(input: { turnId?: string; userText: string }): Promise<string> {
+    await ensureScope();
+    return runInScope({ resources: this.resources, services: this.services }, () => this.session.turn(input));
   }
   transcript() {
     return this.session.transcript();
@@ -186,3 +233,60 @@ export function durableAgentSurface(
     );
   };
 }
+
+// The EDGE channel surface: mount an agent's INBOUND channels (Slack/Crisp webhooks,
+// an http endpoint) on the Worker entry and route each turn into the per-session
+// Durable Object. The sibling of durableAgentSurface, which mounts only the chat
+// endpoint; a worker composes both (`await chat(req) ?? await channels(req) ?? 404`).
+//
+// Channels are resolved from the Worker's `env`, because on workerd a signing secret
+// lives only there (never at module top-level) — so a channel module can default-
+// export a factory: `export default (env) => crispChannel({ signingSecret:
+// env.CRISP_SIGNATURE_SECRET, ... })`. `waitUntil` (workerd's `ctx.waitUntil`) keeps
+// the isolate alive for the fast-ACK background work (run the turn, post the reply
+// back out). The webhook's own signature check still runs first, in the channel.
+//
+//   export default {
+//     fetch(req, env, ctx) {
+//       const channels = durableChannelSurface(() => env.AGENT, {
+//         agentName: "crisp-support", channels: [crispCh], env,
+//         waitUntil: ctx.waitUntil.bind(ctx),
+//       });
+//       return channels(req).then((r) => r ?? new Response("not found", { status: 404 }));
+//     },
+//   }
+//
+// Note: if the DO namespace is unbound, a matched webhook still ACKs but the turn
+// fails in the background — surfaced via the channel's onError IF one is configured,
+// otherwise swallowed (runBackground never rejects). The app is expected to bind
+// env.AGENT when it mounts channels. Returns null for unclaimed requests.
+export function durableChannelSurface(
+  getNamespace: () => DurableObjectNamespace | undefined,
+  opts: {
+    agentName: string;
+    channels: (Channel | ChannelFactory)[];
+    env: unknown;
+    waitUntil?: (p: Promise<unknown>) => void;
+  },
+): (req: Request) => Promise<Response | null> {
+  const resolved = opts.channels.map((c) => resolveChannel(c, opts.env));
+  const ctx: ChannelContext = {
+    // A minimal but complete AgentDefinition — channels only read ctx.agent.name; the
+    // full def isn't present in the worker (tools/model live in the DO).
+    agent: { name: opts.agentName, instructions: "", tools: [], skills: [], channels: [], connections: [] } satisfies AgentDefinition,
+    waitUntil: opts.waitUntil,
+    run: async (message, o) => {
+      const namespace = getNamespace();
+      if (!namespace) throw new Error("durableChannelSurface: no Durable Object namespace bound (env.AGENT)");
+      const res = await durableFetch(
+        namespace,
+        opts.agentName,
+        o?.session ?? "default",
+        new Request("https://do/turn", { method: "POST", body: JSON.stringify({ userText: message, turnId: o?.turnId }) }),
+      );
+      const { text } = (await res.json()) as { text: string };
+      return text;
+    },
+  };
+  return channelDispatch(resolved, ctx);
+}

package/src/app.ts

@@ -9,7 +9,8 @@
 // all change observable output (test/config-output.test.ts) — the PoC shipped a
 // dev server that silently ignored june.config.ts for days.
 
-import { existsSync } from "node:fs";
+import { existsSync, lstatSync, realpathSync, type Stats } from "node:fs";
+import { readFile } from "node:fs/promises";
 import { dirname, join, resolve } from "node:path";
 import { pathToFileURL } from "node:url";
 import type { ComponentType } from "react";
@@ -41,6 +42,7 @@ import {
 import { generateIslandRegistry } from "./island-registry";
 import { findGlobalCss, globalCssUsesTailwind, processCssCached, STYLES_URL } from "./css";
 import { buildModuleCss, registerCssModules, MODULE_STYLES_URL, type ModuleMaps } from "./css-modules";
+import { contentTypeFor, RESERVED_PREFIX, safeRelativePath } from "./static-files";
 
 export type CreateAppOptions = {
   appDir: string;
@@ -117,6 +119,20 @@ export function createApp({ appDir: appDirInput, config = {} }: CreateAppOptions
   // app/ stays the priority/escape-hatch; this is the framework slot, consulted as a fallback.
   const juneRoutesDir = join(dirname(appDir), ".june", "routes");
   const hasJuneRoutes = existsSync(juneRoutesDir);
+  // App-root public/ (sibling of app/): verbatim static files served in dev the
+  // same way the platform serves them in prod. Copied into dist/assets at build.
+  // Resolve to the REAL directory once: if public/ itself is a symlink (e.g.
+  // `public -> ..`, a hostile template), path resolution would follow it and
+  // escape the app root — refuse to serve then (publicRoot stays null). The build
+  // ignores a symlinked public/ too, so this keeps dev/prod parity. Anchoring
+  // later reads on the realpath also lets us reject symlinked entries underneath.
+  const publicDir = join(dirname(appDir), "public");
+  let publicRoot: string | null = null;
+  try {
+    if (lstatSync(publicDir).isDirectory()) publicRoot = realpathSync(publicDir);
+  } catch {
+    /* no public/ dir → nothing to serve */
+  }
   const agent = resolveAgent(config.agent);
   const speculation = config.speculation;
   // app/_client.* present → the dev document loads /client.js and we serve it
@@ -321,7 +337,63 @@ export function createApp({ appDir: appDirInput, config = {} }: CreateAppOptions
           );
         }
       }
-      return runWithTrace(newTrace(), async () => (await getPipeline()).fetch(request));
+      // Static files under app-root public/, served verbatim. Mirrors the prod
+      // asset layer (Cloudflare ASSETS / Vercel filesystem / Deno withDenoAssets
+      // all answer before the pipeline), so a public/ file shadows a same-path
+      // route in dev exactly as it does when deployed. Passthrough — no hashing
+      // or optimization. GET/HEAD only; a miss falls through to the render core.
+      const toPipeline = () => runWithTrace(newTrace(), async () => (await getPipeline()).fetch(request));
+      if (publicRoot !== null && (request.method === "GET" || request.method === "HEAD")) {
+        const rel = safeRelativePath(new URL(request.url).pathname);
+        if (rel !== null && rel.split("/")[0] !== RESERVED_PREFIX) {
+          const segments = rel.split("/");
+          const file = join(publicRoot, ...segments); // anchor on the REAL public root
+          // lstatSync (NOT statSync) gets existence+type+size in one syscall
+          // without following a leaf symlink. ENOENT / EACCES → treat as a miss.
+          let stat: Stats | undefined;
+          try {
+            stat = lstatSync(file);
+          } catch {
+            /* not a readable file → fall through */
+          }
+          // Serve only a real file whose resolved path is STILL inside publicRoot:
+          // realpathSync(file) === file holds iff no path component (leaf OR an
+          // intermediate dir) is a symlink. That blocks symlink escapes AND matches
+          // the build, which drops every symlinked entry under public/.
+          let real: string | null = null;
+          if (stat?.isFile()) {
+            try {
+              real = realpathSync(file);
+            } catch {
+              /* race: gone between stat and realpath → miss */
+            }
+          }
+          if (real === file) {
+            const headers = {
+              "content-type": contentTypeFor(rel),
+              // Not content-hashed → must revalidate, never immutable.
+              "cache-control": "public, max-age=0, must-revalidate",
+            };
+            // HEAD: existence + size already proven — answer without reading the
+            // body (a large asset would otherwise be read and discarded).
+            if (request.method === "HEAD") {
+              return Promise.resolve(
+                new Response(null, { headers: { ...headers, "content-length": String(stat!.size) } }),
+              );
+            }
+            // A file deleted/locked between stat and read (dev editors do atomic
+            // save = write-temp + rename) must not crash the request — fall
+            // through to the pipeline on a read error, same as any other miss.
+            // readFile returns a Buffer (a Uint8Array) — pass it straight through;
+            // re-wrapping in new Uint8Array(buf) would copy every byte.
+            return readFile(file).then(
+              (buf) => new Response(buf, { headers }),
+              () => toPipeline(),
+            );
+          }
+        }
+      }
+      return toPipeline();
     },
     async warmup() {
       const files = await routeFiles(appDir, { pageConvention: true });

package/src/build.ts

@@ -19,8 +19,8 @@
 
 import { execFileSync } from "node:child_process";
 import { createHash } from "node:crypto";
-import { existsSync } from "node:fs";
-import { mkdir, readdir, readFile, rm, writeFile } from "node:fs/promises";
+import { existsSync, lstatSync } from "node:fs";
+import { copyFile, mkdir, readdir, readFile, rm, writeFile } from "node:fs/promises";
 import { basename, dirname, join, relative, resolve, sep } from "node:path";
 import { pathToFileURL } from "node:url";
 
@@ -38,6 +38,7 @@ 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 { RESERVED_PREFIX } from "./static-files";
 import { jsxTransform } from "./tsconfig-jsx";
 import { generateIslandRegistry } from "./island-registry";
 import { buildRsc, findRscRoutes } from "./rsc-build";
@@ -460,6 +461,19 @@ function importPath(fromDir: string, file: string): string {
   return p.startsWith(".") ? p : `./${p}`;
 }
 
+// Recursively list every file under `dir` as a forward-slash relative path. Used
+// to enumerate public/ for the verbatim asset copy (dot-files included — a
+// `.well-known/` under public/ is a legitimate thing to ship).
+async function collectFiles(dir: string, base = dir): Promise<string[]> {
+  const out: string[] = [];
+  for (const entry of await readdir(dir, { withFileTypes: true })) {
+    const abs = join(dir, entry.name);
+    if (entry.isDirectory()) out.push(...(await collectFiles(abs, base)));
+    else if (entry.isFile()) out.push(relative(base, abs).split(sep).join("/"));
+  }
+  return out;
+}
+
 export async function juneBuild(
   appRoot: string,
   options: { outDir?: string; external?: string[] } = {},
@@ -780,6 +794,41 @@ ${adapterEntry.wrap("pipeline")}
   const worker = createWorker(manifest);
   let hasAssets = false;
 
+  // ---- public/ → assets/ : verbatim static files (favicon, images, fonts) ----
+  // Copied here, BEFORE the framework's hashed assets are written below, so a
+  // stray public/_june/* can never overwrite the real client bundle / CSS (it is
+  // skipped outright). Passthrough only — no hashing/optimization. `publicFiles`
+  // is the relative-path list adapters need to place these on their static tier.
+  const publicDir = join(appRoot, "public");
+  const publicFiles: string[] = [];
+  // Only a REAL directory: a symlinked public/ (e.g. `public -> ..`) would copy
+  // files from OUTSIDE the app root into the deploy output. collectFiles already
+  // drops symlinked entries UNDER public/ (Dirent.isFile()/isDirectory()); this
+  // guards the root itself. lstatSync doesn't follow the symlink, so a symlinked
+  // public/ has isDirectory() === false.
+  let publicIsDir = false;
+  try {
+    publicIsDir = lstatSync(publicDir).isDirectory();
+  } catch {
+    /* no public/ */
+  }
+  if (existsSync(publicDir) && !publicIsDir) {
+    console.warn(`[june] public/ is not a real directory (symlink?) — skipped`);
+  }
+  if (publicIsDir) {
+    for (const rel of await collectFiles(publicDir)) {
+      if (rel.split("/")[0] === RESERVED_PREFIX) {
+        console.warn(`[june] public/${rel} ignored — ${RESERVED_PREFIX}/ is reserved for framework assets`);
+        continue;
+      }
+      const dest = join(assetsDir, rel);
+      await mkdir(dirname(dest), { recursive: true });
+      await copyFile(join(publicDir, ...rel.split("/")), dest);
+      publicFiles.push(rel);
+    }
+    if (publicFiles.length) hasAssets = true;
+  }
+
   // static() target: prerender EVERY route (not just opted-in ones) + enumerate
   // dynamic routes via their staticPaths, and write <stem>/index.html so clean URLs
   // resolve on a dumb file host with no rewrite server. Other targets keep the
@@ -898,7 +947,7 @@ ${adapterEntry.wrap("pipeline")}
     resourcesCfg?.db && resourcesCfg.db.kind !== "turso"
       ? { db: { binding: "DB", databaseName: `${defaultName}-db` } }
       : {};
-  await adapter.emit({ appRoot, outDir, hasAssets, linkHeader, config: fullConfig, plan, defaultName });
+  await adapter.emit({ appRoot, outDir, hasAssets, linkHeader, config: fullConfig, plan, defaultName, publicFiles });
   if (plan.db) {
     console.log(
       `  ↳ d1 binding "${plan.db.binding}" emitted — set database_id in wrangler.jsonc (wrangler d1 create ${plan.db.databaseName})`,

package/src/index.ts

@@ -27,6 +27,10 @@ export {
 // raw queries when Juno is installed (Juno registers the tagger via @junejs/db) —
 // so the framework never imports Juno, yet `db` is the tagging one in a Juno app.
 export { db, kv, blob } from "@junejs/db";
+// The app-services seam (see AgentDurableObject's `services` / RequestScope.services):
+// read the isolate's app-defined bag from any tool or loader. The app builds it from
+// env at the isolate entry and types it here — `currentServices<AppServices>()`.
+export { currentServices } from "@junejs/db";
 export { loadJuneConfig } from "./config-loader";
 export {
   migrate,

package/src/static-files.ts

@@ -0,0 +1,84 @@
+// Static-file serving for the app-root `public/` directory — the ONE place that
+// maps a URL path to a verbatim file. Shared by the dev host (app.ts, node:fs)
+// and the Deno adapter runtime (withDenoAssets, Deno.readFile). Cloudflare and
+// Vercel serve public files through their own platform layer (the ASSETS binding
+// / the `filesystem` route handle) and don't call in here.
+//
+// `public/` is PASSTHROUGH: no content-hashing, no format conversion, no
+// optimization — that stays the future image service's job. This module is pure
+// (no node built-ins) so it bundles cleanly into the worker (Deno/edge) too.
+
+// The framework owns this top-level URL segment (hashed client bundle + CSS live
+// under it). A user file must never be served from `public/_june/...`, so the
+// dev lookup and the build copy both skip it. NOTE: the Deno runtime asset server
+// legitimately serves `/_june/*` (the real framework assets), so it does NOT
+// apply this reservation — safeRelativePath() below is traversal-only.
+export const RESERVED_PREFIX = "_june";
+
+// Extension → MIME. Deliberately small and explicit (no `mime` dependency): the
+// set of things people actually drop in public/. Unknown → octet-stream.
+const CONTENT_TYPES: Record<string, string> = {
+  // text / markup
+  html: "text/html; charset=utf-8",
+  css: "text/css; charset=utf-8",
+  js: "text/javascript; charset=utf-8",
+  mjs: "text/javascript; charset=utf-8",
+  json: "application/json; charset=utf-8",
+  map: "application/json; charset=utf-8",
+  xml: "application/xml; charset=utf-8",
+  txt: "text/plain; charset=utf-8",
+  md: "text/markdown; charset=utf-8",
+  csv: "text/csv; charset=utf-8",
+  webmanifest: "application/manifest+json",
+  // images
+  svg: "image/svg+xml",
+  png: "image/png",
+  jpg: "image/jpeg",
+  jpeg: "image/jpeg",
+  gif: "image/gif",
+  webp: "image/webp",
+  avif: "image/avif",
+  ico: "image/x-icon",
+  bmp: "image/bmp",
+  // fonts
+  woff2: "font/woff2",
+  woff: "font/woff",
+  ttf: "font/ttf",
+  otf: "font/otf",
+  // media / binary
+  mp4: "video/mp4",
+  webm: "video/webm",
+  mp3: "audio/mpeg",
+  ogg: "audio/ogg",
+  wav: "audio/wav",
+  wasm: "application/wasm",
+  pdf: "application/pdf",
+  zip: "application/zip",
+};
+
+export function contentTypeFor(pathname: string): string {
+  const dot = pathname.lastIndexOf(".");
+  if (dot === -1) return "application/octet-stream";
+  return CONTENT_TYPES[pathname.slice(dot + 1).toLowerCase()] ?? "application/octet-stream";
+}
+
+// Clean a URL pathname into a safe relative path (forward-slash separated) under
+// a static root, or null if it is malformed, empty, or escapes the root. Callers
+// join the result to their own root (node:path.join for dev, a URL for Deno).
+// Traversal guard ONLY — the reserved `_june` segment is enforced by callers, not
+// here, because the Deno asset server must be able to serve it.
+export function safeRelativePath(pathname: string): string | null {
+  let decoded: string;
+  try {
+    decoded = decodeURIComponent(pathname);
+  } catch {
+    return null; // malformed %-encoding
+  }
+  // A backslash or NUL in a URL path is never a legitimate static file request;
+  // rejecting them closes the Windows separator / null-byte traversal tricks.
+  if (decoded.includes("\0") || decoded.includes("\\")) return null;
+  const segments = decoded.split("/").filter((s) => s !== "" && s !== ".");
+  if (segments.length === 0) return null; // "/" is a page, not a file
+  if (segments.some((s) => s === "..")) return null; // no directory climbing
+  return segments.join("/");
+}

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 { contentTypeFor, RESERVED_PREFIX, safeRelativePath } from "./static-files";
 
 export type WorkerManifest = {
   // Static paths → route definitions ("/", "/users", ...).
@@ -297,39 +298,55 @@ export function withAssets(
 // 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",
+  stat(path: string | URL): Promise<{ isFile: boolean; size: number }>;
 };
 
 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) */
+    const method = request.method;
+    if (method === "GET" || method === "HEAD") {
+      const url = new URL(request.url);
+      // Probe the co-located assets/ dir for ANY non-root path (safeRelativePath
+      // rejects "/"): /_june/* (hashed framework assets) plus public/ files copied
+      // there at build — INCLUDING extensionless ones (e.g. .well-known/
+      // apple-app-site-association), so "public/ served verbatim" holds on Deno
+      // like every other target. A miss (ENOENT) falls through to the pipeline.
+      // The reserved /_june/ prefix is served here too — safeRelativePath is
+      // traversal-only. (An extra ENOENT syscall per page nav is dwarfed by SSR.)
+      {
+        const rel = safeRelativePath(url.pathname);
+        if (rel !== null) {
+          try {
+            // Build the file URL from rel by encoding EACH segment — interpolating
+            // the raw (decoded) rel would let a literal `?`/`#` in a filename start
+            // a query/fragment and read the wrong file.
+            const assetUrl = new URL(
+              `./assets/${rel.split("/").map(encodeURIComponent).join("/")}`,
+              import.meta.url,
+            );
+            // Derive both from the CANONICAL rel, not the raw url.pathname: a
+            // percent-encoded separator (e.g. /_june%2Fapp.js) decodes to the same
+            // asset but would miss a startsWith("/_june/") test on the raw path.
+            const immutable = rel.startsWith(`${RESERVED_PREFIX}/`); // hashed → immutable
+            const headers: Record<string, string> = {
+              "content-type": contentTypeFor(rel),
+              "cache-control": immutable
+                ? "public, max-age=31536000, immutable"
+                : "public, max-age=0, must-revalidate",
+            };
+            // HEAD: stat for size only — don't read a (possibly large) body just to
+            // discard it. A non-file (directory) stat falls through to the pipeline.
+            if (method === "HEAD") {
+              const info = await Deno.stat(assetUrl);
+              if (!info.isFile) throw new Error("not a file");
+              return new Response(null, { headers: { ...headers, "content-length": String(info.size) } });
+            }
+            const file = await Deno.readFile(assetUrl);
+            return new Response(file as BodyInit, { headers });
+          } catch {
+            /* not on disk → fall through (the pipeline 404s) */
+          }
+        }
       }
     }
     // No env arg: Deno has no platform bindings (unlike D1/KV on workers); env-