# `html/render-shell` — ReDoc HTML shell renderer

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

## Purpose

This module exposes `renderRedocShell`, the pure function that produces the
ReDoc HTML shell consumed by both the global and per-plugin handlers. It
embeds the OpenAPI document URL into a `<redoc spec-url="…">` custom element,
ships a JSON option island for the runtime to read, and injects the runtime
runtime asset reference based on the chosen asset strategy. Keeping the
renderer separate from the handler factories lets host operators embed the
shell in custom adapters (e.g. SSR, Edge functions) without reaching for the
handler builder.

## Features

- HTML-escapes every user-supplied value (`title`, `openapiUrl`, etc.) so
  option strings cannot break out of attribute or text-node scope.
- Inlines the runtime body when `strategy === "inline"` and emits a
  `<script src="…">` tag for `cdn` / `bundled` strategies.
- Embeds `theme`, `hideDownloadButton`, `nativeScrollbars`, and
  `expandResponses` into the JSON options island the runtime reads.
- Tags the body element with `data-redoc-theme` so external stylesheets can
  override the colour scheme.
- Pure — no I/O, no clocks, no globals.

## Usage: Basic

```ts
import { renderRedocShell } from "@suaveplan/api-openapi-ui-redoc/html";
import {
    parseRedocUiOptions,
    resolveRedocAsset,
} from "@suaveplan/api-openapi-ui-redoc";

const html = renderRedocShell({
    options: parseRedocUiOptions({ openapiUrl: "/openapi.json" }),
    resolvedAsset: resolveRedocAsset({ strategy: "cdn" }),
});
```

## Usage: Advanced

Pre-render the shell for a multi-tenant host that picks up the OpenAPI URL
from the request path:

```ts
import { renderRedocShell } from "@suaveplan/api-openapi-ui-redoc/html";

const options = parseRedocUiOptions({ openapiUrl: "/openapi.json", theme: "dark" });
const resolvedAsset = resolveRedocAsset({ strategy: "cdn" });

function htmlForTenant(tenant: string): string {
    return renderRedocShell({
        options,
        resolvedAsset,
        openapiUrlOverride: `/${tenant}/openapi.json`,
    });
}
```

## API Reference

| Symbol                   | Kind | Description |
| ------------------------ | ---- | ----------- |
| `RenderRedocShellInput`  | type | `{ options, resolvedAsset, openapiUrlOverride? }` |
| `renderRedocShell`       | fn   | Render the HTML shell as a string |

## Implementation Notes

The escape function covers the five HTML special characters (`&`, `<`, `>`,
`"`, `'`) plus the apostrophe — the same surface as the WHATWG HTML
serialization-attribute rules. The JSON island is serialised via
`JSON.stringify` and HTML-escaped so embedded `</script>` sequences in
option values cannot escape the `<script>` context. The shell's bottom-of-
body initialiser calls `window.Redoc.init` when the runtime defines it,
falling back gracefully when the runtime is unavailable (e.g. during DOM
unit tests that don't load the standalone bundle).