---
title: "Implement it"
description: "What to build, in what order, to write a GistUI Format processor or renderer in another language, and how to prove it conforms."
---

> Documentation Index
> Fetch the complete documentation index at: https://gistui.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Implement it

The specification is written so that a second implementation is possible without reading the first. This is the order that works.

## A processor (Core profile)

1. **Line classifier and lexer**

   Split bytes into lines, handling LF, CRLF, CR and a byte-order mark. Classify each line (statement, table row, comment, fence, prose). Keep the lexer's state between chunks so it only ever scans new bytes. Sections 4 and 5.
2. **Statement parser**

   A recursive-descent or Pratt parser over the tokens of one statement. Apply the recovery rules as you go and record a diagnostic for each. Sections 6 to 8.
3. **Catalog**

   Load the manifest (`schemas/catalog.schema.json`). Build the derived sets: flag names, enum values per component, aliases. Implement the closest-name rule. Section 9.
4. **Binding arguments**

   Turn a parsed call into a node: resolve bare words, bind positional and named arguments, coerce values, collect children. Section 11. Then tables: section 12.
5. **The tree and edits**

   Assign node ids, build the tree, apply replace, patch, append and delete. Sections 13 and 14.
6. **End of stream**

   Close open brackets, drop unresolved references, break cycles, find the root, report unreachable statements. Order the diagnostics as section 22.2 requires. Section 15.
7. **Limits**

   Apply every processor limit of section 21.1. Test with hostile input: deep nesting, huge tables, a shared-reference graph.
8. **Run the suite**

   Every case, whole and one character at a time. See [Conformance](/docs/protocol/conformance/).

A good first milestone is the first twenty cases, which cover the common path. The reference processor is about 16 KB gzip of TypeScript, so this is a project of weeks, not months.

## A runtime (Interactive and Tools)

- An evaluator for the expression grammar that interprets, never compiles.
- State with declared defaults and change notification.
- Dependency tracking, so a state change re-evaluates only what read it.
- The built-in functions of section 18.7, exactly.
- A query manager: caching per argument set, refresh timers, cancellation, the call budget.
- An action runner: steps in order, stop at the first failure, report through the action envelope.
- Every runtime limit of section 21.2.

## A renderer

- Map each catalog component to a native one. Key on node ids, so an update touches only what changed.
- Draw `#pending` nodes as placeholders and nothing for `#unknown` beyond their children.
- Apply the URL policy before loading any image, video or background (section 23.4).
- Render Markdown without raw HTML.
- Meet the accessibility requirements of section 24.
- Report every interaction with the action envelope of section 20.3.

## Use the reference implementation as an oracle

When the specification seems ambiguous, compare with `@gistui/core`:

```ts
import { parse } from "@gistui/core";

const r = parse(source, catalog);
console.log(JSON.stringify({ tree: r.root, errors: r.errors, valid: r.valid }, null, 2));
```

If the two disagree and the specification does not settle it, that is a defect in the specification. Please [report it](https://github.com/GistUI/GistUI/issues): Appendix D lists the points already known.

## Schemas

| Schema | For |
|---|---|
| `tree.schema.json` | The abstract tree in JSON form |
| `diagnostic.schema.json` | One diagnostic |
| `catalog.schema.json` | A catalog manifest |
| `action.schema.json` | The action envelope |
| `capabilities.schema.json` | The capability object |
| `expected.schema.json` | A conformance expectation file |

They are in [`spec/schemas/`](https://github.com/GistUI/GistUI/tree/main/spec/schemas). Their `$id`s are under `https://gistui.com/schemas/1.0/`; those are identifiers, and the files are not published there yet.

Source: https://gistui.com/docs/protocol/implementing/index.mdx