npm - @nifrajs/web - Versions diffs - 3.1.0 → 3.2.0 - Mend

@nifrajs/web 3.1.0 → 3.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (114) hide show

package/dist/build-plan.d.ts +228 -0
package/dist/build-plan.d.ts.map +1 -0
package/dist/build-plan.js +514 -0
package/dist/build-plan.js.map +1 -0
package/dist/build-vite.d.ts +2 -1
package/dist/build-vite.d.ts.map +1 -1
package/dist/build-vite.js.map +1 -1
package/dist/build.d.ts +2 -197
package/dist/build.d.ts.map +1 -1
package/dist/build.js +61 -502
package/dist/build.js.map +1 -1
package/dist/chunk-names.d.ts.map +1 -1
package/dist/chunk-names.js +3 -2
package/dist/chunk-names.js.map +1 -1
package/dist/dev-ssr-graph.d.ts.map +1 -1
package/dist/dev-ssr-graph.js +63 -28
package/dist/dev-ssr-graph.js.map +1 -1
package/dist/diagnostic.d.ts.map +1 -1
package/dist/diagnostic.js +9 -2
package/dist/diagnostic.js.map +1 -1
package/dist/fonts-google.d.ts.map +1 -1
package/dist/fonts-google.js +3 -1
package/dist/fonts-google.js.map +1 -1
package/dist/fs.d.ts.map +1 -1
package/dist/fs.js +2 -1
package/dist/fs.js.map +1 -1
package/dist/index.d.ts +15 -609
package/dist/index.d.ts.map +1 -1
package/dist/index.js +22 -1935
package/dist/index.js.map +1 -1
package/dist/internal/codegen.d.ts +68 -0
package/dist/internal/codegen.d.ts.map +1 -0
package/dist/internal/codegen.js +317 -0
package/dist/internal/codegen.js.map +1 -0
package/dist/internal/head-merge.d.ts +2 -0
package/dist/internal/head-merge.d.ts.map +1 -1
package/dist/internal/head-merge.js +17 -1
package/dist/internal/head-merge.js.map +1 -1
package/dist/internal/parity.d.ts +7 -0
package/dist/internal/parity.d.ts.map +1 -1
package/dist/internal/parity.js +212 -30
package/dist/internal/parity.js.map +1 -1
package/dist/internal/render-document.d.ts +372 -0
package/dist/internal/render-document.d.ts.map +1 -0
package/dist/internal/render-document.js +744 -0
package/dist/internal/render-document.js.map +1 -0
package/dist/internal/runtime-contract.d.ts +48 -0
package/dist/internal/runtime-contract.d.ts.map +1 -0
package/dist/internal/runtime-contract.js +27 -0
package/dist/internal/runtime-contract.js.map +1 -0
package/dist/internal/web-app.d.ts +171 -0
package/dist/internal/web-app.d.ts.map +1 -0
package/dist/internal/web-app.js +844 -0
package/dist/internal/web-app.js.map +1 -0
package/dist/islands.d.ts +48 -0
package/dist/islands.d.ts.map +1 -1
package/dist/islands.js +79 -0
package/dist/islands.js.map +1 -1
package/dist/module-graph.d.ts.map +1 -1
package/dist/module-graph.js +22 -9
package/dist/module-graph.js.map +1 -1
package/dist/nano.d.ts +125 -0
package/dist/nano.d.ts.map +1 -0
package/dist/nano.js +190 -0
package/dist/nano.js.map +1 -0
package/dist/plugins/css-modules.js +2 -2
package/dist/plugins/css-modules.js.map +1 -1
package/dist/plugins/kit.d.ts +12 -0
package/dist/plugins/kit.d.ts.map +1 -1
package/dist/plugins/kit.js +62 -12
package/dist/plugins/kit.js.map +1 -1
package/dist/plugins/postcss.js +2 -2
package/dist/plugins/postcss.js.map +1 -1
package/dist/plugins/scss.js +2 -2
package/dist/plugins/scss.js.map +1 -1
package/dist/plugins/stylex.d.ts +70 -0
package/dist/plugins/stylex.d.ts.map +1 -0
package/dist/plugins/stylex.js +166 -0
package/dist/plugins/stylex.js.map +1 -0
package/dist/plugins/svg.js +2 -2
package/dist/plugins/svg.js.map +1 -1
package/dist/router.d.ts +1 -1
package/dist/router.js +23 -23
package/dist/router.js.map +1 -1
package/dist/vite.d.ts.map +1 -1
package/dist/vite.js +26 -10
package/dist/vite.js.map +1 -1
package/package.json +39 -3
package/src/build-plan.ts +741 -0
package/src/build-vite.ts +1 -4
package/src/build.ts +84 -716
package/src/chunk-names.ts +3 -2
package/src/dev-ssr-graph.ts +63 -28
package/src/diagnostic.ts +14 -2
package/src/fonts-google.ts +3 -1
package/src/fs.ts +2 -1
package/src/index.ts +73 -2705
package/src/internal/codegen.ts +400 -0
package/src/internal/head-merge.ts +19 -1
package/src/internal/parity.ts +215 -35
package/src/internal/render-document.ts +1116 -0
package/src/internal/runtime-contract.ts +54 -0
package/src/internal/web-app.ts +1114 -0
package/src/islands.ts +85 -0
package/src/module-graph.ts +23 -9
package/src/nano.ts +246 -0
package/src/plugins/css-modules.ts +2 -2
package/src/plugins/kit.ts +65 -12
package/src/plugins/postcss.ts +2 -2
package/src/plugins/scss.ts +2 -2
package/src/plugins/stylex.ts +298 -0
package/src/plugins/svg.ts +2 -2
package/src/router.ts +24 -24
package/src/vite.ts +33 -9

package/dist/internal/render-document.d.ts ADDED Viewed

@@ -0,0 +1,372 @@
+import { type ResponseResult } from "@nifrajs/core/server";
+import type { BoundaryRegistration, BoundaryStates } from "../boundary.js";
+import type { Loader as LayoutLoader, LinkDescriptor, Meta, MetaDescriptor, MetaInput, RouteModule, ScriptDescriptor, UnsafeScriptDescriptor } from "../manifest.js";
+import type { RenderAdapter } from "../render-seam.js";
+type MaybePromise<T> = T | Promise<T>;
+declare const RESPONSE_RESULT: unique symbol;
+/** A returned/thrown value that ends the request as-is: either shape of control-flow signal. */
+export declare const isControlFlow: (value: unknown) => value is Response | ResponseResult;
+export interface RenderedPage {
+    readonly [RESPONSE_RESULT]: true;
+    toResponse(): Response;
+    toNodeBody?(): {
+        readonly status: number;
+        readonly headers: Readonly<Record<string, string | readonly string[]>> | undefined;
+        readonly body: string | Uint8Array;
+    };
+}
+export interface RenderPageOptions {
+    readonly adapter: RenderAdapter;
+    /** The layout chain to render - outermost layout → page (opaque; the adapter renders it). */
+    readonly chain: readonly unknown[];
+    /** The loader output for this request. */
+    readonly data: unknown;
+    /** An action's data return (POST only) - surfaced to the page as `actionData` + serialized
+     * for the client so post-POST hydration matches. Omit on GETs. */
+    readonly actionData?: unknown;
+    /**
+     * URL of the built client entry (loaded as a module script).
+     *
+     * Optional ONLY on a `hydrate: false` page, where there is no client takeover to feed and this value
+     * reaches no output at all. The union below is what enforces that: omitting it on a hydrating page
+     * stays a compile error rather than rendering `src=""`.
+     */
+    readonly clientEntry?: string;
+    /** Chunk URLs for the **matched** route (its layout chain + own chunk) to `modulepreload` in the
+     * shell - so the route code downloads in parallel with the entry instead of after it
+     * (`buildClient`'s per-route map). Empty/omitted ⇒ only the entry is preloaded (unchanged). */
+    readonly preload?: readonly string[];
+    /** Stylesheet URLs for the **matched** route (its layout chain + own CSS, from `buildClient`'s
+     * `BuildManifest.css`) - injected as `<link rel="stylesheet">` in `<head>` so styles arrive with the
+     * first paint (no FOUC). Rendered even on non-hydrated pages. Empty/omitted ⇒ none (unchanged). */
+    readonly styles?: readonly string[];
+    /** SSG: the prerendered-path set, serialized to `window.__NIFRA_PRERENDERED__` so the client fetches
+     * a static `_data.json` on soft-nav into a prerendered route. Empty/omitted ⇒ not injected. */
+    readonly prerenderedPaths?: readonly string[];
+    /** ISR: route freshness in seconds, emitted as the `x-nifra-isr-revalidate` header for a `withISR`
+     * wrapper to read. Omit ⇒ no header (the wrapper's default TTL applies). */
+    readonly revalidate?: number;
+    /** ISR invalidation tags emitted as a bounded `x-nifra-isr-tags` header. */
+    readonly revalidateTags?: readonly string[];
+    /** Matched route id; written to `window.__NIFRA_ROUTE__` so the client hydrates this chain. */
+    readonly routeId?: string;
+    /** The matched route's decoded path params - surfaced to the page as `params` (via {@link RenderProps})
+     * so an adapter's `useParams` is SSR-correct. Omit ⇒ `{}` (a route with no dynamic segments, or an
+     * error/404 render). */
+    readonly params?: Readonly<Record<string, string>>;
+    /** The request's `pathname + search` - surfaced as `path` (via {@link RenderProps}) so an adapter's
+     * `useLocation`/`useSearchParams` render the right URL server-side and hydrate without drift. Omit ⇒
+     * `""`. */
+    readonly path?: string;
+    /** The route's validated search (`searchOf(mod.searchSchema, url.search)`, the same value handed to
+     * the loader as `ctx.search`), surfaced as `search` (via {@link RenderProps}) so an adapter's
+     * `useSearch` is SSR-correct. Omit ⇒ `{}` (a render with no search context). */
+    readonly search?: Record<string, unknown>;
+    /** Per-layout loader data, forwarded to the adapter as `RenderProps.layoutData`. Aligned with the
+     * chain's layout prefix; omitted when no layout in the chain has a loader. */
+    readonly layoutData?: readonly unknown[];
+    /** Dynamic-boundary states, forwarded to the adapter and serialized for hydration when present. */
+    readonly boundaries?: BoundaryStates;
+    /** HTTP status for the response (default 200; e.g. 404 for a not-found page). */
+    readonly status?: number;
+    /** Extra response headers - e.g. the `cache-control` a terminal status page wants. `content-type`
+     * is ignored (the document is always HTML) and the ISR freshness header is applied after these,
+     * so neither can be overridden from here. */
+    readonly headers?: HeadersLike;
+    /** Document title (fallback when `head.title` is unset). */
+    readonly title?: string;
+    /** Resolved route head - `title` overrides `title` above; `meta`/`link` render as managed
+     * (`data-nifra`) tags the client updates on navigation.
+     *
+     * **Head contract (the layout chain contributes).** `createWebApp` resolves this via
+     * {@link mergeHeads}: a route's head is its **layout chain's** `meta`/`head` exports merged with the
+     * page's. A `_layout.tsx` may `export const meta` (or `export function meta(args)`) - its tags land
+     * on every page below it (the home for `hreflang`, `preconnect`, a section-default `<title>`). The
+     * merge is **nearest-wins for scalars** (the page's `title` overrides an inner layout's, which
+     * overrides an outer one; an undefined page title keeps the layout's) and **concatenated for the
+     * `meta`/`link` arrays** (outermost layout first, page last). `<meta>`/`<link>` attributes pass a
+     * shared tag-specific allowlist (including inert `data-*` metadata) and values are escaped. */
+    readonly head?: Meta;
+    /** Id of the container wrapping the app markup (default `"root"`). A non-default id also gets
+     * {@link ROOT_ATTRIBUTE}, which is how the generated client entry finds the container to hydrate -
+     * the entry is built once and cannot know what a given render chose. */
+    readonly rootId?: string;
+    /** When `false`, emit a complete but **non-hydrated** document - no client entry script, data
+     * globals, or modulepreloads. Used for server-rendered `_error` pages: a terminal state that needs no
+     * client takeover, and it sidesteps an SSR/hydrate mismatch (the server rendered the boundary, not
+     * the page the client manifest maps this route id to). Default `true`. */
+    readonly hydrate?: boolean;
+    /** Island client bundles (`@nifrajs/web/islands`) to load as `<script type="module">` in the document
+     * tail - emitted **regardless of `hydrate`**, so a static (`hydrate: false`) page can still mount
+     * no-framework islands. URLs are attribute-escaped. Empty/omitted ⇒ none (unchanged output). */
+    readonly islandScripts?: readonly string[];
+    /** CSP nonce applied to every framework-owned executable script in this document. */
+    readonly nonce?: string;
+    /**
+     * Advanced: a per-route slot the renderer fills with the request-invariant document pieces (shell
+     * prefix/suffix, tail statics) on the first render and reuses afterwards, skipping their re-assembly.
+     *
+     * Only pass a cache when every shell-shaping input is IDENTICAL across the requests sharing it:
+     * same `head` content (a static meta chain - never a `meta(data)` function), `title`, `styles`,
+     * `preload`, `islandScripts`, `clientEntry`, `rootId`, `hydrate`, and `prerenderedPaths`. Per-request
+     * values (`data`, `params`, `search`, `actionData`, `layoutData`, deferred state) are always assembled
+     * fresh and safe. A per-request `nonce` disables the cache automatically. `createWebApp` wires this
+     * per route, gated on the route + layout metas being static.
+     */
+    readonly assemblyCache?: RenderAssemblyCache;
+}
+/** The mutable per-route slot {@link RenderPageOptions.assemblyCache} fills. Opaque - create as `{}`. */
+export interface RenderAssemblyCache {
+    /** Shell up to (not including) the deferred-runtime insertion point. */
+    shellPre?: string;
+    /** Shell from after the deferred-runtime insertion point through the open `#root` container. */
+    shellPost?: string;
+    /** Tail opener: the inline script open tag + the route-id global (before the action global). */
+    tailPre?: string;
+    /** Tail mid: the prerendered-paths global (between the action and layout-data globals). */
+    tailMid?: string;
+    /** Tail data prefix: the `window.<data global>=` assignment head. */
+    tailData?: string;
+    /** Tail from after the serialized data through `</html>`. */
+    tailPost?: string;
+}
+/**
+ * `renderPage` input. A hydrating page (the default) must supply `clientEntry`, because the document
+ * loads it as a module script; a `hydrate: false` page may omit it, because nothing in the emitted
+ * document references it. Expressed as a union so the compiler enforces the pairing rather than the
+ * renderer discovering an empty `src` at runtime.
+ */
+export type RenderPageInput = RenderPageOptions & ({
+    readonly hydrate?: true;
+    readonly clientEntry: string;
+} | {
+    readonly hydrate: false;
+});
+/**
+ * Server: render a full HTML document for a page - the adapter's hydration head + the SSR
+ * markup (**streamed**) + the serialized loader data + the client module - as a `Response`.
+ * The shell (`<head>` + the open container) flushes first, the adapter's app stream follows,
+ * then the tail (data globals + client entry). Pure Web Standards, so it returns straight from
+ * a nifra route handler and streams on any fetch runtime (Bun/Node/Deno/Workers).
+ */
+export declare function renderPage(options: RenderPageInput): MaybePromise<Response>;
+export declare function renderPageResult(options: RenderPageInput): MaybePromise<RenderedPage>;
+/** Options for {@link redirect}. */
+export interface RedirectOptions {
+    /** HTTP status (default 303 See Other; pass 307/308 to preserve the method). */
+    readonly status?: number;
+    /** Allow an off-origin / absolute destination. Off by default: only a same-origin path (a single
+     * leading `/`) is permitted, so an action can't be turned into an open redirect by passing
+     * attacker-controlled input straight through. Set `true` for a deliberate external redirect. */
+    readonly external?: boolean;
+    /** Extra response headers. A redirect is no longer a `Response`, so there is no `.headers` to
+     * mutate after the fact - name them here. Cookies still ride `c.set`, as on any other response. */
+    readonly headers?: Readonly<Record<string, string>>;
+}
+/** A same-origin destination is an absolute path: one leading `/`, but NOT `//` (protocol-relative →
+ * another origin), and nothing a URL parser resolves off-origin. Everything else (absolute URL with
+ * a scheme, `//host`, `javascript:`, a bare relative `foo`) requires `external: true`. The predicate
+ * lives in the kernel - see `isSameOriginPath` - so this gate and the auth guards' `redirectTo`
+ * cannot drift apart. */
+/**
+ * Build a redirect - return it from a route `action` for the Post/Redirect/Get pattern (POST
+ * mutates, 303 sends the browser to a fresh GET, so a reload doesn't re-submit). Defaults to 303
+ * (See Other); pass `{ status: 307 }` or `{ status: 308 }` to preserve the method.
+ *
+ * **Secure by default:** `location` must be a same-origin path (begins with `/`, not `//`). An
+ * off-origin/absolute destination throws unless you pass `{ external: true }` - this closes the
+ * open-redirect footgun of `return redirect(formData.get("next"))` on the no-JS (native-form) path,
+ * which serves the action's control-flow value verbatim.
+ *
+ * Returns a plain render, not a `Response`. A redirect is a status line and one header - the most
+ * body-less response there is - and building a `Response` for it costs the whole Web object plus, on
+ * Node, a stream drained back out. As data it renders on the same lane a handler's return takes.
+ * `redirect(...)` is still returned or thrown from exactly the same places; only `.status` /
+ * `.headers` are gone from the value, replaced by `options.headers` and the request's `c.set`.
+ *
+ * @param options redirect status, extra headers, and whether an off-origin destination is intentional.
+ */
+export declare function redirect(location: string, options?: RedirectOptions): ResponseResult;
+/**
+ * Brand marking a `Response` as a **terminal-status signal** rather than a response to serve verbatim.
+ *
+ * A loader that throws a bare `Response` has always been passed straight through - that is how
+ * `throw redirect(...)` works, and apps rely on it. So "render the `_404` boundary at 404" cannot be
+ * expressed by throwing a plain `Response`: the framework would have no way to tell it apart from a
+ * hand-rolled body the app wants served exactly as written. The brand is that distinction, and
+ * checking it *before* the pass-through is what keeps every existing throw working unchanged.
+ *
+ * `Symbol.for` matches `RESPONSE_RESULT` above: a registry symbol survives two copies of this module,
+ * which a `unique symbol` would not - and a duplicate-install turning a 404 into a raw 404 body would
+ * be a maddening bug to trace.
+ */
+/** Derived from the `Headers` constructor rather than the DOM lib's `HeadersInit`: `@nifrajs/web`
+ * is consumed from DOM-free programs (the root tsconfig runs `types: ["bun"]`), and naming the DOM
+ * type here would break their build. Same workaround as `SSEInit.headers` in core. */
+export type HeadersLike = ConstructorParameters<typeof Headers>[0];
+/**
+ * Append the likely cause to an SSR error that carries a duplicate-instance signature.
+ *
+ * Deliberately does NOT claim the resolved paths: `@nifrajs/web` is framework-agnostic and does not
+ * depend on React, so it cannot resolve the copies without guessing. It names the condition and the
+ * command that reports the paths, which is the actionable part. Returns the error untouched when the
+ * signature does not match, so an ordinary render error reads exactly as before.
+ */
+export declare function withDuplicateInstanceHint(err: unknown): unknown;
+/**
+ * An action's control-flow value passes straight through - except a redirect on a client-submit data
+ * request: fetch would follow the 3xx into HTML the client can't use, so the redirect rides the
+ * X-Nifra-Redirect header on a 204 and the client navigates. One conversion shared by the returned-
+ * and thrown- paths, so `return redirect()` and `throw redirect()` agree.
+ *
+ * Takes either shape: `redirect()` is a plain render, while a hand-rolled `new Response(...)` from an
+ * action still arrives as a `Response`. The rewrite stays on the lane its input was on - a plain
+ * redirect converts to a plain 204, and never materializes the `Response` it is replacing.
+ */
+export declare function actionResponse(result: Response | ResponseResult, isDataRequest: boolean): Response | ResponseResult;
+/** A loaded layout module. `loader`/`gate` are the layout-loader surface; `meta` predates it. */
+export type LoadedLayoutModules = ReadonlyArray<{
+    default: unknown;
+    meta?: MetaInput;
+    loader?: LayoutLoader;
+    action?: unknown;
+    gate?: boolean;
+    searchSchema?: RouteModule["searchSchema"];
+    boundaries?: readonly BoundaryRegistration[];
+}>;
+/**
+ * Narrow the route's params to the ones a layout owns.
+ *
+ * A layout wraps a URL prefix, so anything deeper belongs to a route beneath it. Handing it the full
+ * set would let a layout read a param it does not own - which reads fine until the layout is reused
+ * under a route that has no such param and the value silently becomes `undefined`.
+ */
+export declare function scopeParams(params: Record<string, string>, owned: readonly string[] | undefined): Record<string, string>;
+export declare const EMPTY_RETAIN: ReadonlySet<number>;
+export declare const tagLayoutError: (err: unknown, layoutId: string) => unknown;
+export declare const layoutErrorId: (err: unknown) => string | undefined;
+export declare const STATUS_SIGNAL: unique symbol;
+/** Reason phrases for the plain-text fallback, used only when the app authored no `_<status>` and no
+ * `_404` page. Deliberately not exhaustive - anything unlisted falls back to "Error", which is more
+ * useful than shipping a table of every RFC status for a body almost nobody will see. */
+export declare const STATUS_TEXT: Readonly<Record<number, string>>;
+export interface StatusSignal extends Response {
+    readonly [STATUS_SIGNAL]: {
+        readonly status: number;
+        readonly headers?: HeadersLike;
+    };
+}
+export declare function isStatusSignal(value: unknown): value is StatusSignal;
+/** Options shared by {@link notFound}, {@link gone}, and {@link statusPage}. */
+export interface StatusPageOptions {
+    /**
+     * Extra headers for the rendered response - `cache-control` above all.
+     *
+     * The defaults differ by status for a reason: a 404 may be a race with publication, so it wants a
+     * short TTL, while a 410 is a promise that the URL is permanently gone and can be cached hard.
+     * Getting this wrong is the difference between a crawler dropping a dead URL and re-fetching it
+     * for weeks.
+     */
+    readonly headers?: HeadersLike;
+}
+/**
+ * Render the nearest `_404` page at status **404**. `throw` it from a loader when the record does not
+ * exist.
+ *
+ * This is the fix for the soft 404: a matched route whose loader finds nothing has otherwise no way to
+ * answer 404, so the path of least resistance is to return empty data and render "not found" inside a
+ * **200**. That looks correct in a browser and is invisible in review, which is why it ships and stays
+ * shipped - while search engines penalise it and keep the dead URL indexed.
+ *
+ * Returns `never`: these throw, so a loader narrows without a redundant `return`, and the type states
+ * the thing the "loaders `throw` redirect, actions `return` it" rule already trips people on.
+ */
+export declare function notFound(options?: StatusPageOptions): never;
+/**
+ * Render a terminal page at status **410 Gone**. `throw` it from a loader for a record that existed and
+ * was deliberately removed - a withdrawn listing, a deleted post.
+ *
+ * 410 is not a pedantic 404: it tells a crawler to **drop** the URL rather than re-fetch it for weeks
+ * on the assumption the 404 was transient. Uses `_410.tsx` if the app has one, otherwise `_404`.
+ */
+export declare function gone(options?: StatusPageOptions): never;
+/**
+ * Render a terminal page at any 4xx/5xx status - the escape hatch behind {@link notFound} and
+ * {@link gone} (402, 451, …). Uses `_<status>.tsx` if present, otherwise `_404`.
+ */
+export declare function statusPage(status: number, options?: StatusPageOptions): never;
+/** The wrapper `revalidate()` returns: the action's `data` plus the paths it changed. A plain tagged
+ * shape (not a class) so `@nifrajs/client`'s `ActionData` can unwrap it structurally without importing
+ * from `@nifrajs/web`. `createWebApp` strips the wrapper - the client receives `data` as the body and
+ * the paths via the `X-Nifra-Revalidate` header. */
+export interface RevalidateResult<T> {
+    readonly __nifraRevalidate: readonly string[];
+    readonly data: T;
+}
+/**
+ * Return this from an action to declare which routes the mutation changed (alongside the action's
+ * `data`). `createWebApp` sets the `X-Nifra-Revalidate` response header; after the submit the client
+ * marks those cached routes stale - refetching the active one and any mounted fetcher showing them -
+ * so a mutation can refresh views beyond the one that was submitted. `data` is still surfaced to the
+ * component as `actionData` (the wrapper is transparent to `ActionData<typeof action>`).
+ */
+export declare function revalidate<T>(paths: readonly string[], data: T): RevalidateResult<T>;
+/**
+ * Serialize loader data for embedding inside an inline `<script>`. `JSON.stringify` alone
+ * is NOT safe there: a string containing `</script>` or `<!--` would break out of the
+ * script element (an XSS vector). Escape `<`/`>` to `\uXXXX`, plus the U+2028/U+2029
+ * separators.
+ */
+export declare function serializeData(data: unknown): string;
+/**
+ * A `<link rel="canonical">` descriptor for a route's `meta.link`. The canonical URL tells search
+ * engines which URL is authoritative for a page (deduping query-string / tracking variants).
+ *
+ * ```ts
+ * export const meta = (a) => ({ link: [canonical(`https://site.com/posts/${a.params.slug}`)] })
+ * ```
+ */
+export declare function canonical(href: string): LinkDescriptor;
+/** Inputs for {@link openGraph} - the common Open Graph properties. All optional; only the provided
+ * ones become tags. `type` defaults to `"website"`. */
+export interface OpenGraphInput {
+    readonly title?: string;
+    readonly description?: string;
+    /** Absolute URL of the share image (`og:image`). */
+    readonly image?: string;
+    /** Canonical URL of the page (`og:url`). */
+    readonly url?: string;
+    /** Object type (`og:type`) - `"website"`, `"article"`, … Default `"website"`. */
+    readonly type?: string;
+}
+/**
+ * Build the Open Graph `<meta property="og:*">` entries for a route's `meta.meta`. Returns only the
+ * properties you supplied (plus `og:type`, defaulting to `"website"`), so it composes with other meta.
+ *
+ * ```ts
+ * export const meta = { meta: [...openGraph({ title: "Nifra", image: "https://site.com/og.png" })] }
+ * ```
+ */
+export declare function openGraph(input: OpenGraphInput): MetaDescriptor[];
+/**
+ * Build a JSON-LD `<script type="application/ld+json">` entry for a route's `meta.script` from a plain
+ * object. `JSON.stringify` produces the body; the head renderer breakout-escapes it (see
+ * `escapeScriptContent`), so a string field containing `</script>` is embedded safely.
+ *
+ * ```ts
+ * export const meta = {
+ *   script: [jsonLd({ "@context": "https://schema.org", "@type": "Article", headline: "Hi" })],
+ * }
+ * ```
+ */
+export declare function jsonLd(data: Record<string, unknown>): ScriptDescriptor;
+/**
+ * Deliberately unsafe escape hatch for executable inline code. The required nonce keeps the result
+ * compatible with a strict CSP and makes the security-sensitive choice visible at the call site.
+ */
+export declare function unsafeInlineScript(content: string, options: {
+    readonly nonce: string;
+    readonly type?: "module" | "text/javascript";
+}): UnsafeScriptDescriptor;
+export {};
+//# sourceMappingURL=render-document.d.ts.map

package/dist/internal/render-document.d.ts.map ADDED Viewed

@@ -0,0 +1 @@

+ {"version":3,"file":"render-document.d.ts","sourceRoot":"","sources":["../../src/internal/render-document.ts"],"names":[],"mappings":"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"}