@junejs/server 0.1.0-dev.5 → 0.1.0

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
@@ -166,6 +182,15 @@ export function createApp({ appDir: appDirInput, config = {} }: CreateAppOptions
 
   const resources = memoizeResources(config.resources);
 
+  // Build the app-services bag once from process.env (dev's env; stable across the
+  // process) and hand the pipeline a memoized provider — the dev twin of the worker
+  // binding services from its per-isolate env. The `{ v }` box memoizes even a
+  // null/undefined result. Absent config → no provider → currentServices() undefined.
+  let servicesCache: { v: unknown } | undefined;
+  const services = config.services
+    ? () => (servicesCache ??= { v: config.services!.make(process.env) }).v
+    : undefined;
+
   // Boot the opt-in Tier-3 data layer (e.g. `dataLayer: junoDataLayer()`) once:
   // its install() wires the ambient `db` (Juno registers its SQL tagger). Explicit
   // and config-declared — no import-time side-effect, and the framework still never
@@ -229,6 +254,7 @@ export function createApp({ appDir: appDirInput, config = {} }: CreateAppOptions
       routeList: routePaths,
       earlyHints: config.earlyHints,
       resources,
+      services,
       notFoundComponent,
       resolve: async (pathname) => {
         const match =
@@ -321,7 +347,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[] } = {},
@@ -692,6 +706,23 @@ export async function juneBuild(
   }
   const dataLayerBoot = dataLayerModule ? "\ninstallDataLayer();\n" : "";
 
+  // App services: import the app's `(env) => services` factory (the named `services`
+  // export of the declared module) into the entry and hand it to createWorker, which
+  // binds it from the worker env per request — the prod twin of app.ts building it from
+  // process.env. Like resources, the module (not the config) is imported, so the config's
+  // host-only bits never enter the worker graph. Emitted only when declared.
+  //
+  // The specifier is rebased like a route import: an app-relative path (`./app/services.ts`)
+  // is resolved against appRoot then made relative to the entry's dir (.june), since the
+  // generated entry lives there; a bare specifier (a shared package, like dataLayer.module)
+  // is used verbatim.
+  const servicesModule = fullConfig.services?.module;
+  if (servicesModule) {
+    const spec = /^[./]/.test(servicesModule) ? importPath(genDir, resolve(appRoot, servicesModule)) : servicesModule;
+    imports.push(`import { services as __appServices } from ${JSON.stringify(spec)};`);
+  }
+  const servicesField = servicesModule ? `\n  services: __appServices,` : "";
+
   const entry = `// AUTO-GENERATED by \`june build\` — do not edit. Regenerate: june build .
 ${adapterEntry.imports.join("\n")}
 ${imports.join("\n")}
@@ -711,7 +742,7 @@ ${loadings.join("\n")}
   },
   document: ${JSON.stringify(frozen.document, null, 2).replace(/\n/g, "\n  ")},
   agent: ${JSON.stringify(frozen.agent)},${frozen.i18n ? `\n  i18n: ${JSON.stringify(frozen.i18n)},` : ""}
-  earlyHints: ${JSON.stringify(frozen.earlyHints)},${builtExtraFile ? "\n  extra," : ""}${resourcesField}
+  earlyHints: ${JSON.stringify(frozen.earlyHints)},${builtExtraFile ? "\n  extra," : ""}${resourcesField}${servicesField}
 });
 
 ${adapterEntry.wrap("pipeline")}
@@ -780,6 +811,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 +964,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,13 @@ 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";
+// Declare that bag for the Worker side in june.config.ts (`services: defineServices(...)`)
+// — the twin of the DO's constructor injection, seeded into loaders/views/actions.
+export { defineServices, type ServicesConfig } from "@junejs/core/config";
 export { loadJuneConfig } from "./config-loader";
 export {
   migrate,

package/src/pipeline.ts

@@ -121,6 +121,11 @@ export type PipelineConfig = {
   // Opened data resources (db/kv/blob) injected onto ctx before load(). A
   // provider so opening is lazy/memoized; absent → no resources on ctx.
   resources?: () => Promise<Resources> | Resources;
+  // The app-defined services bag, built from the isolate's env (config `services`).
+  // A provider like `resources` (lazy/memoized); seeded into the request scope so
+  // `currentServices()` resolves in loaders/views/actions. Absent → currentServices()
+  // is undefined. This is the Worker-side twin of a Durable Object seeding services.
+  services?: () => Promise<unknown> | unknown;
   earlyHints?: string[];
   htmlCacheControl?: string;
   notFoundComponent?: React.ComponentType<{ pathname: string }>;
@@ -578,7 +583,8 @@ export function createPipeline(cfg: PipelineConfig): Pipeline {
       // async-context provider on first request (no static node:* import).
       await ensureScope();
       const resources = cfg.resources ? await cfg.resources() : {};
-      return runInScope({ resources }, () => handleRequest(request));
+      const services = cfg.services ? await cfg.services() : undefined;
+      return runInScope({ resources, services }, () => handleRequest(request));
     },
   };
 }

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", ...).
@@ -58,6 +59,11 @@ export type WorkerManifest = {
   // bindings come from env, so the generated entry passes an ENV-AWARE provider
   // (bindWorkerResources) — the worker threads its env through on each fetch.
   resources?: (env?: unknown) => Promise<Resources> | Resources;
+  // App-defined services (config `services`), built from the worker's env. The build
+  // imports the app's `(env) => services` factory into the entry and sets it here; the
+  // worker threads its env through and createWorker memoizes it per isolate. Seeded
+  // into the request scope so `currentServices()` resolves in loaders/views/actions.
+  services?: (env?: unknown) => unknown;
 };
 
 type Compiled = { regex: RegExp; names: string[]; def: BrandedRoute; pattern: string };
@@ -132,6 +138,12 @@ export function createWorker(
   let currentEnv: unknown;
   const provider = manifest.resources;
 
+  // App services: the build sets a raw `(env) => services` factory here; memoize it per
+  // isolate (env is stable per isolate, like the resources provider). The `{ v }` box
+  // caches even a null/undefined result. Absent → currentServices() stays undefined.
+  const servicesProvider = manifest.services;
+  let servicesCache: { v: unknown } | undefined;
+
   // Durable agent (edge): route the chat endpoint to the per-session DO bound at
   // env.AGENT. Built only when the app has an agent (manifest.agentName) and the
   // runtime is enabled; the surface is inert (null → fall through) until env.AGENT
@@ -158,6 +170,7 @@ export function createWorker(
     notFoundComponent: manifest.notFound,
     extra: manifest.extra,
     resources: provider ? () => provider(currentEnv) : undefined,
+    services: servicesProvider ? () => (servicesCache ??= { v: servicesProvider(currentEnv) }).v : undefined,
     resolve: async (pathname): Promise<Resolved | ResolvedResource | null> => {
       const staticDef = manifest.routes[pathname];
       if (staticDef) {
@@ -297,39 +310,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-