@mermanjs/node 0.8.0-alpha.5

package/dist/generated/capability-surface.mjs

@@ -0,0 +1,66 @@
+// @generated by `cargo run -p xtask -- gen-capability-surface`.
+// Source: capabilities/feature-surface-v1.json. Do not edit directly.
+
+export const CAPABILITY_DESCRIPTOR_SCHEMA_VERSION = 1;
+export const CAPABILITY_DESCRIPTOR_DIGEST = "sha256:02e572e1010d2a3d440b69eef260cdf3b2d7f5a88f8c28ebe9fa486e184e722e";
+
+export const NODE_BINDING_OPERATIONS = [
+  {
+    "id": "analysis-facts-json",
+    "compiled_prerequisites": []
+  },
+  {
+    "id": "analysis-json",
+    "compiled_prerequisites": []
+  },
+  {
+    "id": "ascii",
+    "compiled_prerequisites": []
+  },
+  {
+    "id": "document-analysis-facts-json",
+    "compiled_prerequisites": []
+  },
+  {
+    "id": "document-analysis-json",
+    "compiled_prerequisites": []
+  },
+  {
+    "id": "jpeg",
+    "compiled_prerequisites": [
+      "svg"
+    ]
+  },
+  {
+    "id": "layout-json",
+    "compiled_prerequisites": []
+  },
+  {
+    "id": "pdf",
+    "compiled_prerequisites": [
+      "svg"
+    ]
+  },
+  {
+    "id": "png",
+    "compiled_prerequisites": [
+      "svg"
+    ]
+  },
+  {
+    "id": "semantic-json",
+    "compiled_prerequisites": []
+  },
+  {
+    "id": "svg",
+    "compiled_prerequisites": []
+  },
+  {
+    "id": "svg-plan-json",
+    "compiled_prerequisites": []
+  },
+  {
+    "id": "validation-json",
+    "compiled_prerequisites": []
+  }
+];

package/dist/generated/node-wire-contract.json

@@ -0,0 +1,122 @@
+{
+  "schema_version": 1,
+  "package_id": "@mermanjs/node",
+  "artifact_id": "merman-node-static-svg",
+  "transport_api_version": 1,
+  "binding_result_payload_version": 1,
+  "artifact": {
+    "capability_ids": [
+      "layout-cytoscape",
+      "layout-elk",
+      "svg"
+    ],
+    "output_ids": [
+      "svg"
+    ],
+    "output_contracts": [
+      {
+        "id": "svg",
+        "media_type": "image/svg+xml",
+        "system_fonts": null,
+        "embedded_images": null
+      }
+    ],
+    "system_adapter_ids": [],
+    "operation_ids": [
+      "layout-json",
+      "semantic-json",
+      "svg",
+      "svg-plan-json"
+    ],
+    "metadata_ids": [
+      "diagram-family-capabilities",
+      "presentation-catalog",
+      "supported-diagrams",
+      "supported-themes"
+    ],
+    "option_group_ids": [
+      "environment",
+      "fixed_local_offset_minutes",
+      "fixed_today",
+      "layout",
+      "parse",
+      "presentation",
+      "resources",
+      "runtime_policy",
+      "site_config",
+      "svg",
+      "version"
+    ],
+    "constructor_service_ids": [],
+    "text_measurement_provider_ids": [
+      "vendored"
+    ]
+  },
+  "documents": {
+    "identity": {
+      "max_utf8_bytes": 4096,
+      "max_depth": 8,
+      "max_members": 128,
+      "max_tokens": 256,
+      "max_string_utf8_bytes": 1024
+    },
+    "binding_options": {
+      "max_utf8_bytes": 1048576,
+      "max_depth": 64,
+      "max_members": 65536,
+      "max_tokens": 262144,
+      "max_string_utf8_bytes": 1048576
+    },
+    "request": {
+      "max_utf8_bytes": 10485760,
+      "max_depth": 8,
+      "max_members": 16,
+      "max_tokens": 64,
+      "max_string_utf8_bytes": 8388608
+    },
+    "runtime_catalog": {
+      "max_utf8_bytes": 1048576,
+      "max_depth": 64,
+      "max_members": 65536,
+      "max_tokens": 262144,
+      "max_string_utf8_bytes": 1048576
+    },
+    "response": {
+      "max_utf8_bytes": 27262976,
+      "max_depth": 8,
+      "max_members": 32,
+      "max_tokens": 128,
+      "max_string_utf8_bytes": 16777216
+    },
+    "error": {
+      "max_utf8_bytes": 262144,
+      "max_depth": 8,
+      "max_members": 32,
+      "max_tokens": 128,
+      "max_string_utf8_bytes": 65536
+    },
+    "metadata": {
+      "max_utf8_bytes": 8388608,
+      "max_depth": 64,
+      "max_members": 131072,
+      "max_tokens": 524288,
+      "max_string_utf8_bytes": 8388608
+    }
+  },
+  "fields": {
+    "operation_id_utf8_bytes": 128,
+    "media_type_utf8_bytes": 128,
+    "metadata_id_utf8_bytes": 128,
+    "uri_utf8_bytes": 16384,
+    "source_utf8_bytes": 8388608,
+    "options_json_utf8_bytes": 1048576,
+    "data_utf8_bytes": 16777216,
+    "metadata_json_utf8_bytes": 8388608,
+    "error_code_name_utf8_bytes": 128,
+    "error_kind_utf8_bytes": 128,
+    "error_message_utf8_bytes": 65536,
+    "capability_id_utf8_bytes": 128,
+    "package_version_utf8_bytes": 128,
+    "contract_digest_utf8_bytes": 128
+  }
+}

package/dist/index.d.ts

@@ -0,0 +1,239 @@
+export type MermanResourceProfile =
+  | "interactive"
+  | "constrained"
+  | "trusted-native"
+  | "unbounded-for-trusted-input";
+
+export interface MermanBindingOptions {
+  version?: 2;
+  runtime_policy?: "deterministic";
+  resources?: {
+    profile?: MermanResourceProfile;
+    limits?: Record<string, number>;
+  };
+  [key: string]: unknown;
+}
+
+export interface CreateNodeEngineOptions {
+  bindingOptions?: MermanBindingOptions;
+  concurrency?: number;
+  maxQueue?: number;
+}
+
+export interface RenderSvgOptions {
+  /**
+   * Cancels only while the request is waiting in the JS queue. Work that has started is not
+   * preempted and its Promise settles with the actual operation result.
+   */
+  signal?: AbortSignal;
+  /** Raw per-request options JSON merged by the shared binding contract. */
+  optionsJson?: string;
+}
+
+export interface MermanOperationRequest {
+  operationId: string;
+  source: string;
+  uri?: string | null;
+  /** Raw per-request options JSON merged over the reusable engine baseline. */
+  optionsJson?: string;
+}
+
+export interface MermanOperationResult {
+  operation_id: string;
+  media_type: string;
+  data: string;
+  metadata_json: string;
+}
+
+export interface MermanTextMeasurementCatalog {
+  protocol_version: number;
+  provider_ids: string[];
+  [key: string]: unknown;
+}
+
+export interface MermanRuntimeResourceLimit {
+  id: string;
+  phase: string;
+  description: string;
+  overridable: boolean;
+  hard_cap: boolean;
+  minimum_value: number;
+  operation_ids: string[];
+  [key: string]: unknown;
+}
+
+export interface MermanRuntimeResourceProfile {
+  id: string;
+  purpose: string;
+  trust_assumption: string;
+  recommended_binding_default: boolean;
+  limits: Record<string, number | null>;
+  [key: string]: unknown;
+}
+
+export interface MermanRuntimeSystemFontContract {
+  source_id: string;
+  discovery: string;
+  cache_scope: string;
+  host_dependent: boolean;
+  caller_configurable: boolean;
+  resource_bounded: boolean;
+  [key: string]: unknown;
+}
+
+export interface MermanRuntimeEmbeddedImageLimits {
+  max_bytes_per_image: number | null;
+  max_total_bytes: number | null;
+  max_pixels_per_image: number | null;
+  max_total_pixels: number | null;
+  [key: string]: unknown;
+}
+
+export interface MermanRuntimeEmbeddedImageContract {
+  source_ids: string[];
+  filesystem_access: boolean;
+  network_access: boolean;
+  caller_configurable: boolean;
+  limits: MermanRuntimeEmbeddedImageLimits;
+  [key: string]: unknown;
+}
+
+export interface MermanRuntimeOutputContract {
+  id: string;
+  media_type: string;
+  system_fonts: MermanRuntimeSystemFontContract | null;
+  embedded_images: MermanRuntimeEmbeddedImageContract | null;
+  [key: string]: unknown;
+}
+
+export interface MermanRuntimePayloadSchema {
+  id: string;
+  version: number;
+  [key: string]: unknown;
+}
+
+export interface MermanRuntimeConstructorResourceLimit {
+  id: string;
+  phase: string;
+  unit: string;
+  description: string;
+  value: number;
+  [key: string]: unknown;
+}
+
+export interface MermanRuntimeConstructorServiceContract {
+  id: string;
+  provided_text_measurement_provider_ids: string[];
+  resource_limits: MermanRuntimeConstructorResourceLimit[];
+  [key: string]: unknown;
+}
+
+export interface MermanRuntimeCatalog {
+  schema_version: 1;
+  transport_api_version: 1;
+  package_version: string;
+  options_schema_versions: number[];
+  payload_schemas: MermanRuntimePayloadSchema[];
+  metadata_ids: string[];
+  option_group_ids: string[];
+  constructor_service_ids: string[];
+  constructor_service_contracts: MermanRuntimeConstructorServiceContract[];
+  capabilities: {
+    capability_ids: string[];
+    output_ids: string[];
+    operation_ids: string[];
+    system_adapter_ids: string[];
+    text_measurement: MermanTextMeasurementCatalog | null;
+    [key: string]: unknown;
+  };
+  output_contracts: MermanRuntimeOutputContract[];
+  registry: {
+    diagram_family_count: number;
+    [key: string]: unknown;
+  };
+  resources: {
+    general_binding_default_profile: string;
+    cli_default_profile: string;
+    limits: MermanRuntimeResourceLimit[];
+    profiles: MermanRuntimeResourceProfile[];
+    [key: string]: unknown;
+  };
+  [key: string]: unknown;
+}
+
+export interface MermanQueueState {
+  readonly active: number;
+  readonly pending: number;
+  readonly concurrency: number;
+  readonly maxQueue: number;
+  readonly state: "open" | "disposing" | "disposed";
+}
+
+export declare class MermanEngine {
+  private constructor();
+  readonly queueState: MermanQueueState;
+  readonly runtimeCatalog: MermanRuntimeCatalog;
+  renderSvg(source: string, options?: RenderSvgOptions): Promise<string>;
+  /** Synchronous rendering is intended only for explicit SSG build paths. */
+  renderSvgSync(source: string, options?: Omit<RenderSvgOptions, "signal">): string;
+  svgPlanJson(source: string, options?: RenderSvgOptions): Promise<string>;
+  svgPlanJsonSync(
+    source: string,
+    options?: Omit<RenderSvgOptions, "signal">,
+  ): string;
+  metadataJson(id: string): string;
+  executeOperation(
+    request: MermanOperationRequest,
+    options?: Pick<RenderSvgOptions, "signal">,
+  ): Promise<MermanOperationResult>;
+  executeOperationSync(request: MermanOperationRequest): MermanOperationResult;
+  dispose(): Promise<void>;
+}
+
+export declare function createNodeEngine(
+  options?: CreateNodeEngineOptions,
+): Promise<MermanEngine>;
+
+export declare class MermanError extends Error {
+  readonly code: string;
+}
+
+/**
+ * A lossless unsigned resource count. Safe integers use `number`; wider `u64` values use a
+ * canonical decimal `string`.
+ */
+export type MermanResourceCount = number | string;
+
+export interface MermanResourceErrorDetails {
+  readonly cause: string;
+  readonly limit_id: string;
+  readonly phase: string;
+  readonly actual: MermanResourceCount;
+  readonly max: MermanResourceCount;
+  readonly profile: string;
+}
+
+export declare class MermanOperationError extends MermanError {
+  readonly status: number | null;
+  readonly codeName: string | null;
+  readonly kind: "generic" | "unknown-operation" | "missing-capability" | string;
+  readonly capabilityId: string | null;
+  readonly resourceDetails: MermanResourceErrorDetails | null;
+}
+
+export declare class MermanQueueSaturatedError extends MermanError {
+  readonly maxQueue: number;
+}
+
+export declare class MermanDisposedError extends MermanError {}
+export declare class MermanInvalidTransportError extends MermanError {}
+export declare class MermanLifecycleError extends MermanError {}
+export declare class MermanMissingPlatformPackageError extends MermanError {
+  readonly packageName: string;
+  readonly target: string;
+}
+export declare class MermanUnsupportedTargetError extends MermanError {
+  readonly platform: string;
+  readonly arch: string;
+  readonly libc: string | null;
+}

package/dist/index.mjs

@@ -0,0 +1,22 @@
+import { loadNativeTransport } from "./candidates/native.mjs";
+import {
+  MermanEngine,
+  createNodeEngine as createEngineWithTransport,
+} from "./engine.mjs";
+
+export { MermanEngine };
+
+export function createNodeEngine(options) {
+  return createEngineWithTransport(options, { loadTransport: loadNativeTransport });
+}
+
+export {
+  MermanDisposedError,
+  MermanError,
+  MermanInvalidTransportError,
+  MermanLifecycleError,
+  MermanMissingPlatformPackageError,
+  MermanOperationError,
+  MermanQueueSaturatedError,
+  MermanUnsupportedTargetError,
+} from "./errors.mjs";

package/dist/native-loader.mjs

@@ -0,0 +1,112 @@
+import { createRequire } from "node:module";
+
+import {
+  MermanInvalidTransportError,
+  MermanMissingPlatformPackageError,
+  MermanUnsupportedTargetError,
+  parseRuntimeCatalogJsonText,
+} from "./errors.mjs";
+
+const TARGET_PACKAGES = Object.freeze({
+  "darwin-arm64": "@mermanjs/node-darwin-arm64",
+  "darwin-x64": "@mermanjs/node-darwin-x64",
+  "linux-x64-gnu": "@mermanjs/node-linux-x64-gnu",
+  "linux-x64-musl": "@mermanjs/node-linux-x64-musl",
+  "win32-x64-msvc": "@mermanjs/node-win32-x64-msvc",
+});
+
+const requireFromPackage = createRequire(import.meta.url);
+const loaderPackageManifest = requireFromPackage("../package.json");
+const loaderPackageVersion = loaderPackageManifest?.version;
+
+if (typeof loaderPackageVersion !== "string" || loaderPackageVersion.length === 0) {
+  throw new Error("The Merman Node package manifest must declare a non-empty version.");
+}
+
+export function nodeLoaderPackageVersion() {
+  return loaderPackageVersion;
+}
+
+export function assertRuntimePackageVersion(value) {
+  const catalog = parseRuntimeCatalogJsonText(value);
+  if (catalog?.package_version !== loaderPackageVersion) {
+    throw new MermanInvalidTransportError(
+      `The Merman runtime package version ${JSON.stringify(catalog?.package_version)} does not match the loader package version ${JSON.stringify(loaderPackageVersion)}.`,
+    );
+  }
+  return value;
+}
+
+export function nativePackageName(target) {
+  const packageName = TARGET_PACKAGES[target];
+  if (!packageName) {
+    throw new MermanUnsupportedTargetError({
+      platform: target,
+      arch: "unknown",
+      reason: `Unknown Merman Node target id: ${target}.`,
+    });
+  }
+  return packageName;
+}
+
+export function resolveNodeTarget({
+  platform = process.platform,
+  arch = process.arch,
+  report = platform === "linux" ? currentProcessReport() : null,
+} = {}) {
+  if (platform === "darwin" && (arch === "arm64" || arch === "x64")) {
+    return `darwin-${arch}`;
+  }
+  if (platform === "win32" && arch === "x64") return "win32-x64-msvc";
+  if (platform === "linux" && arch === "x64") {
+    const libc = linuxLibc(report);
+    return `linux-x64-${libc}`;
+  }
+  throw new MermanUnsupportedTargetError({ platform, arch });
+}
+
+export function loadNativeBinding({
+  platform = process.platform,
+  arch = process.arch,
+  report = platform === "linux" ? currentProcessReport() : null,
+  loadPackage = requireFromPackage,
+} = {}) {
+  const target = resolveNodeTarget({ platform, arch, report });
+  const packageName = nativePackageName(target);
+  try {
+    return loadPackage(packageName);
+  } catch (cause) {
+    if (isMissingModule(cause)) {
+      throw new MermanMissingPlatformPackageError({ packageName, target, cause });
+    }
+    throw cause;
+  }
+}
+
+function linuxLibc(report) {
+  if (report?.header?.glibcVersionRuntime) return "gnu";
+  if (
+    Array.isArray(report?.sharedObjects) &&
+    report.sharedObjects.some((item) => /(?:^|[/\\])ld-musl-[^/\\]+\.so(?:\.1)?$/.test(item))
+  ) {
+    return "musl";
+  }
+  throw new MermanUnsupportedTargetError({
+    platform: "linux",
+    arch: "x64",
+    reason:
+      "Cannot determine Linux libc from process.report; refusing to guess a platform package.",
+  });
+}
+
+function currentProcessReport() {
+  return typeof process.report?.getReport === "function" ? process.report.getReport() : null;
+}
+
+function isMissingModule(error) {
+  return Boolean(
+    error &&
+      typeof error === "object" &&
+      (error.code === "MODULE_NOT_FOUND" || error.code === "ERR_MODULE_NOT_FOUND"),
+  );
+}

package/dist/transport-contract.mjs

@@ -0,0 +1,87 @@
+import { createRequire } from "node:module";
+
+const requireFromModule = createRequire(import.meta.url);
+const contract = requireFromModule("./generated/node-wire-contract.json");
+
+validateContract(contract);
+
+export const NODE_WIRE_CONTRACT = deepFreeze(contract);
+export const NODE_TRANSPORT_LIMITS = NODE_WIRE_CONTRACT.documents;
+export const NODE_TRANSPORT_FIELD_LIMITS = NODE_WIRE_CONTRACT.fields;
+
+function validateContract(value) {
+  if (
+    !value ||
+    value.schema_version !== 1 ||
+    value.package_id !== "@mermanjs/node" ||
+    value.artifact_id !== "merman-node-static-svg" ||
+    value.transport_api_version !== 1 ||
+    value.binding_result_payload_version !== 1 ||
+    !value.artifact ||
+    !value.documents ||
+    !value.fields
+  ) {
+    throw new Error("The generated Node wire contract is invalid.");
+  }
+  for (const field of [
+    "capability_ids",
+    "output_ids",
+    "system_adapter_ids",
+    "operation_ids",
+    "metadata_ids",
+    "option_group_ids",
+    "constructor_service_ids",
+    "text_measurement_provider_ids",
+  ]) {
+    const ids = value.artifact[field];
+    if (
+      !Array.isArray(ids) ||
+      ids.some((id) => typeof id !== "string" || id.length === 0) ||
+      ids.some((id, index) => index > 0 && ids[index - 1] >= id)
+    ) {
+      throw new Error(`The generated Node artifact field \`${field}\` is invalid.`);
+    }
+  }
+  if (
+    !Array.isArray(value.artifact.output_contracts) ||
+    value.artifact.output_contracts.length !== value.artifact.output_ids.length ||
+    value.artifact.output_contracts.some((contract, index) =>
+      !contract ||
+      contract.id !== value.artifact.output_ids[index] ||
+      typeof contract.media_type !== "string" ||
+      contract.media_type.length === 0 ||
+      !(contract.system_fonts === null || isObject(contract.system_fonts)) ||
+      !(contract.embedded_images === null || isObject(contract.embedded_images))
+    )
+  ) {
+    throw new Error("The generated Node artifact output contracts are invalid.");
+  }
+  for (const [id, limits] of Object.entries(value.documents)) {
+    if (
+      !limits ||
+      !Number.isSafeInteger(limits.max_utf8_bytes) ||
+      !Number.isSafeInteger(limits.max_depth) ||
+      !Number.isSafeInteger(limits.max_members) ||
+      !Number.isSafeInteger(limits.max_tokens) ||
+      !Number.isSafeInteger(limits.max_string_utf8_bytes) ||
+      Object.values(limits).some((limit) => limit <= 0)
+    ) {
+      throw new Error(`The generated Node wire document limit \`${id}\` is invalid.`);
+    }
+  }
+  for (const [id, limit] of Object.entries(value.fields)) {
+    if (!Number.isSafeInteger(limit) || limit <= 0) {
+      throw new Error(`The generated Node wire field limit \`${id}\` is invalid.`);
+    }
+  }
+}
+
+function isObject(value) {
+  return Boolean(value && typeof value === "object" && !Array.isArray(value));
+}
+
+function deepFreeze(value) {
+  if (!value || typeof value !== "object" || Object.isFrozen(value)) return value;
+  for (const child of Object.values(value)) deepFreeze(child);
+  return Object.freeze(value);
+}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@mermanjs/node",
+  "version": "0.8.0-alpha.5",
+  "description": "Experimental native Node.js and static-site rendering bindings for Merman.",
+  "type": "module",
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "main": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs"
+    }
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Latias94/merman.git"
+  },
+  "homepage": "https://github.com/Latias94/merman/tree/main/platforms/node#readme",
+  "keywords": [
+    "mermaid",
+    "diagram",
+    "svg",
+    "node",
+    "ssg",
+    "napi"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "CHANGELOG.md",
+    "dist",
+    "LICENSE-APACHE",
+    "LICENSE-MIT",
+    "README.md",
+    "THIRD_PARTY_LICENSES",
+    "THIRD_PARTY_NOTICES.md"
+  ],
+  "license": "MIT OR Apache-2.0",
+  "optionalDependencies": {
+    "@mermanjs/node-darwin-arm64": "0.8.0-alpha.5",
+    "@mermanjs/node-darwin-x64": "0.8.0-alpha.5",
+    "@mermanjs/node-linux-x64-gnu": "0.8.0-alpha.5",
+    "@mermanjs/node-linux-x64-musl": "0.8.0-alpha.5",
+    "@mermanjs/node-win32-x64-msvc": "0.8.0-alpha.5"
+  }
+}