first commit

docs/foundation/bitpacker/bitpacker-schema/src/visualization/visualization.md

@@ -0,0 +1,67 @@
+# 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.