README Hero Studio

Local, deterministic graphics runtime for coding agents.

README Hero Studio turns a repository brief into constrained TypeScript composition code, renders three visual directions, evaluates their structure, and gives a human a local review surface before an SVG or PNG is approved. It follows the Remotion-shaped model—code is the source of truth, skills drive the workflow, preview and export share one renderer—without executing arbitrary templates or fetching remote assets.

Try the agent loop

Requires Node.js 24.19–26 and pnpm 11.24.

corepack enable
pnpm install --frozen-lockfile
pnpm hero init .
pnpm hero create my-project
pnpm hero inspect my-project-1 --json
pnpm hero preview my-project
pnpm dev

Open http://127.0.0.1:3000. The viewer shows three variants, fit/actual/narrow previews, the element tree and computed bounds, quality findings, hash-anchored comments, and approval state.

Final export is explicitly hash-bound:

pnpm hero approve my-project-1 --hash <preview-sha256>
pnpm hero render my-project-1 --output exports/my-project.svg
pnpm hero render my-project-1 --output exports/my-project.png

Authoring model

Trusted composition source uses eight primitives: Frame, Stack, Text, Image, Shape, Icon, Pattern, and Mask. Twelve bundled Elements cover titles, kickers, taglines, badge rails, metrics, rules, grids, marks, code labels, cards, indices, and seeded constellations. Four composition families—editorial, technical, product, and expressive-minimal—share the same renderer and token contract.

Serializable JSON contains only validated composition props, render manifests, and review state. Design control is limited to palette, type scale, spacing, radius, density, alignment, and explicit seed. Satori creates self-contained SVG; Sharp creates metadata-free sRGB PNG. Bundled Geist bytes are the only default font source.

The repository dogfoods the workflow in .hero/compositions, the skills live in skills, and the architecture and security boundaries are documented in docs/architecture.md and docs/security.md.

Runtime contract

@readme-hero/runtime owns the only pipeline: parse input → compose → compile scene → render → evaluate → hash. Its public API is intentionally limited to inspectComposition, renderComposition, and certifyElement. The dependency graph is schema → kernel → elements/render-core → runtime → cli/studio; package exports are explicit and API-snapshotted.

Studio is a read-mostly adapter over the same runtime. Its only render endpoint is POST /api/render, which accepts strict { input, format } JSON and returns { data, hash, manifest, quality }. Preview, CLI export, and this route therefore use identical renderer bytes rather than separate browser markup.

Commands

hero init [directory]
hero create <composition>
hero preview <composition-prefix>
hero render <composition> --output <path>
hero inspect <composition> [--json]
hero evaluate <composition> [--json]
hero element scaffold <name>
hero element test <name>
hero approve <composition> --hash <preview-hash>

render refuses a missing or stale approval and will not overwrite an existing output unless --force is supplied. Machine-readable commands accept --json; failures use non-zero exit codes.

Quality gates

pnpm format:check
pnpm check:architecture
pnpm lint
pnpm typecheck
pnpm test
pnpm test:visual
pnpm test:e2e
pnpm build
pnpm audit:ci

Unit coverage must discover production files (zero-file reports fail). Schema, kernel, render-core, and runtime enforce 95% line/function/statement and 90% branch coverage; Elements, CLI, and pure Studio logic enforce 90% and 85% respectively. check:architecture also rejects cycles, deep imports, wildcard exports, forbidden APIs, oversized modules/functions, and public API drift.

This preview is static-only and local-first. It does not include MCP, hosted collaboration, accounts, telemetry, remote assets, image generation, animation, arbitrary CSS/HTML, or execution of imported third-party composition code. No open-source license has been chosen; publication remains blocked by LICENSE-CHOICE-REQUIRED.md.