@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.