omp packages

@evoclock/pi-bowerbird0.1.2

Reproducible architecture diagrams, statecharts, and concept maps for pi: interactive HTML, animated theme-aware SVG for READMEs and MARP, PNG/WebP export, built-vs-planned tracking, and TLA+ from statecharts.

evoclock Published 16 hours ago MIT ~437 downloads/mo

Untested on omp

This is a pi package. No one has reported whether it works on omp yet. If you try it, add your result below.

Did it work for you?

Result

One report per person. A new report replaces your old one.

Reports 0

No reports yet.

Readme

pi-bowerbird

JavaScript TypeScript Shell npm version

Reproducible diagrams for the pi coding agent. Write one *.bower.json file; get an interactive HTML page, animated theme-aware SVGs for READMEs and slides, and PNG/WebP exports.

bowerbird is built first for pi, as a skill and an extension that an agent uses directly. That is its primary home, not its only one: versions for other agent harnesses will follow. The command line works anywhere today.

Same diagram in isometric view:

Why not Mermaid

  • Clean layouts. Orthogonal routes, spread ports, and labels that never sit on a box. Layout warnings fail loudly instead of drawing a mess.
  • It moves in a README. GitHub keeps an SVG's CSS animation inside <img>, and <picture> follows the reader's light or dark theme.
  • Built versus planned. Each component can show whether it is built, partial, or planned, kept current from git by an optional pre-commit hook.
  • Statecharts that check themselves. Unreachable states, dead ends, and ambiguous events are flagged and drawn on the chart. The same file exports a TLA+ spec and Given/When/Then paths.
  • Click through to code. The HTML page opens a details drawer for each component, with links to the real files.
  • Room to explore. Zoom, pan, fit, fullscreen, and a minimap in every HTML page.

Modes

Left to right Top down
Flat --view flat --direction TD
Isometric --view iso --view iso --direction TD

With no --view flag, every render writes both <name>.flat.* and <name>.iso.* files, each in dark and light. Use --view flat or --view iso (or meta.view) to opt out and write only <name>.*. See examples/gallery/index.html.

In the isometric view, status reads as construction: built is a solid block, partial has a hatched roof, planned is a wireframe.

Styles

  • restrained (default). Matte planes, fine lines, generous space, and soft pastel colour.
  • expressive. Glows, colour washes, shadows, and gradients.

Set meta.style in the diagram, or pass --style expressive to render. Both themes share the chosen style. In restrained flat light diagrams, only the small indicator dots show category colours by default. Set meta.lightFlatFill to "filled" or pass --light-flat-fill filled to fill node cards with category colours; the flat HTML toolbar can switch between dots-only and filled. --light-flat-fill dots restores the default. Dark and isometric styling are unchanged. The former categoryFillParity option is no longer supported.

Install

In pi:

pi install npm:@evoclock/pi-bowerbird

PNG and WebP export use rsvg-convert and cwebp:

brew install librsvg webp

For Geist Sans in rasters and embedded SVGs:

brew install --cask font-geist

Without these, bowerbird falls back to the optional npm packages @resvg/resvg-js and sharp. Install those yourself, through Socket Firewall:

sfw npm install @resvg/resvg-js sharp

Use

In pi, ask for a diagram. The bowerbird skill teaches the format and the bowerbird tool renders it. From a shell:

bowerbird init docs/diagrams/system.bower.json
bowerbird render docs/diagrams/system.bower.json            # both flat and iso; html, svg, png, webp
bowerbird render docs/diagrams/system.bower.json --view iso --direction TD
bowerbird snippets docs/diagrams/system.bower.json          # README and MARP embeds

Statecharts:

bowerbird check examples/proposal-to-merge.bower.json      # dead ends, unreachable, ambiguous
bowerbird journeys examples/proposal-to-merge.bower.json   # Given/When/Then paths
bowerbird tla examples/proposal-to-merge.bower.json        # TLA+ module and TLC config

Keeping a map current:

bowerbird sync docs/diagrams/system.bower.json    # status from git evidence
bowerbird diff docs/diagrams/system.bower.json    # structural changes since HEAD

templates/hooks/pre-commit runs check, sync, diff, and render, then stages the outputs. Copy it into .git/hooks/ to opt in.

Embedding

<picture>
  <source media="(prefers-color-scheme: dark)" srcset="docs/diagrams/system.flat.dark.svg">
  <img alt="System" src="docs/diagrams/system.flat.light.svg">
</picture>

For MARP, use ![bg contain](docs/diagrams/system.flat.light.svg), or the WebP for PDF and PPTX export. Use system.iso.light.svg for the isometric view.

CI

Product CI is Buildkite on the mac-mini queue. The organisation pipeline uploads .buildkite/pipeline.yml, which checks Node >= 22, then runs npm install and npm test.

License

MIT.