Transmute is a headless TypeScript toolkit and Bun CLI for turning checked source into visual assets. It currently provides deterministic diagrams, light and dark raster/vector exports, editable tldraw interchange, bounded raster-to-SVG conversion, authenticated hosted image generation, semantic operation dispatch, and a local MCP server.
The package is designed to compose with editors and video renderers. A diagram, generated image, traced SVG, or .tldr canvas remains an ordinary media input rather than a format trapped inside the tool.
Project site: transmute.rocks
Pin the public repository to the immutable v0.5.0 tag:
bun add --global github:hraness/transmute#v0.5.0
transmute doctorFor programmatic use:
bun add github:hraness/transmute#v0.5.0Transmute requires Bun 1.3.14. Diagram rendering works on macOS, Linux, and Windows. Bounded VTracer execution works on macOS and Linux; Windows fails closed with tool_platform until its output can cross the same bounded capture path.
transmute diagram init diagrams/system.diagram.json
transmute diagram check diagrams/system.diagram.json --strict
transmute diagram render diagrams/system.diagram.jsonThe checked source uses .diagram.json version one. Each render replaces the same five derivatives:
system.tldr
system.light.svg
system.dark.svg
system.light.png
system.dark.png
The source remains authoritative. The five outputs are replaceable and each file is published through an atomic rename. The five-file family is not a filesystem transaction.
Use this schema URL in authored files:
{
"$schema": "https://raw.githubusercontent.com/hraness/transmute/v0.5.0/schema/diagram.schema.json",
"version": 1,
"name": "source-result",
"canvas": { "width": 960, "height": 540 },
"layout": {
"type": "stack",
"direction": "horizontal",
"gap": 160,
"align": "center"
},
"shapes": [
{ "id": "source", "type": "rect", "width": 220, "height": 140, "label": "Source" },
{ "id": "result", "type": "rect", "width": 220, "height": 140, "label": "Result" }
],
"edges": [{ "id": "source-result", "from": "source", "to": "result" }]
}Array order may place shapes, but it never creates relationships. Edges stay explicit. Impossible stack constraints fail instead of silently shrinking shapes, gaps, or the canvas.
Place transmute.config.ts, .mjs, .js, or .json beside a diagram to supply local fonts, sanitized SVG icons, or theme colors. Pass --config <path> when configuration belongs elsewhere. MCP and semantic operations deliberately ignore executable workspace configuration.
transmute image vectorize input.png --output input.svg --json
transmute image vectorize input.png \
--output input.duotone.svg \
--duotone '#171717,#7c3aed'Canonical vectorization requires no account or login and makes no discovery, OAuth, or generation request. It bounds encoded input, decoded dimensions and pixels, subprocess time, paths, emitted bytes, and measured fidelity. The output is rebuilt as inert SVG geometry; foreign tracer SVG is not passed through.
VTracer 0.6.4 downloads from a checksum-pinned official release on first use. TRANSMUTE_VTRACER_PATH may point to a compatible local binary, whose hash is recorded in the receipt. TRANSMUTE_CACHE_DIR overrides the default tool cache.
Programmatic use returns the SVG, published path, and provenance receipt:
import { vectorizeImage } from "@hraness/transmute"
const result = await vectorizeImage("input.png", {
outputPath: "input.svg",
})
console.log(result.receipt.sourceSha256, result.receipt.svgSha256)Hosted generation is separate from local vectorization and requires a Transmute login:
transmute auth login
transmute image generate 'one cobalt circle on white' \
--output circle.webp
transmute auth logoutThe CLI accepts recraft/recraft-v4.1-utility and openai/gpt-image-1.5, requests one WebP, validates its bounded base64 and media magic, and atomically publishes the selected output. Requests carry a durable suite-account Idempotency-Key; the client never retries an ambiguous generation request.
Discovery is pinned to https://transmute.rocks/.well-known/transmute-cli.json. OAuth uses authorization code with S256 PKCE and the fixed http://127.0.0.1:49671/oauth/callback loopback. Tokens are stored through Bun.secrets, never in project files or command output.
The registry has four canonical codes:
transmute.diagram.checktransmute.diagram.rendertransmute.image.vectorizetransmute.image.generate
transmute code search diagram --limit 4
transmute code execute transmute.diagram.check \
--input '{"path":"diagrams/system.diagram.json"}'Search returns bounded descriptors. Execute accepts strict JSON for an exact registered code. It does not accept source text, shell commands, dynamic imports, executable configuration, or caller-selected remote URLs.
The same surface is available from @hraness/transmute/operations:
import {
executeTransmuteOperation,
searchTransmuteOperations,
} from "@hraness/transmute/operations"
const matches = searchTransmuteOperations("diagram")
const result = await executeTransmuteOperation("transmute.diagram.check", {
path: "diagrams/system.diagram.json",
})transmute mcp --root /absolute/path/to/workspaceThe stdio server exposes check_diagram, render_diagram, search_transmute, and execute_transmute. File arguments are root-relative and confined to the selected workspace. Diagram source, shape count, edge count, PNG pixels, returned findings, paths, and outputs are bounded before execution. The server is a trusted local workspace boundary, not an operating-system sandbox against concurrent same-user mutation.
Diagram rendering does not require the tldraw SDK or desktop app. The generated .tldr file is editable interchange:
transmute canvas open diagrams/system.tldr
transmute canvas status
transmute canvas url
transmute canvas installThe optional installer flow resolves an official tldraw Offline release, verifies its published SHA-256 digest, and prepares the platform installer. A native .tldraw file is an app-owned ZIP/SQLite bundle; Transmute opens it but does not rewrite it directly.
transmute skill install --target codex --scope user
transmute skill install --target agents --scope projectThe skill keeps literal prompts, checked diagram source, rendering, vectorization, semantic operations, and review steps together. transmute skill path prints its packaged location.
Version 0.5 folds the former hraness/graphics command into Transmute. The package retains a graphics executable for existing automation. It preserves the v0.4 flat command grammar, graphics.* operation codes, JSON stdout, graphics.config.* discovery, GRAPHICS_VTRACER_PATH, GRAPHICS_CACHE_DIR, the com.hraness.graphics.cli credential entry, hraness.graphics cloud contract, and search_graphics/execute_graphics MCP tools.
New scripts should use the namespaced Transmute grammar. The compatibility executable intentionally continues to report 0.4.0 because it is the frozen v0.4 contract.
| Command | Result |
|---|---|
transmute diagram init [file] |
Create a starter without overwriting an existing file. |
transmute diagram check <file> |
Parse and lint a version-one diagram source. |
transmute diagram render <file> |
Replace .tldr, light/dark SVG, and light/dark PNG derivatives. |
transmute image vectorize <image> |
Trace one local raster to bounded inert SVG without authentication. |
transmute image generate <prompt> |
Generate one authenticated, validated WebP. |
| `transmute auth login | logout |
| `transmute code search | execute` |
transmute mcp --root <workspace> |
Serve confined tools over stdio. |
| `transmute canvas open | status |
| `transmute skill path | install` |
transmute doctor |
Report runtime, vectorizer, hosted-feature, MCP, and canvas status. |
bun install --frozen-lockfile --ignore-scripts
bun run checkbun run check typechecks, validates the schema and skill, runs deterministic and property tests, builds the public entrypoints, and installs the resulting archive in a clean consumer.
MIT. See NOTICE.md for optional tldraw Offline and VTracer integration terms.