The dotgui engine in one package. Everything required to take a .gui file through its entire life — parse, validate, render, score — lives here, behind one version and one install.

bun add @dotgui/kit

A .gui file is markup. On its own it's inert: bytes that mean nothing until something can read them, check them, draw them, and judge them. @dotgui/kit is that something — the reference engine for the format.

It is a pure, deterministic library. Same input → same output, every time. There is zero AI in this package. The kit doesn't generate designs, guess intent, or call a model. It executes the format's rules and nothing else. That separation is deliberate (see Where the AI lives below).

If the format's meaning depends on it, it's in the kit. If it's a product built on top of the format (exporters, hosted services, editors), it isn't.

The kit is organized around the life of a single file. Two paths:

flowchart TD
    A(["✍️ Author markup"]) --> V{"Validate · <code>/validate</code><br/><b>the only required step</b>"}
    V -->|"broken / illegal"| A
    V -->|"valid"| W["Write → .gui<br/><i>zip markup + assets</i>"]
    W --> Z(["📦 .gui package"])

    V -.->|"optional"| R["Render · <code>/render</code><br/><i>see it · or make preview.webp</i>"]
    R -.->|"optional preview"| W
    Z -.->|"optional · advisory · consumer decides policy"| S["Score · <code>/score</code><br/><i>quality report — kit takes no action.<br/>A low score is still a valid file.</i>"]

    style R stroke-dasharray: 5 5
    style S stroke-dasharray: 5 5

Only validate is required. Everything else is à la carte — a tool that just needs to produce a .gui pulls validate, then writes valid markup (+ assets) to a zip. Render and score are capabilities you reach for if you need them, not gates you must pass through.

1. Validate — is this broken? The one hard check. Illegal/unparseable markup can't be saved as a real .gui — fix it and retry. The format's equivalent of a browser rejecting malformed code.
2. Write / pack — bundle valid markup (+ assets) into a .gui. Minimal output needs nothing but valid markup. (This package I/O — read/write/pack/unpack, asset add/rm, set-preview — is the kit's package surface: deterministic file operations every tool reuses. It currently lives in the CLI and is the next consolidation target; see ARCHITECTURE.md.)
3. Render (optional) — what does it look like? The HTML render is the format's reference output. Also feeds the preview.webp; the kit rasterizes via puppeteer-core by default (opt into full puppeteer for a bundled Chromium), falling back to a placeholder preview if no browser is found. See rasterize.

Score is not a mandatory step in packing. Packing a valid file never requires a score. Score is a separate, read-only quality lens you can run on any valid file — it returns a CCAC report (Clean · Consistent · Accessible · Comprehensible; all local and zero-AI; Comprehensible scores how AI-ready the file is as semantics by reach-coverage over its declared role= anchors) and the kit itself takes no action on it. A low score is still a valid, packable file. Think HTML best-practice standards — advisory, not a parser error.

What happens with the score is entirely the author's call. The kit only produces the number; the consuming tool decides the policy. A CLI might fail a build below a threshold; the app might show a warning badge; a batch job might auto-discard known-bad output; another tool might just log it and move on. The kit hands you a measurement and stays out of the way — it never imposes a gate of its own.

.gui bytes  →  parse  →  render
               ─────     ──────
               /parser   /render

Parse resolves tokens, styles, and modes into a normalized model; render turns that model into HTML. That's the whole round trip.

The root exports only the canonical types. Behaviour lives in subpaths, so a consumer only bundles what it imports — import the parser and you don't pull in the renderer.

Each module has its own README with the full API, examples, and use cases — linked below.

import { validate } from '@dotgui/kit/validate'
import { renderToHTML } from '@dotgui/kit/render'
import { score } from '@dotgui/kit/score'

const result = validate(markup)        // legal?
const html   = renderToHTML(model)     // what does it look like?
const report = score(markup)           // how good is it?

• optimize (Clean's diff signal) — injected. The optimizer is a separate, not-yet-stable package, so the kit doesn't depend on it. Pass it into score:

  import { optimize } from 'gui-optimizer'
  score(markup, { optimize })   // Clean scored fully
  score(markup)                 // Clean reported NA — absent with a reason, never faked

• rasterizer (render → preview.webp) — shipped, with a default. The kit rasterizes via puppeteer-core (a light install — no bundled Chromium — that drives a system browser). Opt into full puppeteer with DOTGUI_PUPPETEER=full for a self-contained Chromium. No browser found → placeholder preview.webp + a console error, never a hard failure. Full design and limitations: rasterize.

The kit stays pure and light; heavy or volatile machinery is the consumer's choice.

AI — when it's involved at all — lives at one place only: authoring the markup. And authoring is author-agnostic: the .gui can be written by an AI agent or by a human using tools (the CLI, the app, an editor). The kit sits entirely downstream and never knows, or cares, which one produced the file.

flowchart LR
    AI(["🤖 AI agent<br/>(host + skill)"]) --> M["✍️ .gui markup"]
    H(["🧑 Human<br/>(CLI / app / editor)"]) --> M
    M --> K["@dotgui/kit<br/><i>deterministic · no AI</i><br/>validate → render → pack"]
    K -.->|"advisory"| S["score · quality report"]

Everything to the right of the markup is pure and deterministic. Keeping the kit AI-free means its behaviour is reproducible and testable, and the quality report means the same thing no matter who — or what — wrote the file. The agent (or person) generates; the kit just runs the rules.

Everything that touches .gui files is a thin consumer of this one engine:

Each one imports the kit and stops reimplementing the engine. A fix to the parser or renderer ships once, atomically, to all of them — no version cascade.

• One package, one version. The engine pieces are tightly coupled and move together. No internal version drift.
• Subpath exports + tree-shaking. Use one slice, ship one slice.
• Sensible defaults, swappable. The rasterizer ships a puppeteer-core default (light install) you can upgrade to full puppeteer or override; the optimizer (unstable) is injected. Defaults work out of the box; nothing heavy is forced.
• HTML is the reference output. Other formats are derived, and live outside the kit.

See ../ARCHITECTURE.md for the full consolidation decision and rationale.