@nifrajs/web 2.2.0 → 2.4.0

package/src/draft.ts

@@ -1,8 +1,8 @@
 /**
- * Draft / preview mode — let an editor see unpublished content by flipping a signed cookie that
+ * 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()`.
+ * (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) => {
@@ -26,11 +26,11 @@ import { timingSafeEqual } from "./internal/timing-safe-equal.ts"
 /** 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
+// 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"
 
-/** The response-cookie surface `enableDraft`/`disableDraft` need — nifra's `c.set`. Structural, so any
+/** 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
@@ -38,18 +38,18 @@ export interface DraftCookieControls {
 }
 
 export interface EnableDraftOptions {
-  /** Cookie lifetime in **seconds** (default `3600` = 1h). Keep it short — draft is an editor session. */
+  /** 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
+  /** 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
+ * 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(
@@ -68,7 +68,7 @@ export async function enableDraft(
  *
  * `secure` is resolved here rather than left to the caller: `serializeCookie` is pure and applies
  * **no** security defaults, so the `previewEndpoint` path would silently emit a cookie without
- * `Secure` — over plain HTTP that hands the draft cookie to any network observer. Passing it
+ * `Secure` - over plain HTTP that hands the draft cookie to any network observer. Passing it
  * explicitly makes both paths identical instead of one inheriting a default the other never sees.
  */
 function draftCookieOptions(options: EnableDraftOptions): CookieOptions {
@@ -106,7 +106,7 @@ export async function isDraftEnabled(request: Request, secret: string): Promise<
  *
  * A redirect target that arrives in the query string is attacker-controlled: anyone can mint a link
  * to your own preview route and choose where the editor lands. "Starts with `/`" is the check people
- * write and it is not enough — `//evil.com` is a protocol-relative URL and `/\evil.com` is normalized
+ * write and it is not enough - `//evil.com` is a protocol-relative URL and `/\evil.com` is normalized
  * to one by browsers, so both start with a slash and navigate off-site. Control characters are refused
  * as well, since a newline in a `Location` header splits the response.
  */
@@ -124,7 +124,7 @@ function safeRedirectPath(value: string): string | null {
 export interface PreviewEndpointOptions {
   /** Shared secret the preview link must carry. Compared in **constant time**. */
   readonly secret: string
-  /** Secret that **signs** the draft cookie — the same one passed to `createWebApp({ draftSecret })`
+  /** Secret that **signs** the draft cookie - the same one passed to `createWebApp({ draftSecret })`
    * and `withISR({ draftSecret })`. Keep it distinct from {@link secret}: that one travels in URLs
    * (logs, `Referer`, browser history), this one never leaves the server. */
   readonly draftSecret: string
@@ -140,17 +140,17 @@ export interface PreviewEndpointOptions {
 }
 
 /**
- * A **preview / draft-mode entry point** — a `fetch` handler that checks a preview token, turns draft
+ * A **preview / draft-mode entry point** - a `fetch` handler that checks a preview token, turns draft
  * mode on, and redirects the editor to the page they wanted. `GET` with `?token=<secret>&to=/some/path`;
  * mount it on a nifra route, e.g. `app.get("/api/preview", (c) => handler(c.req))`.
  *
- * This is the link-borne sibling of `revalidateEndpoint`. It exists because the alternative — telling
- * you to gate the route yourself — means hand-rolling two checks that are easy to get subtly wrong and
+ * This is the link-borne sibling of `revalidateEndpoint`. It exists because the alternative - telling
+ * you to gate the route yourself - means hand-rolling two checks that are easy to get subtly wrong and
  * that fail silently when you do: the token compare must not exit early on the first wrong character,
  * and the `?to=` destination must not be allowed to point off-site. Both are handled here.
  *
  * A CMS "Preview" button is a plain link, so the token has to ride the query string. That has a cost
- * no endpoint can remove — the secret lands in server logs, the `Referer` header, and browser history.
+ * no endpoint can remove - the secret lands in server logs, the `Referer` header, and browser history.
  * Use a preview token minted for that purpose, rotate it, and never reuse a token that grants anything
  * beyond draft mode.
  *

package/src/fn-state.ts

@@ -0,0 +1,107 @@
+/**
+ * `@nifrajs/web/fn-state` - the pending/error state around a server-function call.
+ *
+ * Calling a server function needs no binding: the client stub is `(input) => Promise<Output>`, and a
+ * click handler can await it. What a component usually wants on top is whether a call is in flight,
+ * what came back, and what went wrong - which is state, and state is the part every framework spells
+ * differently.
+ *
+ * So the state machine lives here, framework-agnostic, and each adapter contributes only its
+ * subscription primitive. Five copies of "is it pending" would drift, and the drift would be five
+ * subtly different answers to the same question.
+ *
+ * ## Two behaviours worth stating
+ *
+ * **The last call wins.** Concurrent calls are not queued or cancelled; a response that is no longer
+ * the newest is discarded rather than written. Without that, a slow first call landing after a fast
+ * second one would overwrite fresh data with stale - the classic out-of-order bug, and one that only
+ * appears under load, which is to say in production.
+ *
+ * **`call` still rejects.** The error is recorded for rendering AND the promise rejects, so `await`
+ * behaves the way `await` should and a caller who wants to branch can. A caller who only renders from
+ * state should attach a `.catch(() => {})`, the same as `useFetcher`'s `submit`.
+ */
+
+/** What a component renders from. */
+export interface ServerFnState<Output> {
+  /** A call is in flight. */
+  readonly pending: boolean
+  /** The most recent successful result, kept across a later pending call so the UI need not flicker. */
+  readonly data: Output | undefined
+  /** The most recent failure, cleared when a call succeeds. */
+  readonly error: Error | undefined
+}
+
+/** A subscribable call site. One per component instance, created by the framework binding. */
+export interface ServerFnStore<Input, Output> {
+  /** Register a listener; returns the unsubscribe. */
+  subscribe(listener: () => void): () => void
+  /**
+   * The current state. The SAME object is returned until something changes, because
+   * `useSyncExternalStore` and its equivalents compare by reference - a fresh object each call is an
+   * infinite render loop.
+   */
+  snapshot(): ServerFnState<Output>
+  /** Invoke the server function. Records state, and rejects on failure. */
+  call(input: Input): Promise<Output>
+  /** Back to idle, discarding data and error. */
+  reset(): void
+}
+
+const IDLE: ServerFnState<never> = { pending: false, data: undefined, error: undefined }
+
+/** The idle state, shared so a server render and the first client render agree by reference. */
+export function idleServerFnState<Output>(): ServerFnState<Output> {
+  return IDLE as ServerFnState<Output>
+}
+
+const asError = (cause: unknown): Error =>
+  cause instanceof Error ? cause : new Error(String(cause), { cause })
+
+/**
+ * Wrap a server function (or any async function) in a subscribable pending/error state.
+ *
+ * Framework-free by design: the adapters call this and subscribe with their own primitive.
+ */
+export function createServerFnStore<Input, Output>(
+  fn: (input: Input) => Promise<Output> | Output,
+): ServerFnStore<Input, Output> {
+  const listeners = new Set<() => void>()
+  let state: ServerFnState<Output> = idleServerFnState<Output>()
+  /** Identifies the newest call, so an older one landing later cannot write over it. */
+  let generation = 0
+
+  const set = (next: ServerFnState<Output>): void => {
+    state = next
+    for (const listener of listeners) listener()
+  }
+
+  return {
+    subscribe(listener) {
+      listeners.add(listener)
+      return () => {
+        listeners.delete(listener)
+      }
+    },
+    snapshot: () => state,
+    async call(input) {
+      const mine = ++generation
+      // `data` is deliberately kept while pending: dropping it makes a list blank on every refetch.
+      set({ pending: true, data: state.data, error: undefined })
+      try {
+        const data = await fn(input)
+        if (mine === generation) set({ pending: false, data, error: undefined })
+        return data
+      } catch (cause) {
+        const error = asError(cause)
+        if (mine === generation) set({ pending: false, data: state.data, error })
+        throw error
+      }
+    },
+    reset() {
+      // Bump the generation so a call already in flight cannot resurrect the state it was reset from.
+      generation += 1
+      set(idleServerFnState<Output>())
+    },
+  }
+}

package/src/fn.ts

@@ -0,0 +1,199 @@
+/**
+ * `@nifrajs/web/fn` - server functions: write a function, call it from a component.
+ *
+ * ## Every server function is a public endpoint
+ *
+ * This is the first thing to internalise, because the API deliberately reads like a local call. A
+ * mounted function is an HTTP route anyone can POST to, with arguments entirely under the caller's
+ * control. Its id has to be in the client bundle for the browser to call it, so there is no obscurity
+ * to lean on. Treat one exactly as you would a hand-written `app.post`.
+ *
+ * What follows from that, and what this module does about it:
+ *
+ *   - **Input is validated, always.** `input` is not optional decoration; without a schema a function
+ *     takes no arguments at all. Unvalidated arguments on a public endpoint are mass assignment.
+ *   - **`application/json` only.** A cross-origin HTML form can only send urlencoded, multipart or
+ *     text/plain, so requiring JSON forces a CORS preflight the browser blocks. Both alternatives were
+ *     measured rather than assumed: a body schema alone still accepts a cross-origin urlencoded form
+ *     (200, attacker-controlled fields), and `c.boundedJson` alone accepts the `text/plain` trick where
+ *     a form's `name=value` is crafted to parse as JSON. Neither is sufficient by itself.
+ *   - **Same-origin only.** A present `Origin` must match the request's own host. Defence in depth
+ *     behind the JSON requirement, and it costs one comparison. Server functions exist for your own
+ *     frontend; a different origin calling your backend is the typed-client story, not this one.
+ *   - **No closures.** A function is a module-level export taking explicit arguments. Next serialises
+ *     closed-over variables to the browser and back, which it now has to encrypt; refusing the feature
+ *     removes the whole class rather than defending it.
+ *
+ * ## The client half
+ *
+ * A `*.fn.ts` module is never bundled for the browser. The client build replaces it with one stub per
+ * export, each POSTing to the route below, so the bodies and everything they import stay on the server.
+ *
+ * One pipeline cannot do this: `nifra dev --bun`. Bun's dev-server bundler accepts no plugins - a
+ * runtime `Bun.plugin` onLoad does not reach it, which was measured rather than assumed - so a `*.fn`
+ * module there would ship WHOLE, secrets included. That command refuses to start on an app containing
+ * one, the same way it already refuses CSS Modules. `nifra build` and `nifra dev` (Vite) are unaffected.
+ *
+ * ## Why this is not a new lane
+ *
+ * A mounted function registers through the ordinary public `register()`, so it is a route like any
+ * other and inherits the body cap, schema validation, capability declarations, the effect ledger, and
+ * `nifra assure`. Nothing here touches the kernel or the request path, so an app that mounts none of
+ * them pays exactly nothing - which is the whole reason to build it this way rather than as a
+ * bespoke dispatcher.
+ */
+import {
+  type Context,
+  isSameOriginRequest,
+  type RouteSchema,
+  type StandardSchemaV1,
+} from "@nifrajs/core/server"
+
+/** The URL prefix every mounted function lives under. Namespaced per mount, then by export name. */
+export const SERVER_FN_PREFIX = "/_nifra/fn"
+
+type MaybePromise<T> = T | Promise<T>
+
+/** What a server function declares about itself. */
+export interface ServerFnConfig<Input> {
+  /**
+   * Validates the single argument. Omit it and the function takes no argument - never "any argument":
+   * the caller controls this value completely, so an unvalidated one is an open door.
+   */
+  readonly input?: StandardSchemaV1<unknown, Input>
+  /** Effect tokens, forwarded to the route so `nifra assure` and the effect ledger see them. */
+  readonly capabilities?: readonly string[]
+}
+
+/**
+ * A declared server function. Callable directly on the server (the same value your own server-side
+ * code can await); on the client, phase 2's build transform replaces this module with typed stubs
+ * that POST to the mounted route.
+ *
+ * This is the SERVER declaration type, so context is required. Client builds replace the module with
+ * a one-argument {@link ClientServerFn}; UI bindings accept either shape and adapt at that boundary.
+ * Keeping the types separate prevents a direct server call from type-checking while handing the
+ * declaration `undefined` for a context its implementation requires.
+ */
+export interface ServerFn<Input, Output> {
+  (input: Input, context: Context): MaybePromise<Output>
+  readonly [SERVER_FN]: ServerFnConfig<Input>
+}
+
+/** The one-argument callable emitted into a client bundle for a {@link ServerFn}. */
+export type ClientServerFn<Input, Output> = (input: Input) => MaybePromise<Output>
+
+/** A UI binding boundary: source declarations and generated client stubs are both accepted. */
+export type ServerFnReference<Input, Output> =
+  | ServerFn<Input, Output>
+  | ClientServerFn<Input, Output>
+
+/** Brand identifying a value produced by {@link serverFn}, so mounting cannot pick up stray exports. */
+export const SERVER_FN: unique symbol = Symbol.for("@nifrajs/web/server-fn")
+
+/**
+ * Declare a server function.
+ *
+ *     export const addTodo = serverFn(
+ *       { input: t.object({ text: t.string({ minLength: 1 }) }), capabilities: ["db.write"] },
+ *       async ({ text }, c) => db.todos.insert({ text }),
+ *     )
+ *
+ * The second argument receives the validated input and the ordinary nifra `Context` - `c.env`,
+ * `c.clientIp`, `c.budget`, cookies, and the capability guard are all present, because this is a route.
+ */
+export function serverFn<Input = void, Output = unknown>(
+  config: ServerFnConfig<Input>,
+  fn: (input: Input, context: Context) => MaybePromise<Output>,
+): ServerFn<Input, Output> {
+  return Object.assign(fn, { [SERVER_FN]: config }) as ServerFn<Input, Output>
+}
+
+const isServerFn = (value: unknown): value is ServerFn<unknown, unknown> =>
+  typeof value === "function" && SERVER_FN in (value as object)
+
+/** A namespace segment: lowercase, dot/dash separated. Constrained so a mount cannot invent a path. */
+const NAMESPACE = /^[a-z0-9]+(?:[-.][a-z0-9]+)*$/
+/** An export name that is safe in a URL path without escaping. */
+const EXPORT_NAME = /^[A-Za-z_$][A-Za-z0-9_$]*$/
+
+/**
+ * Same-origin, from `@nifrajs/core` so this seam and the WebSocket handshake cannot answer differently
+ * for one request. Host must match; the Origin's scheme may be equal or stronger, never weaker - which
+ * is what keeps a TLS-terminating proxy working without reading a forwarded header.
+ */
+const sameOrigin = isSameOriginRequest
+
+/** The minimum a server needs to expose for functions to be mounted onto it. */
+export interface ServerFnHost {
+  register(
+    method: "POST",
+    path: string,
+    schema: RouteSchema | undefined,
+    handler: (context: never) => unknown,
+  ): void
+}
+
+/** Every server function a module exports, keyed by export name. */
+export type ServerFnModule = Readonly<Record<string, unknown>>
+
+/**
+ * Mount a module's server functions under `namespace`, returning a plugin for `app.use(...)`.
+ *
+ *     import * as todos from "./actions/todos.fn"
+ *     app.use(serverFunctions("todos", todos))   // -> POST /_nifra/fn/todos/addTodo
+ *
+ * The namespace is explicit rather than derived from the file path: a path-derived one would put the
+ * build machine's layout in a public URL, and this keeps the route readable in logs and greppable in
+ * the codebase. Phase 2's transform supplies it automatically from the file's location in the project.
+ *
+ * Exports that are not server functions are ignored, so `export type` and helpers can live alongside.
+ */
+export function serverFunctions<S extends ServerFnHost>(
+  namespace: string,
+  module: ServerFnModule,
+): (app: S) => S {
+  if (!NAMESPACE.test(namespace)) {
+    throw new Error(
+      `[nifra/fn] invalid server-function namespace ${JSON.stringify(namespace)} - use lowercase dot/dash segments (it becomes a URL path).`,
+    )
+  }
+  const mounted = Object.entries(module).filter(
+    (entry): entry is [string, ServerFn<unknown, unknown>] => isServerFn(entry[1]),
+  )
+
+  const apply = (app: S): S => {
+    for (const [name, fn] of mounted) {
+      if (!EXPORT_NAME.test(name)) {
+        throw new Error(
+          `[nifra/fn] server function ${JSON.stringify(name)} in namespace ${JSON.stringify(namespace)} is not a valid identifier.`,
+        )
+      }
+      const config = fn[SERVER_FN]
+      const schema: RouteSchema = {
+        ...(config.input !== undefined ? { body: config.input } : {}),
+        ...(config.capabilities !== undefined ? { capabilities: config.capabilities } : {}),
+      }
+      app.register("POST", `${SERVER_FN_PREFIX}/${namespace}/${name}`, schema, ((c: Context) => {
+        // Ordered cheapest-first, and BEFORE the declared function runs. The body has already been
+        // parsed by the schema layer, but parsing is not a side effect - nothing the caller asked for
+        // has happened yet, so rejecting here is a complete refusal.
+        const request = c.req
+        const contentType = request.headers.get("content-type") ?? ""
+        if (!contentType.includes("application/json")) {
+          // A form cannot send this content type cross-origin without a preflight. Rejecting anything
+          // else is what makes form-driven CSRF against a server function impossible rather than
+          // merely unlikely.
+          return c.json({ ok: false, error: "unsupported_media_type" }, 415)
+        }
+        const origin = request.headers.get("origin")
+        if (origin !== null && !sameOrigin(origin, request)) {
+          return c.json({ ok: false, error: "forbidden_origin" }, 403)
+        }
+        return fn(config.input === undefined ? (undefined as never) : (c.body as never), c)
+      }) as (context: never) => unknown)
+    }
+    return app
+  }
+  return Object.assign(apply, { pluginName: `nifra:server-fn:${namespace}` })
+}

package/src/fonts-google.ts

@@ -1,12 +1,12 @@
 /**
- * Build-time Google Fonts automation — the `next/font/google` equivalent. At **build time** (never on
+ * 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
+ * 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)
+ *   // 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"] },
@@ -16,7 +16,7 @@
  *   // 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
+ * 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).
  */
@@ -30,7 +30,7 @@ import type { LinkDescriptor } from "./manifest.ts"
 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
+  /** 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"]`. */
@@ -42,7 +42,7 @@ export interface GoogleFontOptions {
   /** `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. */
+   * 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
@@ -81,7 +81,7 @@ export interface LoadGoogleFontResult {
   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`.
+  /** `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 LinkDescriptor[]
 }
@@ -121,7 +121,7 @@ const VALID_DISPLAY: ReadonlySet<string> = new Set([
   "optional",
 ])
 
-/** `true` iff `raw` is an `https://fonts.gstatic.com/…` URL — the only host we'll download from. */
+/** `true` iff `raw` is an `https://fonts.gstatic.com/…` URL - the only host we'll download from. */
 export function isAllowedFontUrl(raw: string): boolean {
   let url: URL
   try {
@@ -148,7 +148,7 @@ function validateFamily(family: string): string {
 function normalizeWeight(weight: number | string): string {
   if (typeof weight === "number") {
     if (!Number.isInteger(weight) || weight < 1 || weight > 1000) {
-      throw new Error(`loadGoogleFont: invalid weight ${weight} (1–1000)`)
+      throw new Error(`loadGoogleFont: invalid weight ${weight} (1-1000)`)
     }
     return String(weight)
   }
@@ -221,7 +221,7 @@ function declOf(body: string, prop: string): string | undefined {
 }
 
 /** 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. */
+ * each `@font-face`. Pure - exported so callers can run their own download/write pipeline. */
 export function parseGoogleFontCss(css: string): ParsedFontFace[] {
   const faces: ParsedFontFace[] = []
   for (const match of css.matchAll(FACE_RE)) {
@@ -250,7 +250,7 @@ export function parseGoogleFontCss(css: string): ParsedFontFace[] {
   return faces
 }
 
-/** First 16 hex chars of the SHA-256 of the bytes — a content hash for an immutable, cache-busting
+/** First 16 hex chars of the SHA-256 of the bytes - a content hash for an immutable, cache-busting
  * filename. Web Crypto, so it runs identically on Bun/Node/edge build hosts. `Uint8Array<ArrayBuffer>`
  * (not the generic `ArrayBufferLike`) to satisfy WebCrypto's `BufferSource` under TS 5.7+ generics. */
 async function contentHash(bytes: Uint8Array<ArrayBuffer>): Promise<string> {
@@ -267,7 +267,7 @@ const slug = (s: string): string =>
     .replace(/[^a-z0-9]+/g, "-")
     .replace(/^-+|-+$/g, "")
 
-/** Host of a URL for error messages — we never echo the full untrusted URL+path. */
+/** Host of a URL for error messages - we never echo the full untrusted URL+path. */
 const hostOf = (raw: string): string => {
   try {
     return new URL(raw).host
@@ -330,7 +330,7 @@ export async function loadGoogleFont(
       `loadGoogleFont: Google returned no @font-face rules for ${JSON.stringify(family)}`,
     )
   }
-  // Filter to requested named subsets — but only when not glyph-subsetting (text mode labels faces
+  // Filter to requested named subsets - but only when not glyph-subsetting (text mode labels faces
   // `[0]`, `[1]`, … which carry no subset name).
   if (wantedSubsets && wantedSubsets.length > 0 && options.text === undefined) {
     faces = faces.filter((f) => wantedSubsets.includes(f.subset))

package/src/fonts.ts

@@ -1,17 +1,17 @@
 /**
- * Font optimization primitives — generate a **CLS-safe `@font-face`** rule and the matching
+ * Font optimization primitives - generate a **CLS-safe `@font-face`** rule and the matching
  * **preload `<link>`** for a self-hosted font. The two fixes that matter most (the ones `next/font`
  * automates) are right here: `font-display: swap` (text paints immediately, no invisible-text FOIT)
  * plus a preload so the file downloads with the document, and optional metric overrides
  * (`size-adjust`/`ascent-override`/…) so swapping from the fallback to the web font doesn't shift layout.
  *
- * Self-host the file (drop a `.woff2` in your assets — never hotlink Google's CDN), then:
+ * Self-host the file (drop a `.woff2` in your assets - never hotlink Google's CDN), then:
  *
- *   // fonts.css (imported by your app — the CSS pipeline bundles + links it)
+ *   // fonts.css (imported by your app - the CSS pipeline bundles + links it)
  *   import { fontFace } from "@nifrajs/web"
  *   export default fontFace({ family: "Inter", src: [{ url: "/fonts/inter.woff2" }], weight: "100 900" })
  *
- *   // a root layout's meta — becomes a <link rel="preload" as="font"> in <head>
+ *   // a root layout's meta - becomes a <link rel="preload" as="font"> in <head>
  *   export const meta = { link: [fontPreload({ href: "/fonts/inter.woff2" })] }
  */
 import type { LinkDescriptor } from "./manifest.ts"
@@ -35,7 +35,7 @@ export interface FontFace {
   readonly style?: "normal" | "italic" | "oblique"
   /** Defaults to `"swap"` (no flash of invisible text). */
   readonly display?: FontDisplay
-  /** Restrict the glyphs this face covers, e.g. `"U+0000-00FF"` — lets the browser skip the download
+  /** Restrict the glyphs this face covers, e.g. `"U+0000-00FF"` - lets the browser skip the download
    * for pages without those characters. */
   readonly unicodeRange?: string
   /** Metric overrides that eliminate layout shift when the fallback swaps to the web font (the
@@ -124,14 +124,14 @@ export interface FontPreloadInput {
   readonly href: string
   /** MIME type (`font/woff2`, …). Inferred from the extension when omitted. */
   readonly type?: string
-  /** `crossorigin` mode — defaults to `"anonymous"`. Fonts are always fetched in CORS mode, and a
+  /** `crossorigin` mode - defaults to `"anonymous"`. Fonts are always fetched in CORS mode, and a
    * preload whose `crossorigin` doesn't match the actual fetch is **wasted** (downloaded twice), so
    * this is on by default. */
   readonly crossOrigin?: "anonymous" | "use-credentials"
 }
 
 /**
- * Build a font preload as a `<link>` attribute set for a route/layout's `meta.link` — nifra injects it
+ * Build a font preload as a `<link>` attribute set for a route/layout's `meta.link` - nifra injects it
  * into `<head>` (`<link rel="preload" as="font" type="font/woff2" crossorigin="anonymous">`). Values are
  * escaped at injection by the head renderer. Preloading the font file removes a render-blocking round
  * trip (the browser would otherwise discover the font only after parsing the CSS).

package/src/forms.ts

@@ -1,6 +1,6 @@
 /**
- * `@nifrajs/web/forms` — a typed form ↔ backend-schema binding. The three artifacts that must agree —
- * a form's `<input name>`, the action's `formData.get`, and the typed-client payload — all key off the
+ * `@nifrajs/web/forms` - a typed form ↔ backend-schema binding. The three artifacts that must agree -
+ * a form's `<input name>`, the action's `formData.get`, and the typed-client payload - all key off the
  * ONE route body schema, derived purely from `typeof backend`. A typo'd field name, or a field the
  * schema doesn't have, becomes a COMPILE error instead of a silent runtime empty.
  *
@@ -8,14 +8,14 @@
  *   import { formFor } from "@nifrajs/web/forms"
  *
  *   const f = formFor<typeof backend, "/todos">()   // method defaults to "post"
- *   // In the component (any framework — spread the props onto an input):
+ *   // In the component (any framework - spread the props onto an input):
  *   <input {...f.field("text")} />                  // "text" ∈ the body's keys, else a compile error
  *   // In the action:
  *   const text = f.read(await request.formData(), "text")   // an orphan key won't compile
  *   await api.todos.post({ text })                  // payload already typed by nifra
  *
  * Framework-agnostic + dependency-free: no codegen, no schema is bundled into the client, and the
- * runtime is a trivial pass-through — all the work is in the types. It checks the field KEY, never the
+ * runtime is a trivial pass-through - all the work is in the types. It checks the field KEY, never the
  * MEANING (a `field("email")` collecting a phone is still valid here); that stays an app/AI concern.
  */
 import type { RouteInfo, Server } from "@nifrajs/core/server"
@@ -28,7 +28,7 @@ type FormEntries = ReturnType<FormData["getAll"]>
 /** The route registry baked into a server's type (`typeof app`). */
 type RegistryOf<App> = App extends Server<infer R, infer _Ctx> ? R : never
 
-/** Every route path the app declares — constrains `Path`, so a wrong path is itself a type error. */
+/** Every route path the app declares - constrains `Path`, so a wrong path is itself a type error. */
 export type RoutePaths<App> = keyof RegistryOf<App> & string
 
 /** The body object type of `App`'s `Method Path` route (`never` when the route declares no body). */
@@ -42,7 +42,7 @@ export type RouteBody<
     : never
   : never
 
-/** The valid field names for that route's body — the schema's keys as a string union. */
+/** The valid field names for that route's body - the schema's keys as a string union. */
 export type FieldKey<App, Path extends string, Method extends string> = [
   RouteBody<App, Path, Method>,
 ] extends [never]
@@ -53,13 +53,13 @@ export type FieldKey<App, Path extends string, Method extends string> = [
 export type FieldProps = Record<string, unknown>
 
 export interface FormHandle<App, Path extends string, Method extends string> {
-  /** Input props for a schema field. `name` is constrained to the body's keys — a typo, or a field the
+  /** Input props for a schema field. `name` is constrained to the body's keys - a typo, or a field the
    * schema doesn't have, is a COMPILE error. Spread onto an element: `<input {...f.field("text")} />`. */
   field<K extends FieldKey<App, Path, Method>>(
     name: K,
     props?: FieldProps,
   ): FieldProps & { name: K }
-  /** `formData.get`, key-constrained to the body's fields — reading an orphan key won't compile. */
+  /** `formData.get`, key-constrained to the body's fields - reading an orphan key won't compile. */
   read<K extends FieldKey<App, Path, Method>>(form: FormData, name: K): FormEntry
   /** `formData.getAll`, key-checked the same way. */
   readAll<K extends FieldKey<App, Path, Method>>(form: FormData, name: K): FormEntries

package/src/fs.ts

@@ -1,5 +1,5 @@
 /**
- * @nifrajs/web/fs — filesystem route discovery. Separated from the main entry so `app.fetch`
+ * @nifrajs/web/fs - filesystem route discovery. Separated from the main entry so `app.fetch`
  * (and the rest of @nifrajs/web) stays fs-free + edge-portable: this runs at build/startup
  * only. It scans a routes dir and feeds the pure `buildManifest`.
  */
@@ -8,7 +8,7 @@ import { buildManifest, type Manifest, type RouteModule } from "./manifest.ts"
 
 /** Options for {@link discoverRoutes}. */
 export interface DiscoverRoutesOptions {
-  /** Appended (as `?<importQuery>`) to each route's dynamic import — the dev server sets a
+  /** Appended (as `?<importQuery>`) to each route's dynamic import - the dev server sets a
    * changing value to bust Bun's module cache so SSR picks up edited route files. Ignored when
    * {@link load} is supplied, which does its own cache handling. */
   readonly importQuery?: string