@timber-js/app 0.2.0-alpha.18 → 0.2.0-alpha.180

package/docs/more/50-ai-agent-instructions.mdx

@@ -0,0 +1,169 @@
+---
+title: 'AI Agent Instructions'
+description: 'Structured reference for AI coding agents working with timber.js — key differences from Next.js, import paths, common mistakes, and reading order.'
+slug: 'ai-agent-instructions'
+---
+
+# AI Agent Instructions
+
+This page is for AI coding agents (Claude Code, Cursor, Copilot, Codex, etc.) and developers who paste context into agent prompts. It is concise and structured for machine consumption — but useful as a quick reference for humans too.
+
+## Fetching These Docs as Markdown
+
+Any timber.js documentation page can be fetched as plain markdown by sending an `Accept: text/markdown` header:
+
+```bash
+curl -H 'Accept: text/markdown' https://timberjs.com/docs/ai-agent-instructions
+```
+
+This returns the page content as `text/markdown` with a `203` status code, suitable for piping into agent context or saving to a file.
+
+## How timber.js Docs Are Organized
+
+| Location | Purpose | Audience |
+| --- | --- | --- |
+| `packages/website/content/docs/` | User-facing guides, tutorials, API reference | Developers building with timber |
+| `design/` | Design decisions, architecture, internal specs | Contributors and agents implementing features |
+| `CLAUDE.md` | Contributor workflow, commands, code style | Agents working on timber itself |
+
+**Read the user-facing docs for building apps.** Read the design docs only when you need to understand _why_ something works the way it does or when contributing to timber itself.
+
+## Reading Order by Task
+
+**Starting a new project:**
+1. [Introduction](/docs/introduction) — what timber is and its philosophy
+2. [Quick Start](/docs/quick-start) — project setup
+3. [Pages and Layouts](/docs/pages-and-layouts) — routing basics
+4. [Configuration](/docs/configuration) — `timber.config.ts`
+
+**Adding a feature:**
+1. [API: @timber-js/app/server](/docs/api-server) — server exports
+2. [API: @timber-js/app/client](/docs/api-client) — client exports
+3. The relevant guide (caching, forms, middleware, etc.)
+
+**Debugging:**
+1. [Coming from Next.js](/docs/coming-from-nextjs) — if the code assumes Next.js patterns
+2. [The Flush Point](/docs/the-flush-point) — if status codes or headers are wrong
+3. [Error Handling](/docs/error-handling) — deny, error boundaries, status files
+
+## Key Differences from Next.js
+
+These are the things you will get wrong if you assume Next.js behavior.
+
+| Concept | Next.js | timber.js |
+| --- | --- | --- |
+| Default component type | Client components need `'use client'` | **All components are server components** by default. Only add `'use client'` when you need browser APIs or hooks. |
+| Fetch caching | `fetch()` is patched with implicit caching | `fetch()` is **never patched**. Use `cache.data()` from `@timber-js/app/cache` explicitly. |
+| ISR | `revalidate` option | **Does not exist.** Use `cache.data()` with TTL and tags. |
+| `loading.tsx` | Convention for auto-Suspense | **Does not exist.** Use `<Suspense>` explicitly. |
+| Middleware | Single global `middleware.ts` with matchers | Per-segment `middleware.ts` files + global `proxy.ts`. One-arg signature: `middleware(ctx)`. |
+| `notFound()` | `notFound()` from `next/navigation` | `deny(404)` from `@timber-js/app/server`. Sends a real HTTP 404. |
+| `redirect()` | `redirect()` from `next/navigation` | `redirect()` from `@timber-js/app/server`. Same concept, different import. |
+| Search params | Untyped `useSearchParams()` | Typed `defineSearchParams()` with Zod schemas in `params.ts`. |
+| Auth pattern | In middleware or components | `access.ts` per segment with slot degradation. |
+| Forms | `useFormState` / `useFormStatus` | `createActionClient` + `useActionState` returns a 4-tuple. Forms work without JS. |
+
+## Import Map
+
+| What you need | Import from |
+| --- | --- |
+| `deny`, `redirect`, `getHeaders`, `getCookieJar`, `createActionClient` | `@timber-js/app/server` |
+| `Link`, `useRouter`, `usePathname`, `useActionState` | `@timber-js/app/client` |
+| `cache`, `CacheHandler` | `@timber-js/app/cache` |
+| `defineSearchParams` | `@timber-js/app/search-params` |
+| `defineSchema`, `defineSegmentParams` | `@timber-js/app/params` |
+| Content collection data | `content-collections` |
+| `Metadata` type | `@timber-js/app/server` |
+
+There is **no** `@timber-js/app` default import. Always use the subpath exports above.
+
+## Project Structure
+
+```
+app/                    # Route tree — file-system routing
+  proxy.ts              # Global request handler (like global middleware)
+  layout.tsx            # Root layout
+  page.tsx              # Home page
+  [segment]/
+    page.tsx            # Dynamic route
+    middleware.ts       # Per-segment middleware
+    access.ts           # Per-segment authorization
+    denied.tsx          # Rendered when access.ts denies
+    error.tsx           # Error boundary for this segment
+    params.ts           # Search param definitions
+  schema.ts             # Segment param schemas (from @timber-js/app/params)
+content/                # Content collections (outside route tree)
+timber.config.ts        # Framework configuration
+mdx-components.tsx      # Custom MDX component mappings (optional)
+content-collections.ts  # Collection definitions (optional)
+```
+
+## Common Mistakes
+
+1. **Importing from `next/*`** — there is no `next` package. Use `@timber-js/app/server` and `@timber-js/app/client`. Exception: `next/navigation`'s `redirect()` and `notFound()` are shimmed for compatibility.
+
+2. **Adding `'use client'` to everything** — components are server components by default. Only add `'use client'` when you need browser APIs, event handlers, or React hooks like `useState`/`useEffect`.
+
+3. **Using `fetch()` and expecting caching** — timber never patches `fetch`. Wrap data-fetching functions in `cache.data()` from `@timber-js/app/cache` when you want caching.
+
+4. **Creating `loading.tsx` files** — this convention does not exist. Use `<Suspense>` with an explicit fallback where you want streaming.
+
+5. **Using ISR patterns** (`revalidate`, `unstable_cache`) — ISR does not exist. Use `cache.data()` with `{ ttl: seconds, tags: ['tag'] }`.
+
+6. **Calling `notFound()`** — use `deny(404)` from `@timber-js/app/server` instead. It sends a real HTTP 404 status code.
+
+7. **Putting all middleware in one file** — middleware is per-segment. Place `middleware.ts` at the route level that matches the concern. Use `proxy.ts` for global concerns.
+
+8. **Assuming `useSearchParams()` exists** — use `defineSearchParams()` in a `params.ts` file with Zod schemas, then access via `.get()` (server) or `.useQueryStates()` (client).
+
+## Quick Patterns
+
+### Data fetching with caching
+
+```tsx
+import { cache } from '@timber-js/app/cache';
+
+const getProducts = cache.data(
+  async () => db.products.findMany(),
+  { ttl: 300, tags: ['products'] }
+);
+
+export default async function Page() {
+  const products = await getProducts();
+  return <ProductList products={products} />;
+}
+```
+
+### 404 handling
+
+```tsx
+import { deny } from '@timber-js/app/server';
+
+export default async function Page({ params }: { params: Promise<{ id: string }> }) {
+  const { id } = await params;
+  const item = await getItem(id);
+  if (!item) deny(404);
+  return <Item item={item} />;
+}
+```
+
+### Per-segment middleware
+
+```ts title="app/dashboard/middleware.ts"
+import type { MiddlewareContext } from '@timber-js/app/server';
+
+export default async function middleware(ctx: MiddlewareContext) {
+  ctx.headers.set('X-Dashboard', 'true');
+}
+```
+
+### Access control
+
+```ts title="app/(auth)/access.ts"
+import { redirect, getCookieJar } from '@timber-js/app/server';
+
+export default async function access() {
+  const session = getSession(getCookieJar());
+  if (!session) redirect('/login');
+}
+```

package/llms.txt

@@ -0,0 +1,55 @@
+# @timber-js/app
+
+> Vite-native React Server Components framework built for Servers and Serverless Platforms — correct HTTP semantics, real status codes, pages that work without JavaScript.
+
+timber.js is a React framework built on Vite and React Server Components. It uses file-system routing (app/ directory), server components by default, and produces real HTTP status codes. It deploys to Cloudflare Workers, Node.js, Vercel, Netlify, and more via adapters.
+
+It is inspired by, but _not_ next.js. Do not assume next.js features work in timber, though the routing is similar, much of the rest diverges.
+
+## Docs
+
+Documentation ships with this package in the `docs/` directory. All files are MDX.
+
+### Learn (core concepts, read in order)
+
+- [Introduction](docs/learn/00-introduction.mdx)
+- [Quick Start](docs/learn/01-quick-start.mdx)
+- [Pages and Layouts](docs/learn/02-pages-and-layouts.mdx)
+- [Fetching Data](docs/learn/03-fetching-data.mdx)
+- [Access Control](docs/learn/03b-access-control.mdx)
+- [Loading States](docs/learn/04-loading-states.mdx)
+- [The Flush Point](docs/learn/04b-the-flush-point.mdx)
+- [Typed Params](docs/learn/05-typed-params.mdx)
+- [Forms and Actions](docs/learn/06-forms-and-actions.mdx)
+- [Streaming](docs/learn/08-streaming.mdx)
+- [Caching](docs/learn/09-caching.mdx)
+- [Middleware](docs/learn/10-middleware.mdx)
+- [Error Handling](docs/learn/11-error-handling.mdx)
+- [Client Navigation](docs/learn/12-client-navigation.mdx)
+- [Configuration](docs/learn/13-configuration.mdx)
+- [Deploying](docs/learn/14-deploying.mdx)
+
+### More (advanced topics)
+
+- [Advanced Routing](docs/more/01-advanced-routing.mdx)
+- [Advanced Forms](docs/more/02-advanced-forms.mdx)
+- [Coming from Next.js](docs/more/03-coming-from-nextjs.mdx)
+- [Metadata and Fonts](docs/more/04-metadata-and-fonts.mdx)
+- [MDX](docs/more/04b-mdx.mdx)
+- [Content Collections](docs/more/05-content-collections.mdx)
+- [Instrumentation & Tracing](docs/more/06-instrumentation.mdx)
+- [Security](docs/more/07-security.mdx)
+
+### API Reference
+
+- [@timber-js/app/server](docs/api/30-api-server.mdx)
+- [@timber-js/app/client](docs/api/31-api-client.mdx)
+- [@timber-js/app/cache](docs/api/32-api-cache.mdx)
+- [Search & Segment Params](docs/api/33-api-search-params.mdx)
+- [timber.config.ts](docs/api/34-api-config.mdx)
+- [TypeScript](docs/api/35-api-typescript.mdx)
+- [CLI](docs/api/36-cli.mdx)
+
+## AI Agent Skill
+
+A Claude Code skill is included at `agent-skill.md`. Load it for guidance on building timber.js applications.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@timber-js/app",
-  "version": "0.2.0-alpha.18",
-  "description": "Vite-native React framework for Cloudflare Workers — correct HTTP semantics, real status codes, pages that work without JavaScript",
+  "version": "0.2.0-alpha.180",
+  "description": "Vite-native React framework built for Servers and Serverless Platforms — correct HTTP semantics, real status codes, pages that work without JavaScript",
   "keywords": [
     "cloudflare-workers",
     "framework",
@@ -26,12 +26,27 @@
     "dist",
     "src",
     "bin",
+    "docs",
+    "agent-skill.md",
+    "llms.txt",
     "README.md",
     "LICENSE"
   ],
   "type": "module",
   "imports": {
-    "#/*": "./src/*"
+    "#server-internal": {
+      "types": "./dist/server/internal.d.ts",
+      "default": "./dist/server/internal.js"
+    },
+    "#client-internal": {
+      "types": "./dist/client/internal.d.ts",
+      "default": "./dist/client/internal.js"
+    },
+    "#routing": {
+      "types": "./dist/routing/index.d.ts",
+      "default": "./dist/routing/index.js"
+    },
+    "#server-only-guard": "./src/server/server-only-guard-noop.js"
   },
   "exports": {
     ".": {
@@ -46,13 +61,49 @@
       "types": "./dist/client/index.d.ts",
       "import": "./dist/client/index.js"
     },
+    "./client/internal": {
+      "types": "./dist/client/internal.d.ts",
+      "import": "./dist/client/internal.js"
+    },
     "./cache": {
       "types": "./dist/cache/index.d.ts",
       "import": "./dist/cache/index.js"
     },
-    "./content": {
-      "types": "./dist/content/index.d.ts",
-      "import": "./dist/content/index.js"
+    "./cache/stores/memory": {
+      "types": "./dist/cache/stores/memory.d.ts",
+      "import": "./dist/cache/stores/memory.js"
+    },
+    "./cache/stores/redis": {
+      "types": "./dist/cache/stores/redis.d.ts",
+      "import": "./dist/cache/stores/redis.js"
+    },
+    "./cache/stores/cloudflare-kv": {
+      "types": "./dist/cache/stores/cloudflare-kv.d.ts",
+      "import": "./dist/cache/stores/cloudflare-kv.js"
+    },
+    "./cache/stores/vercel": {
+      "types": "./dist/cache/stores/vercel.d.ts",
+      "import": "./dist/cache/stores/vercel.js"
+    },
+    "./cdn": {
+      "types": "./dist/cdn/index.d.ts",
+      "import": "./dist/cdn/index.js"
+    },
+    "./cdn/cloudflare": {
+      "types": "./dist/cdn/cloudflare-purge.d.ts",
+      "import": "./dist/cdn/cloudflare-purge.js"
+    },
+    "./cdn/cloudflare-workers": {
+      "types": "./dist/cdn/workers-cache-purge.d.ts",
+      "import": "./dist/cdn/workers-cache-purge.js"
+    },
+    "./cdn/fastly": {
+      "types": "./dist/cdn/fastly-purge.d.ts",
+      "import": "./dist/cdn/fastly-purge.js"
+    },
+    "./codec": {
+      "types": "./dist/codec.d.ts",
+      "import": "./dist/codec.js"
     },
     "./cookies": {
       "types": "./dist/cookies/index.d.ts",
@@ -62,45 +113,65 @@
       "types": "./dist/search-params/index.d.ts",
       "import": "./dist/search-params/index.js"
     },
-    "./routing": {
-      "types": "./dist/routing/index.d.ts",
-      "import": "./dist/routing/index.js"
+    "./segment-params": {
+      "types": "./dist/segment-params/index.d.ts",
+      "import": "./dist/segment-params/index.js"
+    },
+    "./params": {
+      "types": "./dist/params/index.d.ts",
+      "import": "./dist/params/index.js"
     },
     "./adapters/cloudflare": {
       "types": "./dist/adapters/cloudflare.d.ts",
       "import": "./dist/adapters/cloudflare.js"
     },
+    "./adapters/cloudflare/cache": {
+      "types": "./dist/adapters/cloudflare-kv-cache.d.ts",
+      "import": "./dist/adapters/cloudflare-kv-cache.js"
+    },
+    "./adapters/cloudflare/dev": {
+      "types": "./dist/adapters/cloudflare-dev.d.ts",
+      "import": "./dist/adapters/cloudflare-dev.js"
+    },
     "./adapters/nitro": {
       "types": "./dist/adapters/nitro.d.ts",
       "import": "./dist/adapters/nitro.js"
     },
+    "./fonts/google": {
+      "types": "./dist/shims/font-google.d.ts",
+      "import": "./dist/shims/font-google.js"
+    },
+    "./fonts/local": {
+      "types": "./dist/shims/font-local.d.ts",
+      "import": "./dist/shims/font-local.js"
+    },
     "./package.json": "./package.json"
   },
   "publishConfig": {
     "access": "public"
   },
-  "scripts": {
-    "build": "vite build --config vite.lib.config.ts && tsc --emitDeclarationOnly --project tsconfig.json --outDir dist",
-    "typecheck": "tsgo --noEmit",
-    "prepublishOnly": "pnpm run build"
-  },
   "dependencies": {
-    "@opentelemetry/api": "^1.9.0",
-    "@opentelemetry/context-async-hooks": "^2.6.0",
-    "@opentelemetry/sdk-trace-base": "^2.6.0",
-    "nitro": "3.0.260311-beta"
+    "@opentelemetry/api": "^1.9.1",
+    "@opentelemetry/context-async-hooks": "^2.9.0",
+    "@opentelemetry/sdk-trace-base": "^2.9.0",
+    "cookie": "^1.1.1",
+    "jsonc-parser": "^3.3.1",
+    "magic-string": "^0.30.21",
+    "nitro": "3.0.260610-beta",
+    "srvx": "^0.11.22"
   },
   "peerDependencies": {
-    "@content-collections/core": "^0.14.0",
+    "@content-collections/core": "^0.14.0 || ^0.15.0",
     "@content-collections/mdx": "^0.2.0",
-    "@content-collections/vite": "^0.2.0",
+    "@content-collections/vite": "^0.2.0 || ^0.3.0",
     "@mdx-js/rollup": "^3.0.0",
     "@vitejs/plugin-react": "^6.0.0",
-    "@vitejs/plugin-rsc": ">=0.5.21",
+    "@vitejs/plugin-rsc": ">=0.5.27",
     "nuqs": "^2.0.0",
-    "react": "^19.2.4",
-    "react-dom": "^19.2.4",
-    "vite": "^8.0.1",
+    "react": "19.2.7",
+    "react-dom": "19.2.7",
+    "vite": "^8.1.0",
+    "wrangler": "^4.0.0",
     "zod": "^3.22.0 || ^4.0.0"
   },
   "peerDependenciesMeta": {
@@ -116,11 +187,19 @@
     "@mdx-js/rollup": {
       "optional": true
     },
+    "wrangler": {
+      "optional": true
+    },
     "zod": {
       "optional": true
     }
   },
   "engines": {
-    "node": ">=20.0.0"
+    "node": ">=22.18.0"
+  },
+  "scripts": {
+    "copy-docs": "node scripts/copy-docs.js",
+    "build": "vite build --config vite.lib.config.ts && tsc --emitDeclarationOnly --project tsconfig.json --outDir dist && pnpm run copy-docs",
+    "typecheck": "tsgo --noEmit"
   }
-}
+}

package/src/adapters/build-output-helper.ts

@@ -0,0 +1,199 @@
+// Shared build-output helper for adapter buildOutput() methods.
+//
+// Steps 1–5 of every adapter's buildOutput are platform-agnostic:
+//   1. Copy client assets to the public/static directory
+//   2. Write _headers file for static asset cache control
+//   3. Copy RSC + SSR server bundles
+//   4. Write manifest-init module (if present)
+//
+// Only the final steps (entry codegen, platform config) vary per adapter.
+//
+// IMPORTANT: This module must remain a leaf — no imports from ../server/,
+// ../client/, or Vite-dependent code. See adapters/shared.ts header.
+
+import { writeFile, mkdir, cp, readdir, readFile } from 'node:fs/promises';
+import { join, basename, relative } from 'node:path';
+import { generateHeadersFile } from './shared.js';
+import type { TimberConfig } from './types';
+
+/** Options for the shared build output steps. */
+export interface BuildOutputBaseOptions {
+  /** Resolved timber config. */
+  config: TimberConfig;
+  /** Root build directory (e.g. `.timber/build`). */
+  buildDir: string;
+  /** Adapter-specific output directory (e.g. `.timber/build/nitro`). */
+  outDir: string;
+  /**
+   * Name of the public/static directory within outDir.
+   * Nitro uses 'public', Cloudflare uses 'static'.
+   */
+  publicDirName: string;
+}
+
+/**
+ * Run the platform-agnostic build output steps shared by all adapters:
+ *
+ * 1. Create the output directory
+ * 2. Copy client assets to the public/static directory
+ * 3. Write the `_headers` file for static asset cache control
+ * 4. Copy RSC and SSR server bundles into the output directory
+ * 5. Write the manifest-init module if present
+ *
+ * Returns the resolved public directory path for further adapter-specific use.
+ */
+export async function runSharedBuildSteps(opts: BuildOutputBaseOptions): Promise<string> {
+  const { config, buildDir, outDir, publicDirName } = opts;
+
+  // 1. Create the output directory.
+  await mkdir(outDir, { recursive: true });
+
+  // 2. Copy client assets to public/static directory.
+  // When client JavaScript is disabled, skip .js files — only CSS,
+  // fonts, images, and other static assets are needed.
+  const clientDir = join(buildDir, 'client');
+  const publicDir = join(outDir, publicDirName);
+  await mkdir(publicDir, { recursive: true });
+  // Find WASM files that are referenced by client JS (legitimate client WASM)
+  // vs orphaned server-only WASM (e.g. @takumi-rs for OG image generation).
+  // Only strip orphaned WASM to avoid breaking client-side WASM usage.
+  const referencedWasm = await findReferencedWasm(clientDir);
+
+  await cp(clientDir, publicDir, {
+    recursive: true,
+    filter: (src: string) => {
+      if (src.endsWith('.wasm') && !referencedWasm.has(basename(src))) {
+        return false;
+      }
+      if (config.clientJavascriptDisabled && src.endsWith('.js')) return false;
+      return true;
+    },
+  }).catch((e: NodeJS.ErrnoException) => {
+    // Client dir may not exist when client JavaScript is disabled
+    if (e.code !== 'ENOENT') throw e;
+  });
+
+  // 3. Write _headers file for static asset cache control.
+  // Scan for unhashed files so they get per-file Cache-Control rules in the
+  // _headers file. On platforms like Cloudflare Workers Static Assets, the
+  // worker never sees static file requests — _headers is the only mechanism.
+  const unhashedPaths = await findUnhashedStaticFiles(publicDir);
+  await writeFile(join(publicDir, '_headers'), generateHeadersFile(unhashedPaths));
+
+  // 4. Copy RSC + SSR server bundles into the output directory.
+  await cp(join(buildDir, 'rsc'), join(outDir, 'rsc'), { recursive: true });
+  await cp(join(buildDir, 'ssr'), join(outDir, 'ssr'), { recursive: true }).catch(
+    (e: NodeJS.ErrnoException) => {
+      // SSR dir may not exist for static-only builds
+      if (e.code !== 'ENOENT') throw e;
+    }
+  );
+
+  // 4b. Copy prebuilt/ flight payloads if present (cache.component artifacts).
+  // These are produced by the post-build capture pass (design/44) and read
+  // at request time via the adapter's PrebuiltPayloadSource.
+  await cp(join(buildDir, 'prebuilt'), join(outDir, 'prebuilt'), { recursive: true }).catch(
+    (e: NodeJS.ErrnoException) => {
+      // No prebuilt dir when the app has no cache.component calls
+      if (e.code !== 'ENOENT') throw e;
+    }
+  );
+
+  // 5. Write manifest-init module if present.
+  if (config.manifestInit) {
+    await writeFile(join(outDir, '_timber-manifest-init.js'), config.manifestInit);
+  }
+
+  return publicDir;
+}
+
+/**
+ * Find unhashed static files in the public directory that need per-file
+ * Cache-Control rules in the `_headers` file.
+ *
+ * Excludes:
+ * - Files under `assets/` and `_timber/` (covered by wildcard rules)
+ * - Underscore-prefixed files (`_headers`, `_worker.js`, etc.)
+ *
+ * @internal Exported for testing.
+ */
+// Well-known metadata files that should be prioritized when capping
+// _headers rules, so they're never dropped in favor of less important files.
+const PRIORITY_FILES = new Set([
+  '/favicon.ico',
+  '/robots.txt',
+  '/sitemap.xml',
+  '/manifest.json',
+  '/manifest.webmanifest',
+  '/apple-touch-icon.png',
+]);
+
+export async function findUnhashedStaticFiles(publicDir: string): Promise<string[]> {
+  let files: string[];
+  try {
+    files = await collectFiles(publicDir);
+  } catch {
+    return [];
+  }
+
+  const priority: string[] = [];
+  const rest: string[] = [];
+  for (const file of files) {
+    const rel = relative(publicDir, file).replace(/\\/g, '/');
+    if (rel.startsWith('assets/') || rel.startsWith('_timber/')) continue;
+    if (basename(rel).startsWith('_')) continue;
+    const urlPath = '/' + rel;
+    if (PRIORITY_FILES.has(urlPath)) {
+      priority.push(urlPath);
+    } else {
+      rest.push(urlPath);
+    }
+  }
+
+  return [...priority.sort(), ...rest.sort()];
+}
+
+/**
+ * Scan client JS files for references to .wasm filenames.
+ * Returns the set of WASM basenames that are actually imported/referenced
+ * by client code and must be preserved in the static output.
+ */
+async function findReferencedWasm(clientDir: string): Promise<Set<string>> {
+  const referenced = new Set<string>();
+
+  let files: string[];
+  try {
+    files = await collectFiles(clientDir);
+  } catch {
+    return referenced;
+  }
+
+  const jsFiles = files.filter((f) => f.endsWith('.js'));
+  const wasmFiles = files.filter((f) => f.endsWith('.wasm')).map((f) => basename(f));
+  if (wasmFiles.length === 0) return referenced;
+
+  for (const jsFile of jsFiles) {
+    const content = await readFile(jsFile, 'utf-8');
+    for (const wasmName of wasmFiles) {
+      if (content.includes(wasmName)) {
+        referenced.add(wasmName);
+      }
+    }
+  }
+
+  return referenced;
+}
+
+async function collectFiles(dir: string): Promise<string[]> {
+  const result: string[] = [];
+  const entries = await readdir(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    const fullPath = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      result.push(...(await collectFiles(fullPath)));
+    } else {
+      result.push(fullPath);
+    }
+  }
+  return result;
+}