@txco/nitro-preset 0.1.0

package/README.md

@@ -0,0 +1,208 @@
+# @txco/nitro-preset
+
+The `thanks-computer` [Nitro](https://nitro.build) preset. It builds a
+Nitro app ([Nuxt](https://nuxt.com), [Analog](https://analogjs.org),
+[SolidStart](https://start.solidjs.com)) as a
+**Web ABI build** for [Thanks, Computer](https://www.thanks.computer) (txco):
+
+- your site as `public/`;
+- the ops it needs as `ops/`;
+- its server as `server/` (`nuxt build` only);
+- a `txco-web.json` manifest.
+
+`txco apply` installs the build into a stack.
+
+```sh
+npm install -D @txco/nitro-preset
+```
+
+It works with Nitro 2 (`nitropack`), which is what Nuxt 4, Analog 2 and
+SolidStart 1 run on.
+
+## Nuxt
+
+```ts
+// nuxt.config.ts
+export default defineNuxtConfig({
+  nitro: { preset: "@txco/nitro-preset" },
+});
+```
+
+Bind the build to a stack in your workspace's `txco.yaml`. The path is
+relative to the workspace root, and must lie outside `OPS/`:
+
+```yaml
+stacks:
+  web:
+    abi: txco-web
+```
+
+Then build, check and deploy:
+
+```sh
+nuxt generate                  # writes txco-web/
+txco web check txco-web        # installs it on a scratch chassis and probes it
+txco apply                     # or: txco push web
+```
+
+Gitignore `txco-web/`. It's all build output, and the 404 op embeds the page,
+asset hashes included, so it changes on every build.
+
+## Analog
+
+Analog sets Nitro's output paths itself, so set all three:
+
+```ts
+// vite.config.ts
+import { resolve } from "node:path";
+
+const out = resolve(__dirname, "txco-web");
+
+export default defineConfig({
+  plugins: [
+    analog({
+      static: true,
+      prerender: { routes: ["/", "/about"] },
+      nitro: {
+        preset: "@txco/nitro-preset",
+        output: { dir: out, publicDir: `${out}/public`, serverDir: `${out}/server` },
+        thanksComputer: { immutable: ["assets/"] },
+      },
+    }),
+  ],
+});
+```
+
+Analog doesn't mark its hashed assets for caching, so name the directory with
+`immutable` (above) to get the year-long cache.
+
+## SolidStart
+
+**SolidStart 1** builds through vinxi on Nitro 2, so the preset goes in
+`app.config.ts`:
+
+```ts
+// app.config.ts
+import { defineConfig } from "@solidjs/start/config";
+
+export default defineConfig({
+  server: {
+    preset: "@txco/nitro-preset",
+    static: true,
+    prerender: { crawlLinks: true },
+    // @ts-expect-error: the preset's own option, not in vinxi's types
+    thanksComputer: { immutable: ["_build/assets/"] },
+  },
+});
+```
+
+**SolidStart 2** runs on Nitro 3, which doesn't load this preset. Until a
+built-in Nitro 3 preset exists, SolidStart's Nitro 2 bridge
+(`@solidjs/vite-plugin-nitro-2`, deprecated upstream) takes the same
+options:
+
+```ts
+// vite.config.ts
+import { solidStart } from "@solidjs/start/config";
+import { nitroV2Plugin } from "@solidjs/vite-plugin-nitro-2";
+
+export default defineConfig({
+  plugins: [
+    solidStart(),
+    nitroV2Plugin({
+      preset: "@txco/nitro-preset",
+      static: true,
+      prerender: { routes: ["/"], crawlLinks: true },
+      // @ts-expect-error: the preset's own option
+      thanksComputer: { immutable: ["_build/assets/"] },
+    }),
+  ],
+});
+```
+
+SolidStart doesn't mark `_build/assets/` for caching, so `immutable` names it.
+For `ssr: false`, add `thanksComputer: { spa: true }`; SolidStart's SPA build
+isn't detected on its own.
+
+## What it writes
+
+```
+txco-web/
+  txco-web.json              { "abi": 1, "immutable": ["_nuxt/"], … }
+  public/                    Nitro's public output, prerendered pages included
+  ops/900000/page-404.txcl   404 + 404.html, for a navigation to a page that doesn't exist
+  ops/900900/not-found.txcl  a plain 404 for everything else (an asset miss, a POST)
+  server/index.mjs           nuxt build only: the app as a Fetch handler
+```
+
+How a navigation that no page answers is handled depends on the build:
+
+- **A prerendered site** (`nuxt generate`) gets `404.html` with status 404.
+  Nuxt's `404.html` is its app shell, so a client route that wasn't
+  prerendered still renders. For a server-rendered error page instead, set
+  `experimental: { prerenderErrorPages: true }` in `nuxt.config`.
+- **An `ssr: false` app** gets the shell (`200.html`) with status 200, since
+  the client router renders every page. It's detected for Nuxt and Analog; set
+  `thanksComputer: { spa: true }` (or `false`) to force it.
+- **A server build** (`nuxt build`) gets the 404 op too, for a static-only
+  install.
+
+`compressPublicAssets`' `.gz`/`.br` copies, and a bundler's `.vite/`
+metadata, are left out of `public/`: nothing serves them, and the edge
+compresses.
+
+`_` paths (`_nuxt/`, `_payload.json`) are served: the installer marks every
+`_` path in `public/` as public.
+
+## The server
+
+`nuxt build` adds `server/index.mjs`. It exports
+`{ fetch(request, ctx) }`, and the client's IP from `ctx.client.ip` reaches
+the app through h3's `getRequestIP`. Every dependency is bundled in, so the
+server needs no install step. A native addon (`sharp`, say) can't be bundled.
+
+No chassis runs `server/` yet. `txco apply` and `txco web check` refuse a
+build with a server unless you pass `--static-only`, which deploys
+`public/` and `ops/` and leaves the server out:
+
+```sh
+nuxt build
+npx -p @txco/web-abi txco-web-abi check-server txco-web   # the server half
+txco web check txco-web --static-only    # the static half
+txco apply --static-only
+```
+
+## Options
+
+Set them as `nitro: { thanksComputer: { … } }` (Nuxt), or as `thanksComputer`
+in a Nitro config.
+
+| Option      | Default        | Meaning |
+| ----------- | -------------- | ------- |
+| `spa`       | detected       | Answer every unknown page path with the shell and 200. |
+| `immutable` | derived        | The `public/` prefixes cached for a year (`["assets/"]`). For Nuxt it's derived as `_nuxt/`. |
+| `scope`     | `900000`       | The navigation op's scope. The catch-all goes 900 above it. |
+
+For the types in `nuxt.config.ts`, add `import type {} from "@txco/nitro-preset"`.
+
+## Safety
+
+Nitro empties its output directory on every build. Before that happens, the
+preset refuses an output directory that:
+
+- is inside `OPS/`;
+- holds anything that isn't part of a Web ABI build;
+- holds your sources.
+
+A refused build leaves the directory untouched.
+
+## Limits
+
+- **Nitro 2 only.** Nitro 3 doesn't load external presets; a built-in
+  `thanks-computer` preset there is the plan.
+- **Dot paths** (`.well-known/…`) in `public/` never deploy; the preset warns.
+- **A non-root `app.baseURL`** is untested.
+
+## License
+
+MIT

package/dist/finalize.d.ts

@@ -0,0 +1,59 @@
+import { type AssetDir } from "./immutable.js";
+import { type Mode } from "./ops.js";
+import type { ThanksComputerOptions } from "./types.js";
+export declare const NAME = "@txco/nitro-preset";
+export declare const VERSION = "0.1.0";
+export declare const PRESET = "thanks-computer";
+export declare const MANIFEST = "txco-web.json";
+/** The producer band (chassis/webabi ProducerScope). */
+export declare const PRODUCER_SCOPE = 900000;
+/** The part of a Nitro instance finalize reads. A `Nitro` from nitropack 2 is one. */
+export interface FinalizeNitro {
+    options: {
+        static: boolean;
+        baseURL: string;
+        output: {
+            dir: string;
+            publicDir: string;
+            serverDir: string;
+        };
+        publicAssets: readonly AssetDir[];
+        routeRules: Record<string, {
+            ssr?: boolean;
+        } | undefined>;
+        renderer?: string;
+        framework: {
+            name?: string;
+            version?: string;
+        };
+        compressPublicAssets?: unknown;
+        rollupConfig?: {
+            output?: unknown;
+        };
+        thanksComputer?: ThanksComputerOptions;
+    };
+    _prerenderedRoutes?: readonly {
+        route: string;
+    }[];
+    logger: {
+        info(...args: unknown[]): void;
+        warn(...args: unknown[]): void;
+        success(...args: unknown[]): void;
+    };
+}
+export interface FinalizeResult {
+    mode: Mode;
+    manifest: Record<string, unknown>;
+    ops: string[];
+    warnings: string[];
+}
+/** Whether the app routes in the browser: the option, or what Nuxt and Analog tell us. */
+export declare function isSpa(nitro: FinalizeNitro): boolean;
+/**
+ * Writes the build's ops and manifest into Nitro's output dir and removes
+ * what isn't part of a Web ABI build. `server` says whether Nitro built
+ * server/.
+ */
+export declare function finalize(nitro: FinalizeNitro, { server }: {
+    server: boolean;
+}): Promise<FinalizeResult>;

package/dist/finalize.js

@@ -0,0 +1,145 @@
+// Turns Nitro's output dir into a Web ABI build: the ops, the manifest, and
+// the cleanup. It runs once, after Nitro has written public/ (and server/).
+import { readFile, rm, stat } from "node:fs/promises";
+import { join, relative, sep } from "node:path";
+import { listFiles, writeManifest, writeOps } from "@txco/web-abi/producer";
+import { checkImmutable, deriveImmutable, looksHashed } from "./immutable.js";
+import { renderOps } from "./ops.js";
+export const NAME = "@txco/nitro-preset";
+export const VERSION = "0.1.0";
+export const PRESET = "thanks-computer";
+export const MANIFEST = "txco-web.json";
+/** The producer band (chassis/webabi ProducerScope). */
+export const PRODUCER_SCOPE = 900000;
+/** An op answer is capped at 4 MiB (--op-payload-max), base64 included. */
+const PAGE_WARN_BYTES = 1 << 20;
+const exists = (p) => stat(p).then(() => true, () => false);
+const posix = (p) => p.split(sep).join("/");
+/** Whether the app routes in the browser: the option, or what Nuxt and Analog tell us. */
+export function isSpa(nitro) {
+    const forced = nitro.options.thanksComputer?.spa;
+    if (typeof forced === "boolean")
+        return forced;
+    // Nuxt prerenders /index.html as the shell only for an ssr: false app;
+    // with component islands it turns that into a routeRule instead.
+    if (nitro._prerenderedRoutes?.some((r) => r.route === "/index.html"))
+        return true;
+    if (nitro.options.routeRules?.["/**"]?.ssr === false)
+        return true;
+    // Analog's ssr: false renderer.
+    return typeof nitro.options.renderer === "string" && /CLIENT_RENDERER/.test(nitro.options.renderer);
+}
+/**
+ * Writes the build's ops and manifest into Nitro's output dir and removes
+ * what isn't part of a Web ABI build. `server` says whether Nitro built
+ * server/.
+ */
+export async function finalize(nitro, { server }) {
+    const o = nitro.options;
+    const { dir, publicDir, serverDir } = o.output;
+    const opts = o.thanksComputer ?? {};
+    const warnings = [];
+    const warn = (msg) => {
+        warnings.push(msg);
+        nitro.logger.warn(`[${PRESET}] ${msg}`);
+    };
+    // Nitro's build info: read for the manifest, then dropped (it isn't part
+    // of a Web ABI build, and Nuxt 4's CLI keeps its own).
+    let nitroVersion;
+    try {
+        nitroVersion = JSON.parse(await readFile(join(dir, "nitro.json"), "utf8"))?.versions?.nitro;
+    }
+    catch { }
+    await rm(join(dir, "nitro.json"), { force: true });
+    let entry;
+    if (server) {
+        const out = o.rollupConfig?.output;
+        const name = typeof out?.entryFileNames === "string" ? out.entryFileNames : "index.mjs";
+        const file = join(serverDir, name);
+        if (!(await exists(file)))
+            throw new Error(`[${PRESET}] the server build has no entry at ${file}`);
+        entry = posix(relative(dir, file));
+    }
+    else if (await exists(serverDir)) {
+        // No server was built, so server/ holds only build-time leftovers: a
+        // framework can prepare it and then skip the server build, and one that
+        // passes its own output paths into the config (Analog) has the
+        // prerenderer bundle into it.
+        await rm(serverDir, { recursive: true, force: true });
+    }
+    const mode = server ? "server" : isSpa(nitro) ? "spa" : "static";
+    const readPage = async (name) => {
+        const html = await readFile(join(publicDir, name), "utf8").catch(() => null);
+        return html === null ? null : { name, html };
+    };
+    const page = mode === "spa" ? ((await readPage("200.html")) ?? (await readPage("index.html"))) : await readPage("404.html");
+    if (mode === "spa" && page === null) {
+        throw new Error(`[${PRESET}] an ssr: false build needs its shell, ${join(publicDir, "200.html")} or index.html, and has neither`);
+    }
+    if (page && Buffer.byteLength(page.html) > PAGE_WARN_BYTES) {
+        warn(`${page.name} is ${Buffer.byteLength(page.html)} bytes; the op that serves it is capped at 4 MiB, base64 included`);
+    }
+    const ops = renderOps({ scope: opts.scope ?? PRODUCER_SCOPE, mode, page, producer: NAME });
+    await writeOps(dir, ops);
+    // public/ as installed: paths relative to it (they include the app's baseURL).
+    const publicRoot = join(dir, "public");
+    let files = (await exists(publicRoot)) ? await listFiles(publicRoot) : [];
+    // What never deploys, taken out rather than shipped: a bundler's .vite/
+    // metadata (vinxi leaves one under _build/), and the .gz/.br copies
+    // compressPublicAssets writes beside a file (nothing serves them; the edge
+    // compresses).
+    const have = new Set(files);
+    const drop = files.filter((f) => f.split("/").includes(".vite") ||
+        (Boolean(o.compressPublicAssets) && /\.(gz|br)$/.test(f) && have.has(f.replace(/\.(gz|br)$/, ""))));
+    for (const f of drop)
+        await rm(join(publicRoot, f), { force: true });
+    for (const d of new Set(files.filter((f) => f.split("/").includes(".vite")).map((f) => f.slice(0, f.indexOf(".vite/") + 5)))) {
+        await rm(join(publicRoot, d), { recursive: true, force: true });
+    }
+    const compressed = drop.filter((f) => /\.(gz|br)$/.test(f)).length;
+    if (compressed > 0)
+        nitro.logger.info(`[${PRESET}] left out ${compressed} precompressed .gz/.br copies (the edge compresses)`);
+    files = files.filter((f) => !drop.includes(f));
+    let immutable;
+    if (opts.immutable) {
+        const problems = checkImmutable(opts.immutable);
+        if (problems.length > 0)
+            throw new Error(`[${PRESET}] thanksComputer.immutable: ${problems.join("; ")}`);
+        immutable = [...opts.immutable];
+    }
+    else {
+        immutable = deriveImmutable({ assets: o.publicAssets, appBaseURL: o.baseURL, framework: o.framework.name ?? "" });
+    }
+    for (const prefix of immutable) {
+        const under = files.filter((f) => f.startsWith(prefix));
+        if (under.length === 0) {
+            warn(`the immutable prefix ${prefix} matches no file in public/`);
+            continue;
+        }
+        // Nuxt's builds/latest.json is fetched with a cache-busting query.
+        const unhashed = under.filter((f) => !looksHashed(f.split("/").pop()) && !/\/builds\/latest\.json$/.test(f));
+        if (unhashed.length > 0) {
+            warn(`${unhashed.length} file(s) under the immutable prefix ${prefix} carry no content hash (${unhashed.slice(0, 3).join(", ")}), so a change to them wouldn't reach a browser for a year`);
+        }
+    }
+    const dots = files.filter((f) => f.split("/").some((s) => s.startsWith(".")));
+    if (dots.length > 0)
+        warn(`public/ has ${dots.length} dot path(s) (${dots.slice(0, 3).join(", ")}); they never deploy`);
+    const manifest = {
+        abi: 1,
+        ...(entry ? { server: { entry } } : {}),
+        ...(immutable.length > 0 ? { immutable } : {}),
+        "x-producer": { name: NAME, version: VERSION },
+        "x-nitro": {
+            ...(nitroVersion ? { nitro: nitroVersion } : {}),
+            preset: PRESET,
+            framework: { name: o.framework.name || "nitro", ...(o.framework.version ? { version: o.framework.version } : {}) },
+            mode,
+        },
+    };
+    await writeManifest(dir, manifest);
+    nitro.logger.success(`[${PRESET}] Web ABI build (${mode}) at ${dir}: ${files.length} public file(s), ${Object.keys(ops).length} op(s)${entry ? `, server entry ${entry}` : ""}`);
+    nitro.logger.info(`[${PRESET}] Next: \`txco web check ${relative(process.cwd(), dir) || "."}${entry ? " --static-only" : ""}\`, bind it in txco.yaml (stacks: <name>: abi: <dir>), then \`txco apply\`.` +
+        (entry ? " No chassis runs server/ yet: deploy the static half with --static-only." : ""));
+    return { mode, manifest, ops: Object.keys(ops).sort(), warnings };
+}

package/dist/guard.d.ts

@@ -0,0 +1,16 @@
+export interface OutDirInput {
+    /** `nitro.options.output.dir`. */
+    dir: string;
+    /** `nitro.options.output.publicDir`. */
+    publicDir: string;
+    /** `nitro.options.output.serverDir`. */
+    serverDir: string;
+    /** The app's baseURL ("/" for most apps). */
+    baseURL: string;
+    /** Dirs the wipe must not touch: rootDir, srcDir, buildDir, the public asset sources. */
+    protect: readonly string[];
+    /** The dir's current entries, or null when it doesn't exist. */
+    entries: readonly string[] | null;
+}
+/** Every reason the build mustn't write (and so wipe) the output dir. Empty when it may. */
+export declare function checkOutDir(i: OutDirInput): string[];

package/dist/guard.js

@@ -0,0 +1,19 @@
+// The check that runs before Nitro wipes the output dir. Pure (paths in,
+// problems out), so it's unit-tested; the module reads the dir's entries.
+// The generic checks are the kit's; the layout check is Nitro's.
+import { join, resolve } from "node:path";
+import { checkOutDir as checkABIOutDir } from "@txco/web-abi/producer";
+/** Every reason the build mustn't write (and so wipe) the output dir. Empty when it may. */
+export function checkOutDir(i) {
+    const dir = resolve(i.dir);
+    const problems = [];
+    const base = i.baseURL.replace(/^\/+|\/+$/g, "");
+    const wantPublic = resolve(join(dir, "public", base));
+    const wantServer = resolve(join(dir, "server"));
+    if (resolve(i.publicDir) !== wantPublic || resolve(i.serverDir) !== wantServer) {
+        problems.push(`the output dirs don't follow the Web ABI layout: publicDir is ${resolve(i.publicDir)} (want ${wantPublic}) and serverDir is ${resolve(i.serverDir)} (want ${wantServer}). ` +
+            `If your framework sets its own output paths (Analog does), set nitro.output.dir and nitro.output.publicDir together, or leave all three to the preset.`);
+    }
+    // Nitro's build info is a previous build's own file.
+    return [...checkABIOutDir({ dir, protect: i.protect, entries: i.entries, allow: ["nitro.json"] }), ...problems];
+}

package/dist/immutable.d.ts

@@ -0,0 +1,30 @@
+/** One of Nitro's public asset dirs, as `nitro.options.publicAssets` holds it. */
+export interface AssetDir {
+    baseURL?: string;
+    maxAge?: number;
+}
+export interface ImmutableInput {
+    assets: readonly AssetDir[];
+    /** The app's baseURL ("/" for most apps). */
+    appBaseURL: string;
+    /** `nitro.options.framework.name` ("nuxt", "analog", "nitro", …). */
+    framework: string;
+}
+/** A year: what a framework sets on its content-hashed asset dir. */
+export declare const YEAR = 31536000;
+/**
+ * The prefixes (relative to public/, ending in "/") whose files the
+ * framework already caches for a year: its content-hashed asset dir, like
+ * Nuxt's `_nuxt/`.
+ *
+ * A candidate is a non-root asset dir with a year's maxAge. It is dropped
+ * when a dir with a shorter maxAge shares or sits inside it, since those files
+ * change between builds. The exception is Nuxt's `<buildAssetsDir>/builds`:
+ * Nuxt fetches its `latest.json` with a cache-busting query. Nested
+ * candidates collapse into the outer one.
+ */
+export declare function deriveImmutable(input: ImmutableInput): string[];
+/** What's wrong with an explicit `immutable` list, if anything. */
+export declare function checkImmutable(prefixes: readonly string[]): string[];
+/** Whether a file name carries a content hash (the kit's heuristic, shared by every producer). */
+export { looksHashed } from "@txco/web-abi/producer";

package/dist/immutable.js

@@ -0,0 +1,50 @@
+// Which public/ prefixes the manifest may call immutable (cached for a year).
+// Pure, so it's unit-tested.
+/** A year: what a framework sets on its content-hashed asset dir. */
+export const YEAR = 31536000;
+const trim = (u) => u.replace(/^\/+|\/+$/g, "");
+const norm = (u) => "/" + trim(u ?? "/");
+const inside = (inner, outer) => outer === "/" || inner === outer || inner.startsWith(outer + "/");
+/**
+ * The prefixes (relative to public/, ending in "/") whose files the
+ * framework already caches for a year: its content-hashed asset dir, like
+ * Nuxt's `_nuxt/`.
+ *
+ * A candidate is a non-root asset dir with a year's maxAge. It is dropped
+ * when a dir with a shorter maxAge shares or sits inside it, since those files
+ * change between builds. The exception is Nuxt's `<buildAssetsDir>/builds`:
+ * Nuxt fetches its `latest.json` with a cache-busting query. Nested
+ * candidates collapse into the outer one.
+ */
+export function deriveImmutable(input) {
+    const dirs = input.assets.map((a) => ({ base: norm(a.baseURL), maxAge: a.maxAge ?? 0 }));
+    const kept = dirs
+        .filter((c) => c.maxAge >= YEAR && c.base !== "/")
+        .filter((c) => !dirs.some((o) => o.maxAge < YEAR &&
+        o.base !== "/" &&
+        inside(o.base, c.base) &&
+        !(input.framework === "nuxt" && o.base === c.base + "/builds")))
+        .map((c) => c.base);
+    const outer = [...new Set(kept)].filter((b) => !kept.some((o) => o !== b && inside(b, o)));
+    const app = trim(input.appBaseURL);
+    return outer.map((b) => (app ? `${app}/` : "") + `${trim(b)}/`).sort();
+}
+/** What's wrong with an explicit `immutable` list, if anything. */
+export function checkImmutable(prefixes) {
+    const problems = [];
+    for (const p of prefixes) {
+        const segs = p.split("/").slice(0, -1);
+        if (!p.endsWith("/") || p.startsWith("/") || segs.length === 0) {
+            problems.push(`"${p}": an immutable prefix is a directory relative to public/, ending in "/" (e.g. "assets/")`);
+        }
+        else if (segs.some((s) => s === "" || s.startsWith("."))) {
+            problems.push(`"${p}": no empty or dot segments`);
+        }
+        else if (segs[0] === "_txco") {
+            problems.push(`"${p}": _txco/ is reserved for the installer`);
+        }
+    }
+    return problems;
+}
+/** Whether a file name carries a content hash (the kit's heuristic, shared by every producer). */
+export { looksHashed } from "@txco/web-abi/producer";

package/dist/module.d.ts

@@ -0,0 +1,5 @@
+import type { Nitro } from "nitropack/types";
+export declare const thanksComputerModule: {
+    name: string;
+    setup(nitro: Nitro): Promise<void>;
+};

package/dist/module.js

@@ -0,0 +1,51 @@
+// The preset's Nitro module. Nitro runs modules inside createNitro, before
+// prepare() wipes the output dir, so this is where the guard goes; it also
+// registers the hooks that finish the build.
+import { readdir } from "node:fs/promises";
+import { finalize, PRESET } from "./finalize.js";
+import { checkOutDir } from "./guard.js";
+export const thanksComputerModule = {
+    name: PRESET,
+    async setup(nitro) {
+        const o = nitro.options;
+        const entries = await readdir(o.output.dir).catch(() => null);
+        const problems = checkOutDir({
+            dir: o.output.dir,
+            publicDir: o.output.publicDir,
+            serverDir: o.output.serverDir,
+            baseURL: o.baseURL,
+            protect: [o.rootDir, o.srcDir, o.buildDir, ...o.publicAssets.map((a) => a.dir)],
+            entries,
+        });
+        if (problems.length > 0)
+            throw new Error(`[${PRESET}] ${problems.join("\n")}`);
+        // A static build (nuxi generate) crawls from the home page, as Nitro's
+        // `static` preset does: Nuxt seeds "/" only when crawlLinks is on, and
+        // reads it in nitro:init, after this module. An explicit setting stands.
+        const asked = o._config?.prerender?.crawlLinks;
+        if (o.static && asked === undefined)
+            o.prerender.crawlLinks = true;
+        // Hooks registered here, not in the preset's `hooks`: the config merge
+        // lets a user's own `hooks.compiled` replace a preset's.
+        let finalized = false;
+        let prerendered = false;
+        const run = async (server) => {
+            finalized = true;
+            await finalize(nitro, { server });
+        };
+        nitro.hooks.hook("prerender:done", ({ failedRoutes }) => {
+            prerendered = !(o.prerender.failOnError && failedRoutes.length > 0);
+        });
+        nitro.hooks.hook("compiled", async () => {
+            if (!finalized)
+                await run(!o.static);
+        });
+        // A framework that prerenders and never calls build() (Analog's static
+        // build) never fires `compiled`; it always closes. Without a finished
+        // prerender (nuxi prepare, a failed build) there is nothing to finish.
+        nitro.hooks.hook("close", async () => {
+            if (!finalized && prerendered)
+                await run(false);
+        });
+    },
+};

package/dist/ops.d.ts

@@ -0,0 +1,31 @@
+import { BUILTIN_404, catchAllScope, NAV_GUARD, type Page } from "@txco/web-abi/producer";
+export { BUILTIN_404, catchAllScope, NAV_GUARD, type Page };
+/**
+ * How the build answers a page navigation nothing else answered:
+ *
+ *  - "static": every page was prerendered into public/, so a path that
+ *    reaches the ops has no page: 404, with the 404 page;
+ *  - "spa": an `ssr: false` app routes in the browser: 200, with the shell;
+ *  - "server": the build has a server (server/). No chassis runs one yet, so
+ *    a --static-only install answers like "static".
+ */
+export type Mode = "static" | "spa" | "server";
+export interface RenderOptions {
+    /** The producer band's scope for the navigation op (900000). */
+    scope: number;
+    mode: Mode;
+    /**
+     * The page the navigation op serves: 404.html (static, server) or the
+     * shell (spa). null in static or server mode writes a small built-in 404
+     * page instead. spa mode needs one.
+     */
+    page: Page | null;
+    /** The generated-file header's producer name. */
+    producer: string;
+}
+/**
+ * Renders the build's ops, as path (relative to ops/) → file text: one
+ * navigation op for the mode, and the catch-all, a plain 404 for every other
+ * HTTP request, so every request reaching the end of the stack is answered.
+ */
+export declare function renderOps(opts: RenderOptions): Record<string, string>;

package/dist/ops.js

@@ -0,0 +1,29 @@
+// The ops this preset writes into a Web ABI build's ops/. Pure: no filesystem
+// and no Nitro runtime, so the output is golden-tested. The rules come from
+// @txco/web-abi/producer, which every producer shares; this file maps the
+// preset's build modes onto them.
+import { BUILTIN_404, catchAllScope, NAV_GUARD, renderOps as renderABIOps } from "@txco/web-abi/producer";
+export { BUILTIN_404, catchAllScope, NAV_GUARD };
+const NOTES = {
+    spa: ["An ssr: false app: the client router renders every page."],
+    static: ["A client route that wasn't prerendered still renders: Nuxt's 404.html", "is its app shell."],
+    server: [
+        "This build has a server (server/), and no chassis runs one yet: a",
+        "--static-only install serves its prerendered pages, and every other page",
+        "navigation ends here. A dispatch op replaces this one once a runner exists.",
+    ],
+};
+/**
+ * Renders the build's ops, as path (relative to ops/) → file text: one
+ * navigation op for the mode, and the catch-all, a plain 404 for every other
+ * HTTP request, so every request reaching the end of the stack is answered.
+ */
+export function renderOps(opts) {
+    return renderABIOps({
+        scope: opts.scope,
+        producer: opts.producer,
+        mode: opts.mode === "spa" ? "spa" : "404",
+        page: opts.page,
+        notes: NOTES[opts.mode],
+    });
+}