# `ScalarUiOptions` — Zod-validated configuration

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

## Purpose

The options module owns the single Zod schema consumed by every Scalar
UI handler factory. It is exposed both directly (`scalarUiOptionsSchema`)
and via the convenience `parseScalarUiOptions(input)` helper that wraps
the underlying `ZodError` in an `OpenapiUiScalarError` tagged with
`OPENAPI_UI_SCALAR.INVALID_OPTIONS`. This double-surface lets host
config ingestion decide whether to surface raw Zod issues or rely on the
package's stable error-code contract.

## Features

- Required `openapiUrl` field (with default `/openapi.json`).
- Endpoint defaults match design doc §7 (`/docs/ui/scalar`).
- Eleven built-in `theme` literals matching the upstream Scalar palette.
- `layout` literals `"modern" | "classic"`.
- `assetMode` literals `"cdn" | "bundled"` toggling the runtime asset
  resolution path.
- `cdnUrl` defaults to the upstream JSDelivr URL of
  `@scalar/api-reference`.
- `editorOptions` is an open passthrough bag for upstream Scalar config
  options the schema does not enumerate.
- `.strict()` rejects unknown keys so typos surface at host-config load.

## Usage: Basic

```ts
import { parseScalarUiOptions } from "@suaveplan/api-openapi-ui-scalar/options";

const opts = parseScalarUiOptions({ openapiUrl: "/openapi.json" });
console.log(opts.uiEndpoint); // "/docs/ui/scalar"
```

## Usage: Advanced

```ts
import {
    parseScalarUiOptions,
    scalarUiOptionsSchema,
} from "@suaveplan/api-openapi-ui-scalar/options";

// Schema can be composed with host-config layers — every default is
// safe in the empty-object case so the schema can be merged with other
// host config without surprises.
const hostSchema = scalarUiOptionsSchema.extend({
    enabled: scalarUiOptionsSchema.shape.darkMode,
});

const parsed = parseScalarUiOptions({
    openapiUrl: "/v1/openapi.json",
    theme: "deepSpace",
    layout: "classic",
    assetMode: "bundled",
});
```

## API Reference

- `scalarUiOptionsSchema` — Zod object schema, `.strict()`.
- `parseScalarUiOptions(input?)` — returns the resolved `ScalarUiOptions`
  or throws `OpenapiUiScalarError(INVALID_OPTIONS)`.
- `SCALAR_THEMES` / `SCALAR_LAYOUTS` / `SCALAR_ASSET_MODES` — literal
  unions backing the schema enums.
- `ScalarUiOptions` / `ScalarUiOptionsInput` — output / input types.

## Implementation Notes

The schema uses Zod `.default()` on every optional field so the empty
`{}` case round-trips to a complete options object. The `.strict()` mode
is essential — host operators frequently mistype keys (e.g. `themes` vs
`theme`) and the strict guard surfaces those at boot rather than at
first request. `INVALID_OPTIONS` wraps `safeParse` failures so the error
chain preserves the underlying issue list for log/telemetry consumers.