@daloyjs/core 1.0.0-beta.5 → 1.0.0-beta.7

package/dist/conn-info.d.ts

@@ -69,6 +69,9 @@ interface MutableConnInfo {
  * @internal Adapter helper — attach {@link ConnInfo} to a `Request`. Called
  * by the Node / Bun / Deno / Cloudflare / Vercel / Lambda adapters before
  * `app.fetch(request)`.
+ *
+ * @param request - Incoming request to tag (stored under a private symbol).
+ * @param info - Connection metadata gathered by the adapter.
  */
 export declare function setConnInfo(request: Request, info: ConnInfo): void;
 /**
@@ -76,6 +79,8 @@ export declare function setConnInfo(request: Request, info: ConnInfo): void;
  * `undefined` when the adapter does not expose connection metadata (e.g.
  * Cloudflare Workers without `cf` enabled).
  *
+ * @param request - Request previously tagged by {@link setConnInfo}.
+ * @returns The attached {@link ConnInfo}, or `undefined` when absent.
  * @since 0.24.0
  */
 export declare function getConnInfo(request: Request): ConnInfo | undefined;
@@ -83,6 +88,9 @@ export declare function getConnInfo(request: Request): ConnInfo | undefined;
  * Refuses-at-construction on malformed {@link BehindProxyConfig}. Called once
  * during `new App({ behindProxy })`.
  *
+ * @param cfg - Proxy posture to validate; `undefined` is accepted as "unset".
+ * @throws Error when `hops` is not an integer in [0, 64], when `cidrs` is
+ *   empty or contains non-string entries, or when the shape is unrecognized.
  * @since 0.24.0
  */
 export declare function assertBehindProxy(cfg: BehindProxyConfig | undefined): void;
@@ -93,6 +101,10 @@ export declare function assertBehindProxy(cfg: BehindProxyConfig | undefined): v
  * `undefined` when the header is shorter than the configured hop count
  * (caller falls back to the immediate peer).
  *
+ * @param header - Raw `X-Forwarded-For` header value, or `null` when absent.
+ * @param hops - Declared number of trusted proxy hops (must be >= 1).
+ * @returns The client IP at the declared hop, or `undefined` when the chain
+ *   is too short or `hops < 1`.
  * @internal
  */
 export declare function pickForwardedForByHops(header: string | null, hops: number): string | undefined;
@@ -102,6 +114,10 @@ export declare function pickForwardedForByHops(header: string | null, hops: numb
  * available (the caller — rate-limit, ipRestriction, audit-log — must fail
  * closed rather than guess).
  *
+ * @param request - Incoming request whose client IP should be resolved.
+ * @param cfg - The app's `behindProxy` posture; `undefined` behaves as `"none"`.
+ * @returns The trusted client IP, or `undefined` when neither the peer
+ *   address nor a trusted `X-Forwarded-For` slot is available.
  * @since 0.24.0
  */
 export declare function resolveClientIp(request: Request, cfg: BehindProxyConfig | undefined): string | undefined;
@@ -110,11 +126,28 @@ export declare function resolveClientIp(request: Request, cfg: BehindProxyConfig
  * `undefined` rather than allocating a plain object so the IP cannot be
  * serialized into logs by accident.
  *
+ * @param ctx - Request context whose adapter-attached {@link ConnInfo} is read.
+ * @returns The immediate peer address, or `undefined` when the adapter did
+ *   not attach connection metadata.
  * @since 0.24.0
  */
 export declare function readRemoteAddress(ctx: BaseContext<any, any>): string | undefined;
-/** @since 0.24.0 */
+/**
+ * Lazy accessor for `ctx.remotePort` (the immediate peer's TCP port).
+ *
+ * @param ctx - Request context whose adapter-attached {@link ConnInfo} is read.
+ * @returns The immediate peer port, or `undefined` when the adapter did not
+ *   attach connection metadata.
+ * @since 0.24.0
+ */
 export declare function readRemotePort(ctx: BaseContext<any, any>): number | undefined;
-/** @internal Test-only helper. */
+/**
+ * Test-only helper that shallow-copies a {@link ConnInfo} into a mutable shape
+ * so tests can tweak fields without casting away `readonly`.
+ *
+ * @param info - Connection metadata to copy.
+ * @returns A mutable shallow copy of `info`.
+ * @internal
+ */
 export declare function _makeConnInfoForTests(info: ConnInfo): MutableConnInfo;
 export {};

package/dist/conn-info.js

@@ -23,6 +23,9 @@ const CONN_INFO_SYMBOL = Symbol.for("daloyjs.connInfo");
  * @internal Adapter helper — attach {@link ConnInfo} to a `Request`. Called
  * by the Node / Bun / Deno / Cloudflare / Vercel / Lambda adapters before
  * `app.fetch(request)`.
+ *
+ * @param request - Incoming request to tag (stored under a private symbol).
+ * @param info - Connection metadata gathered by the adapter.
  */
 export function setConnInfo(request, info) {
     request[CONN_INFO_SYMBOL] = info;
@@ -32,6 +35,8 @@ export function setConnInfo(request, info) {
  * `undefined` when the adapter does not expose connection metadata (e.g.
  * Cloudflare Workers without `cf` enabled).
  *
+ * @param request - Request previously tagged by {@link setConnInfo}.
+ * @returns The attached {@link ConnInfo}, or `undefined` when absent.
  * @since 0.24.0
  */
 export function getConnInfo(request) {
@@ -41,6 +46,9 @@ export function getConnInfo(request) {
  * Refuses-at-construction on malformed {@link BehindProxyConfig}. Called once
  * during `new App({ behindProxy })`.
  *
+ * @param cfg - Proxy posture to validate; `undefined` is accepted as "unset".
+ * @throws Error when `hops` is not an integer in [0, 64], when `cidrs` is
+ *   empty or contains non-string entries, or when the shape is unrecognized.
  * @since 0.24.0
  */
 export function assertBehindProxy(cfg) {
@@ -76,6 +84,10 @@ export function assertBehindProxy(cfg) {
  * `undefined` when the header is shorter than the configured hop count
  * (caller falls back to the immediate peer).
  *
+ * @param header - Raw `X-Forwarded-For` header value, or `null` when absent.
+ * @param hops - Declared number of trusted proxy hops (must be >= 1).
+ * @returns The client IP at the declared hop, or `undefined` when the chain
+ *   is too short or `hops < 1`.
  * @internal
  */
 export function pickForwardedForByHops(header, hops) {
@@ -97,6 +109,10 @@ export function pickForwardedForByHops(header, hops) {
  * available (the caller — rate-limit, ipRestriction, audit-log — must fail
  * closed rather than guess).
  *
+ * @param request - Incoming request whose client IP should be resolved.
+ * @param cfg - The app's `behindProxy` posture; `undefined` behaves as `"none"`.
+ * @returns The trusted client IP, or `undefined` when neither the peer
+ *   address nor a trusted `X-Forwarded-For` slot is available.
  * @since 0.24.0
  */
 export function resolveClientIp(request, cfg) {
@@ -129,16 +145,33 @@ export function resolveClientIp(request, cfg) {
  * `undefined` rather than allocating a plain object so the IP cannot be
  * serialized into logs by accident.
  *
+ * @param ctx - Request context whose adapter-attached {@link ConnInfo} is read.
+ * @returns The immediate peer address, or `undefined` when the adapter did
+ *   not attach connection metadata.
  * @since 0.24.0
  */
 export function readRemoteAddress(ctx) {
     return getConnInfo(ctx.request)?.remoteAddress;
 }
-/** @since 0.24.0 */
+/**
+ * Lazy accessor for `ctx.remotePort` (the immediate peer's TCP port).
+ *
+ * @param ctx - Request context whose adapter-attached {@link ConnInfo} is read.
+ * @returns The immediate peer port, or `undefined` when the adapter did not
+ *   attach connection metadata.
+ * @since 0.24.0
+ */
 export function readRemotePort(ctx) {
     return getConnInfo(ctx.request)?.remotePort;
 }
-/** @internal Test-only helper. */
+/**
+ * Test-only helper that shallow-copies a {@link ConnInfo} into a mutable shape
+ * so tests can tweak fields without casting away `readonly`.
+ *
+ * @param info - Connection metadata to copy.
+ * @returns A mutable shallow copy of `info`.
+ * @internal
+ */
 export function _makeConnInfoForTests(info) {
     return { ...info };
 }

package/dist/contract.d.ts

@@ -44,6 +44,8 @@ export interface ContractTestOptions {
  * routes don't carry body schemas by accident, and that `meta.examples`
  * reference declared response statuses.
  *
+ * @param app The {@link App} whose registered routes are inspected.
+ * @param opts Check toggles ({@link ContractTestOptions}); `requireOperationId` defaults to `true`.
  * @returns A {@link ContractReport}. In CI, exit non-zero when `report.ok` is `false`.
  */
 export declare function runContractTests(app: App, opts?: ContractTestOptions): Promise<ContractReport>;

package/dist/contract.js

@@ -19,6 +19,8 @@ import { validate } from "./schema.js";
  * routes don't carry body schemas by accident, and that `meta.examples`
  * reference declared response statuses.
  *
+ * @param app The {@link App} whose registered routes are inspected.
+ * @param opts Check toggles ({@link ContractTestOptions}); `requireOperationId` defaults to `true`.
  * @returns A {@link ContractReport}. In CI, exit non-zero when `report.ok` is `false`.
  */
 export async function runContractTests(app, opts = {}) {

package/dist/cookie.d.ts

@@ -84,6 +84,11 @@ export declare function assertCookieAttributes(input: {
  * The value is URI-encoded so binary signature bytes and base64 padding
  * round-trip safely.
  *
+ * @param name Cookie name; `__Host-`/`__Secure-` prefixes are enforced by validation.
+ * @param value Cookie value; URI-encoded before serialization.
+ * @param attributes Cookie attributes. Defaults: `SameSite=Strict`, `Secure`, `HttpOnly`, `Path=/`.
+ * @returns A single `Set-Cookie` header value.
+ * @throws Error if the name or attributes fail {@link assertCookieAttributes} validation.
  * @since 0.27.0
  */
 export declare function serializeCookie(name: string, value: string, attributes?: CookieAttributes): string;
@@ -92,6 +97,10 @@ export declare function serializeCookie(name: string, value: string, attributes?
  * `Max-Age=0` per RFC 6265 §5.2.2 and preserves the original attributes so
  * intermediaries match the original cookie when deciding what to delete.
  *
+ * @param name Name of the cookie to clear.
+ * @param attributes Attributes of the original cookie; must match for deletion to apply.
+ * @returns A `Set-Cookie` header value with an empty value and `Max-Age=0`.
+ * @throws Error if the name or attributes fail {@link assertCookieAttributes} validation.
  * @since 0.27.0
  */
 export declare function serializeClearCookie(name: string, attributes?: CookieAttributes): string;
@@ -118,6 +127,9 @@ export declare function serializeClearCookie(name: string, attributes?: CookieAt
  * parser-level guard is defense-in-depth for developers who customize the
  * cookie name or read other cookies through this helper.
  *
+ * @param header The raw `Cookie` request header, or `null`/`undefined` when absent.
+ * @param name Exact cookie name to read (case-sensitive).
+ * @returns The decoded cookie value, or `null` when absent or duplicated.
  * @since 0.27.0
  */
 export declare function readRequestCookie(header: string | null | undefined, name: string): string | null;

package/dist/cookie.js

@@ -96,6 +96,11 @@ export function assertCookieAttributes(input) {
  * The value is URI-encoded so binary signature bytes and base64 padding
  * round-trip safely.
  *
+ * @param name Cookie name; `__Host-`/`__Secure-` prefixes are enforced by validation.
+ * @param value Cookie value; URI-encoded before serialization.
+ * @param attributes Cookie attributes. Defaults: `SameSite=Strict`, `Secure`, `HttpOnly`, `Path=/`.
+ * @returns A single `Set-Cookie` header value.
+ * @throws Error if the name or attributes fail {@link assertCookieAttributes} validation.
  * @since 0.27.0
  */
 export function serializeCookie(name, value, attributes = {}) {
@@ -125,6 +130,10 @@ export function serializeCookie(name, value, attributes = {}) {
  * `Max-Age=0` per RFC 6265 §5.2.2 and preserves the original attributes so
  * intermediaries match the original cookie when deciding what to delete.
  *
+ * @param name Name of the cookie to clear.
+ * @param attributes Attributes of the original cookie; must match for deletion to apply.
+ * @returns A `Set-Cookie` header value with an empty value and `Max-Age=0`.
+ * @throws Error if the name or attributes fail {@link assertCookieAttributes} validation.
  * @since 0.27.0
  */
 export function serializeClearCookie(name, attributes = {}) {
@@ -170,6 +179,9 @@ export function serializeClearCookie(name, attributes = {}) {
  * parser-level guard is defense-in-depth for developers who customize the
  * cookie name or read other cookies through this helper.
  *
+ * @param header The raw `Cookie` request header, or `null`/`undefined` when absent.
+ * @param name Exact cookie name to read (case-sensitive).
+ * @returns The decoded cookie value, or `null` when absent or duplicated.
  * @since 0.27.0
  */
 export function readRequestCookie(header, name) {

package/dist/dependency.d.ts

@@ -31,6 +31,7 @@ export interface DependencyOptions<TName extends string, TValue, TStateKey exten
 }
 /** Hooks bundle returned by {@link defineDependency} (carries metadata). */
 export interface DependencyHooks extends Hooks {
+    /** Non-enumerable dependency metadata (`name` + `dependsOn`) used for dedup and cycle checks. */
     readonly [DEPENDENCY_MARKER]: {
         readonly name: string;
         readonly dependsOn: readonly string[];
@@ -42,6 +43,9 @@ export interface DependencyHooks extends Hooks {
  * `ctx.state[stateKey]` (default `name`). Composing the same dependency
  * twice in one chain runs `resolve()` exactly once.
  *
+ * @param opts - Dependency `name`, optional `dependsOn` / `stateKey`, and the `resolve` function.
+ * @returns A {@link DependencyHooks} bundle to compose via `app.use()` / route hooks.
+ * @throws {Error} When `name` is empty or the dependency declares itself in `dependsOn` (cycle).
  * @since 0.24.0
  */
 export declare function defineDependency<TName extends string, TValue, TStateKey extends string = TName>(opts: DependencyOptions<TName, TValue, TStateKey>): DependencyHooks;

package/dist/dependency.js

@@ -21,6 +21,9 @@ const RESULTS_KEY = Symbol.for("daloyjs.dependency.results");
  * `ctx.state[stateKey]` (default `name`). Composing the same dependency
  * twice in one chain runs `resolve()` exactly once.
  *
+ * @param opts - Dependency `name`, optional `dependsOn` / `stateKey`, and the `resolve` function.
+ * @returns A {@link DependencyHooks} bundle to compose via `app.use()` / route hooks.
+ * @throws {Error} When `name` is empty or the dependency declares itself in `dependsOn` (cycle).
  * @since 0.24.0
  */
 export function defineDependency(opts) {

package/dist/discriminator.d.ts

@@ -27,6 +27,11 @@ export interface DiscriminatorObject {
  * Build an OpenAPI 3.1 Discriminator Object. Throws on an empty
  * `propertyName` so misconfigurations fail at boot rather than producing a
  * silently invalid spec.
+ *
+ * @param propertyName Name of the property that selects the variant schema.
+ * @param mapping Optional explicit discriminator-value-to-$ref map.
+ * @returns A {@link DiscriminatorObject} ready to embed in an OpenAPI schema.
+ * @throws TypeError if `propertyName` is not a non-empty string.
  */
 export declare function discriminator(propertyName: string, mapping?: Record<string, string>): DiscriminatorObject;
 /** Options for {@link discriminatedUnion}. */
@@ -68,6 +73,14 @@ export type DiscriminatedUnion<V extends Record<string, StandardSchemaV1>> = Sta
  * const Cat = z.object({ kind: z.literal("cat"), meow: z.boolean() });
  * const Dog = z.object({ kind: z.literal("dog"), bark: z.boolean() });
  * const Animal = discriminatedUnion("kind", { cat: Cat, dog: Dog });
+ *
+ * @param propertyName Discriminator property read off the incoming value.
+ * @param variants Map from discriminator value to variant schema. Only own
+ *   properties are consulted, so prototype names like `constructor` cannot
+ *   be abused to bypass variant lookup.
+ * @param opts Optional {@link DiscriminatedUnionOptions} (explicit `mapping`, `vendor`).
+ * @returns A {@link DiscriminatedUnion} usable as validator and OpenAPI emitter.
+ * @throws TypeError if `propertyName` is empty or `variants` has no entries.
  */
 export declare function discriminatedUnion<P extends string, V extends Record<string, StandardSchemaV1>>(propertyName: P, variants: V, opts?: DiscriminatedUnionOptions): DiscriminatedUnion<V>;
 export {};

package/dist/discriminator.js

@@ -19,6 +19,11 @@
  * Build an OpenAPI 3.1 Discriminator Object. Throws on an empty
  * `propertyName` so misconfigurations fail at boot rather than producing a
  * silently invalid spec.
+ *
+ * @param propertyName Name of the property that selects the variant schema.
+ * @param mapping Optional explicit discriminator-value-to-$ref map.
+ * @returns A {@link DiscriminatorObject} ready to embed in an OpenAPI schema.
+ * @throws TypeError if `propertyName` is not a non-empty string.
  */
 export function discriminator(propertyName, mapping) {
     if (typeof propertyName !== "string" || propertyName.length === 0) {
@@ -35,6 +40,14 @@ export function discriminator(propertyName, mapping) {
  * const Cat = z.object({ kind: z.literal("cat"), meow: z.boolean() });
  * const Dog = z.object({ kind: z.literal("dog"), bark: z.boolean() });
  * const Animal = discriminatedUnion("kind", { cat: Cat, dog: Dog });
+ *
+ * @param propertyName Discriminator property read off the incoming value.
+ * @param variants Map from discriminator value to variant schema. Only own
+ *   properties are consulted, so prototype names like `constructor` cannot
+ *   be abused to bypass variant lookup.
+ * @param opts Optional {@link DiscriminatedUnionOptions} (explicit `mapping`, `vendor`).
+ * @returns A {@link DiscriminatedUnion} usable as validator and OpenAPI emitter.
+ * @throws TypeError if `propertyName` is empty or `variants` has no entries.
  */
 export function discriminatedUnion(propertyName, variants, opts) {
     if (typeof propertyName !== "string" || propertyName.length === 0) {
@@ -71,7 +84,16 @@ export function discriminatedUnion(propertyName, variants, opts) {
                     ],
                 };
             }
-            const variant = variants[discriminatorValue];
+            // Only accept an OWN property of the variant map. A bare
+            // `variants[discriminatorValue]` lookup would resolve inherited
+            // `Object.prototype` members (`constructor`, `toString`, `valueOf`,
+            // `hasOwnProperty`, `__proto__`, …) to a truthy non-variant, slipping
+            // past the `!variant` guard below; the subsequent `variant["~standard"]`
+            // access then throws an uncaught `TypeError` that the app surfaces as an
+            // unauthenticated 500 (and error-log flood) instead of a clean 400.
+            const variant = Object.hasOwn(variants, discriminatorValue)
+                ? variants[discriminatorValue]
+                : undefined;
             if (!variant) {
                 return {
                     issues: [

package/dist/docs.d.ts

@@ -24,72 +24,129 @@ export type ScalarTheme = "alternate" | "default" | "moon" | "purple" | "solariz
  */
 export interface ScalarReferenceConfiguration {
     [key: string]: ScalarJsonValue | undefined;
+    /** Built-in color theme name. See {@link ScalarTheme}. */
     theme?: ScalarTheme;
+    /** Extra CSS injected into the reference UI. */
     customCss?: string;
+    /** Start the UI in dark mode. */
     darkMode?: boolean;
+    /** Pin the color scheme and hide the user's ability to change it. */
     forceDarkModeState?: "dark" | "light";
+    /** Load Scalar's default fonts (Inter/JetBrains Mono) from its CDN. */
     withDefaultFonts?: boolean;
+    /** URL of the favicon shown in the browser tab. */
     favicon?: string;
+    /** Overall page layout: `"modern"` (default) or `"classic"`. */
     layout?: "modern" | "classic";
+    /** Hide the "Open API Client" button. */
     hideClientButton?: boolean;
+    /** Hide the dark-mode toggle. */
     hideDarkModeToggle?: boolean;
+    /** Hide the Models (schemas) section. */
     hideModels?: boolean;
+    /** Hide the search bar. */
     hideSearch?: boolean;
+    /** Hide the "Test Request" button on operations. */
     hideTestRequestButton?: boolean;
+    /** Show each operation's `operationId` next to its title. */
     showOperationId?: boolean;
+    /** Show the navigation sidebar. */
     showSidebar?: boolean;
+    /** When to expose Scalar's developer tools panel. */
     showDeveloperTools?: "always" | "localhost" | "never";
+    /** Expand the first tag's operations on load. */
     defaultOpenFirstTag?: boolean;
+    /** Expand every tag's operations on load. */
     defaultOpenAllTags?: boolean;
+    /** Expand all model (schema) sections on load. */
     expandAllModelSections?: boolean;
+    /** Expand all response sections on load. */
     expandAllResponses?: boolean;
+    /** Which spec download button(s) to offer, or `"none"` to hide them. */
     documentDownloadType?: "json" | "yaml" | "both" | "direct" | "none";
+    /** Label operations by their `summary` or by their `path`. */
     operationTitleSource?: "summary" | "path";
+    /** List required schema properties before optional ones. */
     orderRequiredPropertiesFirst?: boolean;
+    /** Sort schema properties alphabetically or keep spec order. */
     orderSchemaPropertiesBy?: "alpha" | "preserve";
+    /** Keyboard key that focuses search, e.g. `"k"` for Ctrl/Cmd+K. */
     searchHotKey?: string;
+    /** Base URL prepended to relative server URLs in the spec. */
     baseServerURL?: string;
+    /** Proxy URL used by "Test Request" calls to avoid CORS issues. */
     proxyUrl?: string;
+    /** Redirect URI used by the OAuth2 authorization-code flow. */
     oauth2RedirectUri?: string;
+    /** Persist entered credentials in browser storage across reloads. */
     persistAuth?: boolean;
+    /** Enable Scalar's anonymous usage telemetry. */
     telemetry?: boolean;
+    /** Sort tags alphabetically. */
     tagsSorter?: "alpha";
+    /** Sort operations alphabetically or by HTTP method. */
     operationsSorter?: "alpha" | "method";
+    /** Prefill security-scheme credentials (JSON-only Scalar `authentication` object). */
     authentication?: {
         [key: string]: ScalarJsonValue | undefined;
     };
+    /** Snippet target preselected in the client picker, e.g. `{ targetKey, clientKey }`. */
     defaultHttpClient?: {
         [key: string]: ScalarJsonValue | undefined;
     };
+    /** Extra HTML meta tags (title, description, Open Graph, ...) for the page. */
     metaData?: {
         [key: string]: ScalarJsonValue | undefined;
     };
+    /** Scalar MCP integration settings (JSON-only). */
     mcp?: {
         [key: string]: ScalarJsonValue | undefined;
     };
+    /** Use path-based routing for deep links, e.g. `{ basePath }`. */
     pathRouting?: {
         [key: string]: ScalarJsonValue | undefined;
     };
+    /** Override the spec's `servers` list shown in the UI. */
     servers?: ScalarJsonValue[];
+    /** Not serializable; the spec is always loaded from {@link DocsOptions.specUrl}. */
     content?: never;
+    /** Function-valued option; cannot cross the server-to-HTML boundary. */
     fetch?: never;
+    /** Function-valued option; cannot cross the server-to-HTML boundary. */
     generateHeadingSlug?: never;
+    /** Function-valued option; cannot cross the server-to-HTML boundary. */
     generateModelSlug?: never;
+    /** Function-valued option; cannot cross the server-to-HTML boundary. */
     generateOperationSlug?: never;
+    /** Function-valued option; cannot cross the server-to-HTML boundary. */
     generateTagSlug?: never;
+    /** Function-valued option; cannot cross the server-to-HTML boundary. */
     generateWebhookSlug?: never;
+    /** Function-valued callback; cannot cross the server-to-HTML boundary. */
     onBeforeRequest?: never;
+    /** Function-valued callback; cannot cross the server-to-HTML boundary. */
     onDocumentSelect?: never;
+    /** Function-valued callback; cannot cross the server-to-HTML boundary. */
     onLoaded?: never;
+    /** Function-valued callback; cannot cross the server-to-HTML boundary. */
     onRequestSent?: never;
+    /** Function-valued callback; cannot cross the server-to-HTML boundary. */
     onServerChange?: never;
+    /** Function-valued callback; cannot cross the server-to-HTML boundary. */
     onShowMore?: never;
+    /** Function-valued callback; cannot cross the server-to-HTML boundary. */
     onSidebarClick?: never;
+    /** Function-valued callback; cannot cross the server-to-HTML boundary. */
     onSpecUpdate?: never;
+    /** Function-valued Scalar plugins; cannot cross the server-to-HTML boundary. */
     plugins?: never;
+    /** Function-valued option; cannot cross the server-to-HTML boundary. */
     redirect?: never;
+    /** Multi-document sources are not serializable here; serve one spec per page. */
     sources?: never;
+    /** Internal URL wiring owned by DaloyJS. Use {@link DocsOptions.specUrl} instead. */
     spec?: never;
+    /** Internal URL wiring owned by DaloyJS. Use {@link DocsOptions.specUrl} instead. */
     url?: never;
 }
 /**
@@ -425,6 +482,10 @@ export interface HtmlResponseOptions extends DocsContentSecurityPolicyOptions {
  * The output is a single HTML document with configurable external assets;
  * pair it with {@link htmlResponse} (or your own `Response`) and serve from
  * any route.
+ *
+ * @param opts Spec URL, page title, asset overrides, CSP nonce, and Scalar configuration.
+ * @returns The complete HTML document as a string.
+ * @throws {TypeError} when an SRI integrity value or `auth.loginUrl` is invalid.
  */
 export declare function scalarHtml(opts: ScalarHtmlOptions): string;
 /**
@@ -434,6 +495,10 @@ export declare function scalarHtml(opts: ScalarHtmlOptions): string;
  * Developer-entered credentials are persisted by default
  * (`persistAuthorization: true`) so routes with OpenAPI security requirements
  * can be exercised after using Swagger UI's Authorize dialog.
+ *
+ * @param opts Spec URL, page title, asset overrides, CSP nonce, and Swagger UI configuration.
+ * @returns The complete HTML document as a string.
+ * @throws {TypeError} when an SRI integrity value or `auth.loginUrl` is invalid.
  */
 export declare function swaggerUiHtml(opts: SwaggerUiHtmlOptions): string;
 /**
@@ -448,6 +513,9 @@ export declare function swaggerUiHtml(opts: SwaggerUiHtmlOptions): string;
  * you). The spec URL and configuration are embedded with `<`-escaped JSON so
  * an attacker-controlled value cannot break out of the inline `<script>`.
  *
+ * @param opts Spec URL, page title, asset overrides, CSP nonce, and Redoc configuration.
+ * @returns The complete HTML document as a string.
+ * @throws {TypeError} when an SRI integrity value or `auth.loginUrl` is invalid.
  * @since 0.39.0
  */
 export declare function redocHtml(opts: RedocHtmlOptions): string;
@@ -465,6 +533,9 @@ export declare function redocHtml(opts: RedocHtmlOptions): string;
  * and configuration are embedded with `<`-escaped JSON so an attacker-controlled
  * value cannot break out of the inline `<script>`.
  *
+ * @param opts Spec URL, page title, asset overrides, CSP nonce, and AsyncAPI configuration.
+ * @returns The complete HTML document as a string.
+ * @throws {TypeError} when an SRI integrity value is invalid.
  * @since 0.42.0
  */
 export declare function asyncapiHtml(opts: AsyncApiHtmlOptions): string;
@@ -474,11 +545,18 @@ export declare function asyncapiHtml(opts: AsyncApiHtmlOptions): string;
  *
  * Allows `'self'` plus the listed `assetOrigins` (default: jsDelivr) and
  * either `'unsafe-inline'` or the provided `scriptNonce` for scripts.
+ *
+ * @param opts Asset/connect origins, script nonce, inline-style, and blob-worker toggles.
+ * @returns The policy string, ready for a `content-security-policy` header.
  */
 export declare function docsContentSecurityPolicy(opts?: DocsContentSecurityPolicyOptions): string;
 /**
  * Wrap a docs HTML string in a `Response` with safe defaults:
  * `text/html` content type, `nosniff`, `no-referrer`, and a CSP from
  * {@link docsContentSecurityPolicy} (or a caller-supplied override).
+ *
+ * @param html The HTML document body to serve.
+ * @param opts CSP options, or a verbatim `contentSecurityPolicy` override.
+ * @returns A `Response` with the HTML body and hardened security headers.
  */
 export declare function htmlResponse(html: string, opts?: HtmlResponseOptions): Response;

package/dist/docs.js

@@ -45,6 +45,10 @@ function integrityAttr(integrity, crossOrigin) {
  * The output is a single HTML document with configurable external assets;
  * pair it with {@link htmlResponse} (or your own `Response`) and serve from
  * any route.
+ *
+ * @param opts Spec URL, page title, asset overrides, CSP nonce, and Scalar configuration.
+ * @returns The complete HTML document as a string.
+ * @throws {TypeError} when an SRI integrity value or `auth.loginUrl` is invalid.
  */
 export function scalarHtml(opts) {
     const title = escapeHtml(opts.title ?? "API Reference");
@@ -71,6 +75,10 @@ ${docsAuthLauncherHtml(opts.auth, opts.scriptNonce)}
  * Developer-entered credentials are persisted by default
  * (`persistAuthorization: true`) so routes with OpenAPI security requirements
  * can be exercised after using Swagger UI's Authorize dialog.
+ *
+ * @param opts Spec URL, page title, asset overrides, CSP nonce, and Swagger UI configuration.
+ * @returns The complete HTML document as a string.
+ * @throws {TypeError} when an SRI integrity value or `auth.loginUrl` is invalid.
  */
 export function swaggerUiHtml(opts) {
     const title = escapeHtml(opts.title ?? "API Docs");
@@ -110,6 +118,9 @@ ${docsAuthLauncherHtml(opts.auth, opts.scriptNonce)}
  * you). The spec URL and configuration are embedded with `<`-escaped JSON so
  * an attacker-controlled value cannot break out of the inline `<script>`.
  *
+ * @param opts Spec URL, page title, asset overrides, CSP nonce, and Redoc configuration.
+ * @returns The complete HTML document as a string.
+ * @throws {TypeError} when an SRI integrity value or `auth.loginUrl` is invalid.
  * @since 0.39.0
  */
 export function redocHtml(opts) {
@@ -145,6 +156,9 @@ ${docsAuthLauncherHtml(opts.auth, opts.scriptNonce)}
  * and configuration are embedded with `<`-escaped JSON so an attacker-controlled
  * value cannot break out of the inline `<script>`.
  *
+ * @param opts Spec URL, page title, asset overrides, CSP nonce, and AsyncAPI configuration.
+ * @returns The complete HTML document as a string.
+ * @throws {TypeError} when an SRI integrity value is invalid.
  * @since 0.42.0
  */
 export function asyncapiHtml(opts) {
@@ -176,6 +190,9 @@ export function asyncapiHtml(opts) {
  *
  * Allows `'self'` plus the listed `assetOrigins` (default: jsDelivr) and
  * either `'unsafe-inline'` or the provided `scriptNonce` for scripts.
+ *
+ * @param opts Asset/connect origins, script nonce, inline-style, and blob-worker toggles.
+ * @returns The policy string, ready for a `content-security-policy` header.
  */
 export function docsContentSecurityPolicy(opts = {}) {
     const assetOrigins = opts.assetOrigins ?? [JSDELIVR_ORIGIN];
@@ -206,6 +223,10 @@ export function docsContentSecurityPolicy(opts = {}) {
  * Wrap a docs HTML string in a `Response` with safe defaults:
  * `text/html` content type, `nosniff`, `no-referrer`, and a CSP from
  * {@link docsContentSecurityPolicy} (or a caller-supplied override).
+ *
+ * @param html The HTML document body to serve.
+ * @param opts CSP options, or a verbatim `contentSecurityPolicy` override.
+ * @returns A `Response` with the HTML body and hardened security headers.
  */
 export function htmlResponse(html, opts = {}) {
     return new Response(html, {

package/dist/errors.d.ts

@@ -81,6 +81,7 @@ export declare const SAFE_CUSTOM_ERROR_RESPONSE_HEADERS: ReadonlySet<string>;
  * @since 0.32.0
  */
 export declare class MessageLeakError extends Error {
+    /** The refused headers, each with its name and the reason it was disallowed. */
     readonly offendingHeaders: ReadonlyArray<{
         name: string;
         reason: string;
@@ -93,6 +94,10 @@ export declare class MessageLeakError extends Error {
 /**
  * @internal — header-safety check applied by {@link httpError} when a custom
  * `res` is supplied. Exported for audits and tests.
+ *
+ * @param headers Headers of the caller-supplied custom error `Response`.
+ * @returns The disallowed headers (name plus refusal reason); an empty array
+ *   means every header passed the safe-error-response allowlist.
  */
 export declare function checkCustomErrorResponseHeaders(headers: Headers): Array<{
     name: string;
@@ -108,7 +113,9 @@ export declare function checkCustomErrorResponseHeaders(headers: Headers): Array
  * @since 0.32.0
  */
 export interface HttpErrorOptions {
+    /** HTTP status code for the rendered problem+json response. */
     status: number;
+    /** RFC 9457 problem document fields; `title` is required. */
     problem: Partial<ProblemDetails> & {
         title: string;
     };
@@ -136,6 +143,12 @@ export interface HttpErrorOptions {
  * Build an {@link HttpError} with optional safe-header extraction from a
  * custom `Response`. See {@link HttpErrorOptions}.
  *
+ * @param opts Status, problem document, plain headers, and the optional
+ *   custom `res` whose safe headers are merged (never overwriting
+ *   caller-supplied headers; `Content-Length` is always dropped).
+ * @returns The constructed {@link HttpError}, ready to be thrown.
+ * @throws MessageLeakError in production under `secureDefaults` when the
+ *   custom `res` carries headers outside the safe allowlist.
  * @since 0.32.0
  */
 export declare function httpError(opts: HttpErrorOptions): HttpError;
@@ -178,8 +191,11 @@ export declare function httpError(opts: HttpErrorOptions): HttpError;
  * @since 0.1.0
  */
 export declare class HttpError extends Error {
+    /** HTTP status code of the rendered response. */
     readonly status: number;
+    /** RFC 9457 problem document; `type` defaults to `https://httpstatuses.io/<status>`. */
     readonly problem: ProblemDetails;
+    /** Extra response headers (e.g. `Retry-After`, `Allow`) merged onto the response. */
     readonly headers?: Record<string, string>;
     constructor(status: number, problem: Partial<ProblemDetails> & {
         title: string;