cascivo-html 0.2.0

Render .cv text into one deterministic, self-contained cascivo HTML file
Documentation
  • Coverage
  • 37.8%
    62 out of 164 items documented1 out of 60 items with examples
  • Size
  • Source code size: 458.1 kB This is the summed size of all the files inside the crates.io package for this release.
  • Documentation size: 2.1 MB This is the summed size of all files generated by rustdoc for all configured targets
  • Ø build duration
  • this release: 2s Average build duration of successful builds.
  • all releases: 2s Average build duration of successful builds in releases after 2024-10-23.
  • Links
  • Homepage
  • cascivo/cascivo
    1 0 1
  • crates.io
  • Dependencies
  • Versions
  • Owners
  • urbanisierung

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

cargo install cascivo-html-cli   # the `cascivo-html` binary
cargo add cascivo-html           # the library

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
cascivo-html check page.cv                 # validate; errors are file:line:col
cascivo-html render page.cv -o page.html   # one self-contained file
cascivo-html guide                         # syntax + component list for agents
cascivo-html guide table                   # every prop of one component

In Rust:

use cascivo_html::{render, Options};

fn main() {
    match render("card \"Hi\"\n", &Options::default()) {
        Ok(html) => println!("{html}"),
        Err(diagnostics) => eprintln!("{} error(s)", diagnostics.len()),
    }
}

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; GUIDE and guide_for(name) ship the agent cheat sheet.
  • Zero dependencies; the library never reads files (@brand-file needs Options::brand_resolver, images and SVG need Options::asset_resolver or pre-supplied Options::assets).

Links

Development

  • src/catalog_gen.rs, src/css_gen.rs, src/guide_gen.rs and assets/ are generated by pnpm html-kit:generate (part of pnpm regen); do not edit them.
  • examples/*.cv have byte-compared .html snapshots: 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 {
    assets: vec![("logo.png".into(), png_bytes)], // looked up first, no 'static needed
    // asset_resolver: Some(&|src| read_somehow(src)),  // for everything else
    // embed_urls: true,  // also send http(s) srcs to the resolver
    max_asset_bytes: Some(4 << 20), // default 2 MiB
    ..Options::default()
};

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

  1. First release, manual. crates.io only allows trusted publishing for crates that already exist. Log in with a token scoped to publish-new, then cargo publish -p cascivo-html and, once the index has it, cargo publish -p cascivo-html-cli. Dry run: cargo package --workspace (cargo package -p cascivo-html-cli alone fails until the library is on crates.io; --no-verify skips the build).
  2. Trusted publishing. On crates.io, for each crate: Settings → Trusted Publishing → add GitHub: repository cascivo/cascivo, workflow rust-release.yml, environment crates-io. Create the crates-io environment in the repo's Settings → Environments (add required reviewers if wanted). Revoke the manual token.
  3. Later releases (changesets). Record the change with pnpm changeset:rust add --crate cascivo-html --bump minor --summary "…" (or run pnpm changeset:rust for the prompt) and commit the .changeset-rust/*.md with your PR. After it lands on main, rust-release.yml opens a "Version Rust crates" PR that bumps both crates (they are a fixed group, one shared version), the cascivo-html dependency requirement, Cargo.lock and each CHANGELOG.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 changing crates/*/src/** or non-version Cargo.toml lines needs a changeset or the no-rust-changeset label. A failed publish is resumed with Actions → Rust release → Run workflow on main. See docs/RELEASING.md.