# Schema visualization

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

The visualization module renders a `BitPackerSchema` into one of five inspection-friendly formats — JSON, HTML, Markdown, plain text, or Graphviz DOT — for tooling, documentation, and debugging. Schemas are JSON-serialisable but their nested structure (objects of `_optional`, `_oneOf`, `_conditional`, primitive tokens, arrays) is fiddly to read at scale; this module produces a renderable tree view that surfaces the structure at a glance. It is the layer that downstream developer tools (schema explorers, doc generators, registry UIs) consume to display the contents of the registry without parsing the schema themselves.

## Features

- Five output formats (`SchemaVisualizationFormat`): `JSON`, `HTML`, `MARKDOWN`, `TEXT`, `DOT`.
- Configurable via `SchemaVisualizationOptions` (format, depth limit, include/exclude metadata).
- Recursive descent through nested objects, arrays, and the `_optional` / `_oneOf` / `_conditional` operators.
- Recognises the canonical primitive tokens (UUID, float, integer, string).

## Usage: Basic Example

```ts
import {
  visualizeSchema,
  SchemaVisualizationFormat,
} from "@suaveplan/bitpacker-schema";

const html = visualizeSchema(
  { name: "-16", age: 255, tags: [{ _optional: "-32" }] },
  { format: SchemaVisualizationFormat.HTML }
);
```

## Usage: Advanced Example

```ts
import {
  visualizeSchema,
  SchemaVisualizationFormat,
} from "@suaveplan/bitpacker-schema";

// Render a Graphviz DOT graph for a docs site.
const dot = visualizeSchema(playerSchema, {
  format: SchemaVisualizationFormat.DOT,
  maxDepth: 5,
});
// Pipe through `dot -Tsvg` to produce an SVG of the schema tree.
```

## API Reference

### `enum SchemaVisualizationFormat`

`JSON | HTML | MARKDOWN | TEXT | DOT` — pick the renderer to apply.

### `interface SchemaVisualizationOptions`

- `format?: SchemaVisualizationFormat` — default `JSON`.
- `maxDepth?: number` — recursion depth limit; deeper nodes render as `…`.
- `includeMetadata?: boolean` — include `description`, `tags`, etc. when present.

### `visualizeSchema(schema, options?): string`

Renders the schema as a string in the requested format. Returns valid syntax for the chosen format (parseable JSON, render-ready HTML, etc.).

## Implementation Notes

- HTML output is intentionally semantic (`<details>` / `<summary>` for nesting) so the result is keyboard-navigable and accessible without extra CSS.
- DOT output names every node deterministically (path-based IDs) so two renders of the same schema produce identical graphs — useful for regression-diffing schema docs.
- The renderer handles cycles via a max-depth limit, not via cycle detection. `BitPackerSchema` is a tree by construction, but `_ref` lookups can produce structural cycles; in practice the `maxDepth` ceiling keeps the renderer linear.