@dotgui/kit · engine
The reference engine for the .gui format
@dotgui/kit takes a .gui file through its entire life — parse, validate, render, score — in one package, behind one version. It is a pure, deterministic library: same input, same output, zero AI. If the format's meaning depends on it, it lives here.
npm install @dotgui/kitLifecycle
The write path is author → validate → pack. Validation is the one hard check — illegal markup can't be saved as a real .gui. Everything else is à la carte: render when you want pixels, score when you want a quality report. The read path is just as short — parse → render.
import { validate } from '@dotgui/kit/validate' import { pack } from '@dotgui/kit/package' import { render } from '@dotgui/kit/render' const errors = validate(markup) // the only required step if (!errors.length) { const file = await pack({ markup }) // → .gui bytes (+ preview.webp) const dom = render(markup) // → live DOM, one call }
Modules
The root export is just the canonical types. Behaviour lives in subpath exports, so a consumer only bundles what it imports — pull the parser without the renderer. Open any module for its API and examples.
the format vocabulary — The root export is only the format’s canonical TypeScript types — the shared vocabulary every other module and every consumer builds on. Behaviour lives in the subpaths, so importing the types pulls in no runtime code.
Open module →the only required step — The one hard check in a file’s life. It answers “is this broken?” — not “is this good?”. Illegal or unparseable markup can’t be saved as a real .gui, so validation is the gate every write passes through.
Open module →markup → resolved model — Turns .gui markup into a resolved model — tokens, styles, and modes already resolved — ready for rendering, scoring, or analysis.
Open module →the reference output — The format’s reference output — render .gui markup to HTML. Browser-clean: no heavy dependencies, no browser engine bundled.
Open module →CCAC quality report — The CCAC quality model — a read-only, advisory quality report. The kit produces a number and takes no action; what you do with it is your policy.
Open module →the .gui container, in memory — A .gui is a ZIP of the markup (design.guix), an assets/ folder, and a rendered preview.webp. This module reads and edits that container entirely in memory — nothing touches disk.
Open module →idiom & content checks — The dotgui linter — idiom, best-practice, and content checks on top of schema legality. Where /validate answers “is this legal?”, lint answers “is this good, idiomatic dotgui?”.
Open module →deterministic repair — Deterministic auto-repair for dotgui markup. Models make the same mechanical mistakes — CSS habits, invented attributes, boolean="false", bad color formats — and each is an unambiguous string rewrite, so autofix fixes them in place instead of bouncing back to the author.
Open module →markup → bitmap — Turns a .gui into a bitmap — most importantly the preview.webp embedded when packing, but also PNG/JPEG for gui render. It renders the .gui with the built render bundle in a headless page, then screenshots the result.
Open module → The optimizer (Clean's diff signal) is injected — pass it into score or Clean reports NA, never faked. The rasterizer ships a light puppeteer-core default; opt into full puppeteer for a bundled Chromium.
Quality
The scorer measures whether a file is well-built, never whether the design is fashionable — the way an HTML validator judges markup, not websites. Four levels: Clean, Consistent, Accessible (WCAG 2.2 visual criteria), and Comprehensible (AI-ready semantics via the 53-role vocabulary). All four run locally, offline, with zero AI. A low score is still a valid file — the kit reports and takes no action.
Frequently asked
Does @dotgui/kit use AI?
No — zero AI, by design. The kit executes the format's rules and nothing else: pure rule evaluation with deterministic output. AI-assisted authoring lives in agents and skills outside the kit, so the engine stays trustworthy and reproducible.
Is validation required to create a .gui file?
Yes — and it is the only required step. The minimal path is valid markup → zip. Render, lint, score, and preview are optional capabilities, not gates.
Can I use just the parser or just the renderer?
Yes. Each capability is a subpath export (@dotgui/kit/parser, /render, /validate, …), so bundlers tree-shake everything you don't import. The parser and linter are DOM-free and run in any JavaScript environment.
How is the preview.webp thumbnail generated?
pack() renders the file to HTML and rasterizes it with puppeteer-core driving a system Chromium — a light install with no bundled browser. If no browser is found, packing still succeeds with a placeholder preview and a console error explaining the fix.