@franken-suite/franken-markdown 0.3.0

package/franken_markdown.d.ts

@@ -0,0 +1,102 @@
+export type FmdOutputFormat = "html" | "pdf";
+export type FmdFont = "sans" | "serif";
+export type FmdDarkMode = "auto" | "disabled";
+
+export interface FmdDiagnostic {
+  severity: "warning" | "error";
+  start: number;
+  end: number;
+  message: string;
+}
+
+export interface FmdPdfImageAsset {
+  /** Markdown image destination, for example `images/chart.png` from `![Chart](images/chart.png)`. */
+  destination: string;
+  /** Browser-supplied image bytes. PNG and SVG assets are supported in PDF output. */
+  bytes: Uint8Array | ArrayBuffer | ArrayBufferView;
+}
+
+export type FmdFontAssetSlot =
+  | "body-regular"
+  | "body-bold"
+  | "body-italic"
+  | "body-bold-italic"
+  | "mono-regular";
+
+export interface FmdFontAsset {
+  /** Renderer font slot to replace. Missing slots use bundled deterministic fallback fonts. */
+  slot: FmdFontAssetSlot;
+  /** Browser-supplied TrueType font bytes. */
+  bytes: Uint8Array | ArrayBuffer | ArrayBufferView;
+}
+
+export interface FmdRenderOptions {
+  font?: FmdFont;
+  darkMode?: FmdDarkMode;
+  title?: string;
+  customCss?: string;
+  allowRawHtml?: boolean;
+  author?: string;
+  /** Finite non-negative integer seconds, <= Number.MAX_SAFE_INTEGER. */
+  metadataEpochSeconds?: number;
+  codeLineNumbers?: boolean;
+  /** Host-supplied PDF image bytes; any number of assets may be supplied per render call. */
+  pdfImages?: FmdPdfImageAsset[];
+  /** Host-supplied TrueType font bytes by renderer slot. */
+  fontAssets?: FmdFontAsset[];
+}
+
+export interface FmdRenderOutput {
+  format: FmdOutputFormat;
+  mimeType: string;
+  extension: "html" | "pdf";
+  sourceLength: number;
+  bytes: Uint8Array;
+  diagnostics: FmdDiagnostic[];
+  text(): string;
+  blob(): Blob;
+  filename(baseName?: string): string;
+}
+
+export interface FmdCapabilities {
+  schema: "fmd-wasm-capabilities-v1";
+  outputs: FmdOutputFormat[];
+  input: "markdown_utf8";
+  html: {
+    mime_type: "text/html; charset=utf-8";
+    self_contained: boolean;
+    custom_css_utf8: boolean;
+    font_assets: "ttf_v0_host_supplied_bytes";
+  };
+  pdf: {
+    mime_type: "application/pdf";
+    deterministic_metadata_epoch: boolean;
+    image_assets: "png_svg_v0_host_supplied_bytes";
+    font_assets: "ttf_v0_host_supplied_bytes";
+  };
+  diagnostics: {
+    source_spans: "byte_offsets";
+    json: boolean;
+  };
+  runtime_assumptions: {
+    filesystem: false;
+    process: false;
+    network: false;
+    threads: false;
+  };
+  theme: unknown;
+}
+
+export interface FmdRenderer {
+  capabilities(): Promise<FmdCapabilities>;
+  renderHtml(markdown: string, options?: FmdRenderOptions): Promise<FmdRenderOutput>;
+  renderPdf(markdown: string, options?: FmdRenderOptions): Promise<FmdRenderOutput>;
+}
+
+export function init(input?: RequestInfo | URL | Response | BufferSource | WebAssembly.Module): Promise<void>;
+export function capabilities(): Promise<FmdCapabilities>;
+export function renderHtml(markdown: string, options?: FmdRenderOptions): Promise<FmdRenderOutput>;
+export function renderPdf(markdown: string, options?: FmdRenderOptions): Promise<FmdRenderOutput>;
+export function createRenderer(
+  input?: RequestInfo | URL | Response | BufferSource | WebAssembly.Module
+): Promise<FmdRenderer>;

package/franken_markdown.js

@@ -0,0 +1,295 @@
+import initWasm, {
+  capabilities as wasmCapabilities,
+  renderHtmlConfigured,
+  renderHtmlConfiguredWithFonts,
+  renderPdfConfiguredMulti
+} from "./pkg/franken_markdown.js";
+
+let initPromise = null;
+
+export async function init(input) {
+  if (initPromise === null) {
+    initPromise = input === undefined ? initWasm() : initWasm({ module_or_path: input });
+  }
+  try {
+    await initPromise;
+  } catch (error) {
+    initPromise = null;
+    throw error;
+  }
+}
+
+export async function capabilities() {
+  await init();
+  return parseJson(wasmCapabilities(), "capabilities JSON");
+}
+
+export async function renderHtml(markdown, options = {}) {
+  await init();
+  const fontAssets = fontAssetsOption(options.fontAssets);
+  if (fontAssets.length > 0) {
+    return normalizeResult(
+      renderHtmlConfiguredWithFonts(
+        String(markdown),
+        stringOption(options.font),
+        darkModeOption(options.darkMode),
+        verbatimOption(options.title),
+        verbatimOption(options.customCss),
+        Boolean(options.allowRawHtml),
+        fontBytesForSlot(fontAssets, "body-regular"),
+        fontBytesForSlot(fontAssets, "body-bold"),
+        fontBytesForSlot(fontAssets, "body-italic"),
+        fontBytesForSlot(fontAssets, "body-bold-italic"),
+        fontBytesForSlot(fontAssets, "mono-regular")
+      )
+    );
+  }
+  return normalizeResult(
+    renderHtmlConfigured(
+      String(markdown),
+      stringOption(options.font),
+      darkModeOption(options.darkMode),
+      verbatimOption(options.title),
+      verbatimOption(options.customCss),
+      Boolean(options.allowRawHtml)
+    )
+  );
+}
+
+export async function renderPdf(markdown, options = {}) {
+  await init();
+  const pdfImages = pdfImagesOption(options.pdfImages);
+  const fontAssets = fontAssetsOption(options.fontAssets);
+
+  // Flatten any number of images into the three parallel arrays the core ABI
+  // accepts (wasm-bindgen cannot pass a Vec<Vec<u8>>): a destination per image,
+  // all image bytes concatenated, and each image's byte length.
+  const destinations = pdfImages.map((image) => image.destination);
+  const lengths = new Uint32Array(pdfImages.map((image) => image.bytes.length));
+  const totalBytes = pdfImages.reduce((sum, image) => sum + image.bytes.length, 0);
+  const flatBytes = new Uint8Array(totalBytes);
+  let offset = 0;
+  for (const image of pdfImages) {
+    flatBytes.set(image.bytes, offset);
+    offset += image.bytes.length;
+  }
+
+  return normalizeResult(
+    renderPdfConfiguredMulti(
+      String(markdown),
+      stringOption(options.font),
+      darkModeOption(options.darkMode),
+      verbatimOption(options.title),
+      verbatimOption(options.author),
+      epochOption(options.metadataEpochSeconds),
+      Boolean(options.allowRawHtml),
+      Boolean(options.codeLineNumbers),
+      destinations,
+      flatBytes,
+      lengths,
+      fontBytesForSlot(fontAssets, "body-regular"),
+      fontBytesForSlot(fontAssets, "body-bold"),
+      fontBytesForSlot(fontAssets, "body-italic"),
+      fontBytesForSlot(fontAssets, "body-bold-italic"),
+      fontBytesForSlot(fontAssets, "mono-regular")
+    )
+  );
+}
+
+export async function createRenderer(input) {
+  await init(input);
+  return Object.freeze({
+    capabilities,
+    renderHtml,
+    renderPdf
+  });
+}
+
+function normalizeResult(result) {
+  let bytes;
+  let diagnostics;
+  let format;
+  let mimeType;
+  let extension;
+  let sourceLength;
+  try {
+    bytes = result.bytes;
+    diagnostics = parseDiagnostics(result.diagnosticsJson());
+    format = result.format;
+    mimeType = result.mimeType;
+    extension = result.extension;
+    sourceLength = result.sourceLength;
+  } finally {
+    if (typeof result.free === "function") {
+      result.free();
+    }
+  }
+  const output = {
+    format,
+    mimeType,
+    extension,
+    sourceLength,
+    bytes,
+    diagnostics,
+    text() {
+      return new TextDecoder().decode(bytes);
+    },
+    blob() {
+      if (typeof Blob === "undefined") {
+        throw new Error("Blob is not available in this JavaScript runtime");
+      }
+      return new Blob([bytes], { type: output.mimeType });
+    },
+    filename(baseName = "document") {
+      const cleanBase = String(baseName).trim() || "document";
+      return `${cleanBase}.${output.extension}`;
+    }
+  };
+  return Object.freeze(output);
+}
+
+function parseDiagnostics(json) {
+  if (json === "") {
+    return [];
+  }
+  return parseJson(json, "diagnostics JSON");
+}
+
+function parseJson(json, label) {
+  try {
+    return JSON.parse(json);
+  } catch (error) {
+    throw new Error(`Invalid ${label} returned by franken_markdown wasm core: ${error.message}`);
+  }
+}
+
+function stringOption(value) {
+  if (value === undefined || value === null) {
+    return undefined;
+  }
+  const text = String(value).trim();
+  return text === "" ? undefined : text;
+}
+
+// Preserve a caller value VERBATIM (including surrounding whitespace), mapping
+// only null/undefined/"" to `undefined`. Mirrors the Rust ABI's
+// `nonempty_verbatim` so title/author/customCss reach the renderer byte-for-byte
+// identical to the native CLI (native never trims them). `stringOption` (which
+// trims) is kept only for the enum-like `font` value.
+function verbatimOption(value) {
+  if (value === undefined || value === null) {
+    return undefined;
+  }
+  const text = String(value);
+  return text === "" ? undefined : text;
+}
+
+function darkModeOption(value) {
+  if (value === undefined || value === null) {
+    return undefined;
+  }
+  const text = String(value).trim().toLowerCase();
+  if (text === "" || text === "auto" || text === "system") {
+    return text === "system" ? "auto" : text || undefined;
+  }
+  if (text === "disabled" || text === "disable" || text === "off" || text === "light") {
+    return "disabled";
+  }
+  throw new TypeError("darkMode must be 'auto' or 'disabled'");
+}
+
+function epochOption(value) {
+  if (value === undefined || value === null) {
+    return undefined;
+  }
+  const epoch = value;
+  if (typeof epoch !== "number") {
+    throw new TypeError("metadataEpochSeconds must be a number");
+  }
+  if (!Number.isSafeInteger(epoch) || epoch < 0) {
+    throw new TypeError(
+      "metadataEpochSeconds must be a finite non-negative integer <= Number.MAX_SAFE_INTEGER"
+    );
+  }
+  return epoch;
+}
+
+function pdfImagesOption(value) {
+  if (value === undefined || value === null) {
+    return [];
+  }
+  if (!Array.isArray(value)) {
+    throw new TypeError("pdfImages must be an array of { destination, bytes } objects");
+  }
+  return value.map((asset, index) => {
+    if (asset === null || typeof asset !== "object") {
+      throw new TypeError(`pdfImages[${index}] must be an object`);
+    }
+    const destination = stringOption(asset.destination);
+    if (destination === undefined) {
+      throw new TypeError(`pdfImages[${index}].destination must be a non-empty string`);
+    }
+    const bytes = bytesOption(asset.bytes, `pdfImages[${index}].bytes`);
+    return Object.freeze({ destination, bytes });
+  });
+}
+
+function fontAssetsOption(value) {
+  if (value === undefined || value === null) {
+    return [];
+  }
+  if (!Array.isArray(value)) {
+    throw new TypeError("fontAssets must be an array of { slot, bytes } objects");
+  }
+  const seen = new Set();
+  return value.map((asset, index) => {
+    if (asset === null || typeof asset !== "object") {
+      throw new TypeError(`fontAssets[${index}] must be an object`);
+    }
+    const slot = fontSlotOption(asset.slot, `fontAssets[${index}].slot`);
+    if (seen.has(slot)) {
+      throw new TypeError(`fontAssets contains duplicate slot ${slot}`);
+    }
+    seen.add(slot);
+    const bytes = bytesOption(asset.bytes, `fontAssets[${index}].bytes`);
+    if (bytes.byteLength === 0) {
+      throw new TypeError(`fontAssets[${index}].bytes must not be empty`);
+    }
+    return Object.freeze({ slot, bytes });
+  });
+}
+
+function fontSlotOption(value, label) {
+  const slot = stringOption(value);
+  const allowed = new Set([
+    "body-regular",
+    "body-bold",
+    "body-italic",
+    "body-bold-italic",
+    "mono-regular"
+  ]);
+  if (slot === undefined || !allowed.has(slot)) {
+    throw new TypeError(
+      `${label} must be one of body-regular, body-bold, body-italic, body-bold-italic, mono-regular`
+    );
+  }
+  return slot;
+}
+
+function fontBytesForSlot(assets, slot) {
+  const asset = assets.find((entry) => entry.slot === slot);
+  return asset === undefined ? new Uint8Array() : asset.bytes;
+}
+
+function bytesOption(value, label) {
+  if (value instanceof Uint8Array) {
+    return value;
+  }
+  if (value instanceof ArrayBuffer) {
+    return new Uint8Array(value);
+  }
+  if (ArrayBuffer.isView(value)) {
+    return new Uint8Array(value.buffer, value.byteOffset, value.byteLength);
+  }
+  throw new TypeError(`${label} must be a Uint8Array, ArrayBuffer, or typed-array view`);
+}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@franken-suite/franken-markdown",
+  "version": "0.3.0",
+  "description": "Browser/WASM package for franken_markdown Markdown to HTML/PDF rendering.",
+  "type": "module",
+  "sideEffects": false,
+  "license": "LicenseRef-MIT-OpenAI-Anthropic-Rider",
+  "author": "Jeffrey Emanuel",
+  "homepage": "https://github.com/Dicklesworthstone/franken_markdown#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Dicklesworthstone/franken_markdown.git",
+    "directory": "wasm"
+  },
+  "bugs": {
+    "url": "https://github.com/Dicklesworthstone/franken_markdown/issues"
+  },
+  "keywords": [
+    "markdown",
+    "pdf",
+    "html",
+    "renderer",
+    "wasm",
+    "webassembly",
+    "typesetting"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "exports": {
+    ".": {
+      "types": "./franken_markdown.d.ts",
+      "import": "./franken_markdown.js"
+    }
+  },
+  "files": [
+    "franken_markdown.js",
+    "franken_markdown.d.ts",
+    "demo/index.html",
+    "demo/demo.js",
+    "pkg/franken_markdown.js",
+    "pkg/franken_markdown_bg.wasm",
+    "pkg/franken_markdown_bg.wasm.d.ts",
+    "pkg/franken_markdown.d.ts"
+  ]
+}

package/pkg/franken_markdown.d.ts

@@ -0,0 +1,172 @@
+/* tslint:disable */
+/* eslint-disable */
+
+/**
+ * Render output object exposed to JavaScript.
+ */
+export class FmdRenderResult {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Recoverable parser diagnostics as stable JSON.
+     */
+    diagnosticsJson(): string;
+    /**
+     * Rendered output bytes. HTML is UTF-8; PDF is binary.
+     */
+    readonly bytes: Uint8Array;
+    /**
+     * Default file extension without a leading dot.
+     */
+    readonly extension: string;
+    /**
+     * Stable output format: `html` or `pdf`.
+     */
+    readonly format: string;
+    /**
+     * Browser MIME type for Blob construction.
+     */
+    readonly mimeType: string;
+    /**
+     * Source size in bytes.
+     */
+    readonly sourceLength: number;
+}
+
+/**
+ * Dependency-free capability contract as JSON.
+ */
+export function capabilities(): string;
+
+/**
+ * Render Markdown to self-contained HTML using default browser-safe options.
+ *
+ * # Errors
+ * Returns a JavaScript error when rendering fails.
+ */
+export function renderHtml(markdown: string): FmdRenderResult;
+
+/**
+ * Render Markdown to self-contained HTML with browser package options.
+ *
+ * # Errors
+ * Returns a JavaScript error when options are invalid or rendering fails.
+ */
+export function renderHtmlConfigured(markdown: string, font: string | null | undefined, dark_mode: string | null | undefined, title: string | null | undefined, custom_css: string | null | undefined, allow_raw_html: boolean): FmdRenderResult;
+
+/**
+ * Render Markdown to self-contained HTML with browser package options and
+ * caller-supplied font bytes.
+ *
+ * Empty byte arrays mean "use bundled fallback" for that slot.
+ *
+ * # Errors
+ * Returns a JavaScript error when options are invalid or rendering fails.
+ */
+export function renderHtmlConfiguredWithFonts(markdown: string, font: string | null | undefined, dark_mode: string | null | undefined, title: string | null | undefined, custom_css: string | null | undefined, allow_raw_html: boolean, body_regular: Uint8Array, body_bold: Uint8Array, body_italic: Uint8Array, body_bold_italic: Uint8Array, mono_regular: Uint8Array): FmdRenderResult;
+
+/**
+ * Render Markdown to PDF using default browser-safe options.
+ *
+ * # Errors
+ * Returns a JavaScript error when rendering fails.
+ */
+export function renderPdf(markdown: string): FmdRenderResult;
+
+/**
+ * Render Markdown to PDF with browser package options.
+ *
+ * # Errors
+ * Returns a JavaScript error when options are invalid or rendering fails.
+ */
+export function renderPdfConfigured(markdown: string, font: string | null | undefined, dark_mode: string | null | undefined, title: string | null | undefined, author: string | null | undefined, metadata_epoch_seconds: number | null | undefined, allow_raw_html: boolean, code_line_numbers: boolean): FmdRenderResult;
+
+/**
+ * Render Markdown to PDF with browser package options, ANY number of image
+ * assets, and caller-supplied font bytes. This is the general form the JS
+ * wrapper uses so multi-image documents reach native↔WASM parity (the
+ * single-image entry points above remain for a narrower ABI).
+ *
+ * Images arrive as three parallel arrays — a destination per image, all image
+ * bytes concatenated, and the byte length of each image — because wasm-bindgen
+ * cannot pass a `Vec<Vec<u8>>` directly. Empty font byte arrays mean "use
+ * bundled fallback" for that slot.
+ *
+ * # Errors
+ * Returns a JavaScript error when the image arrays are inconsistent, an option
+ * is invalid, or rendering fails.
+ */
+export function renderPdfConfiguredMulti(markdown: string, font: string | null | undefined, dark_mode: string | null | undefined, title: string | null | undefined, author: string | null | undefined, metadata_epoch_seconds: number | null | undefined, allow_raw_html: boolean, code_line_numbers: boolean, image_destinations: string[], image_bytes_flat: Uint8Array, image_bytes_lengths: Uint32Array, body_regular: Uint8Array, body_bold: Uint8Array, body_italic: Uint8Array, body_bold_italic: Uint8Array, mono_regular: Uint8Array): FmdRenderResult;
+
+/**
+ * Render Markdown to PDF with browser package options, one optional image
+ * asset, and caller-supplied font bytes.
+ *
+ * Empty image destination/bytes means "no image asset"; empty font byte arrays
+ * mean "use bundled fallback" for that slot.
+ *
+ * # Errors
+ * Returns a JavaScript error when options are invalid or rendering fails.
+ */
+export function renderPdfConfiguredWithAssets(markdown: string, font: string | null | undefined, dark_mode: string | null | undefined, title: string | null | undefined, author: string | null | undefined, metadata_epoch_seconds: number | null | undefined, allow_raw_html: boolean, code_line_numbers: boolean, image_destination: string, image_bytes: Uint8Array, body_regular: Uint8Array, body_bold: Uint8Array, body_italic: Uint8Array, body_bold_italic: Uint8Array, mono_regular: Uint8Array): FmdRenderResult;
+
+/**
+ * Render Markdown to PDF with one browser-supplied image asset.
+ *
+ * This dependency-free adapter is intentionally narrow: callers pass bytes
+ * they already own (for example from a file picker or fetch handled outside
+ * the core). The renderer never touches the browser filesystem or network.
+ *
+ * # Errors
+ * Returns a JavaScript error when options are invalid or rendering fails.
+ */
+export function renderPdfConfiguredWithImage(markdown: string, font: string | null | undefined, dark_mode: string | null | undefined, title: string | null | undefined, author: string | null | undefined, metadata_epoch_seconds: number | null | undefined, allow_raw_html: boolean, code_line_numbers: boolean, image_destination: string, image_bytes: Uint8Array): FmdRenderResult;
+
+export type InitInput = RequestInfo | URL | Response | BufferSource | WebAssembly.Module;
+
+export interface InitOutput {
+    readonly memory: WebAssembly.Memory;
+    readonly __wbg_fmdrenderresult_free: (a: number, b: number) => void;
+    readonly capabilities: (a: number) => void;
+    readonly fmdrenderresult_bytes: (a: number, b: number) => void;
+    readonly fmdrenderresult_diagnosticsJson: (a: number, b: number) => void;
+    readonly fmdrenderresult_extension: (a: number, b: number) => void;
+    readonly fmdrenderresult_format: (a: number, b: number) => void;
+    readonly fmdrenderresult_mimeType: (a: number, b: number) => void;
+    readonly fmdrenderresult_sourceLength: (a: number) => number;
+    readonly renderHtml: (a: number, b: number, c: number) => void;
+    readonly renderHtmlConfigured: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number, i: number, j: number, k: number, l: number) => void;
+    readonly renderHtmlConfiguredWithFonts: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number, i: number, j: number, k: number, l: number, m: number, n: number, o: number, p: number, q: number, r: number, s: number, t: number, u: number, v: number) => void;
+    readonly renderPdf: (a: number, b: number, c: number) => void;
+    readonly renderPdfConfigured: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number, i: number, j: number, k: number, l: number, m: number, n: number, o: number) => void;
+    readonly renderPdfConfiguredMulti: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number, i: number, j: number, k: number, l: number, m: number, n: number, o: number, p: number, q: number, r: number, s: number, t: number, u: number, v: number, w: number, x: number, y: number, z: number, a1: number, b1: number, c1: number, d1: number, e1: number) => void;
+    readonly renderPdfConfiguredWithAssets: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number, i: number, j: number, k: number, l: number, m: number, n: number, o: number, p: number, q: number, r: number, s: number, t: number, u: number, v: number, w: number, x: number, y: number, z: number, a1: number, b1: number, c1: number) => void;
+    readonly renderPdfConfiguredWithImage: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number, i: number, j: number, k: number, l: number, m: number, n: number, o: number, p: number, q: number, r: number, s: number) => void;
+    readonly __wbindgen_export: (a: number, b: number) => number;
+    readonly __wbindgen_export2: (a: number, b: number, c: number, d: number) => number;
+    readonly __wbindgen_add_to_stack_pointer: (a: number) => number;
+    readonly __wbindgen_export3: (a: number, b: number, c: number) => void;
+}
+
+export type SyncInitInput = BufferSource | WebAssembly.Module;
+
+/**
+ * Instantiates the given `module`, which can either be bytes or
+ * a precompiled `WebAssembly.Module`.
+ *
+ * @param {{ module: SyncInitInput }} module - Passing `SyncInitInput` directly is deprecated.
+ *
+ * @returns {InitOutput}
+ */
+export function initSync(module: { module: SyncInitInput } | SyncInitInput): InitOutput;
+
+/**
+ * If `module_or_path` is {RequestInfo} or {URL}, makes a request and
+ * for everything else, calls `WebAssembly.instantiate` directly.
+ *
+ * @param {{ module_or_path: InitInput | Promise<InitInput> }} module_or_path - Passing `InitInput` directly is deprecated.
+ *
+ * @returns {Promise<InitOutput>}
+ */
+export default function __wbg_init (module_or_path?: { module_or_path: InitInput | Promise<InitInput> } | InitInput | Promise<InitInput>): Promise<InitOutput>;