@frockbot/cloudflare 0.0.0 → 0.7.292

package/build-artifact.ts

@@ -0,0 +1,130 @@
+/**
+ * The application artifact: `src/user-application.ts` bundled with a brand, for
+ * the Worker to load from R2.
+ *
+ *   bun build-artifact.ts [--brand <module>] [--dist <directory>]
+ *
+ * `--dist` is where `build-flutter-web.ts` staged the client and where
+ * `artifacts/foundation-v1.mjs` is written: this package's own `dist` by
+ * default, and a white-label's own directory when it builds from the published
+ * package ([ADR 0038](../../docs/adr/0038-white-label-deployments.md) §4).
+ */
+import { readFile, rm } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { decodeBrandV1 } from "@frockbot/core/contracts";
+
+const root = fileURLToPath(new URL(".", import.meta.url));
+
+/** The value after `flag`, or undefined when the flag is absent. */
+function flagValue(flag: string): string | undefined {
+  const index = process.argv.indexOf(flag);
+  if (index === -1) return undefined;
+  const value = process.argv[index + 1];
+  if (!value || value.startsWith("--"))
+    throw new Error(`${flag} names nothing`);
+  return value;
+}
+
+const dist = resolve(flagValue("--dist") ?? resolve(root, "dist"));
+const outdir = resolve(dist, "artifacts");
+await rm(outdir, { recursive: true, force: true });
+
+// The document the artifact renders names the client's payload, which is
+// content-addressed under `/_flutter/<buildHash>/`; `build-flutter-web.ts`
+// stages it and writes the hash here.
+let flutterBuild: string;
+try {
+  flutterBuild = (
+    JSON.parse(await readFile(resolve(dist, "flutter-web.json"), "utf8")) as {
+      buildHash: string;
+    }
+  ).buildHash;
+} catch (error) {
+  throw new Error("Flutter web client was not built", { cause: error });
+}
+
+// The brand this artifact is built with: `--brand <module>` names a
+// deployment's own (the profile's `brand`, resolved), and without it `#brand`
+// resolves through the package import to FrockBot's. The artifact is bundled
+// here rather than by wrangler, so the profile's alias never reaches it; the
+// plugin below is that alias for this build. The brand is validated here, where
+// a build can still refuse it: every look through the ThemeDocument decoder
+// and its contrast floor. Its icon is a path beside the brand module, which the
+// shell serves as the site icon.
+const brandFlag = flagValue("--brand");
+const brandModule =
+  brandFlag === undefined
+    ? fileURLToPath(import.meta.resolve("#brand"))
+    : resolve(brandFlag);
+const brand = decodeBrandV1(
+  ((await import(brandModule)) as { BRAND_V1?: unknown }).BRAND_V1,
+);
+const clientIcon = await readFile(
+  resolve(dirname(brandModule), brand.iconPng),
+  "base64",
+);
+
+const result = await Bun.build({
+  entrypoints: [resolve(root, "src/user-application.ts")],
+  outdir,
+  // The Worker uses nodejs_compat, and hosted runtime Contributions may import
+  // supported Node built-ins (for example the Computer host SDK's node:net shim).
+  target: "node",
+  format: "esm",
+  naming: "foundation-v1.mjs",
+  minify: true,
+  sourcemap: "external",
+  packages: "bundle",
+  plugins: [
+    {
+      name: "brand",
+      setup(build) {
+        build.onResolve({ filter: /^#brand$/ }, () => ({ path: brandModule }));
+      },
+    },
+  ],
+  define: {
+    __FROCKBOT_FLUTTER_BUILD__: JSON.stringify(flutterBuild),
+    __FROCKBOT_CLIENT_ICON__: JSON.stringify(clientIcon),
+    // The module identity this bundle reports to itself.
+    //
+    // A Worker Loader module has no file URL, so `import.meta.url` is
+    // `undefined` inside the isolate. That is fatal rather than cosmetic: the
+    // provider catalog reaches the model provider SDKs (`openai`,
+    // `@anthropic-ai/sdk`, `google-auth-library` and the CommonJS packages
+    // underneath them), and for those Bun emits
+    // `var require = createRequire(import.meta.url)` as the bundle's *first*
+    // top-level statement. `createRequire(undefined)` throws
+    // `TypeError: The argument 'path' must be a file URL object, a file URL
+    // string, or an absolute path string`, so the artifact never finishes
+    // evaluating and every request answers `Failed to start Worker`.
+    //
+    // Naming the bundle here is what a module loaded from a file would have
+    // had. The `require` it builds is only ever called from inside the lazy
+    // CommonJS wrappers of those SDKs' Node-only code paths — none of which an
+    // artifact takes — and when one is, it reaches the `nodejs_compat`
+    // built-ins exactly as any other `require` in the Worker does.
+    "import.meta.url": JSON.stringify("file:///frockbot/foundation-v1.mjs"),
+  },
+});
+
+if (result.success) {
+  const artifact = result.outputs.find((output) =>
+    output.path.endsWith(".mjs"),
+  );
+  if (!artifact) throw new Error("user application artifact was not emitted");
+  // The `import.meta.url` substitution above is load-bearing, and a bundler
+  // that stopped honouring it would leave an artifact that builds, ships, and
+  // then fails to evaluate in every isolate that loads it. That is only
+  // visible in the browser end-to-end job, hours later, as
+  // `Failed to start Worker`. Read the bytes back instead.
+  if ((await readFile(artifact.path, "utf8")).includes("import.meta.url"))
+    throw new Error(
+      "user application artifact still reads import.meta.url, which is undefined in a Worker Loader isolate",
+    );
+  process.stdout.write(`Built ${artifact.path} (${artifact.size} bytes)\n`);
+} else {
+  for (const log of result.logs) process.stderr.write(`${String(log)}\n`);
+  process.exitCode = 1;
+}

package/build-flutter-web.ts

@@ -0,0 +1,508 @@
+/**
+ * The Flutter client, built for the browser and staged where the Worker's
+ * static assets are uploaded from.
+ *
+ * `FROCKBOT_ORIGIN` is deliberately left undefined: the browser build talks to
+ * the origin it was served from, which is what a deployment, a `wrangler dev`
+ * on an arbitrary port and the e2e harness all need. CanvasKit is built local
+ * (`--no-web-resources-cdn`) so the app origin's `script-src 'self'` stays
+ * true and the engine is never fetched from gstatic. Rive Native's WebAssembly
+ * runtime is staged here for the same reason and named by
+ * `RIVE_NATIVE_WASM_HOST`; see `stageRiveWasm`. So are the engine's fallback
+ * fonts, which it otherwise fetches from gstatic; see `stageFallbackFonts`.
+ *
+ * Everything is staged under `_flutter/<buildHash>/`, so every URL the
+ * document names is content-addressed and can be served `immutable`. The
+ * document itself is rendered by the application artifact, which reads the
+ * same hash from `dist/flutter-web.json`.
+ *
+ *   bun build-flutter-web.ts [--app <directory>] [--dist <directory>]
+ *
+ * `--app` is the Flutter application to build — `apps/native` by default, and
+ * a white-label's own thin application, carrying its own client brand, when it
+ * builds from the published package ([ADR 0038](../../docs/adr/0038-white-label-deployments.md)
+ * §4). `--dist` is where the client is staged: `<dist>/web` is what the Worker
+ * uploads and `<dist>/flutter-web.json` is what `build-artifact.ts --dist`
+ * reads, this package's own `dist` by default.
+ */
+import { createHash } from "node:crypto";
+import {
+  cp,
+  mkdir,
+  readdir,
+  readFile,
+  rename,
+  rm,
+  stat,
+  writeFile,
+} from "node:fs/promises";
+import { join, relative, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { releaseVersion } from "./release-version.ts";
+
+const root = fileURLToPath(new URL(".", import.meta.url));
+
+/** The value after `flag`, or undefined when the flag is absent. */
+function flagValue(flag: string): string | undefined {
+  const index = process.argv.indexOf(flag);
+  if (index === -1) return undefined;
+  const value = process.argv[index + 1];
+  if (!value || value.startsWith("--"))
+    throw new Error(`${flag} names nothing`);
+  return value;
+}
+
+const nativeRoot = resolve(flagValue("--app") ?? resolve(root, "../native"));
+const dist = resolve(flagValue("--dist") ?? resolve(root, "dist"));
+const flutterOut = resolve(nativeRoot, "build/web");
+const assetsRoot = resolve(dist, "web");
+const clientManifest = resolve(dist, "flutter-web.json");
+const payloadPrefix = "_flutter";
+
+/**
+ * What the browser never asks for.
+ *
+ * The `.symbols` files are the engine's debug symbol maps — 7 MB of them, read
+ * by a stack-trace symbolizer nobody runs here. The rest are the pieces of
+ * Flutter's own page: this deployment renders its document from the
+ * application artifact, so the template index, the PWA manifest and its icons,
+ * and the service worker that `--pwa-strategy=none` leaves empty have no
+ * reader.
+ */
+const OMITTED = new Set([
+  ".last_build_id",
+  "version.json",
+  "index.html",
+  "manifest.json",
+  "flutter_service_worker.js",
+  "favicon.png",
+]);
+
+async function emittedFiles(directory: string): Promise<string[]> {
+  const entries = await readdir(directory, {
+    withFileTypes: true,
+    recursive: true,
+  });
+  return entries
+    .filter((entry) => entry.isFile())
+    .map((entry) =>
+      relative(flutterOut, join(entry.parentPath, entry.name)).replaceAll(
+        "\\",
+        "/",
+      ),
+    )
+    .filter(
+      (path) =>
+        !path.endsWith(".symbols") &&
+        !path.startsWith("icons/") &&
+        !OMITTED.has(path),
+    )
+    .sort();
+}
+
+const BUILD_FLAGS = [
+  "--release",
+  "--pwa-strategy=none",
+  "--no-web-resources-cdn",
+];
+
+/**
+ * Rive Native's WebAssembly runtime, served from this origin.
+ *
+ * `rive_native` otherwise fetches `wasm/rive_native.js` from jsdelivr as the
+ * app starts, which the app origin's `script-src 'self' 'wasm-unsafe-eval'`
+ * refuses. Its loader appends a `<script>` and awaits the `load` event, so a
+ * blocked script is not a failure it ever sees: `RiveNative.init()` never
+ * settles, `main()` never reaches `runApp`, and the window stays blank. That
+ * is what turned `Main` red on 2026-09-16 — every browser end-to-end test
+ * timed out waiting for a shell that was still awaiting a script the browser
+ * had already refused.
+ *
+ * The payload is staged under its own version rather than the Flutter build
+ * hash, because that hash is only known after a build which has to be told
+ * this URL first. A version is just as immutable a name.
+ */
+const RIVE_WASM_PACKAGE = "@rive-app/flutter-native-wasm";
+// Resolved rather than joined onto a `node_modules`, because the workspace
+// install is free to hoist the package to the repository root instead.
+const riveManifest = Bun.resolveSync(`${RIVE_WASM_PACKAGE}/package.json`, root);
+const rivePackageRoot = resolve(riveManifest, "..");
+
+/** The wasm version the resolved `rive_native` links against, from its source. */
+async function riveWasmVersion(): Promise<string> {
+  const packageConfig = JSON.parse(
+    await readFile(
+      resolve(nativeRoot, ".dart_tool/package_config.json"),
+      "utf8",
+    ),
+  ) as { packages?: { name?: string; rootUri?: string }[] };
+  const entry = packageConfig.packages?.find(
+    (candidate) => candidate.name === "rive_native",
+  );
+  if (!entry?.rootUri?.startsWith("file:")) {
+    throw new Error(
+      `${relative(root, resolve(nativeRoot, ".dart_tool/package_config.json"))} does not resolve rive_native ` +
+        "to a file: root.",
+    );
+  }
+  const packageRoot = fileURLToPath(entry.rootUri);
+  const source = await readFile(
+    resolve(packageRoot, "lib/src/wasm_version.dart"),
+    "utf8",
+  );
+  const version = /wasmVersion\s*=\s*'([^']+)'/u.exec(source);
+  if (!version) {
+    throw new Error("rive_native's wasm_version.dart states no wasmVersion.");
+  }
+  return version[1]!;
+}
+
+/**
+ * Copy the runtime into `dist/web`, and answer the URL prefix it is served at.
+ *
+ * The staged version has to be the one `rive_native` asks for: it names the
+ * exports the Dart side links against, so a mismatch is a blank artboard at
+ * runtime rather than an error at build time. The two are pinned in different
+ * files — `pubspec.lock` and `package.json` — so the drift is checked here
+ * rather than assumed.
+ */
+async function stageRiveWasm(expected: string): Promise<string> {
+  const installed = (
+    JSON.parse(await readFile(riveManifest, "utf8")) as { version?: string }
+  ).version;
+  if (installed !== expected) {
+    throw new Error(
+      `rive_native expects ${RIVE_WASM_PACKAGE}@${expected}, but ${installed} is installed. ` +
+        "Update that dependency in apps/cloudflare/package.json to match.",
+    );
+  }
+  const staged = resolve(assetsRoot, "rive", expected);
+  for (const directory of ["wasm", "wasm_compatibility"]) {
+    await cp(resolve(rivePackageRoot, directory), resolve(staged, directory), {
+      recursive: true,
+      force: true,
+    });
+  }
+  return `/rive/${expected}/`;
+}
+
+/**
+ * The Noto faces the engine falls back to, served from this origin.
+ *
+ * When the app's own fonts lack a glyph — "♯" in a chat message is enough —
+ * the engine fetches a Noto face that has it from `fontFallbackBaseUrl`, which
+ * defaults to fonts.gstatic.com. The app document's `connect-src 'self'`
+ * refuses that, so the glyph was never drawn. `web/flutter_bootstrap.js`
+ * points the engine at `fallback-fonts/` beside the build instead, and this
+ * stages every file the engine's own fallback table can ask for there: which
+ * one a message needs is not knowable ahead of time, and the whole table is
+ * about 22 MB. The table is read from the SDK doing the build, so a Flutter
+ * upgrade that rolls the fonts rolls these with it.
+ *
+ * Each file's gstatic path carries its version, so a download is cached
+ * outside `dist/` and fetched once per version rather than once per build.
+ */
+const FALLBACK_FONTS = "fallback-fonts";
+const FALLBACK_FONT_ORIGIN = "https://fonts.gstatic.com/s/";
+const fallbackFontCache = resolve(
+  root,
+  "node_modules/.cache/flutter-fallback-fonts",
+);
+
+async function fallbackFontPaths(): Promise<string[]> {
+  const version = JSON.parse(
+    Bun.spawnSync({
+      cmd: ["flutter", "--version", "--machine"],
+      cwd: nativeRoot,
+    }).stdout.toString(),
+  ) as { flutterRoot?: string };
+  if (!version.flutterRoot) {
+    throw new Error("`flutter --version --machine` names no flutterRoot.");
+  }
+  const table = await readFile(
+    resolve(
+      version.flutterRoot,
+      "bin/cache/flutter_web_sdk/lib/_engine/engine/font_fallback_data.dart",
+    ),
+    "utf8",
+  );
+  const paths = [
+    ...new Set(
+      [
+        ...table.matchAll(/'([a-z0-9]+\/v\d+\/[\w.-]+\.(?:woff2|ttf|otf))'/gu),
+      ].map((match) => match[1]!),
+    ),
+  ].sort();
+  // A table this build cannot read would stage nothing and quietly put every
+  // fallback glyph back to undrawn.
+  if (paths.length < 100) {
+    throw new Error(
+      `Read only ${paths.length} fallback fonts from the Flutter web SDK; ` +
+        "its font_fallback_data.dart has changed shape.",
+    );
+  }
+  return paths;
+}
+
+async function downloadFallbackFont(path: string): Promise<void> {
+  const cached = resolve(fallbackFontCache, path);
+  if (await stat(cached).catch(() => undefined)) return;
+  for (let attempt = 1; ; attempt++) {
+    try {
+      const response = await fetch(`${FALLBACK_FONT_ORIGIN}${path}`);
+      if (!response.ok) throw new Error(`HTTP ${response.status}`);
+      const body = new Uint8Array(await response.arrayBuffer());
+      await mkdir(resolve(cached, ".."), { recursive: true });
+      // Written aside and renamed, so an interrupted build never leaves a
+      // truncated font the next one would take as cached.
+      await writeFile(`${cached}.partial`, body);
+      await rename(`${cached}.partial`, cached);
+      return;
+    } catch (error) {
+      if (attempt >= 3) {
+        throw new Error(
+          `Could not fetch fallback font ${path}: ${String(error)}`,
+        );
+      }
+    }
+  }
+}
+
+/** Copy the fallback fonts into the payload, and answer their staged paths. */
+async function stageFallbackFonts(payload: string): Promise<string[]> {
+  const paths = await fallbackFontPaths();
+  const queue = [...paths];
+  await Promise.all(
+    Array.from({ length: 16 }, async () => {
+      for (let path = queue.pop(); path; path = queue.pop()) {
+        await downloadFallbackFont(path);
+      }
+    }),
+  );
+  for (const path of paths) {
+    await cp(
+      resolve(fallbackFontCache, path),
+      resolve(payload, FALLBACK_FONTS, path),
+      { force: true, recursive: true },
+    );
+  }
+  return paths.map((path) => `${FALLBACK_FONTS}/${path}`);
+}
+
+/**
+ * The Dart sources, the assets, and the page template the build reads: the
+ * application's and those of the client package it depends on.
+ *
+ * `build/` and `.dart_tool/` are the build's own outputs, and the platform
+ * directories belong to the phone builds; nothing under them reaches the web
+ * bundle.
+ */
+const SOURCE_ROOTS = [
+  "lib",
+  "web",
+  "assets",
+  "vendor",
+  "packages/frockbot_client/lib",
+  "packages/frockbot_client/assets",
+];
+const SOURCE_FILES = [
+  "pubspec.yaml",
+  "pubspec.lock",
+  "packages/frockbot_client/pubspec.yaml",
+];
+
+async function sourceFingerprint(defines: string[]): Promise<string> {
+  const digest = createHash("sha256");
+  // The flags and this script are part of what the output is: a change to
+  // either produces a different bundle from the same Dart. So are the
+  // defines, such as the Rive runtime's URL, which a version bump moves and
+  // the bundle has baked in.
+  digest.update(BUILD_FLAGS.join(" "));
+  digest.update(defines.join(" "));
+  digest.update(await readFile(fileURLToPath(import.meta.url)));
+  // The toolchain too — a Flutter upgrade rewrites the engine even though no
+  // file in this repository moved.
+  const version = Bun.spawnSync({
+    cmd: ["flutter", "--version", "--machine"],
+    cwd: nativeRoot,
+  });
+  digest.update(version.stdout);
+
+  const paths: string[] = [];
+  for (const directory of SOURCE_ROOTS) {
+    const absolute = resolve(nativeRoot, directory);
+    const there = await stat(absolute).catch(() => undefined);
+    if (!there?.isDirectory()) continue;
+    for (const entry of await readdir(absolute, {
+      withFileTypes: true,
+      recursive: true,
+    })) {
+      if (!entry.isFile()) continue;
+      paths.push(join(entry.parentPath, entry.name));
+    }
+  }
+  for (const file of SOURCE_FILES) paths.push(resolve(nativeRoot, file));
+  paths.sort();
+  for (const path of paths) {
+    digest.update(relative(nativeRoot, path).replaceAll("\\", "/"));
+    digest.update(await readFile(path).catch(() => Buffer.alloc(0)));
+  }
+  return digest.digest("hex");
+}
+
+/**
+ * Whether the staged bundle was built from exactly these sources.
+ *
+ * `flutter build web --release` is not incremental — dart2js runs whole, for
+ * about a minute, whether or not a line changed — and the browser end-to-end
+ * harness builds the client before every run. Fingerprinting the inputs turns
+ * the second run of an unchanged tree into a no-op. `FROCKBOT_FORCE_CLIENT_BUILD`
+ * builds anyway.
+ */
+async function stagedIsCurrent(fingerprint: string): Promise<boolean> {
+  if (process.env.FROCKBOT_FORCE_CLIENT_BUILD) return false;
+  const manifest = await readFile(clientManifest, "utf8").catch(
+    () => undefined,
+  );
+  if (!manifest) return false;
+  let parsed: { sourceHash?: unknown; buildHash?: unknown; files?: unknown };
+  try {
+    parsed = JSON.parse(manifest) as typeof parsed;
+  } catch {
+    return false;
+  }
+  if (parsed.sourceHash !== fingerprint) return false;
+  if (typeof parsed.buildHash !== "string" || !Array.isArray(parsed.files)) {
+    return false;
+  }
+  // The manifest is only a promise about `dist/web`; a half-deleted staging
+  // directory has to rebuild rather than serve a document naming files that
+  // are not there.
+  const staged = resolve(assetsRoot, payloadPrefix, parsed.buildHash);
+  for (const path of parsed.files as string[]) {
+    if (!(await stat(resolve(staged, path)).catch(() => undefined))) {
+      return false;
+    }
+  }
+  return true;
+}
+
+/**
+ * Run a `flutter` subcommand, and fail the build if it did.
+ *
+ * A failed command leaves whatever the last successful one wrote in place —
+ * a stale `package_config.json`, a stale `build/web` — so an unread exit code
+ * is how a build that never happened gets staged and announced as one.
+ */
+function flutter(...args: string[]): void {
+  const run = Bun.spawnSync({
+    cmd: ["flutter", ...args],
+    cwd: nativeRoot,
+    stdout: "inherit",
+    stderr: "inherit",
+  });
+  if (run.exitCode !== 0) {
+    throw new Error(`\`flutter ${args.join(" ")}\` exited ${run.exitCode}.`);
+  }
+}
+
+// `flutter build` resolves the pub dependencies itself, but the wasm version
+// has to be read out of the resolved `rive_native` before the build, because
+// the build is what carries the URL it produces.
+flutter("pub", "get");
+const riveVersion = await riveWasmVersion();
+// The tag `release.yml` builds is the app's version; any other build has none.
+const release = releaseVersion(process.env.FROCKBOT_RELEASE)?.release;
+const defines = [
+  ...(release ? [`--dart-define=FROCKBOT_RELEASE=${release}`] : []),
+  `--dart-define=RIVE_NATIVE_WASM_HOST=/rive/${riveVersion}/`,
+];
+
+const fingerprint = await sourceFingerprint(defines);
+if (await stagedIsCurrent(fingerprint)) {
+  // The staging directory is rewritten whole by a build, so the runtime is
+  // copied on the skipping path too rather than only alongside one.
+  await stageRiveWasm(riveVersion);
+  process.stdout.write(
+    "The Flutter web client is already built from these sources; skipping.\n",
+  );
+  process.exit(0);
+}
+
+flutter("build", "web", ...BUILD_FLAGS, ...defines);
+
+const files = await emittedFiles(flutterOut);
+if (
+  !files.includes("flutter_bootstrap.js") ||
+  !files.includes("main.dart.js")
+) {
+  throw new Error("Flutter web build did not emit an entry point");
+}
+
+// The define actually reached the compiler. A dart-define that stops being
+// read — a renamed key, a flag dropped from the command — leaves the jsdelivr
+// default compiled in, and the only symptom is a blank window in a browser
+// whose policy refuses it. Better to fail here than to ship that.
+const entry = await readFile(resolve(flutterOut, "main.dart.js"), "utf8");
+if (entry.includes("cdn.jsdelivr.net")) {
+  throw new Error(
+    "The web bundle still names cdn.jsdelivr.net, which the app origin's " +
+      "`script-src 'self'` refuses. RIVE_NATIVE_WASM_HOST did not take.",
+  );
+}
+// Same for the fallback fonts: a bootstrap that stopped naming them leaves
+// the engine on its gstatic default, which `connect-src 'self'` refuses.
+const bootstrap = await readFile(
+  resolve(flutterOut, "flutter_bootstrap.js"),
+  "utf8",
+);
+if (!bootstrap.includes("fontFallbackBaseUrl")) {
+  throw new Error(
+    "The built flutter_bootstrap.js sets no fontFallbackBaseUrl, so the " +
+      "engine would fetch fallback fonts from gstatic. Did " +
+      "apps/native/web/flutter_bootstrap.js stop being the template?",
+  );
+}
+
+const digest = createHash("sha256");
+for (const path of files) {
+  digest.update(path);
+  digest.update(
+    createHash("sha256")
+      .update(await readFile(resolve(flutterOut, path)))
+      .digest(),
+  );
+}
+const buildHash = digest.digest("hex").slice(0, 32);
+
+await rm(assetsRoot, { recursive: true, force: true });
+const payload = resolve(assetsRoot, payloadPrefix, buildHash);
+await mkdir(payload, { recursive: true });
+for (const path of files) {
+  await cp(resolve(flutterOut, path), resolve(payload, path), {
+    force: true,
+    // `recursive` creates the intermediate directories a nested asset needs.
+    recursive: true,
+  });
+}
+
+const fallbackFonts = await stageFallbackFonts(payload);
+const riveHost = await stageRiveWasm(riveVersion);
+
+// Every URL under either prefix carries a version — the build hash, or Rive's
+// own — so a browser may keep it for a year: a new build is a new path, not a
+// new body at the same one.
+await writeFile(
+  resolve(assetsRoot, "_headers"),
+  `/${payloadPrefix}/*\n  cache-control: public, max-age=31536000, immutable\n` +
+    `${riveHost}*\n  cache-control: public, max-age=31536000, immutable\n`,
+);
+await writeFile(
+  clientManifest,
+  `${JSON.stringify({ schemaVersion: 1, buildHash, sourceHash: fingerprint, files: [...files, ...fallbackFonts] }, null, 2)}\n`,
+);
+
+process.stdout.write(
+  `Built the Flutter web client at /${payloadPrefix}/${buildHash}/ (${files.length} files, ${fallbackFonts.length} fallback fonts)\n` +
+    `Staged Rive Native's wasm runtime at ${riveHost}\n`,
+);