pikru 1.0.0

# pikru

[![crates.io](https://img.shields.io/crates/v/pikru.svg)](https://crates.io/crates/pikru)
[![docs.rs](https://docs.rs/pikru/badge.svg)](https://docs.rs/pikru)
[![MIT/Apache 2.0](https://img.shields.io/badge/license-MIT%20OR%20Apache--2.0-blue)](./LICENSE-MIT)

A pure Rust implementation of [pikchr](https://pikchr.org/), a PIC-like diagram
markup language for creating technical diagrams that generates SVG.

## Usage

```rust
let svg = pikru::pikchr(r#"box "Hello" arrow box "World""#).unwrap();
assert!(svg.contains("<svg"));
```

## Features

- **Pure Rust** - No C dependencies, safe and portable
- **Light/Dark Mode Support** - Generate SVGs with CSS variables that
  automatically adapt to `prefers-color-scheme`
- **Drop-in Compatible** - Aims for full compatibility with the original
  C implementation

## Light/Dark Mode

Enable CSS variables for automatic light/dark theming:

```rust
use pikru::{pikchr_with_options, RenderOptions};

let options = RenderOptions { css_variables: true };
let svg = pikchr_with_options(r#"box "Hello""#, &options).unwrap();
assert!(svg.contains("light-dark("));
```

The generated SVG includes a `<style>` block with CSS variables using
`light-dark()`, so colors automatically adapt to the user's color scheme.

## Dependencies

pikru has a minimal dependency footprint (7 direct dependencies by default):

| Crate | Purpose |
|-------|---------|
| [glam](https://crates.io/crates/glam) | 2D vector math for coordinates and geometry |
| [pest](https://crates.io/crates/pest) | PEG parser generator for the pikchr grammar |
| [facet-svg](https://github.com/facet-rs/facet) | SVG DOM generation and XML serialization |
| [miette](https://crates.io/crates/miette) | Error reporting with source snippets |
| [thiserror](https://crates.io/crates/thiserror) | Derive macro for error types |
| [enum_dispatch](https://crates.io/crates/enum_dispatch) | Efficient shape rendering dispatch |

### Optional Features

- **`tracing`** - Enable debug logging via the [tracing](https://crates.io/crates/tracing) crate.
  Disabled by default for smaller builds.

## Development

### Testing

The test suite validates output against the original C implementation:

```bash
cargo test                     # Run all tests
cargo xtask compare-html       # Generate visual comparison HTML
cargo xtask generate-pngs      # Convert SVGs to PNGs for debugging
```

See `comparison.html` for a side-by-side visual comparison of C vs Rust output.

### Pre-commit Hooks

```bash
./hooks/install.sh
```

## Attribution

pikru is a clean-room Rust implementation inspired by:

- **[pikchr](https://pikchr.org/)** by D. Richard Hipp - The original C
  implementation, released under the
  [0-clause BSD license](https://pikchr.org/home/doc/trunk/doc/license.md).
  The C source is vendored in `vendor/pikchr-c/` for reference during development.

- **[gopikchr](https://github.com/gopikchr/gopikchr)** - A Go port of pikchr
  by [@zellyn](https://github.com/zellyn), which served as inspiration for
  this Rust implementation.

## Continuous Integration

Our CI runs on [Depot](https://depot.dev) hosted runners &mdash; huge thanks
to Depot for sponsoring the compute that keeps the pikru test suite flying.

## Sponsors

Thanks to all individual sponsors:

<p>
<a href="https://github.com/sponsors/fasterthanlime">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="./static/sponsors-v3/github-dark.svg">
<img src="./static/sponsors-v3/github-light.svg" height="40" alt="GitHub Sponsors">
</picture>
</a>
<a href="https://patreon.com/fasterthanlime">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="./static/sponsors-v3/patreon-dark.svg">
<img src="./static/sponsors-v3/patreon-light.svg" height="40" alt="Patreon">
</picture>
</a>
</p>

...along with corporate sponsors:

<p>
<a href="https://aws.amazon.com">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="./static/sponsors-v3/aws-dark.svg">
<img src="./static/sponsors-v3/aws-light.svg" height="40" alt="AWS">
</picture>
</a>
<a href="https://zed.dev">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="./static/sponsors-v3/zed-dark.svg">
<img src="./static/sponsors-v3/zed-light.svg" height="40" alt="Zed">
</picture>
</a>
<a href="https://depot.dev?utm_source=facet">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="./static/sponsors-v3/depot-dark.svg">
<img src="./static/sponsors-v3/depot-light.svg" height="40" alt="Depot">
</picture>
</a>
</p>

## License

Licensed under either of:

- Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE) or
  <http://www.apache.org/licenses/LICENSE-2.0>)
- MIT license ([LICENSE-MIT](LICENSE-MIT) or
  <http://opensource.org/licenses/MIT>)

at your option.