@boundsvg/core

Core layout engine for boundsvg — JSX to SVG/PNG/WebP/GIF rendering pipeline.

All text shaping, measurement, layout, and rasterization run inside WASM. No browser DOM or OS fonts required.

Installation

npm install @boundsvg/core

Usage

import { Box, Canvas, Text, createEngineAsync } from "@boundsvg/core";

const engine = await createEngineAsync({
  fonts: [{ alias: "Inter", weight: 400, style: "normal", data: fontBuffer }],
});

const svg = engine.renderToSvg(
  <Canvas width={600} height={400} background="#fff">
    <Box padding={20}>
      <Text font="Inter" fontSizePx={24} color="#333">
        Hello, boundsvg!
      </Text>
    </Box>
  </Canvas>,
);

Compile once when several outputs share one layout:

const compiled = engine.compile(vnode);
const svg = engine.renderCompiledToSvg(compiled);
const png = engine.renderCompiledToPng(compiled, { scale: 2 });
const inspectionIr = engine.snapshotCompiledIR(compiled);

Decode Scene documents received from JSON, caches, or another process at the public structural boundary:

import { decodeSceneDocument, fromSceneDocument } from "@boundsvg/core";

const scene = decodeSceneDocument(value); // detached mutable SceneNode
const vnode = fromSceneDocument(value); // the same decode, then VNode conversion

The decoder covers every recursive Scene variant and nested record without invoking input getters, serialization hooks, coercion, iterators, or callbacks. Malformed structure and resource-limit excesses throw stable SCENE_DECODE_* FatalError diagnostics at stage validate.

CompiledScene is an opaque, immutable runtime artifact owned by the exact Engine that created it. It exposes readonly width, height, and textPathMode metadata; it has no public .ir. Do not clone, persist, transport, or construct it as a plain object. Use snapshotCompiledIR for a detached editable inspection copy, which is not accepted by compiled render methods. Forged values fail with COMPILED_SCENE_INVALID, and authentic artifacts passed to another Engine fail with COMPILED_SCENE_WRONG_ENGINE.

Animated raster output

Animated WebP/GIF methods require a destination and return a Promise. Use a file or external spool sink to avoid collecting the entire output. For a small download, opt into the memory collector:

import { createAnimatedRasterCollector } from "@boundsvg/core";

const collector = createAnimatedRasterCollector();
try {
  const result = await engine.renderToAnimatedWebp(
    vnode,
    {
      durationMs: 2000,
      fps: 23.976,
      iterations: 1,
    },
    collector,
  );
  const bytes = collector.takeBytes();
} catch (error) {
  await collector.abort(error);
  throw error;
}

The collector retains O(output) memory and a 256 MiB limit; file sinks have no corresponding total cap. WebP sinks patch four RIFF length bytes before finish. Core cancellation waits for pending callbacks, and a successfully completed pending finish returns success. See the full contract for ownership, structured errors, and migration from the old bytes-returning calls.

When to use the utility entry points

import { inspectScene } from "@boundsvg/core";
import { collectInspectionBBoxes } from "@boundsvg/core/inspect";
import { replaceTextById, withNodeIdPrefix } from "@boundsvg/core/vnode";

const inspection = inspectScene(engine, vnode);
const bboxes = collectInspectionBBoxes(inspection.ir);
console.table(
  inspection.bboxes.map(({ nodeId, drawIndex, w, h }) => ({
    nodeId,
    drawIndex,
    w,
    h,
  })),
);
const localized = replaceTextById(vnode, "headline", "Hello");
const embedded = withNodeIdPrefix(localized, "preview:");

• inspectScene is the high-level read API for build tools, CI checks, and editors that need layout, sampled IR, positioned bboxes, warnings, lookup maps, and node ID validation in one call.

Fatal and recoverable diagnostics use explicit options objects and severity-specific serialized shapes. Recoverable values require both fallback and a closed pipeline stage. Public IR.warnings contains detached RecoverableError instances; structural IR transported through WASM does not contain nested warnings.

• @boundsvg/core/inspect contains the lower-level bbox collector and the complete inspection type surface.
• @boundsvg/core/vnode is for template transforms such as localization, composing multiple generated scenes, and prefixing explicit node IDs before embedding.

@boundsvg/core/wasm exposes all nine low-level shape operations: SVG and path compilation, part hit testing, symbol resolution, part and region evaluation, region SVG rendering, division, and intersection queries. The entry validates structured success values and converts known shape failures to stable FatalError diagnostics. Custom WASM modules must implement the complete operation family and schema expected by this Core version.

See Choosing an API for the coordinate space, animation sampling, and cost of each read API.

JSX Runtime

This package exposes a @boundsvg/core/jsx-runtime entry for use with jsxImportSource:

{
  "compilerOptions": {
    "jsx": "react-jsx",
    "jsxImportSource": "@boundsvg/core"
  }
}

Documentation

Full documentation: https://github.com/zakideee/boundsvg

License

MIT OR Apache-2.0