# `handler.ts` — `createSwaggerUiHandler` factory

<!-- begin:auto-docs -->
_(no submodules)_
<!-- end:auto-docs -->

## Purpose

This module exposes the primary entry point of `@suaveplan/api-openapi-ui-swagger`: a factory that returns an HTTP handler serving the Swagger UI HTML shell. The factory composes three earlier modules — options validation, asset resolution, and HTML rendering — into a single call site that the host's router can mount under `/docs/ui/swagger`.

Construction is eager: validation, asset resolution, and shell rendering all happen at factory-call time. The returned handler is therefore an O(1) lookup that returns a pre-baked response. That puts all the failure modes (`INVALID_OPTIONS`, `ASSETS_MISSING`) at boot, where operators see them, never at first request.

## Features

- `createSwaggerUiHandler({ openapiUrl, ...options })` — returns a `SwaggerUiHandler`.
- `createSwaggerUiHandlerArtifacts(...)` — handler plus parsed options for hosts that want introspection.
- Strict response headers: `Content-Type: text/html; charset=utf-8`, `X-Content-Type-Options: nosniff`, `Referrer-Policy: no-referrer`.
- Pure handler — identical bytes returned on every call (no per-request work).
- Eager validation at boot time.

## Usage: Basic

```ts
import { createSwaggerUiHandler } from "@suaveplan/api-openapi-ui-swagger/handler";

const handler = createSwaggerUiHandler({ openapiUrl: "/openapi.json" });
const response = handler();
// response.status === 200; response.body is the rendered HTML
```

## Usage: Advanced

```ts
import { createSwaggerUiHandlerArtifacts } from "@suaveplan/api-openapi-ui-swagger/handler";

const { handler, options } = createSwaggerUiHandlerArtifacts({
    openapiUrl: "/openapi.json",
    title: "Acme — Customer API",
    theme: "dark",
    tryItOutEnabled: false,
    uiAssets: "bundled",
    assetBasePath: "/docs/ui/swagger/assets",
});

// `options` is the parsed, defaults-applied record; host can log it.
console.log("[swagger-ui] mounted", options.title, options.uiAssets);

// `handler` is a pure function — call it from every route adapter.
const res = handler();
void res;
```

## API Reference

- `interface CreateSwaggerUiHandlerInput extends SwaggerUiOptionsInput { openapiUrl: string; assetBasePath?: string }`.
- `interface SwaggerUiResponse { status; headers; body }`.
- `type SwaggerUiHandler = () => SwaggerUiResponse`.
- `createSwaggerUiHandler(input): SwaggerUiHandler`.
- `createSwaggerUiHandlerArtifacts(input): { handler; options; openapiUrl }`.

## Implementation Notes

The factory is eager by design. The alternative — lazy validation per request — would let operators ship misconfigured handlers that look healthy until a doc-fetch arrives. The package picks reliability over latency: a single render per handler at boot.

`assetBasePath` is required when `uiAssets = "bundled"`; omitting it raises `OPENAPI_UI_SWAGGER.ASSETS_MISSING` via `resolveAssets`. The factory does not infer a base path because the host owns the asset-route mount point — guessing would create cross-host inconsistency.

The returned `SwaggerUiResponse` is an adapter-agnostic record. Hosts running on Hono call `c.html(body, status, headers)`; hosts on the in-memory router pass the record straight back; hosts on Node's `http` write `(status, headers, body)` directly. Avoiding `Response` keeps the package universal.