@takazudo/zfb-adapter-cloudflare 0.1.0-next.8 → 0.1.0-next.80

package/README.md

@@ -2,10 +2,10 @@
 
 > Rust-built static-site engine for Astro and Next.js users — millisecond rebuilds, single binary.
 
-The Cloudflare Pages adapter for [zfb][zfb-site]. Wraps the
-`@takazudo/zfb-runtime` page router into a Cloudflare Pages advanced-mode
-`_worker.js` entry, threading `(env, ctx)` through to user code via
-`AsyncLocalStorage`.
+The Cloudflare adapter for [zfb][zfb-site], targeting **Workers Static
+Assets** (also deployable to Cloudflare Pages advanced mode). It wraps the
+`@takazudo/zfb-runtime` page router into a Worker entry (`_worker.js`),
+threading `(env, ctx)` through to user code via `AsyncLocalStorage`.
 
 This package is the Cloudflare half of the SSR adapter contract. Other
 targets (Node, Netlify, …) will land as sibling `@takazudo/zfb-adapter-*`
@@ -27,7 +27,7 @@ npm install --save-dev @takazudo/zfb-adapter-cloudflare
 
 In `zfb.config.json`:
 
-```jsonc
+```json
 {
   "framework": "preact",
   "adapter": "@takazudo/zfb-adapter-cloudflare"
@@ -62,36 +62,114 @@ export default async function Products() {
 See the [SSR and Cloudflare Bindings guide][ssr-guide] for the full D1
 lifecycle (`wrangler d1 create`, migrations, preview-vs-prod).
 
-[ssr-guide]: https://takazudomodular.com/pj/zudo-front-builder/guides/ssr-and-cloudflare-bindings/
+[ssr-guide]: https://takazudomodular.com/pj/zudo-front-builder/docs/guides/ssr-and-cloudflare-bindings/
 
 `zfb build` will:
 
 1. Render every SSG page (`prerender !== false`) into static HTML under
    `dist/`.
-2. Hand the SSR bundle to this adapter, which writes
-   `dist/_worker.js` (the wrapper) and `dist/_zfb_inner.mjs` (the
-   bundle) ready to be deployed via Cloudflare Pages advanced mode.
+2. Hand the SSR bundle to this adapter, which writes `dist/_worker.js`
+   (the wrapper), `dist/_zfb_inner.mjs` (the bundle), and
+   `dist/.assetsignore` (see below) — ready to deploy as a Worker with
+   Static Assets, or via Cloudflare Pages advanced mode.
+
+## `wrangler.toml`
+
+```toml
+name = "my-site"
+main = "./dist/_worker.js"
+compatibility_date = "2024-09-23"
+compatibility_flags = ["nodejs_compat"]
+
+[assets]
+directory = "./dist"
+binding = "ASSETS" # optional — lets the Worker probe assets itself
+not_found_handling = "404-page"
+```
+
+- `compatibility_flags = ["nodejs_compat"]` is **required**. The wrapper
+  imports `node:async_hooks` to thread `(env, ctx)` into your route
+  handlers; without this flag the Worker fails at runtime with
+  `No such module "node:async_hooks"`.
+- `not_found_handling = "404-page"` is recommended. With it, an
+  unmatched path makes the asset layer serve your styled `dist/404.html`
+  (built from `pages/404.tsx`) with a `404` status. The `_worker.js`
+  wrapper still probes the inner Worker for genuinely dynamic
+  `prerender = false` routes, but its **404 precedence** is:
+  - inner returns a non-404 (a real dynamic route) → the inner response
+    wins;
+  - inner also 404s with only the framework default body (Hono's default
+    `text/plain` "404 Not Found", or a bare 404 with no content-type) →
+    the **styled `404.html` wins**, so visitors see your designed 404 page
+    instead of plain text;
+  - inner 404s with any other content-type → that **deliberate response is
+    preserved** and the styled page does not stomp it: a `text/html` 404 is
+    a rendered custom not-found page (e.g. a `prerender = false` route
+    SSRing its own 404), and an `application/json` 404 is an intentional
+    API error.
+
+  A bare `text/plain` API 404 is indistinguishable from the framework
+  default and yields to the styled page — use `application/json` for API
+  errors you want preserved.
+
+  Under `not_found_handling = "none"` the asset 404 has no styled body, so
+  the inner Worker's plain 404 is always shown. Avoid
+  `single-page-application`: it returns `index.html` for every unresolved
+  path _before_ the Worker ever sees the request, which breaks dynamic
+  routes like `pages/api/*.tsx`.
+
+- `[assets] binding = "ASSETS"` is optional but recommended — it lets
+  the `_worker.js` wrapper probe `env.ASSETS.fetch()` directly for
+  GET/HEAD requests, matching the SSG-vs-SSR precedence described
+  below.
+
+## `wrangler dev` / `wrangler deploy`
+
+```sh
+zfb build
+wrangler dev     # local Worker + assets simulation
+wrangler deploy  # ship it
+```
 
-## CLI
+## `.assetsignore`
 
-The package ships a `zfb-adapter-cloudflare` bin invoked by
-`zfb-build`:
+The adapter emits `dist/.assetsignore` alongside `_worker.js` and
+`_zfb_inner.mjs`:
 
 ```
-zfb-adapter-cloudflare bundle <input.mjs> --outdir dist/
+_worker.js
+_zfb_inner.mjs
 ```
 
-`<input.mjs>` is the ESM bundle `zfb-build`'s bundler emits. The
-output is a single Workers-shaped entry plus a sidecar copy of the
-inner bundle.
+This excludes the wrapper and the inner SSR bundle from the asset
+upload, so they are reachable only through the Worker's own module
+graph — never served as public static files. Without it, a request for
+`/_worker.js` or `/_zfb_inner.mjs` would serve your server code as a
+plain-text download.
+
+**Precedence:** zfb copies your project's `public/` directory into
+`dist/` _after_ running this adapter. If your `public/` directory
+contains its own `.assetsignore`, it overrides the one this adapter
+emits — the adapter's excludes are silently dropped. Only add a
+`public/.assetsignore` if you have additional paths to exclude and
+include the two lines above yourself.
+
+## Cloudflare Pages compatibility
+
+The same `dist/` output is still deployable to Cloudflare Pages
+advanced mode (a `_worker.js` at the root of the Pages output directory
+is Pages' equivalent convention). The `_worker.js` wrapper dispatches
+requests identically on both platforms; the only platform-visible
+difference is that trailing-slash asset redirects come back as `307`
+on Workers Static Assets versus `308` on Pages.
 
-## Why two files
+## Why two bundle files instead of one
 
 The wrapper imports the inner bundle by relative path
 (`./_zfb_inner.mjs`) instead of inlining it, so the adapter package
 itself does not need to ship an esbuild binary. Workerd's Module
-loader resolves relative ESM imports inside an advanced-mode
-`_worker.js` directory layout.
+loader resolves relative ESM imports inside the `_worker.js` directory
+layout.
 
 ## Why AsyncLocalStorage on a globalThis registry
 

package/bin/cli.mjs

@@ -6,8 +6,10 @@
 //
 //   bundle <input> --outdir <dir>
 //
-//     Wrap the input ESM bundle into a Cloudflare Pages `_worker.js`
-//     placed under <dir>. The input bundle is the file `zfb_build`'s
+//     Wrap the input ESM bundle into a Cloudflare Workers Static Assets
+//     (Pages-compatible) `_worker.js` placed under <dir>, alongside a
+//     `.assetsignore` that excludes the wrapper and inner bundle from
+//     the asset upload. The input bundle is the file `zfb_build`'s
 //     bundler emits; <dir> is typically the project's `dist/`.
 //
 // The CLI is intentionally tiny and dependency-free. It imports the
@@ -15,9 +17,8 @@
 // no TypeScript loader required) so there is a single source of truth.
 // invariant: no runtime npm deps — see SECURITY-DEPS.md
 
-import { copyFile, mkdir, writeFile } from "node:fs/promises";
 import { realpathSync } from "node:fs";
-import { join, resolve } from "node:path";
+import { resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 
 // ---------------------------------------------------------------------------
@@ -27,18 +28,14 @@ import { fileURLToPath } from "node:url";
 import { WORKER_WRAPPER_SOURCE } from "../src/worker-wrapper.mjs";
 export { WORKER_WRAPPER_SOURCE };
 
-export async function emitWorker({ inputBundlePath, outdir }) {
-  const outdirAbs = resolve(outdir);
-  const inputAbs = resolve(inputBundlePath);
-
-  await mkdir(outdirAbs, { recursive: true });
-  const innerBundlePath = join(outdirAbs, "_zfb_inner.mjs");
-  await copyFile(inputAbs, innerBundlePath);
+// ---------------------------------------------------------------------------
+// emitWorker — shared implementation, no runtime npm deps.
+// ---------------------------------------------------------------------------
 
-  const workerPath = join(outdirAbs, "_worker.js");
-  await writeFile(workerPath, WORKER_WRAPPER_SOURCE, "utf8");
+import { emitWorker as _emitWorker } from "../src/emit-worker.mjs";
 
-  return { workerPath, innerBundlePath };
+export async function emitWorker({ inputBundlePath, outdir }) {
+  return _emitWorker({ inputBundlePath, outdir, workerWrapperSource: WORKER_WRAPPER_SOURCE });
 }
 
 // ---------------------------------------------------------------------------
@@ -55,7 +52,8 @@ function printUsage() {
   zfb-adapter-cloudflare bundle <input> --outdir <dir>
 
 Wrap an ESM bundle (the output of zfb-build's bundler) into a
-Cloudflare Pages \`_worker.js\` placed under <dir>.
+Cloudflare Workers Static Assets \`_worker.js\` placed under <dir>
+(also deployable to Cloudflare Pages advanced mode).
 
 Options:
   --outdir <dir>    Output directory. Required.
@@ -143,7 +141,9 @@ async function main() {
     inputBundlePath: inputAbs,
     outdir: outdirAbs,
   });
-  process.stdout.write(`wrote ${out.workerPath}\nwrote ${out.innerBundlePath}\n`);
+  process.stdout.write(
+    `wrote ${out.workerPath}\nwrote ${out.innerBundlePath}\nwrote ${out.assetsIgnorePath}\n`,
+  );
 }
 
 main().catch((err) => {

package/dist/build.d.ts

@@ -18,8 +18,8 @@ export interface EmitWorkerInput {
     readonly inputBundlePath: string;
     /**
      * Absolute path to the output directory. The emitter creates it if
-     * missing and writes `_worker.js` plus `_zfb_inner.mjs` (the copied
-     * input bundle) into it.
+     * missing and writes `_worker.js`, `_zfb_inner.mjs` (the copied input
+     * bundle), and `.assetsignore` into it.
      */
     readonly outdir: string;
 }
@@ -30,24 +30,29 @@ export interface EmitWorkerInput {
 export interface EmitWorkerOutput {
     readonly workerPath: string;
     readonly innerBundlePath: string;
+    readonly assetsIgnorePath: string;
 }
 /**
- * Emit a Cloudflare Pages `_worker.js` that wraps the zfb input bundle.
+ * Emit a Cloudflare Workers Static Assets (Pages-compatible) `_worker.js`
+ * that wraps the zfb input bundle.
  *
- * Output shape (two files in `outdir`):
+ * Output shape (three files in `outdir`):
  *
- *   _worker.js       — entry imported by Cloudflare Pages advanced mode
+ *   _worker.js       — Worker entry point (`main` in wrangler.toml, or the
+ *                      Pages advanced-mode convention)
  *   _zfb_inner.mjs   — the input bundle, copied verbatim
+ *   .assetsignore    — excludes the two files above from the asset upload
+ *                      so they are only reachable through the Worker's
+ *                      module graph, never served as a public static file
  *
  * The wrapper imports the inner bundle via the relative path
  * `./_zfb_inner.mjs`. Workerd's Module loader resolves relative ESM
- * imports inside an advanced-mode `_worker.js` directory, so this layout
- * works without re-bundling.
+ * imports inside the `_worker.js` directory, so this layout works
+ * without re-bundling.
  *
- * Why two files instead of one: re-bundling here would require a second
- * esbuild pass and would force the adapter to ship its own esbuild
- * binary slot. The two-file layout keeps the adapter dependency-free at
- * runtime — it is just `node:fs` glue.
+ * Why two bundle files instead of one: re-bundling here would require a
+ * second esbuild pass and would force the adapter to ship its own
+ * esbuild binary slot. The two-file layout keeps the adapter
+ * dependency-free at runtime — it is just `node:fs` glue.
  */
 export declare function emitWorker(input: EmitWorkerInput): Promise<EmitWorkerOutput>;
-//# sourceMappingURL=build.d.ts.map

package/dist/build.js

@@ -10,6 +10,9 @@
 // @ts-expect-error worker-wrapper.mjs has no declaration file; the export
 // shape is narrowed explicitly below.
 import { WORKER_WRAPPER_SOURCE as _wrapper } from "./worker-wrapper.mjs";
+// @ts-expect-error emit-worker.mjs has no declaration file; the export
+// shape is narrowed via EmitWorkerInput/EmitWorkerOutput below.
+import { emitWorker as _emitWorker } from "./emit-worker.mjs";
 /**
  * The wrapper source written to `_worker.js`. Imported from the single
  * canonical `.mjs` file so `src/build.ts` and `bin/cli.mjs` always stay
@@ -17,33 +20,33 @@ import { WORKER_WRAPPER_SOURCE as _wrapper } from "./worker-wrapper.mjs";
  */
 export const WORKER_WRAPPER_SOURCE = _wrapper;
 /**
- * Emit a Cloudflare Pages `_worker.js` that wraps the zfb input bundle.
+ * Emit a Cloudflare Workers Static Assets (Pages-compatible) `_worker.js`
+ * that wraps the zfb input bundle.
  *
- * Output shape (two files in `outdir`):
+ * Output shape (three files in `outdir`):
  *
- *   _worker.js       — entry imported by Cloudflare Pages advanced mode
+ *   _worker.js       — Worker entry point (`main` in wrangler.toml, or the
+ *                      Pages advanced-mode convention)
  *   _zfb_inner.mjs   — the input bundle, copied verbatim
+ *   .assetsignore    — excludes the two files above from the asset upload
+ *                      so they are only reachable through the Worker's
+ *                      module graph, never served as a public static file
  *
  * The wrapper imports the inner bundle via the relative path
  * `./_zfb_inner.mjs`. Workerd's Module loader resolves relative ESM
- * imports inside an advanced-mode `_worker.js` directory, so this layout
- * works without re-bundling.
+ * imports inside the `_worker.js` directory, so this layout works
+ * without re-bundling.
  *
- * Why two files instead of one: re-bundling here would require a second
- * esbuild pass and would force the adapter to ship its own esbuild
- * binary slot. The two-file layout keeps the adapter dependency-free at
- * runtime — it is just `node:fs` glue.
+ * Why two bundle files instead of one: re-bundling here would require a
+ * second esbuild pass and would force the adapter to ship its own
+ * esbuild binary slot. The two-file layout keeps the adapter
+ * dependency-free at runtime — it is just `node:fs` glue.
  */
 export async function emitWorker(input) {
-    const { mkdir, copyFile, writeFile } = await import("node:fs/promises");
-    const { resolve, join } = await import("node:path");
-    const outdir = resolve(input.outdir);
-    const inputBundle = resolve(input.inputBundlePath);
-    await mkdir(outdir, { recursive: true });
-    const innerBundlePath = join(outdir, "_zfb_inner.mjs");
-    await copyFile(inputBundle, innerBundlePath);
-    const workerPath = join(outdir, "_worker.js");
-    await writeFile(workerPath, WORKER_WRAPPER_SOURCE, "utf8");
-    return { workerPath, innerBundlePath };
+    return _emitWorker({
+        inputBundlePath: input.inputBundlePath,
+        outdir: input.outdir,
+        workerWrapperSource: WORKER_WRAPPER_SOURCE,
+    });
 }
 //# sourceMappingURL=build.js.map

package/dist/build.js.map

@@ -1 +1 @@
-{"version":3,"file":"build.js","sourceRoot":"","sources":["../src/build.ts"],"names":[],"mappings":"AAAA,sEAAsE;AACtE,EAAE;AACF,0EAA0E;AAC1E,kEAAkE;AAClE,sEAAsE;AACtE,+DAA+D;AAC/D,EAAE;AACF,yEAAyE;AACzE,mEAAmE;AAEnE,0EAA0E;AAC1E,sCAAsC;AACtC,OAAO,EAAE,qBAAqB,IAAI,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAEzE;;;;GAIG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAW,QAAkB,CAAC;AA+BhE;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,KAAsB;IACrD,MAAM,EAAE,KAAK,EAAE,QAAQ,EAAE,SAAS,EAAE,GAAG,MAAM,MAAM,CAAC,kBAAkB,CAAC,CAAC;IACxE,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,GAAG,MAAM,MAAM,CAAC,WAAW,CAAC,CAAC;IAEpD,MAAM,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;IACrC,MAAM,WAAW,GAAG,OAAO,CAAC,KAAK,CAAC,eAAe,CAAC,CAAC;IAEnD,MAAM,KAAK,CAAC,MAAM,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACzC,MAAM,eAAe,GAAG,IAAI,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;IACvD,MAAM,QAAQ,CAAC,WAAW,EAAE,eAAe,CAAC,CAAC;IAE7C,MAAM,UAAU,GAAG,IAAI,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;IAC9C,MAAM,SAAS,CAAC,UAAU,EAAE,qBAAqB,EAAE,MAAM,CAAC,CAAC;IAE3D,OAAO,EAAE,UAAU,EAAE,eAAe,EAAE,CAAC;AACzC,CAAC"}
+{"version":3,"file":"build.js","sourceRoot":"","sources":["../src/build.ts"],"names":[],"mappings":"AAAA,sEAAsE;AACtE,EAAE;AACF,0EAA0E;AAC1E,kEAAkE;AAClE,sEAAsE;AACtE,+DAA+D;AAC/D,EAAE;AACF,yEAAyE;AACzE,mEAAmE;AAEnE,0EAA0E;AAC1E,sCAAsC;AACtC,OAAO,EAAE,qBAAqB,IAAI,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AACzE,uEAAuE;AACvE,gEAAgE;AAChE,OAAO,EAAE,UAAU,IAAI,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAE9D;;;;GAIG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAW,QAAkB,CAAC;AAgChE;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,KAAsB;IACrD,OAAO,WAAW,CAAC;QACjB,eAAe,EAAE,KAAK,CAAC,eAAe;QACtC,MAAM,EAAE,KAAK,CAAC,MAAM;QACpB,mBAAmB,EAAE,qBAAqB;KAC3C,CAA8B,CAAC;AAClC,CAAC","sourcesContent":["// `@takazudo/zfb-adapter-cloudflare/build` — Node-only build helpers.\n//\n// This sub-entry is intentionally **not** imported by the Workers-runtime\n// entry (`./`). Code in this module may freely use Node built-ins\n// (`node:fs`, `node:path`, …) because it only ever runs in a Node 22+\n// build environment, never inside a Cloudflare Worker isolate.\n//\n// The `./` entry (`src/index.ts`) exports only Workers-runtime-safe code\n// (AsyncLocalStorage helpers) that can be bundled into the worker.\n\n// @ts-expect-error worker-wrapper.mjs has no declaration file; the export\n// shape is narrowed explicitly below.\nimport { WORKER_WRAPPER_SOURCE as _wrapper } from \"./worker-wrapper.mjs\";\n// @ts-expect-error emit-worker.mjs has no declaration file; the export\n// shape is narrowed via EmitWorkerInput/EmitWorkerOutput below.\nimport { emitWorker as _emitWorker } from \"./emit-worker.mjs\";\n\n/**\n * The wrapper source written to `_worker.js`. Imported from the single\n * canonical `.mjs` file so `src/build.ts` and `bin/cli.mjs` always stay\n * in sync without any duplication.\n */\nexport const WORKER_WRAPPER_SOURCE: string = _wrapper as string;\n\n/**\n * Inputs to [`emitWorker`].\n */\nexport interface EmitWorkerInput {\n  /**\n   * Absolute path to the input ESM bundle produced by `zfb-build`. The\n   * bundle must export a Workers-shaped `default { fetch: (request) =>\n   * Promise<Response> }` (this is the contract `zfb_build::bundler`\n   * pins). The file is copied verbatim next to the emitted wrapper so\n   * relative imports inside it keep resolving.\n   */\n  readonly inputBundlePath: string;\n  /**\n   * Absolute path to the output directory. The emitter creates it if\n   * missing and writes `_worker.js`, `_zfb_inner.mjs` (the copied input\n   * bundle), and `.assetsignore` into it.\n   */\n  readonly outdir: string;\n}\n\n/**\n * Output paths the emitter produced. Returned for callers that want to\n * log them (the Rust orchestrator surfaces them in build output).\n */\nexport interface EmitWorkerOutput {\n  readonly workerPath: string;\n  readonly innerBundlePath: string;\n  readonly assetsIgnorePath: string;\n}\n\n/**\n * Emit a Cloudflare Workers Static Assets (Pages-compatible) `_worker.js`\n * that wraps the zfb input bundle.\n *\n * Output shape (three files in `outdir`):\n *\n *   _worker.js       — Worker entry point (`main` in wrangler.toml, or the\n *                      Pages advanced-mode convention)\n *   _zfb_inner.mjs   — the input bundle, copied verbatim\n *   .assetsignore    — excludes the two files above from the asset upload\n *                      so they are only reachable through the Worker's\n *                      module graph, never served as a public static file\n *\n * The wrapper imports the inner bundle via the relative path\n * `./_zfb_inner.mjs`. Workerd's Module loader resolves relative ESM\n * imports inside the `_worker.js` directory, so this layout works\n * without re-bundling.\n *\n * Why two bundle files instead of one: re-bundling here would require a\n * second esbuild pass and would force the adapter to ship its own\n * esbuild binary slot. The two-file layout keeps the adapter\n * dependency-free at runtime — it is just `node:fs` glue.\n */\nexport async function emitWorker(input: EmitWorkerInput): Promise<EmitWorkerOutput> {\n  return _emitWorker({\n    inputBundlePath: input.inputBundlePath,\n    outdir: input.outdir,\n    workerWrapperSource: WORKER_WRAPPER_SOURCE,\n  }) as Promise<EmitWorkerOutput>;\n}\n"]}

package/dist/emit-worker.mjs

@@ -0,0 +1,49 @@
+// Shared, dependency-free implementation of `emitWorker`.
+//
+// Kept as a plain `.mjs` module (no TypeScript) so it can be imported from
+// both the typed TypeScript surface (`src/build.ts`) and the dependency-free
+// CLI binary (`bin/cli.mjs`) without needing a TypeScript loader.
+//
+// Do NOT duplicate this logic elsewhere. The two consumers always stay in
+// sync by importing from here.
+//
+// invariant: no runtime npm deps — see SECURITY-DEPS.md
+
+import { copyFile, mkdir, writeFile } from "node:fs/promises";
+import { join, resolve } from "node:path";
+
+// `.assetsignore` tells the Workers Static Assets uploader (and Pages'
+// asset server) to skip these two files, so they are only ever reachable
+// through the Worker's module graph, not served as public static assets.
+const ASSETS_IGNORE_CONTENT = "_worker.js\n_zfb_inner.mjs\n";
+
+/**
+ * Emit a Cloudflare Workers Static Assets (Pages-compatible) `_worker.js`
+ * that wraps the zfb input bundle.
+ *
+ * Output shape (three files in `outdir`):
+ *
+ *   _worker.js       — Worker entry point (`main` in wrangler.toml, or the
+ *                      Pages advanced-mode convention)
+ *   _zfb_inner.mjs   — the input bundle, copied verbatim
+ *   .assetsignore    — excludes the two files above from the asset upload
+ *
+ * @param {{ inputBundlePath: string; outdir: string; workerWrapperSource: string }} input
+ * @returns {Promise<{ workerPath: string; innerBundlePath: string; assetsIgnorePath: string }>}
+ */
+export async function emitWorker({ inputBundlePath, outdir, workerWrapperSource }) {
+  const outdirAbs = resolve(outdir);
+  const inputAbs = resolve(inputBundlePath);
+
+  await mkdir(outdirAbs, { recursive: true });
+  const innerBundlePath = join(outdirAbs, "_zfb_inner.mjs");
+  await copyFile(inputAbs, innerBundlePath);
+
+  const workerPath = join(outdirAbs, "_worker.js");
+  await writeFile(workerPath, workerWrapperSource, "utf8");
+
+  const assetsIgnorePath = join(outdirAbs, ".assetsignore");
+  await writeFile(assetsIgnorePath, ASSETS_IGNORE_CONTENT, "utf8");
+
+  return { workerPath, innerBundlePath, assetsIgnorePath };
+}

package/dist/index.d.ts

@@ -39,4 +39,3 @@ export declare function runWithCloudflareContext<T>(context: CloudflareContext,
  * recommended so TypeScript catches typos like `env.ANTRHOPIC_KEY`.
  */
 export declare function getCloudflareContext<Env = unknown>(): CloudflareContext<Env>;
-//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -1,5 +1,6 @@
-// `@takazudo/zfb-adapter-cloudflare` — Cloudflare Pages adapter for the
-// zfb framework.
+// `@takazudo/zfb-adapter-cloudflare` — Cloudflare Workers Static Assets
+// adapter for the zfb framework (also deployable to Cloudflare Pages
+// advanced mode).
 //
 // This entry (`./`) is the **Workers-runtime** surface. It is safe to
 // bundle into a Cloudflare Worker and does not depend on any Node-only

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,wEAAwE;AACxE,iBAAiB;AACjB,EAAE;AACF,sEAAsE;AACtE,uEAAuE;AACvE,iEAAiE;AACjE,EAAE;AACF,wCAAwC;AACxC,EAAE;AACF,6EAA6E;AAC7E,EAAE;AACF,oCAAoC;AACpC,+CAA+C;AAC/C,kFAAkF;AAClF,yDAAyD;AACzD,MAAM;AACN,EAAE;AACF,wEAAwE;AACxE,qBAAqB;AACrB,EAAE;AACF,yEAAyE;AACzE,EAAE;AACF,oDAAoD;AACpD,EAAE;AACF,uEAAuE;AACvE,yEAAyE;AACzE,yEAAyE;AACzE,4DAA4D;AAC5D,EAAE;AACF,sEAAsE;AACtE,yEAAyE;AACzE,mEAAmE;AACnE,yEAAyE;AACzE,qEAAqE;AACrE,uEAAuE;AACvE,uEAAuE;AACvE,6CAA6C;AAE7C,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AA8BrD,uDAAuD;AACvD,MAAM,WAAW,GAAG,wBAAwB,CAAC;AAM7C;;;;;;GAMG;AACH,SAAS,UAAU;IACjB,MAAM,CAAC,GAAG,UAAuC,CAAC;IAClD,IAAI,GAAG,GAAG,CAAC,CAAC,WAAW,CAAC,CAAC;IACzB,IAAI,CAAC,GAAG,EAAE,CAAC;QACT,GAAG,GAAG,IAAI,iBAAiB,EAAqB,CAAC;QACjD,CAAC,CAAC,WAAW,CAAC,GAAG,GAAG,CAAC;IACvB,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,wBAAwB,CAAI,OAA0B,EAAE,EAAW;IACjF,OAAO,UAAU,EAAE,CAAC,GAAG,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;AACvC,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,oBAAoB;IAClC,MAAM,CAAC,GAAG,UAAU,EAAE,CAAC,QAAQ,EAAE,CAAC;IAClC,IAAI,CAAC,CAAC,EAAE,CAAC;QACP,MAAM,IAAI,KAAK,CACb,6FAA6F;YAC3F,yFAAyF;YACzF,gGAAgG,CACnG,CAAC;IACJ,CAAC;IACD,OAAO,CAA2B,CAAC;AACrC,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,wEAAwE;AACxE,qEAAqE;AACrE,kBAAkB;AAClB,EAAE;AACF,sEAAsE;AACtE,uEAAuE;AACvE,iEAAiE;AACjE,EAAE;AACF,wCAAwC;AACxC,EAAE;AACF,6EAA6E;AAC7E,EAAE;AACF,oCAAoC;AACpC,+CAA+C;AAC/C,kFAAkF;AAClF,yDAAyD;AACzD,MAAM;AACN,EAAE;AACF,wEAAwE;AACxE,qBAAqB;AACrB,EAAE;AACF,yEAAyE;AACzE,EAAE;AACF,oDAAoD;AACpD,EAAE;AACF,uEAAuE;AACvE,yEAAyE;AACzE,yEAAyE;AACzE,4DAA4D;AAC5D,EAAE;AACF,sEAAsE;AACtE,yEAAyE;AACzE,mEAAmE;AACnE,yEAAyE;AACzE,qEAAqE;AACrE,uEAAuE;AACvE,uEAAuE;AACvE,6CAA6C;AAE7C,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AA8BrD,uDAAuD;AACvD,MAAM,WAAW,GAAG,wBAAwB,CAAC;AAM7C;;;;;;GAMG;AACH,SAAS,UAAU;IACjB,MAAM,CAAC,GAAG,UAAuC,CAAC;IAClD,IAAI,GAAG,GAAG,CAAC,CAAC,WAAW,CAAC,CAAC;IACzB,IAAI,CAAC,GAAG,EAAE,CAAC;QACT,GAAG,GAAG,IAAI,iBAAiB,EAAqB,CAAC;QACjD,CAAC,CAAC,WAAW,CAAC,GAAG,GAAG,CAAC;IACvB,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,wBAAwB,CAAI,OAA0B,EAAE,EAAW;IACjF,OAAO,UAAU,EAAE,CAAC,GAAG,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;AACvC,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,oBAAoB;IAClC,MAAM,CAAC,GAAG,UAAU,EAAE,CAAC,QAAQ,EAAE,CAAC;IAClC,IAAI,CAAC,CAAC,EAAE,CAAC;QACP,MAAM,IAAI,KAAK,CACb,6FAA6F;YAC3F,yFAAyF;YACzF,gGAAgG,CACnG,CAAC;IACJ,CAAC;IACD,OAAO,CAA2B,CAAC;AACrC,CAAC","sourcesContent":["// `@takazudo/zfb-adapter-cloudflare` — Cloudflare Workers Static Assets\n// adapter for the zfb framework (also deployable to Cloudflare Pages\n// advanced mode).\n//\n// This entry (`./`) is the **Workers-runtime** surface. It is safe to\n// bundle into a Cloudflare Worker and does not depend on any Node-only\n// built-ins beyond `node:async_hooks` (which workerd polyfills).\n//\n// Usage in a `prerender = false` route:\n//\n//   import { getCloudflareContext } from \"@takazudo/zfb-adapter-cloudflare\";\n//\n//   export const prerender = false;\n//   export default async function ApiRoute() {\n//     const { env, ctx } = getCloudflareContext<{ ANTHROPIC_API_KEY: string }>();\n//     // env.ANTHROPIC_API_KEY, ctx.waitUntil(...), etc.\n//   }\n//\n// For Node-only build helpers (e.g. `emitWorker`), import the `./build`\n// sub-entry instead:\n//\n//   import { emitWorker } from \"@takazudo/zfb-adapter-cloudflare/build\";\n//\n// ## Why AsyncLocalStorage on a globalThis registry\n//\n// Cloudflare Workers can process multiple requests concurrently in the\n// same isolate. A naïve `globalThis.__env = env` write would race across\n// requests. AsyncLocalStorage gives us a per-request scope that survives\n// `await` points without interfering with sibling requests.\n//\n// We register the storage instance on `globalThis` under a stable key\n// (`__zfb_cf_adapter_als__`) so the wrapper at `_worker.js` and the user\n// pages bundled together can share the same instance even when the\n// adapter module ends up duplicated in the final bundle graph (e.g. when\n// the wrapper file is emitted side-by-side with the inner bundle and\n// each pulls in its own copy of this module). Module-instance identity\n// is the property AsyncLocalStorage relies on; the registry pattern is\n// what makes it survive bundler duplication.\n\nimport { AsyncLocalStorage } from \"node:async_hooks\";\n\n/**\n * Cloudflare execution context — minimal projection of the workerd\n * `ExecutionContext` interface. We do not depend on `@cloudflare/workers-types`\n * at the type level here because that would force every consumer of this\n * package to install it; instead we keep a minimal structural shape and\n * let users widen it via the generic on [`getCloudflareContext`] when\n * they need richer bindings.\n */\nexport interface CloudflareExecutionContext {\n  /** Extends the lifetime of the request beyond the response. */\n  waitUntil(promise: Promise<unknown>): void;\n  /** Falls through to the static origin on uncaught exceptions. */\n  passThroughOnException(): void;\n}\n\n/**\n * Per-request Cloudflare context. `Env` defaults to `unknown` so the\n * caller can narrow it at the call site (recommended) or leave it open.\n */\nexport interface CloudflareContext<Env = unknown> {\n  /** CF env bindings (secrets, KV, D1, …) wired up via wrangler.toml. */\n  readonly env: Env;\n  /** ExecutionContext for waitUntil / passThroughOnException. */\n  readonly ctx: CloudflareExecutionContext;\n  /** The original Request, useful when handlers want headers / URL. */\n  readonly request: Request;\n}\n\n/** Stable globalThis key the registry pattern uses. */\nconst STORAGE_KEY = \"__zfb_cf_adapter_als__\";\n\ninterface RegistryGlobal {\n  [STORAGE_KEY]?: AsyncLocalStorage<CloudflareContext>;\n}\n\n/**\n * Acquire (or lazily create) the singleton AsyncLocalStorage instance.\n *\n * Stored on `globalThis` under a stable key so the wrapper at\n * `_worker.js` and the user bundle share state even if the adapter\n * module ends up duplicated in the final module graph.\n */\nfunction getStorage(): AsyncLocalStorage<CloudflareContext> {\n  const g = globalThis as unknown as RegistryGlobal;\n  let als = g[STORAGE_KEY];\n  if (!als) {\n    als = new AsyncLocalStorage<CloudflareContext>();\n    g[STORAGE_KEY] = als;\n  }\n  return als;\n}\n\n/**\n * Establish a Cloudflare context for the duration of `fn`. Used by the\n * `_worker.js` wrapper; not normally called by user code.\n */\nexport function runWithCloudflareContext<T>(context: CloudflareContext, fn: () => T): T {\n  return getStorage().run(context, fn);\n}\n\n/**\n * Read the current Cloudflare context. Throws if called outside a\n * Cloudflare request scope (e.g. from a build-time SSG render). Catch\n * the error and gate on `prerender = false` if you need a route to work\n * in both modes.\n *\n * The `Env` generic narrows the bindings shape — passing it is\n * recommended so TypeScript catches typos like `env.ANTRHOPIC_KEY`.\n */\nexport function getCloudflareContext<Env = unknown>(): CloudflareContext<Env> {\n  const c = getStorage().getStore();\n  if (!c) {\n    throw new Error(\n      \"[zfb-adapter-cloudflare] getCloudflareContext() called outside a Cloudflare request scope. \" +\n        \"This usually means the route was rendered at build time (SSG) instead of dispatched by \" +\n        \"the Worker. Add `export const prerender = false;` to the page if it needs Cloudflare bindings.\",\n    );\n  }\n  return c as CloudflareContext<Env>;\n}\n"]}

package/dist/worker-wrapper.mjs

@@ -10,34 +10,59 @@
 /** @type {string} */
 export const WORKER_WRAPPER_SOURCE = `// AUTO-GENERATED by @takazudo/zfb-adapter-cloudflare. Do not edit.
 //
-// Cloudflare Pages advanced mode entry. Forwards (request, env, ctx) to
-// the inner zfb worker bundle, exposing env/ctx to user code via
-// AsyncLocalStorage under a stable globalThis key.
+// Cloudflare Workers Static Assets entry (\`main\` in wrangler.toml,
+// alongside an \`[assets]\` block; also deployable to Cloudflare Pages
+// advanced mode). Forwards (request, env, ctx) to the inner zfb worker
+// bundle, exposing env/ctx to user code via AsyncLocalStorage under a
+// stable globalThis key.
 //
 // The same key is read by @takazudo/zfb-adapter-cloudflare's
 // getCloudflareContext() inside the user bundle, so the two ends share
 // state even though they live in separate ESM module instances.
 //
-// CF Pages advanced-mode contract: when _worker.js is present, every
-// request hits the worker — static asset routing is OFF unless the
-// worker explicitly delegates to env.ASSETS. The dispatch order below
-// is deliberately "ASSETS first, inner on 404":
+// Dispatch order is deliberately "ASSETS first, inner on 404" — this
+// holds across both deploy targets, but *why* the ASSETS probe fires
+// differs:
 //
-//   - GET/HEAD requests probe env.ASSETS first. CF Pages' asset server
+//   - Workers Static Assets with \`run_worker_first = false\` (the zfb
+//     default): the platform itself serves asset hits before the
+//     Worker ever runs, so for those requests this in-Worker probe is
+//     normally bypassed — it never had a chance to run. The probe below
+//     is NOT dead code: it is still exercised for Pages (no
+//     \`run_worker_first\` concept; every request hits the Worker), for
+//     \`run_worker_first = true\` deployments, and for any request the
+//     platform's asset router itself does not resolve (which still
+//     reaches this Worker as a "miss").
+//   - GET/HEAD requests probe env.ASSETS first. The asset server
 //     handles the trailing-slash canonicalisation for SSG output (e.g.
-//     "/docs/foo" → 308 → "/docs/foo/" → dist/docs/foo/index.html), so
+//     "/docs/foo" → redirect → "/docs/foo/" → dist/docs/foo/index.html
+//     — 307 on Workers Static Assets, 308 on Cloudflare Pages), so
 //     prerendered routes get the build-time head-injected HTML
 //     (<link rel="stylesheet">, <script type="module" src="/assets/
 //     islands-…">). If we let the inner Hono router handle them first,
 //     it would dynamic-SSR the page WITHOUT the prod head injection
 //     (which is a build-time post-process, not a runtime concern), and
-//     islands would never hydrate. See zfb#XXX (filed by Wave 10 of
-//     the zudo-doc#1355 zfb-pipeline-gaps epic).
-//   - On 404 from ASSETS, fall through to the inner zfb worker. This is
-//     where genuinely dynamic routes (\`prerender = false\`, e.g.
-//     \`pages/api/*.tsx\`) are served.
+//     islands would never hydrate.
+//   - On 404 from ASSETS, fall through to the inner zfb worker — this
+//     is where genuinely dynamic routes (\`prerender = false\`, e.g.
+//     \`pages/api/*.tsx\`) are served. EXCEPTION: when the asset 404
+//     carries a *styled* 404-page body (\`not_found_handling = "404-page"\`
+//     on Workers Static Assets, or the \`404.html\` convention on Pages —
+//     detected as an HTML document with a real Content-Length) AND the
+//     inner ALSO 404s with only the framework default body (Hono's
+//     default not-found, \`text/plain\` "404 Not Found", or a bare 404
+//     with no content-type), the earlier styled asset 404 is preferred
+//     over the inner's plain 404 — otherwise the styled \`404.html\` would
+//     be discarded and users would see the inner plain-text 404 (issue
+//     #1322). Any inner 404 that declares another content-type is a
+//     deliberate response and WINS: a \`text/html\` 404 is a rendered
+//     custom not-found page (a \`prerender = false\` route SSRing its own
+//     404), and an \`application/json\` 404 is an intentional API error —
+//     both are returned unchanged. Under \`not_found_handling = "none"\`
+//     the asset 404 body is empty/non-HTML, so the inner always wins —
+//     the historical behavior is preserved.
 //   - Non-GET/HEAD requests skip ASSETS and go straight to the inner —
-//     CF Pages assets are read-only by definition, and we want POSTs
+//     assets are read-only by definition, and we want POSTs
 //     (\`/api/ai-chat\`, etc.) to reach the SSR handler without a probe
 //     that would always 405 / 404.
 import { AsyncLocalStorage } from "node:async_hooks";
@@ -65,14 +90,77 @@ function isAssetProbeMethod(method) {
   return method === "GET" || method === "HEAD";
 }
 
+function assetHasStyled404Body(response) {
+  // True iff an ASSETS 404 carries the site's *styled* 404 page.
+  // Platform fact: \`not_found_handling = "404-page"\` (Workers Static
+  // Assets) and the Pages \`404.html\` convention both serve that page as
+  // an HTML document — auto-detected \`content-type: text/html\` and a real
+  // \`Content-Length\` (it is a static file). \`not_found_handling = "none"\`
+  // and a bare Pages advanced-mode 404 send Cloudflare's default 404 with
+  // an empty / non-HTML body, so this returns false and the inner wins.
+  // Header-only (never reads the body) so it holds for HEAD too and leaves
+  // the one-shot asset stream intact for a verbatim return.
+  const contentType = (response.headers.get("content-type") || "").toLowerCase();
+  const contentLength = Number(response.headers.get("content-length") || "0");
+  return contentType.includes("text/html") && contentLength > 0;
+}
+
+function innerIsFrameworkDefault404(response) {
+  // True iff an inner 404 is the framework's *generic* not-found, which
+  // yields to the styled asset 404 page. The inner zfb router never
+  // overrides Hono's default handler, so a route miss is always Hono's
+  // default not-found — \`text/plain\` "404 Not Found" (or a bare 404 with no
+  // content-type). Any inner 404 that declares another content-type is a
+  // *deliberate* response and must WIN over the static styled asset page: a
+  // \`text/html\` 404 is a rendered custom not-found page (e.g. a
+  // \`prerender = false\` [slug] route SSRing its own 404), and an
+  // \`application/json\` 404 is an intentional machine-readable API error.
+  // Trade-off: a bare \`text/plain\` API 404 is indistinguishable from the
+  // framework default and will yield to the styled page — API errors should
+  // use \`application/json\` to be preserved.
+  const contentType = (response.headers.get("content-type") || "").toLowerCase();
+  if (contentType === "") return true;
+  return contentType.includes("text/plain");
+}
+
 export default {
   async fetch(request, env, ctx) {
     if (isAssetProbeMethod(request.method) && canDelegateToAssets(env)) {
+      // Trade-off: every GET/HEAD request that matches a prerendered route pays
+      // the cost of one env.ASSETS.fetch() round-trip before the inner worker
+      // sees it (when this probe actually runs — see the header comment on
+      // run_worker_first). The upside is that the asset server handles
+      // trailing-slash canonicalisation (e.g. /docs/foo → redirect → /docs/foo/)
+      // and serves the build-time head-injected HTML with the hashed
+      // <link>/<script> tags. If we skipped this probe, prerendered routes
+      // would be dynamic-SSR'd by the inner Hono router without the prod head
+      // injection, and islands would never hydrate. For purely dynamic apps
+      // (prerender=false everywhere) the extra round-trip is pure overhead;
+      // splitting the wrapper into two variants is the accepted future escape
+      // hatch for that case.
       const assetResponse = await env.ASSETS.fetch(request);
       if (assetResponse.status !== 404) {
         return assetResponse;
       }
-      // Fall through to the inner worker for genuinely dynamic routes.
+      // Asset 404. Fall through to the inner worker for genuinely dynamic
+      // routes, but first hold the asset response UNREAD if it carries a
+      // styled 404 page: if the inner also 404s with only the framework
+      // default body (text/plain or none), we return this styled page
+      // instead of the inner's plain 404 (issue #1322). An inner 404 that
+      // renders its own page (text/html) or a structured API error
+      // (application/json) wins. Returned verbatim — the one-shot body is
+      // untouched.
+      const styledAsset404 = assetHasStyled404Body(assetResponse) ? assetResponse : null;
+      const store = { env, ctx, request };
+      const innerResponse = await getStorage().run(store, () => inner.fetch(request));
+      if (
+        styledAsset404 !== null &&
+        innerResponse.status === 404 &&
+        innerIsFrameworkDefault404(innerResponse)
+      ) {
+        return styledAsset404;
+      }
+      return innerResponse;
     }
     const store = { env, ctx, request };
     return getStorage().run(store, () => inner.fetch(request));

package/package.json

@@ -1,15 +1,16 @@
 {
   "name": "@takazudo/zfb-adapter-cloudflare",
-  "version": "0.1.0-next.8",
+  "version": "0.1.0-next.80",
   "private": false,
   "type": "module",
-  "description": "Rust-built static-site engine for Astro and Next.js users — millisecond rebuilds, single binary. Cloudflare Pages adapter.",
+  "description": "Rust-built static-site engine for Astro and Next.js users — millisecond rebuilds, single binary. Cloudflare adapter: Workers Static Assets (Pages-compatible).",
   "keywords": [
     "zfb",
     "zfb-adapter",
     "cloudflare",
     "cloudflare-pages",
     "cloudflare-workers",
+    "workers-static-assets",
     "ssg",
     "static-site-generator",
     "adapter"
@@ -44,6 +45,7 @@
     "dist",
     "bin",
     "src/worker-wrapper.mjs",
+    "src/emit-worker.mjs",
     "README.md",
     "CHANGELOG.md",
     "LICENSE"
@@ -61,7 +63,7 @@
     "vitest": "^2.1.9"
   },
   "scripts": {
-    "build": "tsc && cp src/worker-wrapper.mjs dist/worker-wrapper.mjs",
+    "build": "tsc && cp src/worker-wrapper.mjs dist/worker-wrapper.mjs && cp src/emit-worker.mjs dist/emit-worker.mjs",
     "test": "vitest run",
     "test:watch": "vitest",
     "typecheck": "tsc --noEmit"

package/src/emit-worker.mjs

@@ -0,0 +1,49 @@
+// Shared, dependency-free implementation of `emitWorker`.
+//
+// Kept as a plain `.mjs` module (no TypeScript) so it can be imported from
+// both the typed TypeScript surface (`src/build.ts`) and the dependency-free
+// CLI binary (`bin/cli.mjs`) without needing a TypeScript loader.
+//
+// Do NOT duplicate this logic elsewhere. The two consumers always stay in
+// sync by importing from here.
+//
+// invariant: no runtime npm deps — see SECURITY-DEPS.md
+
+import { copyFile, mkdir, writeFile } from "node:fs/promises";
+import { join, resolve } from "node:path";
+
+// `.assetsignore` tells the Workers Static Assets uploader (and Pages'
+// asset server) to skip these two files, so they are only ever reachable
+// through the Worker's module graph, not served as public static assets.
+const ASSETS_IGNORE_CONTENT = "_worker.js\n_zfb_inner.mjs\n";
+
+/**
+ * Emit a Cloudflare Workers Static Assets (Pages-compatible) `_worker.js`
+ * that wraps the zfb input bundle.
+ *
+ * Output shape (three files in `outdir`):
+ *
+ *   _worker.js       — Worker entry point (`main` in wrangler.toml, or the
+ *                      Pages advanced-mode convention)
+ *   _zfb_inner.mjs   — the input bundle, copied verbatim
+ *   .assetsignore    — excludes the two files above from the asset upload
+ *
+ * @param {{ inputBundlePath: string; outdir: string; workerWrapperSource: string }} input
+ * @returns {Promise<{ workerPath: string; innerBundlePath: string; assetsIgnorePath: string }>}
+ */
+export async function emitWorker({ inputBundlePath, outdir, workerWrapperSource }) {
+  const outdirAbs = resolve(outdir);
+  const inputAbs = resolve(inputBundlePath);
+
+  await mkdir(outdirAbs, { recursive: true });
+  const innerBundlePath = join(outdirAbs, "_zfb_inner.mjs");
+  await copyFile(inputAbs, innerBundlePath);
+
+  const workerPath = join(outdirAbs, "_worker.js");
+  await writeFile(workerPath, workerWrapperSource, "utf8");
+
+  const assetsIgnorePath = join(outdirAbs, ".assetsignore");
+  await writeFile(assetsIgnorePath, ASSETS_IGNORE_CONTENT, "utf8");
+
+  return { workerPath, innerBundlePath, assetsIgnorePath };
+}

package/src/worker-wrapper.mjs

@@ -10,34 +10,59 @@
 /** @type {string} */
 export const WORKER_WRAPPER_SOURCE = `// AUTO-GENERATED by @takazudo/zfb-adapter-cloudflare. Do not edit.
 //
-// Cloudflare Pages advanced mode entry. Forwards (request, env, ctx) to
-// the inner zfb worker bundle, exposing env/ctx to user code via
-// AsyncLocalStorage under a stable globalThis key.
+// Cloudflare Workers Static Assets entry (\`main\` in wrangler.toml,
+// alongside an \`[assets]\` block; also deployable to Cloudflare Pages
+// advanced mode). Forwards (request, env, ctx) to the inner zfb worker
+// bundle, exposing env/ctx to user code via AsyncLocalStorage under a
+// stable globalThis key.
 //
 // The same key is read by @takazudo/zfb-adapter-cloudflare's
 // getCloudflareContext() inside the user bundle, so the two ends share
 // state even though they live in separate ESM module instances.
 //
-// CF Pages advanced-mode contract: when _worker.js is present, every
-// request hits the worker — static asset routing is OFF unless the
-// worker explicitly delegates to env.ASSETS. The dispatch order below
-// is deliberately "ASSETS first, inner on 404":
+// Dispatch order is deliberately "ASSETS first, inner on 404" — this
+// holds across both deploy targets, but *why* the ASSETS probe fires
+// differs:
 //
-//   - GET/HEAD requests probe env.ASSETS first. CF Pages' asset server
+//   - Workers Static Assets with \`run_worker_first = false\` (the zfb
+//     default): the platform itself serves asset hits before the
+//     Worker ever runs, so for those requests this in-Worker probe is
+//     normally bypassed — it never had a chance to run. The probe below
+//     is NOT dead code: it is still exercised for Pages (no
+//     \`run_worker_first\` concept; every request hits the Worker), for
+//     \`run_worker_first = true\` deployments, and for any request the
+//     platform's asset router itself does not resolve (which still
+//     reaches this Worker as a "miss").
+//   - GET/HEAD requests probe env.ASSETS first. The asset server
 //     handles the trailing-slash canonicalisation for SSG output (e.g.
-//     "/docs/foo" → 308 → "/docs/foo/" → dist/docs/foo/index.html), so
+//     "/docs/foo" → redirect → "/docs/foo/" → dist/docs/foo/index.html
+//     — 307 on Workers Static Assets, 308 on Cloudflare Pages), so
 //     prerendered routes get the build-time head-injected HTML
 //     (<link rel="stylesheet">, <script type="module" src="/assets/
 //     islands-…">). If we let the inner Hono router handle them first,
 //     it would dynamic-SSR the page WITHOUT the prod head injection
 //     (which is a build-time post-process, not a runtime concern), and
-//     islands would never hydrate. See zfb#XXX (filed by Wave 10 of
-//     the zudo-doc#1355 zfb-pipeline-gaps epic).
-//   - On 404 from ASSETS, fall through to the inner zfb worker. This is
-//     where genuinely dynamic routes (\`prerender = false\`, e.g.
-//     \`pages/api/*.tsx\`) are served.
+//     islands would never hydrate.
+//   - On 404 from ASSETS, fall through to the inner zfb worker — this
+//     is where genuinely dynamic routes (\`prerender = false\`, e.g.
+//     \`pages/api/*.tsx\`) are served. EXCEPTION: when the asset 404
+//     carries a *styled* 404-page body (\`not_found_handling = "404-page"\`
+//     on Workers Static Assets, or the \`404.html\` convention on Pages —
+//     detected as an HTML document with a real Content-Length) AND the
+//     inner ALSO 404s with only the framework default body (Hono's
+//     default not-found, \`text/plain\` "404 Not Found", or a bare 404
+//     with no content-type), the earlier styled asset 404 is preferred
+//     over the inner's plain 404 — otherwise the styled \`404.html\` would
+//     be discarded and users would see the inner plain-text 404 (issue
+//     #1322). Any inner 404 that declares another content-type is a
+//     deliberate response and WINS: a \`text/html\` 404 is a rendered
+//     custom not-found page (a \`prerender = false\` route SSRing its own
+//     404), and an \`application/json\` 404 is an intentional API error —
+//     both are returned unchanged. Under \`not_found_handling = "none"\`
+//     the asset 404 body is empty/non-HTML, so the inner always wins —
+//     the historical behavior is preserved.
 //   - Non-GET/HEAD requests skip ASSETS and go straight to the inner —
-//     CF Pages assets are read-only by definition, and we want POSTs
+//     assets are read-only by definition, and we want POSTs
 //     (\`/api/ai-chat\`, etc.) to reach the SSR handler without a probe
 //     that would always 405 / 404.
 import { AsyncLocalStorage } from "node:async_hooks";
@@ -65,14 +90,77 @@ function isAssetProbeMethod(method) {
   return method === "GET" || method === "HEAD";
 }
 
+function assetHasStyled404Body(response) {
+  // True iff an ASSETS 404 carries the site's *styled* 404 page.
+  // Platform fact: \`not_found_handling = "404-page"\` (Workers Static
+  // Assets) and the Pages \`404.html\` convention both serve that page as
+  // an HTML document — auto-detected \`content-type: text/html\` and a real
+  // \`Content-Length\` (it is a static file). \`not_found_handling = "none"\`
+  // and a bare Pages advanced-mode 404 send Cloudflare's default 404 with
+  // an empty / non-HTML body, so this returns false and the inner wins.
+  // Header-only (never reads the body) so it holds for HEAD too and leaves
+  // the one-shot asset stream intact for a verbatim return.
+  const contentType = (response.headers.get("content-type") || "").toLowerCase();
+  const contentLength = Number(response.headers.get("content-length") || "0");
+  return contentType.includes("text/html") && contentLength > 0;
+}
+
+function innerIsFrameworkDefault404(response) {
+  // True iff an inner 404 is the framework's *generic* not-found, which
+  // yields to the styled asset 404 page. The inner zfb router never
+  // overrides Hono's default handler, so a route miss is always Hono's
+  // default not-found — \`text/plain\` "404 Not Found" (or a bare 404 with no
+  // content-type). Any inner 404 that declares another content-type is a
+  // *deliberate* response and must WIN over the static styled asset page: a
+  // \`text/html\` 404 is a rendered custom not-found page (e.g. a
+  // \`prerender = false\` [slug] route SSRing its own 404), and an
+  // \`application/json\` 404 is an intentional machine-readable API error.
+  // Trade-off: a bare \`text/plain\` API 404 is indistinguishable from the
+  // framework default and will yield to the styled page — API errors should
+  // use \`application/json\` to be preserved.
+  const contentType = (response.headers.get("content-type") || "").toLowerCase();
+  if (contentType === "") return true;
+  return contentType.includes("text/plain");
+}
+
 export default {
   async fetch(request, env, ctx) {
     if (isAssetProbeMethod(request.method) && canDelegateToAssets(env)) {
+      // Trade-off: every GET/HEAD request that matches a prerendered route pays
+      // the cost of one env.ASSETS.fetch() round-trip before the inner worker
+      // sees it (when this probe actually runs — see the header comment on
+      // run_worker_first). The upside is that the asset server handles
+      // trailing-slash canonicalisation (e.g. /docs/foo → redirect → /docs/foo/)
+      // and serves the build-time head-injected HTML with the hashed
+      // <link>/<script> tags. If we skipped this probe, prerendered routes
+      // would be dynamic-SSR'd by the inner Hono router without the prod head
+      // injection, and islands would never hydrate. For purely dynamic apps
+      // (prerender=false everywhere) the extra round-trip is pure overhead;
+      // splitting the wrapper into two variants is the accepted future escape
+      // hatch for that case.
       const assetResponse = await env.ASSETS.fetch(request);
       if (assetResponse.status !== 404) {
         return assetResponse;
       }
-      // Fall through to the inner worker for genuinely dynamic routes.
+      // Asset 404. Fall through to the inner worker for genuinely dynamic
+      // routes, but first hold the asset response UNREAD if it carries a
+      // styled 404 page: if the inner also 404s with only the framework
+      // default body (text/plain or none), we return this styled page
+      // instead of the inner's plain 404 (issue #1322). An inner 404 that
+      // renders its own page (text/html) or a structured API error
+      // (application/json) wins. Returned verbatim — the one-shot body is
+      // untouched.
+      const styledAsset404 = assetHasStyled404Body(assetResponse) ? assetResponse : null;
+      const store = { env, ctx, request };
+      const innerResponse = await getStorage().run(store, () => inner.fetch(request));
+      if (
+        styledAsset404 !== null &&
+        innerResponse.status === 404 &&
+        innerIsFrameworkDefault404(innerResponse)
+      ) {
+        return styledAsset404;
+      }
+      return innerResponse;
     }
     const store = { env, ctx, request };
     return getStorage().run(store, () => inner.fetch(request));

package/dist/build.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"build.d.ts","sourceRoot":"","sources":["../src/build.ts"],"names":[],"mappings":"AAcA;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,EAAE,MAA2B,CAAC;AAEhE;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B;;;;;;OAMG;IACH,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC;;;;OAIG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;CAClC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,UAAU,CAAC,KAAK,EAAE,eAAe,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAelF"}

package/dist/index.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAwCA;;;;;;;GAOG;AACH,MAAM,WAAW,0BAA0B;IACzC,+DAA+D;IAC/D,SAAS,CAAC,OAAO,EAAE,OAAO,CAAC,OAAO,CAAC,GAAG,IAAI,CAAC;IAC3C,iEAAiE;IACjE,sBAAsB,IAAI,IAAI,CAAC;CAChC;AAED;;;GAGG;AACH,MAAM,WAAW,iBAAiB,CAAC,GAAG,GAAG,OAAO;IAC9C,uEAAuE;IACvE,QAAQ,CAAC,GAAG,EAAE,GAAG,CAAC;IAClB,+DAA+D;IAC/D,QAAQ,CAAC,GAAG,EAAE,0BAA0B,CAAC;IACzC,qEAAqE;IACrE,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;CAC3B;AA0BD;;;GAGG;AACH,wBAAgB,wBAAwB,CAAC,CAAC,EAAE,OAAO,EAAE,iBAAiB,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CAEtF;AAED;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,GAAG,OAAO,KAAK,iBAAiB,CAAC,GAAG,CAAC,CAU5E"}