# `error-codes.ts` — `OPENAPI_UI_SWAGGER.*` registry

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

## Purpose

This module owns the stable error-code registry for `@suaveplan/api-openapi-ui-swagger`. Every public failure path raises an `OpenapiUiSwaggerError` carrying one of the two namespaced codes, so consumers can discriminate without parsing message strings. The codes survive across releases and form part of the public contract; renaming one is a breaking change.

The registry is built via `defineCodes("OPENAPI_UI_SWAGGER", [...])` from `@suaveplan/error`. The resulting object freezes the code map at module load, so attempts to mutate it from outside throw immediately. The companion `OpenapiUiSwaggerError` widens the `SuaveplanError` constructor to `public` (no factory required) and re-exposes the parsed code on a `swaggerUiCode` accessor for narrowing in `instanceof` branches.

## Features

- Two-entry registry: `ASSETS_MISSING`, `INVALID_OPTIONS`.
- `OpenapiUiSwaggerCode` union literal type derived from the registry.
- `OpenapiUiSwaggerError` extending `SuaveplanError<OpenapiUiSwaggerCode>`.
- Side-effect import from `src/index.ts` so consumers picking up the package barrel get the registry initialised.

## Usage: Basic

```ts
import {
    OPENAPI_UI_SWAGGER_CODES,
    OpenapiUiSwaggerError,
} from "@suaveplan/api-openapi-ui-swagger/error-codes";

throw new OpenapiUiSwaggerError(
    OPENAPI_UI_SWAGGER_CODES.INVALID_OPTIONS,
    "theme must be one of 'light' | 'dark' | 'system'"
);
```

## Usage: Advanced

```ts
import { OpenapiUiSwaggerError } from "@suaveplan/api-openapi-ui-swagger/error-codes";

try {
    bootSwaggerUi(configFromOperator);
} catch (err) {
    if (
        err instanceof OpenapiUiSwaggerError &&
        err.swaggerUiCode === "ASSETS_MISSING"
    ) {
        // Fall back to a remote-CDN profile and report the gap.
        return bootSwaggerUi({ ...configFromOperator, uiAssets: "cdn" });
    }
    throw err;
}
```

## API Reference

- `OPENAPI_UI_SWAGGER_CODES: Readonly<Record<"ASSETS_MISSING"|"INVALID_OPTIONS", string>>`.
- `type OpenapiUiSwaggerCode = "OPENAPI_UI_SWAGGER.ASSETS_MISSING" | "OPENAPI_UI_SWAGGER.INVALID_OPTIONS"`.
- `class OpenapiUiSwaggerError extends SuaveplanError<OpenapiUiSwaggerCode>` — public constructor `(code, message, options?)`.

## Implementation Notes

Adding a new code is a public-API change: bump the package version and add a `**Verified by:**` entry in the spec for the throw site that emits it. Removing a code is a breaking change.

The registry is intentionally tiny — Swagger UI is a presentation surface and most failures are configuration mistakes (caught by `INVALID_OPTIONS`) or asset-pipeline gaps (caught by `ASSETS_MISSING`). The conformance gate (`conformance.ts`) walks the registry and asserts each code is thrown from at least one non-test source file in this package.