@nifrajs/web 0.1.0-alpha.1

package/dist/dev-error.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Dev-only error overlay. When a loader/action/render throws during `@nifrajs/web/vite` dev, this
+ * renders a readable full-page overlay — the message, the source-mapped stack (Vite's
+ * `ssrFixStacktrace` runs first), and the request line — instead of the bare `err.stack` text dump.
+ * Dev-only by construction: it's called solely from the Vite middleware's catch, never in
+ * production (production maps errors to the `_error` route boundary).
+ */
+/**
+ * Render the dev error overlay HTML. `req` (method + url) is shown for context. The page is
+ * self-contained (inline CSS), dark, and labels itself a dev overlay so it's never mistaken for a
+ * production error page.
+ */
+export declare function renderDevErrorOverlay(err: unknown, req: {
+    method: string;
+    url: string;
+}): string;
+//# sourceMappingURL=dev-error.d.ts.map

package/dist/dev-error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dev-error.d.ts","sourceRoot":"","sources":["../src/dev-error.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAkBH;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,CAgChG"}

package/dist/dev-error.js

@@ -0,0 +1,59 @@
+/**
+ * Dev-only error overlay. When a loader/action/render throws during `@nifrajs/web/vite` dev, this
+ * renders a readable full-page overlay — the message, the source-mapped stack (Vite's
+ * `ssrFixStacktrace` runs first), and the request line — instead of the bare `err.stack` text dump.
+ * Dev-only by construction: it's called solely from the Vite middleware's catch, never in
+ * production (production maps errors to the `_error` route boundary).
+ */
+const esc = (s) => s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+/** Split a stack into the message (first line) + the frame lines, for separate styling. */
+function parseStack(err) {
+    const stack = err.stack ?? `${err.name}: ${err.message}`;
+    const lines = stack.split("\n");
+    // The message can span multiple leading lines (some errors do); frames start at the first "    at ".
+    const firstFrame = lines.findIndex((l) => /^\s*at\s/.test(l));
+    if (firstFrame === -1)
+        return { message: stack, frames: [] };
+    return {
+        message: lines.slice(0, firstFrame).join("\n").trim(),
+        frames: lines.slice(firstFrame).map((l) => l.trim()),
+    };
+}
+/**
+ * Render the dev error overlay HTML. `req` (method + url) is shown for context. The page is
+ * self-contained (inline CSS), dark, and labels itself a dev overlay so it's never mistaken for a
+ * production error page.
+ */
+export function renderDevErrorOverlay(err, req) {
+    const error = err instanceof Error ? err : new Error(String(err));
+    const { message, frames } = parseStack(error);
+    const name = esc(error.name || "Error");
+    const framesHtml = frames.length > 0
+        ? `<ol class="frames">${frames.map((f) => `<li>${esc(f)}</li>`).join("")}</ol>`
+        : `<p class="no-frames">No stack frames.</p>`;
+    return `<!doctype html><html lang="en"><head><meta charset="utf-8"><title>${name} — nifra dev</title>
+<style>
+  :root { color-scheme: dark }
+  body { margin: 0; background: #0b0d10; color: #e6e6e6; font: 14px/1.6 ui-monospace, SFMono-Regular, Menlo, monospace; }
+  .bar { background: #2a0e0e; border-bottom: 1px solid #5a1d1d; padding: 10px 20px; font-weight: 700; color: #ff8a8a; display: flex; gap: 12px; align-items: baseline; }
+  .bar .tag { font-size: 11px; font-weight: 600; color: #ffb4b4; background: #401616; padding: 2px 8px; border-radius: 99px; letter-spacing: .04em; text-transform: uppercase; }
+  .bar .req { margin-left: auto; color: #c98; font-weight: 500; font-size: 12px; }
+  main { padding: 24px 28px; max-width: 1000px; }
+  h1 { font-size: 13px; color: #9aa; font-weight: 600; margin: 0 0 6px; text-transform: uppercase; letter-spacing: .05em; }
+  .message { font-size: 18px; color: #ff9b9b; white-space: pre-wrap; margin: 0 0 28px; font-weight: 600; }
+  .frames { list-style: none; margin: 0; padding: 0; border-left: 2px solid #333; }
+  .frames li { padding: 3px 0 3px 16px; color: #9fb0c0; white-space: pre-wrap; word-break: break-all; }
+  .frames li:first-child { color: #d6e2ee; }
+  .no-frames { color: #778; }
+  footer { margin-top: 28px; color: #667; font-size: 12px; }
+</style></head><body>
+<div class="bar"><span class="tag">nifra dev</span><span>${name}</span><span class="req">${esc(req.method)} ${esc(req.url)}</span></div>
+<main>
+  <h1>Unhandled error during SSR</h1>
+  <p class="message">${esc(message)}</p>
+  <h1>Stack</h1>
+  ${framesHtml}
+  <footer>This overlay is shown only by the dev server. In production this error maps to your <code>_error</code> route boundary.</footer>
+</main></body></html>`;
+}
+//# sourceMappingURL=dev-error.js.map

package/dist/dev-error.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dev-error.js","sourceRoot":"","sources":["../src/dev-error.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,GAAG,GAAG,CAAC,CAAS,EAAU,EAAE,CAChC,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAA;AAE9F,2FAA2F;AAC3F,SAAS,UAAU,CAAC,GAAU;IAC5B,MAAM,KAAK,GAAG,GAAG,CAAC,KAAK,IAAI,GAAG,GAAG,CAAC,IAAI,KAAK,GAAG,CAAC,OAAO,EAAE,CAAA;IACxD,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,CAAA;IAC/B,qGAAqG;IACrG,MAAM,UAAU,GAAG,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAA;IAC7D,IAAI,UAAU,KAAK,CAAC,CAAC;QAAE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,CAAA;IAC5D,OAAO;QACL,OAAO,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,UAAU,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE;QACrD,MAAM,EAAE,KAAK,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;KACrD,CAAA;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,qBAAqB,CAAC,GAAY,EAAE,GAAoC;IACtF,MAAM,KAAK,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAA;IACjE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,UAAU,CAAC,KAAK,CAAC,CAAA;IAC7C,MAAM,IAAI,GAAG,GAAG,CAAC,KAAK,CAAC,IAAI,IAAI,OAAO,CAAC,CAAA;IACvC,MAAM,UAAU,GACd,MAAM,CAAC,MAAM,GAAG,CAAC;QACf,CAAC,CAAC,sBAAsB,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,GAAG,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,OAAO;QAC/E,CAAC,CAAC,2CAA2C,CAAA;IACjD,OAAO,qEAAqE,IAAI;;;;;;;;;;;;;;;;2DAgBvB,IAAI,4BAA4B,GAAG,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC;;;uBAGnG,GAAG,CAAC,OAAO,CAAC;;IAE/B,UAAU;;sBAEQ,CAAA;AACtB,CAAC"}

package/dist/dev.d.ts

@@ -0,0 +1,25 @@
+import { type BuildClientOptions } from "./build.js";
+/** Minimal app surface the dev server needs — `createWebApp(...)` satisfies it. */
+interface FetchApp {
+    fetch(request: Request): Response | Promise<Response>;
+}
+export interface DevServerOptions extends Omit<BuildClientOptions, "minify"> {
+    /**
+     * Build the nifra app for the freshly-built client entry. `importQuery` changes on every
+     * rebuild — pass it to `discoverRoutes(routesDir, { importQuery })` so SSR re-imports edited
+     * route modules instead of Bun's cached copies.
+     */
+    readonly createApp: (clientEntry: string, importQuery: string) => FetchApp | Promise<FetchApp>;
+    /** Directories to watch (default: `[routesDir]`). */
+    readonly watch?: readonly string[];
+    /** Port to listen on (default 3000). */
+    readonly port?: number;
+}
+export interface DevServer {
+    readonly port: number;
+    stop(): void;
+}
+/** Start the dev server: build → serve → watch → rebuild + reload on change. */
+export declare function createDevServer(options: DevServerOptions): Promise<DevServer>;
+export {};
+//# sourceMappingURL=dev.d.ts.map

package/dist/dev.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dev.d.ts","sourceRoot":"","sources":["../src/dev.ts"],"names":[],"mappings":"AAQA,OAAO,EAAE,KAAK,kBAAkB,EAAe,MAAM,YAAY,CAAA;AAEjE,mFAAmF;AACnF,UAAU,QAAQ;IAChB,KAAK,CAAC,OAAO,EAAE,OAAO,GAAG,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAA;CACtD;AAED,MAAM,WAAW,gBAAiB,SAAQ,IAAI,CAAC,kBAAkB,EAAE,QAAQ,CAAC;IAC1E;;;;OAIG;IACH,QAAQ,CAAC,SAAS,EAAE,CAAC,WAAW,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,KAAK,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAA;IAC9F,qDAAqD;IACrD,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IAClC,wCAAwC;IACxC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CACvB;AAED,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,IAAI,IAAI,IAAI,CAAA;CACb;AAOD,gFAAgF;AAChF,wBAAsB,eAAe,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,SAAS,CAAC,CAoEnF"}

package/dist/dev.js

@@ -0,0 +1,83 @@
+/**
+ * `@nifrajs/web/dev` — a zero-config dev server (Bun-only). Builds the client unminified on boot,
+ * serves the nifra app + hashed assets, and injects a live-reload client. Watches the routes dir:
+ * on change it rebuilds the client and re-creates the app with a fresh `importQuery` (so SSR
+ * picks up edited route modules past Bun's import cache), then tells the browser to reload.
+ * Bun-only + build-time; never imported by the edge runtime.
+ */
+import { readdirSync, unwatchFile, watchFile } from "node:fs";
+import { buildClient } from "./build.js";
+const RELOAD_PATH = "/__nifra_dev";
+const RELOAD_TOPIC = "reload";
+// Live-reload client: reloads on a server "reload" push; reconnects if the socket drops.
+const reloadClient = `<script>(()=>{const x=()=>{const w=new WebSocket((location.protocol==="https:"?"wss:":"ws:")+"//"+location.host+"${RELOAD_PATH}");w.onmessage=()=>location.reload();w.onclose=()=>setTimeout(x,500)};x()})()</script>`;
+/** Start the dev server: build → serve → watch → rebuild + reload on change. */
+export async function createDevServer(options) {
+    const { createApp, port = 3000, outDir, routesDir } = options;
+    const publicPath = options.publicPath ?? "/assets/";
+    let version = 0;
+    const rebuild = async () => {
+        const manifest = await buildClient({ ...options, minify: false });
+        return createApp(manifest.entry, `v=${version}`);
+    };
+    let app = await rebuild();
+    const server = Bun.serve({
+        port,
+        async fetch(req, srv) {
+            const url = new URL(req.url);
+            if (url.pathname === RELOAD_PATH) {
+                return srv.upgrade(req) ? undefined : new Response("expected websocket", { status: 426 });
+            }
+            if (url.pathname.startsWith(publicPath)) {
+                const file = Bun.file(`${outDir}/${url.pathname.slice(publicPath.length)}`);
+                return (await file.exists())
+                    ? new Response(file, { headers: { "content-type": "text/javascript; charset=utf-8" } })
+                    : new Response("Not Found", { status: 404 });
+            }
+            const res = await app.fetch(req);
+            if (!(res.headers.get("content-type") ?? "").includes("text/html"))
+                return res;
+            const headers = new Headers(res.headers);
+            headers.delete("content-length"); // the body grows with the injected reload client
+            const html = (await res.text()).replace("</body>", `${reloadClient}</body>`);
+            return new Response(html, { status: res.status, headers });
+        },
+        websocket: {
+            open: (ws) => ws.subscribe(RELOAD_TOPIC),
+            message: () => { },
+        },
+    });
+    // On a route change: rebuild the client, re-create the app with a fresh import cache-buster,
+    // then push a reload. Debounced so a burst of saves rebuilds once.
+    let timer;
+    const onChange = () => {
+        if (timer)
+            clearTimeout(timer);
+        timer = setTimeout(() => {
+            version += 1;
+            rebuild()
+                .then((next) => {
+                app = next;
+                server.publish(RELOAD_TOPIC, "reload");
+                console.log(`[nifra/web/dev] rebuilt + reloaded (v${version})`);
+            })
+                .catch((err) => console.error("[nifra/web/dev] rebuild failed:", err));
+        }, 60);
+    };
+    // Poll the source files for changes. Bun's fs.watch is unreliable here, so watchFile (mtime
+    // polling) is used. New files need a restart to be tracked — fine for dev.
+    const watched = (options.watch ?? [routesDir]).flatMap((dir) => readdirSync(dir, { recursive: true })
+        .filter((file) => /\.(tsx|jsx|ts|js|mdx|svelte|vue)$/.test(file))
+        .map((file) => `${dir}/${file}`));
+    for (const file of watched)
+        watchFile(file, { interval: 150 }, onChange);
+    return {
+        port: server.port ?? port,
+        stop: () => {
+            for (const file of watched)
+                unwatchFile(file);
+            server.stop();
+        },
+    };
+}
+//# sourceMappingURL=dev.js.map

package/dist/dev.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dev.js","sourceRoot":"","sources":["../src/dev.ts"],"names":[],"mappings":"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"}

package/dist/draft.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Draft / preview mode — let an editor see unpublished content by flipping a signed cookie that
+ * loaders read (`ctx.draft`) and ISR bypasses (fresh render, never cached). The cookie is **HMAC-signed**
+ * (so a visitor can't forge it) and **HttpOnly** (JS can't read it). You gate `enableDraft` yourself —
+ * behind an editor login or a `?token=` check — exactly like Next's `draftMode().enable()`.
+ *
+ *   // a route you've protected (e.g. checked ?token= against a secret):
+ *   app.get("/api/draft", async (c) => {
+ *     await enableDraft(c, env.DRAFT_SECRET)
+ *     return redirect("/")
+ *   })
+ *
+ *   // wire the same secret so the framework can verify the cookie:
+ *   createWebApp({ ..., draftSecret: env.DRAFT_SECRET })   // → loaders get ctx.draft
+ *   withISR(app, { ..., draftSecret: env.DRAFT_SECRET })   // → editors bypass the cache
+ */
+import { type CookieOptions } from "@nifrajs/core";
+/** The cookie name nifra uses for draft/preview mode. */
+export declare const DRAFT_COOKIE = "__nifra_draft";
+/** The response-cookie surface `enableDraft`/`disableDraft` need — nifra's `c.set`. Structural, so any
+ * nifra handler context satisfies it without importing the full `Context`. */
+export interface DraftCookieControls {
+    cookie(name: string, value: string, options?: CookieOptions): void;
+    deleteCookie(name: string, options?: {
+        readonly path?: string;
+        readonly domain?: string;
+    }): void;
+}
+export interface EnableDraftOptions {
+    /** Cookie lifetime in **seconds** (default `3600` = 1h). Keep it short — draft is an editor session. */
+    readonly maxAgeSeconds?: number;
+    /** Cookie `Path` (default `"/"`). */
+    readonly path?: string;
+    /** Override the `Secure` attribute (defaults to `true` — secure-by-default). Pass `false` only for
+     * local `http://` dev, where a `Secure` cookie isn't stored. */
+    readonly secure?: boolean;
+}
+/**
+ * Turn draft mode **on** for this client by setting a signed, HttpOnly `__nifra_draft` cookie. Call it
+ * from a route you've already authorized. `secret` signs the cookie — pass the SAME secret to
+ * `createWebApp({ draftSecret })` and `withISR({ draftSecret })` so the framework can verify it.
+ */
+export declare function enableDraft(c: {
+    readonly set: DraftCookieControls;
+}, secret: string, options?: EnableDraftOptions): Promise<void>;
+/** Turn draft mode **off**: clear the `__nifra_draft` cookie. Match the `path` used in `enableDraft`. */
+export declare function disableDraft(c: {
+    readonly set: DraftCookieControls;
+}, options?: {
+    readonly path?: string;
+}): void;
+/**
+ * Whether `request` carries a **valid** signed draft cookie (constant-time verify via `unsignValue`).
+ * `createWebApp` uses it to set `ctx.draft`; `withISR` uses it to bypass the cache for editors. A
+ * missing, forged, or tampered cookie returns `false`.
+ */
+export declare function isDraftEnabled(request: Request, secret: string): Promise<boolean>;
+//# sourceMappingURL=draft.d.ts.map

package/dist/draft.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"draft.d.ts","sourceRoot":"","sources":["../src/draft.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,EAAE,KAAK,aAAa,EAAwC,MAAM,eAAe,CAAA;AAExF,yDAAyD;AACzD,eAAO,MAAM,YAAY,kBAAkB,CAAA;AAM3C;8EAC8E;AAC9E,MAAM,WAAW,mBAAmB;IAClC,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,IAAI,CAAA;IAClE,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAA;CACjG;AAED,MAAM,WAAW,kBAAkB;IACjC,wGAAwG;IACxG,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAA;IAC/B,qCAAqC;IACrC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;IACtB;oEACgE;IAChE,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAA;CAC1B;AAED;;;;GAIG;AACH,wBAAsB,WAAW,CAC/B,CAAC,EAAE;IAAE,QAAQ,CAAC,GAAG,EAAE,mBAAmB,CAAA;CAAE,EACxC,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,kBAAuB,GAC/B,OAAO,CAAC,IAAI,CAAC,CAWf;AAED,yGAAyG;AACzG,wBAAgB,YAAY,CAC1B,CAAC,EAAE;IAAE,QAAQ,CAAC,GAAG,EAAE,mBAAmB,CAAA;CAAE,EACxC,OAAO,GAAE;IAAE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAO,GACvC,IAAI,CAEN;AAED;;;;GAIG;AACH,wBAAsB,cAAc,CAAC,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAIvF"}

package/dist/draft.js

@@ -0,0 +1,55 @@
+/**
+ * Draft / preview mode — let an editor see unpublished content by flipping a signed cookie that
+ * loaders read (`ctx.draft`) and ISR bypasses (fresh render, never cached). The cookie is **HMAC-signed**
+ * (so a visitor can't forge it) and **HttpOnly** (JS can't read it). You gate `enableDraft` yourself —
+ * behind an editor login or a `?token=` check — exactly like Next's `draftMode().enable()`.
+ *
+ *   // a route you've protected (e.g. checked ?token= against a secret):
+ *   app.get("/api/draft", async (c) => {
+ *     await enableDraft(c, env.DRAFT_SECRET)
+ *     return redirect("/")
+ *   })
+ *
+ *   // wire the same secret so the framework can verify the cookie:
+ *   createWebApp({ ..., draftSecret: env.DRAFT_SECRET })   // → loaders get ctx.draft
+ *   withISR(app, { ..., draftSecret: env.DRAFT_SECRET })   // → editors bypass the cache
+ */
+import { parseCookies, signValue, unsignValue } from "@nifrajs/core";
+/** The cookie name nifra uses for draft/preview mode. */
+export const DRAFT_COOKIE = "__nifra_draft";
+// The signed cookie's payload is a fixed marker — a *valid signature* (not the value) is the signal
+// that the server issued this via enableDraft(). Nothing secret is stored in it.
+const DRAFT_MARKER = "1";
+/**
+ * Turn draft mode **on** for this client by setting a signed, HttpOnly `__nifra_draft` cookie. Call it
+ * from a route you've already authorized. `secret` signs the cookie — pass the SAME secret to
+ * `createWebApp({ draftSecret })` and `withISR({ draftSecret })` so the framework can verify it.
+ */
+export async function enableDraft(c, secret, options = {}) {
+    const signed = await signValue(DRAFT_MARKER, secret);
+    // Explicit security attributes (don't lean on the context default): signed + HttpOnly + SameSite=Lax.
+    const cookieOptions = {
+        httpOnly: true,
+        sameSite: "lax",
+        path: options.path ?? "/",
+        maxAge: options.maxAgeSeconds ?? 3600,
+        ...(options.secure === undefined ? {} : { secure: options.secure }),
+    };
+    c.set.cookie(DRAFT_COOKIE, signed, cookieOptions);
+}
+/** Turn draft mode **off**: clear the `__nifra_draft` cookie. Match the `path` used in `enableDraft`. */
+export function disableDraft(c, options = {}) {
+    c.set.deleteCookie(DRAFT_COOKIE, { path: options.path ?? "/" });
+}
+/**
+ * Whether `request` carries a **valid** signed draft cookie (constant-time verify via `unsignValue`).
+ * `createWebApp` uses it to set `ctx.draft`; `withISR` uses it to bypass the cache for editors. A
+ * missing, forged, or tampered cookie returns `false`.
+ */
+export async function isDraftEnabled(request, secret) {
+    const cookie = parseCookies(request.headers.get("cookie"))[DRAFT_COOKIE];
+    if (cookie === undefined)
+        return false;
+    return (await unsignValue(cookie, secret)) !== null;
+}
+//# sourceMappingURL=draft.js.map

package/dist/draft.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"draft.js","sourceRoot":"","sources":["../src/draft.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,EAAsB,YAAY,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,eAAe,CAAA;AAExF,yDAAyD;AACzD,MAAM,CAAC,MAAM,YAAY,GAAG,eAAe,CAAA;AAE3C,oGAAoG;AACpG,iFAAiF;AACjF,MAAM,YAAY,GAAG,GAAG,CAAA;AAmBxB;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,CAAwC,EACxC,MAAc,EACd,UAA8B,EAAE;IAEhC,MAAM,MAAM,GAAG,MAAM,SAAS,CAAC,YAAY,EAAE,MAAM,CAAC,CAAA;IACpD,sGAAsG;IACtG,MAAM,aAAa,GAAkB;QACnC,QAAQ,EAAE,IAAI;QACd,QAAQ,EAAE,KAAK;QACf,IAAI,EAAE,OAAO,CAAC,IAAI,IAAI,GAAG;QACzB,MAAM,EAAE,OAAO,CAAC,aAAa,IAAI,IAAI;QACrC,GAAG,CAAC,OAAO,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC;KACpE,CAAA;IACD,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,YAAY,EAAE,MAAM,EAAE,aAAa,CAAC,CAAA;AACnD,CAAC;AAED,yGAAyG;AACzG,MAAM,UAAU,YAAY,CAC1B,CAAwC,EACxC,UAAsC,EAAE;IAExC,CAAC,CAAC,GAAG,CAAC,YAAY,CAAC,YAAY,EAAE,EAAE,IAAI,EAAE,OAAO,CAAC,IAAI,IAAI,GAAG,EAAE,CAAC,CAAA;AACjE,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,OAAgB,EAAE,MAAc;IACnE,MAAM,MAAM,GAAG,YAAY,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,YAAY,CAAC,CAAA;IACxE,IAAI,MAAM,KAAK,SAAS;QAAE,OAAO,KAAK,CAAA;IACtC,OAAO,CAAC,MAAM,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,KAAK,IAAI,CAAA;AACrD,CAAC"}

package/dist/fonts-google.d.ts

@@ -0,0 +1,109 @@
+/**
+ * Build-time Google Fonts automation — the `next/font/google` equivalent. At **build time** (never on
+ * the request path) it: builds the Google Fonts CSS2 URL, downloads the stylesheet, parses the
+ * `@font-face` rules, downloads each `.woff2`, content-hashes it, writes it next to your assets, and
+ * hands back a **self-hosted** `@font-face` stylesheet + the matching `<link rel="preload">`s. The
+ * result is identical to dropping the files in yourself and calling {@link fontFace} — no runtime CDN
+ * hotlink, no layout shift, hashed filenames for immutable caching.
+ *
+ *   // fonts.build.ts — run once at build time (e.g. a prebuild step)
+ *   import { loadGoogleFont } from "@nifrajs/web/fonts"
+ *   const inter = await loadGoogleFont(
+ *     { family: "Inter", weights: [400, 700], subsets: ["latin"] },
+ *     { outDir: "public/fonts" },               // → public/fonts/inter-latin-normal-400-<hash>.woff2
+ *   )
+ *   await Bun.write("app/fonts.css", inter.css) // import this stylesheet from your app
+ *   // inter.preloads → spread into a root layout's `meta.link`
+ *
+ * Security: this fetches remote content and writes it to disk, so every input is validated and the
+ * font-file host is **allowlisted to `fonts.gstatic.com` over https** — a tampered/MITM'd stylesheet
+ * cannot make the build fetch an arbitrary URL (SSRF) or write an attacker-chosen blob. Downloads are
+ * size-capped. Filenames are derived only from validated tokens + a content hash (no path traversal).
+ */
+import { type FontDisplay } from "./fonts.js";
+/** Options describing the Google font to fetch + self-host. */
+export interface GoogleFontOptions {
+    /** Family name exactly as Google lists it, e.g. `"Inter"`, `"Open Sans"`, `"Roboto Mono"`. */
+    readonly family: string;
+    /** Weights to request — numbers (`400`), numeric strings, a variable range (`"100 900"`), or the
+     * keywords `"normal"`/`"bold"`. Defaults to `[400]`. */
+    readonly weights?: readonly (number | string)[];
+    /** Styles to request. Defaults to `["normal"]`. */
+    readonly styles?: readonly ("normal" | "italic")[];
+    /** Keep only these named subsets (`"latin"`, `"latin-ext"`, `"cyrillic"`, …). Google returns every
+     * subset it has as a separate `@font-face`; this filters to the ones you serve. Defaults to keeping
+     * all returned subsets. Ignored when {@link text} is set (glyph subsetting supersedes it). */
+    readonly subsets?: readonly string[];
+    /** `font-display` strategy for the generated faces. Defaults to `"swap"`. */
+    readonly display?: FontDisplay;
+    /** Glyph subsetting: request only the glyphs needed to render exactly this text (Google's `&text=`).
+     * Ideal for a logo/heading font — produces one tiny file. */
+    readonly text?: string;
+    /** CLS metric overrides forwarded to every generated `@font-face` (the layout-shift fix). */
+    readonly sizeAdjust?: string;
+    readonly ascentOverride?: string;
+    readonly descentOverride?: string;
+    readonly lineGapOverride?: string;
+}
+/** A single `@font-face` block parsed out of Google's stylesheet. */
+export interface ParsedFontFace {
+    readonly family: string;
+    readonly style: string;
+    readonly weight: string;
+    readonly subset: string;
+    readonly unicodeRange?: string;
+    readonly src: readonly {
+        readonly url: string;
+        readonly format?: string;
+    }[];
+}
+/** One downloaded + written font file. */
+export interface FontAsset {
+    /** The hashed filename written under `outDir` (no directory part). */
+    readonly fileName: string;
+    /** The public URL the generated `@font-face`/preload reference (`${publicPath}/${fileName}`). */
+    readonly href: string;
+    /** The original `fonts.gstatic.com` URL the bytes came from. */
+    readonly sourceUrl: string;
+    readonly bytes: Uint8Array;
+    readonly subset: string;
+    readonly weight: string;
+    readonly style: string;
+}
+export interface LoadGoogleFontResult {
+    readonly family: string;
+    /** A self-hosted `@font-face` stylesheet (one rule per written file). Import it from your app. */
+    readonly css: string;
+    /** Every file written to `outDir`. */
+    readonly assets: readonly FontAsset[];
+    /** `fontPreload()` link-attribute sets — spread the ones you want into a layout's `meta.link`.
+     * Preloading *every* weight/subset is wasteful; usually preload just the primary subset + weight. */
+    readonly preloads: readonly Record<string, string>[];
+}
+export interface LoadGoogleFontIO {
+    /** Directory to write the hashed `.woff2` files into (created if missing). */
+    readonly outDir: string;
+    /** URL prefix the files are served under. Defaults to `"/fonts"`. */
+    readonly publicPath?: string;
+    /** Injectable `fetch` (defaults to the global). Tests pass a canned implementation. */
+    readonly fetch?: typeof fetch;
+    /** Injectable writer (defaults to `node:fs`). Tests pass an in-memory sink. */
+    readonly writeFile?: (path: string, bytes: Uint8Array) => Promise<void>;
+    /** Per-file download cap in bytes. Defaults to 5 MB (real woff2 are well under 1 MB). */
+    readonly maxBytesPerFile?: number;
+}
+/** `true` iff `raw` is an `https://fonts.gstatic.com/…` URL — the only host we'll download from. */
+export declare function isAllowedFontUrl(raw: string): boolean;
+/** Build the Google Fonts CSS2 request URL. Pure + fully validated, so it's safe to feed a dynamic
+ * family/weights/text. Exported for advanced callers who fetch + parse the stylesheet themselves. */
+export declare function googleFontsCssUrl(options: GoogleFontOptions): string;
+/** Parse Google's stylesheet into structured faces, capturing the `/* subset *​/` label that precedes
+ * each `@font-face`. Pure — exported so callers can run their own download/write pipeline. */
+export declare function parseGoogleFontCss(css: string): ParsedFontFace[];
+/**
+ * Download a Google font, self-host it, and return a CLS-safe `@font-face` stylesheet + preloads.
+ * See the module header for the full flow and security model. I/O (`fetch`, `writeFile`) is injectable
+ * so this is unit-testable without the network.
+ */
+export declare function loadGoogleFont(options: GoogleFontOptions, io: LoadGoogleFontIO): Promise<LoadGoogleFontResult>;
+//# sourceMappingURL=fonts-google.d.ts.map

package/dist/fonts-google.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fonts-google.d.ts","sourceRoot":"","sources":["../src/fonts-google.ts"],"names":[],"mappings":"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"}