scriptorium/docs/API.md

# API

Scriptorium is a library with one package and five exported functions. The
signatures below are the whole public surface; everything else lives under
`internal/` and reaches no caller. `go doc sourcedock.dev/petrbalvin/scriptorium`
is the authority on the signatures, and this file explains what each function
does, when it fails, and where the edges of the rendered surfaces are.

## Library

### `Render(source []byte) []byte`

Renders Markdown to HTML. The grammar is CommonMark 0.31.2 in full, with the
GitHub Flavored Markdown extensions on top: tables, strikethrough, task lists
and extended autolinks, plus footnotes and definition lists. Rendering never
fails and never returns an error: any input parses, and a construct the
grammar does not know stays in the output as literal text.

The extended autolinks supersede three CommonMark examples: a bare
`www.`/`http(s)://`/`ftp://` address or a bare email address becomes a link
where CommonMark without the extension would leave it as text. That is the
specification's own trade, and GitHub's reference implementation makes it
too.

```go
html := scriptorium.Render([]byte("# Title\n\nText with [a link](/uri).\n"))
```

The Markdown engine embeds no mathematics and no diagrams: a `$…$` run stays
what the CommonMark grammar says it is. A consumer that wants mathematics
inside its documents calls `RenderMath` on the math spans it recognises and
splices the results into the HTML itself.

### `RenderMath(source []byte) []byte`

Renders TeX mathematics to a complete MathML Core `<math>` element in the
inline form. Returns one line of markup with the namespace declared, ready to
embed in HTML. Never fails: see the degradation contract below.

### `RenderMathDisplay(source []byte) []byte`

The display form: the same engine, with `display="block"` on the element and
the movable limits of big operators set above and below instead of beside.

### `RenderDiagram(source []byte) ([]byte, error)`

Renders Mermaid source to a self-contained SVG document. The first line names
the diagram type; only two families are carried:

- `flowchart` and its historical `graph` alias, with any direction
  (`TB`/`TD`, `BT`, `LR`, `RL`), every node shape, every edge kind, subgraphs
  with their own direction, and the `classDef`, `class`, `style` and
  `linkStyle` statements;
- `sequenceDiagram`, with participants and actors, all arrow kinds, notes,
  activations in both spellings, the `alt`, `opt`, `loop`, `par`, `critical`
  and `break` blocks, coloured `rect` regions, `autonumber` and dividers.

Returns an error when the type is outside the two families, when a direction
is unknown, or when a statement does not parse; every error names the diagram
type or the source line, so the author can find the sentence at fault. The
`click` statement is refused on purpose: the SVG is static and carries no
interactivity.

### `SupportedDiagram(kind string) bool`

Reports whether `RenderDiagram` carries the named Mermaid type. It answers
the question the error path would answer, before the call.

## What every function guarantees

- **Determinism.** The same input produces byte-identical output on every
  call, in every process, on every machine. No layout decision reads a map
  iteration order; the tests assert byte equality across repeated renders.
- **No sanitisation.** The input is trusted, and the output is written to
  HTML, MathML or SVG verbatim. Whether the output may reach a given audience
  is the consumer's policy: a consumer of untrusted input keeps its own
  sanitiser and applies it to the rendered result.
- **Concurrency safety.** The engines hold no state between calls and share
  nothing, so every function is safe for concurrent use.
- **No dependencies.** The standard library alone; there is no `go.sum`
  because there is nothing to sum.

## The mathematics surface

The mathematics engine renders the standard TeX command surface that maps
into MathML Core, measured against the coverage list of KaTeX as the external
standard: the Greek letters including the variants, the relation and operator
tables including the negations and the colon relations, the arrows including
the extensible `\x` family, the big operators, the delimiters, the amsmath
environments, accents, the font and spacing commands, colours, and bounded
macros (`\newcommand`, `\renewcommand`, `\providecommand`, `\def`,
`\DeclareMathOperator`) with expansion limits.

Multi-character relations have no single Unicode character, so they render as
the linear two-character operators KaTeX's own MathML branch produces
(`\coloneqq` as `≔`, `\coloneq` as `:−`, `\Coloneqq` as `∷=`).

### Degradation, not failure

A construct outside the mappable surface degrades in place: the offending
command stays in the output as its verbatim source inside an `<merror>`
element, and the rest of the expression still renders. The author sees what
was not understood, in the document, at the place it happened.

The commands that degrade are the ones no MathML Core construct can carry:
positioning (`\raisebox`, `\vcenter`, `\smash`, the `\llap`/`\rlap`/
`\mathclap` family, `\kern`, `\mkern`, `\hskip`), boxes and overlays
(`\boxed`, `\colorbox`, `\fcolorbox`, `\sideset`), text annotations of the
page rather than the formula (`\tag`, `\label`, `\notag`, `\verb`,
`\char`, `\mathstrut`), and the environments outside the table family
(`\begin{CD}`, `\begin{tikzpicture}` and every other unknown name).
A macro whose expansion would not terminate is cut by the expansion limits
and degrades at the call site.

A degraded render is still a valid render: the output remains well-formed
MathML Core, and the tests assert well-formedness for every degraded corpus
case.

## Notes

The exported surface is documented in godoc form in the source, and `go doc ./...` is
the authority on signatures and types. This file explains what the surface is for and
how the parts fit together. It does not repeat the signatures, because a copy of a
signature is a future lie.