Stack Engine

stack-sh/engine is the shared execution engine behind the Stack CLI and browser Playground. It formats and validates Stack source, calculates deterministic theme-aware layouts, and renders safe standalone SVGs with the same behavior in native Rust and browser WebAssembly.

Use this repository when embedding Stack rendering or language intelligence in an application. If you only want to create a diagram, start with the CLI or Playground.

Choose an interface

Environment	Package	API documentation
Rust	stack-engine	docs.rs
Browser JavaScript / TypeScript	@stack-sh/engine	Package guide

Both packages provide format, check, render, completion, and hover operations over caller-owned source. The browser package exposes the same engine through WebAssembly.

Rust quick start

cargo add stack-engine@0.9.1

use stack_engine::Engine;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let source = b"stack 1.0 diagram \"API\" { node api \"API\" { icon \"api\" } }";
    let output = Engine::bundled().render(source)?;

    if let Some(svg) = output.svg {
        std::fs::write("api.svg", svg)?;
    } else {
        for diagnostic in output.diagnostics {
            eprintln!("{}: {}", diagnostic.code, diagnostic.message);
        }
    }

    Ok(())
}

The crate supports Rust 1.85 or newer.

Browser quick start

npm install @stack-sh/engine@0.9.1

import init, { render } from "@stack-sh/engine";

await init();

const result = render(
  'stack 1.0 diagram "API" { node api "API" { icon "api" } }',
);

if (result.svg) {
  console.log(result.svg);
} else {
  console.error(result.diagnostics);
}

Initialization loads the WebAssembly module once. Operations are synchronous afterward and accept source already held by the caller; the adapter does not read files, access the DOM, or contact a network service.

What the engine guarantees

• Deterministic integer layout and orthogonal routing using versioned font metrics and themes.
• Standalone SVG with embedded icons, accessible metadata, escaped authored text, and no script or external URL.
• Ordered, source-mapped diagnostics for invalid source, missing resources, and unsatisfied layout hints.
• Exact native/WebAssembly result parity over shared fixtures.
• Caller-owned provider packs that are validated in memory and never discovered, downloaded, or stored by the engine.

Every result includes engine, language, theme catalog version, and catalog revision metadata. See the npm package guide for JavaScript types and provider-pack APIs, and docs.rs for the Rust facade.

Workspace

• stack-engine: the pure operation facade, layout, routing, language intelligence, and SVG rendering.
• stack-formatter: canonical comment-preserving Stack source formatting.
• stack-engine-wasm and @stack-sh/engine: the typed browser adapter.

The engine consumes the public Stack compiler and theme catalog. Language syntax and normalized IR remain owned by the Stack specification.

Filesystem behavior, process exit codes, user authentication, billing, entitlement checks, and paid-theme delivery belong to host applications and are outside this repository.

Architecture

The design records cover the pure engine facade, deterministic layout, orthogonal routing, safe SVG, browser adapter, language intelligence, label-aware graph composition, and distributed terminals and lanes.

See CONTRIBUTING.md for repository setup, quality gates, the reviewed layout corpus, and release verification.

Licensing

This repository is licensed under the Apache License 2.0. Third-party dependencies and bundled assets are recorded in THIRD_PARTY_LICENSES.md.