@stack-scribe/core

@stack-scribe/core is the browser-safe Stack Scribe engine for diagram parsing, validation, layout, rendering, theming, and editor-facing SVG metadata.

It is provider-neutral by default. You can use it with generic node types on its own, or attach icon registries and resolvers from packages such as @stack-scribe/icon-pack-aws.

Install

npm install @stack-scribe/core

What It Provides

• Diagram schema parsing and normalization
• Semantic validation
• Layout and incremental relayout
• SVG rendering
• Theme presets and theme normalization
• Editor-facing DOM bindings for nodes, edges, labels, groups, and callouts
• Icon registry primitives for external icon packs

Quick Start

This package works without a provider-specific icon pack as long as node types are syntactically valid.

import {
  renderDiagramFromInput,
  validateDiagram,
} from "@stack-scribe/core";

const diagram = {
  title: "Core Example",
  nodes: [
    { id: "api", type: "acme.compute.api" },
    { id: "worker", type: "acme.compute.worker" },
  ],
  edges: [{ from: "api", to: "worker", label: "dispatch" }],
};

const validation = validateDiagram(diagram);

if (!validation.valid) {
  throw new Error(JSON.stringify(validation.errors, null, 2));
}

const rendered = await renderDiagramFromInput(diagram);

console.log(rendered.width, rendered.height);
console.log(rendered.svg);

Using An Icon Pack

For canonical provider types, shorthand aliases, and real icon assets, supply an icon registry and resolver.

import {
  createIconRegistry,
  renderDiagramFromInput,
  validateDiagram,
} from "@stack-scribe/core";
import { awsIconPack } from "@stack-scribe/icon-pack-aws";
import { createAwsIconResolver } from "@stack-scribe/icon-pack-aws/node";

const iconRegistry = createIconRegistry([awsIconPack]);
const iconResolver = createAwsIconResolver();

const diagram = {
  nodes: [
    { id: "api", type: "aws.networking-content-delivery.api-gateway" },
    { id: "fn", type: "lambda" },
  ],
  edges: [{ from: "api", to: "fn" }],
};

const validation = validateDiagram(diagram, { iconRegistry });

if (!validation.valid) {
  throw new Error(JSON.stringify(validation.errors, null, 2));
}

const rendered = await renderDiagramFromInput(diagram, {
  iconRegistry,
  iconResolver,
});

console.log(rendered.svg);

Main APIs

• parseDiagram(input) and normalizeDiagram(input)
• cloneDiagram(diagram) and applyDiagramMutation(diagram, mutator)
• serializeDiagram(diagram)
• validateDiagram(input)
• layoutDiagram(diagram) and relayoutDiagram(nextDiagram, context)
• renderDiagramFromInput(input, options)
• renderDiagramDocument(layoutResult, options) and renderSvgDocument(renderModel, options)
• buildRenderModel(layoutResult, options)
• createIconRegistry(packs) and createIconResolver(registry, loader)

Public Subpaths

• @stack-scribe/core/document: document helpers and round-trip utilities
• @stack-scribe/core/editor: editor mutation and DOM-contract helpers
• @stack-scribe/core/layout: layout and relayout types
• @stack-scribe/core/icon-registry: icon pack and registry primitives
• @stack-scribe/core/render-contract: render-model and DOM-contract types
• @stack-scribe/core/render-model: render-model construction
• @stack-scribe/core/renderer: SVG rendering functions
• @stack-scribe/core/render-theme: theme presets and normalization
• @stack-scribe/core/rendering-options: resolver and measuring options
• @stack-scribe/core/schema: Zod schemas and diagram types
• @stack-scribe/core/validator: low-level validation API

Themes

Built-in render theme names:

• default
• dark

Use normalizeRenderTheme() to apply overrides or getRenderThemePreset() to load a preset.

Notes

• The package stays browser-safe and does not depend on Node filesystem APIs.
• Without an icon registry, provider-neutral node types are accepted and unknown types render with fallback icon behavior.
• Use renderDiagramDocument(..., { editor: { enabled: true, includeDomIndex: true } }) when you need editor metadata in addition to SVG.