cascivo-html
Turn agent-written .cv text into one deterministic, self-contained HTML file styled by real
cascivo CSS. 51 elements, seven SVG charts, @brand theming, embedded images
and SVG. No React, no build step, no JavaScript runtime. The same input gives the same bytes.
This repository folder holds the library (cascivo-html). The command-line tool is the crate
cascivo-html-cli (binary cascivo-html).
Install
Quick example
page.cv:
@title "Sales"
@brand #5b5bd6 r8 gap4 dark
page-header "Sales" "Q3 overview"
cols 3
stat Revenue "$48k" "+12%"
stat Users 1204
stat Churn "2.1%"
card "Trend"
line 3 5 8 13 9 14
In Rust:
use ;
CLI options: render [in.cv|-] [-o out.html] [--brand brand.cv] [--assets dir] [--fetch] [--max-asset bytes], check, guide [name]. Exit codes: 0 ok, 1 invalid .cv, 2 usage or
I/O error.
Library notes
render,parse,check;GUIDEandguide_for(name)ship the agent cheat sheet.- Zero dependencies; the library never reads files (
@brand-fileneedsOptions::brand_resolver, images and SVG needOptions::asset_resolveror pre-suppliedOptions::assets).
Links
- Full guide: https://cascivo.com/docs/guides/using-cascivo-html (source)
- API docs: https://docs.rs/cascivo-html
- Agent skill:
skills/cascivo-html - Examples:
examples/*.cv
Development
src/catalog_gen.rs,src/css_gen.rs,src/guide_gen.rsandassets/are generated bypnpm html-kit:generate(part ofpnpm regen); do not edit them.examples/*.cvhave byte-compared.htmlsnapshots:UPDATE_SNAPSHOTS=1 cargo test --test examples.- Gates:
cargo fmt --check,cargo clippy --all-targets -- -D warnings,cargo test.
Images and SVG
image logo.png "Alt" w=64 fit=cover embeds the file as a base64 data URI. svg icon.svg "Alt"
(or svg "<svg …>…</svg>") inlines the markup after a strict sanitizer (no <script>,
<foreignObject>, on* handlers, external hrefs, @import, DOCTYPE/entities), so currentColor
and theme tokens apply. data: URIs pass through; unfetched http(s) sources stay links.
let opts = Options ;
The CLI wires the resolver for you: paths relative to the input file, extra roots with
--assets <dir>, --fetch for URLs (cargo feature fetch, on by default), --max-asset <bytes>.
See examples/brand-assets.cv.
Releasing
Crates: cascivo-html (library), then cascivo-html-cli (binary cascivo-html; depends on the
library, so it goes second). Both share one version (a fixed group in .changeset-rust/config.json).
- First release, manual. crates.io only allows trusted publishing for crates that already
exist. Log in with a token scoped to
publish-new, thencargo publish -p cascivo-htmland, once the index has it,cargo publish -p cascivo-html-cli. Dry run:cargo package --workspace(cargo package -p cascivo-html-clialone fails until the library is on crates.io;--no-verifyskips the build). - Trusted publishing. On crates.io, for each crate: Settings → Trusted Publishing → add
GitHub: repository
cascivo/cascivo, workflowrust-release.yml, environmentcrates-io. Create thecrates-ioenvironment in the repo's Settings → Environments (add required reviewers if wanted). Revoke the manual token. - Later releases (changesets). Record the change with
pnpm changeset:rust add --crate cascivo-html --bump minor --summary "…"(or runpnpm changeset:rustfor the prompt) and commit the.changeset-rust/*.mdwith your PR. After it lands onmain,rust-release.ymlopens a "Version Rust crates" PR that bumps both crates (they are a fixed group, one shared version), thecascivo-htmldependency requirement,Cargo.lockand eachCHANGELOG.md. Merging that PR publishes whatever is not yet on crates.io, in dependency order, then tags<crate>@<version>and creates a GitHub release. A PR changingcrates/*/src/**or non-versionCargo.tomllines needs a changeset or theno-rust-changesetlabel. A failed publish is resumed with Actions → Rust release → Run workflow onmain. Seedocs/RELEASING.md.