From c70390d2b9e992bfafd7d5c169277d2147f0b3ab Mon Sep 17 00:00:00 2001
From: Sergey Plotnikov <sergey.plotnikov@ogresearch.com>
Date: Fri, 26 Jun 2026 14:05:22 +0200
Subject: [PATCH] Embed custom fonts into vector exports

Add an opt `fonts` (a list of font-file paths) that embeds the given
fonts into Kaleido's output so figures render with the correct typeface
without the font being installed system-wide.

Plotly's SVG output only references fonts by name; it never embeds the
font bytes. For PDF/EPS, Kaleido loads that SVG into an isolated <img>
document, so an uninstalled font silently falls back (e.g. Times New
Roman). This change fixes that end to end:

- font_tools.py: parse a .ttf/.otf/.woff file, read its family name from
  the sfnt `name` table, and build a base64 `@font-face` descriptor.
  .woff2 (Brotli) and .ttc collections are rejected with actionable
  errors.
- fig_tools.py: accept `fonts` in LayoutOpts and package each path into
  the spec sent to the render scope.
- render.js: load the fonts into the page before rendering (correct text
  metrics) and inline the `@font-face` (with base64 data) into the SVG so
  vector output is self-contained and survives the isolated <img> used
  for PDF/EPS.
- Rebuilt vendor/kaleido_scopes.js bundle.
- Tests for font parsing, format hints, error paths, and coerce_for_js.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 src/js/src/plotly/parse.js              |   1 +
 src/js/src/plotly/render.js             |  91 +++++++++--
 src/py/README.md                        |   6 +-
 src/py/kaleido/_utils/fig_tools.py      |  13 +-
 src/py/kaleido/_utils/font_tools.py     | 208 ++++++++++++++++++++++++
 src/py/kaleido/vendor/kaleido_scopes.js |  92 +++++++++--
 src/py/tests/test_font_tools.py         | 160 ++++++++++++++++++
 7 files changed, 546 insertions(+), 25 deletions(-)
 create mode 100644 src/py/kaleido/_utils/font_tools.py
 create mode 100644 src/py/tests/test_font_tools.py

diff --git a/src/js/src/plotly/parse.js b/src/js/src/plotly/parse.js
index c5e7b944..be0c9844 100644
--- a/src/js/src/plotly/parse.js
+++ b/src/js/src/plotly/parse.js
@@ -60,6 +60,7 @@ function parse (body, _opts) {
   result.scale = isPositiveNumeric(opts.scale) ? Number(opts.scale) : cst.dflt.scale
   result.fid = isNonEmptyString(opts.fid) ? opts.fid : null
   result.encoded = !!opts.encoded
+  result.fonts = Array.isArray(opts.fonts) ? opts.fonts : []
 
   if (isNonEmptyString(opts.format)) {
     if (cst.contentFormat[opts.format]) {
diff --git a/src/js/src/plotly/render.js b/src/js/src/plotly/render.js
index a190d52e..b2b74a39 100644
--- a/src/js/src/plotly/render.js
+++ b/src/js/src/plotly/render.js
@@ -38,6 +38,7 @@ function render (info, topojsonURL, stepper) {
   const figure = info.figure;
   const format = info.format;
   const encoded = info.encoded;
+  const fonts = info.fonts || [];
 
   // Build default config, and let figure.config override it
   const defaultConfig = {
@@ -113,15 +114,23 @@ function render (info, topojsonURL, stepper) {
     return new Promise((resolve) => {resolve(done())})
   }
 
-  let promise
+  if (semver.lt(Plotly.version, '1.11.0')) {
+    errorCode = 526
+    errorMsg = `plotly.js version: ${Plotly.version}`
+    return new Promise((resolve) => {resolve(done())})
+  }
 
-  if (semver.gte(Plotly.version, '1.30.0')) {
-    promise = Plotly
-      .toImage({ data: figure.data, layout: figure.layout, config: config }, imgOpts)
-  } else if (semver.gte(Plotly.version, '1.11.0')) {
-    const gd = document.createElement('div')
+  // Render the figure to an image. Wrapped in a function so it only runs
+  // *after* any custom fonts have loaded (see loadFonts below), ensuring text
+  // is measured with the correct font metrics.
+  const makeImage = () => {
+    if (semver.gte(Plotly.version, '1.30.0')) {
+      return Plotly
+        .toImage({ data: figure.data, layout: figure.layout, config: config }, imgOpts)
+    }
 
-    promise = Plotly
+    const gd = document.createElement('div')
+    return Plotly
       .newPlot(gd, figure.data, figure.layout, config)
       .then(() => Plotly.toImage(gd, imgOpts))
       .then((imgData) => {
@@ -148,16 +157,22 @@ function render (info, topojsonURL, stepper) {
             return imgData
         }
       })
-  } else {
-    errorCode = 526
-    errorMsg = `plotly.js version: ${Plotly.version}`
-    return new Promise((resolve) => {resolve(done())})
   }
 
+  // Load any custom fonts into the page before rendering. This both fixes text
+  // measurement and lets the (now embedded) @font-face survive into vector
+  // output. No-op when no fonts were requested.
+  const promise = loadFonts(fonts).then(makeImage)
+
   const img = document.getElementById("kaleido-image")
   const style = document.getElementById("head-style")
 
   let exportPromise = promise.then((imgData) => {
+    // For vector output, inline the fonts into the SVG itself so the result is
+    // self-contained and renders correctly without the font being installed.
+    if (fonts.length && (format === 'svg' || PRINT_TO_PDF)) {
+      imgData = injectFontsIntoSVG(imgData, fonts)
+    }
     result = imgData
     return done()
   })
@@ -218,4 +233,58 @@ function decodeSVG (imgData) {
   return window.decodeURIComponent(imgData.replace(cst.imgPrefix.svg, ''))
 }
 
+/**
+ * Register custom fonts with the page and wait for them to be ready.
+ *
+ * @param {Array<{family: string, format: string, url: string}>} fonts
+ * @return {Promise} resolves once every font has loaded (failures are logged,
+ *   not fatal, so rendering still proceeds with a fallback).
+ */
+function loadFonts (fonts) {
+  if (!fonts || !fonts.length ||
+      typeof FontFace === 'undefined' || !document.fonts) {
+    return Promise.resolve()
+  }
+
+  return Promise.all(fonts.map((font) => {
+    const face = new FontFace(font.family, `url(${font.url})`)
+    document.fonts.add(face)
+    return face.load().catch((err) => {
+      console.log(`kaleido: failed to load font '${font.family}': ${err}`)
+    })
+  })).then(() => document.fonts.ready)
+}
+
+/**
+ * Inline @font-face rules (with base64 font data) into an SVG so the vector
+ * output embeds the fonts and renders identically anywhere, with no system
+ * font installation required.
+ *
+ * @param {string} imgData : either a raw SVG string or a
+ *   `data:image/svg+xml,...` URI (handled transparently).
+ * @param {Array<{family: string, format: string, url: string}>} fonts
+ * @return {string} imgData in the same form it was passed in.
+ */
+function injectFontsIntoSVG (imgData, fonts) {
+  if (!fonts || !fonts.length) return imgData
+
+  const css = fonts.map((font) =>
+    `@font-face { font-family: '${font.family}';` +
+    ` src: url(${font.url}) format('${font.format}'); }`
+  ).join('\n')
+  const styleEl = `<style type="text/css"><![CDATA[\n${css}\n]]></style>`
+
+  const isDataUri = imgData.indexOf('data:image/svg+xml,') === 0
+  let svg = isDataUri
+    ? window.decodeURIComponent(imgData.replace(cst.imgPrefix.svg, ''))
+    : imgData
+
+  // Insert the <style> block immediately after the opening <svg ...> tag.
+  svg = svg.replace(/(<svg\b[^>]*>)/, `$1${styleEl}`)
+
+  return isDataUri
+    ? 'data:image/svg+xml,' + window.encodeURIComponent(svg)
+    : svg
+}
+
 module.exports = render
diff --git a/src/py/README.md b/src/py/README.md
index 899d6740..17fafe21 100644
--- a/src/py/README.md
+++ b/src/py/README.md
@@ -81,7 +81,11 @@ async with kaleido.Kaleido(n=4, timeout=90) as k:
 # - path:      A directory (names auto-generated based on title)
 #              or a single file.
 # - opts:      A dictionary with image options:
-#              `{"scale":..., "format":..., "width":..., "height":...}`
+#              `{"scale":..., "format":..., "width":..., "height":...,
+#                "fonts": [...]}`
+#              `fonts` is a list of paths to font files (.ttf/.otf/.woff).
+#              They are embedded into vector output (svg/pdf/eps) so charts
+#              render with the right font without installing it system-wide.
 # - error_log: If you pass a list here, image-generation errors will be appended
 #              to the list and generation continues. If left as `None`, the
 #              first error will cause failure.
diff --git a/src/py/kaleido/_utils/fig_tools.py b/src/py/kaleido/_utils/fig_tools.py
index b5e24029..d2e6a520 100644
--- a/src/py/kaleido/_utils/fig_tools.py
+++ b/src/py/kaleido/_utils/fig_tools.py
@@ -10,13 +10,13 @@
 
 import logistro
 
-from . import path_tools
+from . import font_tools, path_tools
 
 if TYPE_CHECKING:
     from pathlib import Path
     from typing import Any
 
-    from typing_extensions import TypeGuard
+    from typing_extensions import NotRequired, TypeGuard
 
     Figurish = Any  # Be nice to make it more specific, dictionary or something
     FormatString = Literal["png", "jpg", "jpeg", "webp", "svg", "json", "pdf"]
@@ -28,6 +28,9 @@ class LayoutOpts(TypedDict, total=False):
     scale: int | float
     height: int | float
     width: int | float
+    # Paths to font files (.ttf/.otf/.woff) to embed into vector output so the
+    # figure renders with them without the fonts being installed system-wide.
+    fonts: list[str | Path]
 
 
 # Output of to_spec (we give kaleido_scopes.js this)
@@ -38,6 +41,7 @@ class Spec(TypedDict):
     height: int | float
     scale: int | float
     data: Figurish
+    fonts: NotRequired[list[font_tools.FontFace]]
 
 
 _logger = logistro.getLogger(__name__)
@@ -147,4 +151,9 @@ def coerce_for_js(
         "data": fig,
     }
 
+    # Custom fonts: read each file once, derive its family name, and package it
+    # as a base64 @font-face descriptor for the render scope to embed.
+    if fonts := opts.get("fonts"):
+        spec["fonts"] = [font_tools.font_face_from_path(font) for font in fonts]
+
     return spec
diff --git a/src/py/kaleido/_utils/font_tools.py b/src/py/kaleido/_utils/font_tools.py
new file mode 100644
index 00000000..ede91f62
--- /dev/null
+++ b/src/py/kaleido/_utils/font_tools.py
@@ -0,0 +1,208 @@
+"""
+Tools for embedding custom fonts into vector exports.
+
+Plotly's SVG output only references fonts by name; it never embeds the font
+itself. When Kaleido renders that SVG (for PDF, SVG, or EPS), the font name is
+resolved against fonts available to the browser/OS, so a font that is not
+installed falls back to a default (e.g. Times New Roman).
+
+This module turns a font file on disk into a self-describing ``@font-face``
+descriptor (family name + format hint + base64 ``data:`` URL). The descriptor
+is sent to the render scope, which both loads the font in the page (so text is
+measured correctly) and embeds it into the produced SVG (so the vector output
+is self-contained and needs no system font installation).
+
+The font family name is read directly from the font's ``name`` table, so the
+caller only has to supply the file path; the family they reference in the
+figure's ``font_family`` is matched automatically.
+
+Only the uncompressed sfnt formats (``.ttf``/``.otf``) and ``.woff`` are
+parsed. ``.woff2`` stores all tables in a single Brotli stream and cannot be
+read without a Brotli decoder, so it is rejected with an actionable error.
+"""
+
+from __future__ import annotations
+
+import base64
+import struct
+import zlib
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+import logistro
+
+if TYPE_CHECKING:
+    from typing import TypedDict
+
+    class FontFace(TypedDict):
+        family: str
+        format: str
+        url: str
+
+
+_logger = logistro.getLogger(__name__)
+
+# sfnt flavor (first 4 bytes) -> (@font-face format hint, data: URL mime type)
+_SFNT_FLAVORS = {
+    b"\x00\x01\x00\x00": ("truetype", "font/ttf"),  # TrueType outlines
+    b"true": ("truetype", "font/ttf"),  # legacy Apple TrueType
+    b"typ1": ("truetype", "font/ttf"),  # legacy Apple Type 1
+    b"OTTO": ("opentype", "font/otf"),  # CFF (OpenType) outlines
+}
+
+_NAME_FAMILY = 1  # nameID 1: Font Family name
+_NAME_TYPOGRAPHIC_FAMILY = 16  # nameID 16: Typographic (preferred) Family name
+
+_SFNT_HEADER_LEN = 12  # offsetTable: flavor(4) + numTables(2) + 3x uint16
+
+
+def _decode_name_record(platform_id: int, raw: bytes) -> str | None:
+    """Decode a name-table string per its platform's encoding."""
+    try:
+        if platform_id in (0, 3):  # Unicode, Windows -> UTF-16BE
+            return raw.decode("utf-16-be")
+        if platform_id == 1:  # Macintosh -> (approximate as) Latin-1
+            return raw.decode("latin-1")
+    except UnicodeDecodeError:
+        return None
+    return None
+
+
+def _read_family_from_sfnt(data: bytes) -> str | None:
+    """Extract the family name from an in-memory sfnt (TrueType/OpenType) font."""
+    if len(data) < _SFNT_HEADER_LEN:
+        return None
+    num_tables = struct.unpack(">H", data[4:6])[0]
+
+    name_offset = None
+    for i in range(num_tables):
+        rec = 12 + i * 16
+        tag = data[rec : rec + 4]
+        if tag == b"name":
+            name_offset = struct.unpack(">I", data[rec + 8 : rec + 12])[0]
+            break
+    if name_offset is None:
+        return None
+
+    count, string_offset = struct.unpack(">HH", data[name_offset + 2 : name_offset + 6])
+    storage = name_offset + string_offset
+
+    # Prefer the typographic family (nameID 16) over the basic family (nameID 1),
+    # since that is the name CSS/users normally reference for multi-weight families.
+    candidates: dict[int, str] = {}
+    for i in range(count):
+        rec = name_offset + 6 + i * 12
+        platform_id, _enc, _lang, name_id, length, offset = struct.unpack(
+            ">HHHHHH",
+            data[rec : rec + 12],
+        )
+        if name_id not in (_NAME_FAMILY, _NAME_TYPOGRAPHIC_FAMILY):
+            continue
+        raw = data[storage + offset : storage + offset + length]
+        decoded = _decode_name_record(platform_id, raw)
+        if decoded and name_id not in candidates:
+            candidates[name_id] = decoded.strip()
+
+    return candidates.get(_NAME_TYPOGRAPHIC_FAMILY) or candidates.get(_NAME_FAMILY)
+
+
+def _woff_to_sfnt(data: bytes) -> bytes:
+    """
+    Reassemble an sfnt blob from a WOFF (v1) container, enough to read names.
+
+    Only the ``name`` table's bytes need to be valid for family extraction, but
+    rebuilding the full table directory keeps the parser identical to sfnt.
+    """
+    flavor = data[4:8]
+    num_tables = struct.unpack(">H", data[12:14])[0]
+
+    # WOFF table directory entries are 20 bytes: tag, offset, compLength,
+    # origLength, origChecksum.
+    tables = []
+    for i in range(num_tables):
+        rec = 44 + i * 20
+        tag, offset, comp_len, orig_len, _ = struct.unpack(
+            ">4sIIII",
+            data[rec : rec + 20],
+        )
+        blob = data[offset : offset + comp_len]
+        if comp_len != orig_len:
+            blob = zlib.decompress(blob)
+        tables.append((tag, blob))
+
+    # Rebuild a minimal sfnt: header + directory + concatenated tables.
+    out = bytearray()
+    out += flavor
+    out += struct.pack(">H", num_tables)
+    out += struct.pack(">HHH", 0, 0, 0)  # searchRange/entrySelector/rangeShift (unused)
+
+    body = bytearray()
+    body_base = 12 + num_tables * 16
+    for tag, blob in tables:
+        offset = body_base + len(body)
+        out += struct.pack(">4sIII", tag, 0, offset, len(blob))
+        body += blob
+        body += b"\x00" * (-len(blob) % 4)  # 4-byte align
+    out += body
+    return bytes(out)
+
+
+def font_face_from_path(path: str | Path) -> FontFace:
+    """
+    Build an ``@font-face`` descriptor from a font file on disk.
+
+    Args:
+        path: Path to a ``.ttf``, ``.otf``, or ``.woff`` font file.
+
+    Returns:
+        A dict with ``family`` (read from the font), ``format`` (``@font-face``
+        ``format()`` hint), and ``url`` (a base64 ``data:`` URL).
+
+    Raises:
+        FileNotFoundError: If the path does not exist.
+        ValueError: If the font format is unsupported or the family name cannot
+            be read.
+
+    """
+    path = Path(path)
+    if not path.is_file():
+        raise FileNotFoundError(f"Font file not found: {path}")
+
+    data = path.read_bytes()
+    signature = data[:4]
+
+    if signature == b"wOFF":
+        fmt, mime = "woff", "font/woff"
+        family = _read_family_from_sfnt(_woff_to_sfnt(data))
+    elif signature == b"wOF2":
+        raise ValueError(
+            f"{path.name}: .woff2 fonts are not supported (they require a Brotli "
+            "decoder). Supply the .ttf, .otf, or .woff version of the font.",
+        )
+    elif signature in _SFNT_FLAVORS:
+        fmt, mime = _SFNT_FLAVORS[signature]
+        family = _read_family_from_sfnt(data)
+    elif signature == b"ttcf":
+        raise ValueError(
+            f"{path.name}: TrueType/OpenType Collections (.ttc) are not "
+            "supported. Supply a single-font .ttf or .otf file.",
+        )
+    else:
+        raise ValueError(
+            f"{path.name}: unrecognized font format (signature {signature!r}). "
+            "Supported formats: .ttf, .otf, .woff.",
+        )
+
+    if not family:
+        raise ValueError(
+            f"{path.name}: could not read a font family name from the font's "
+            "'name' table.",
+        )
+
+    encoded = base64.b64encode(data).decode("ascii")
+    _logger.debug(f"Prepared font '{family}' ({fmt}) from {path}")
+    return {
+        "family": family,
+        "format": fmt,
+        "url": f"data:{mime};base64,{encoded}",
+    }
diff --git a/src/py/kaleido/vendor/kaleido_scopes.js b/src/py/kaleido/vendor/kaleido_scopes.js
index 3ed4cbf8..057cda95 100644
--- a/src/py/kaleido/vendor/kaleido_scopes.js
+++ b/src/py/kaleido/vendor/kaleido_scopes.js
@@ -2723,6 +2723,7 @@ function parse (body, _opts) {
   result.scale = isPositiveNumeric(opts.scale) ? Number(opts.scale) : cst.dflt.scale
   result.fid = isNonEmptyString(opts.fid) ? opts.fid : null
   result.encoded = !!opts.encoded
+  result.fonts = Array.isArray(opts.fonts) ? opts.fonts : []
 
   if (isNonEmptyString(opts.format)) {
     if (cst.contentFormat[opts.format]) {
@@ -2941,6 +2942,7 @@ function render (info, topojsonURL, stepper) {
   const figure = info.figure;
   const format = info.format;
   const encoded = info.encoded;
+  const fonts = info.fonts || [];
 
   // Build default config, and let figure.config override it
   const defaultConfig = {
@@ -3016,15 +3018,23 @@ function render (info, topojsonURL, stepper) {
     return new Promise((resolve) => {resolve(done())})
   }
 
-  let promise
+  if (semver.lt(Plotly.version, '1.11.0')) {
+    errorCode = 526
+    errorMsg = `plotly.js version: ${Plotly.version}`
+    return new Promise((resolve) => {resolve(done())})
+  }
 
-  if (semver.gte(Plotly.version, '1.30.0')) {
-    promise = Plotly
-      .toImage({ data: figure.data, layout: figure.layout, config: config }, imgOpts)
-  } else if (semver.gte(Plotly.version, '1.11.0')) {
-    const gd = document.createElement('div')
+  // Render the figure to an image. Wrapped in a function so it only runs
+  // *after* any custom fonts have loaded (see loadFonts below), ensuring text
+  // is measured with the correct font metrics.
+  const makeImage = () => {
+    if (semver.gte(Plotly.version, '1.30.0')) {
+      return Plotly
+        .toImage({ data: figure.data, layout: figure.layout, config: config }, imgOpts)
+    }
 
-    promise = Plotly
+    const gd = document.createElement('div')
+    return Plotly
       .newPlot(gd, figure.data, figure.layout, config)
       .then(() => Plotly.toImage(gd, imgOpts))
       .then((imgData) => {
@@ -3051,16 +3061,22 @@ function render (info, topojsonURL, stepper) {
             return imgData
         }
       })
-  } else {
-    errorCode = 526
-    errorMsg = `plotly.js version: ${Plotly.version}`
-    return new Promise((resolve) => {resolve(done())})
   }
 
+  // Load any custom fonts into the page before rendering. This both fixes text
+  // measurement and lets the (now embedded) @font-face survive into vector
+  // output. No-op when no fonts were requested.
+  const promise = loadFonts(fonts).then(makeImage)
+
   const img = document.getElementById("kaleido-image")
   const style = document.getElementById("head-style")
 
   let exportPromise = promise.then((imgData) => {
+    // For vector output, inline the fonts into the SVG itself so the result is
+    // self-contained and renders correctly without the font being installed.
+    if (fonts.length && (format === 'svg' || PRINT_TO_PDF)) {
+      imgData = injectFontsIntoSVG(imgData, fonts)
+    }
     result = imgData
     return done()
   })
@@ -3121,6 +3137,60 @@ function decodeSVG (imgData) {
   return window.decodeURIComponent(imgData.replace(cst.imgPrefix.svg, ''))
 }
 
+/**
+ * Register custom fonts with the page and wait for them to be ready.
+ *
+ * @param {Array<{family: string, format: string, url: string}>} fonts
+ * @return {Promise} resolves once every font has loaded (failures are logged,
+ *   not fatal, so rendering still proceeds with a fallback).
+ */
+function loadFonts (fonts) {
+  if (!fonts || !fonts.length ||
+      typeof FontFace === 'undefined' || !document.fonts) {
+    return Promise.resolve()
+  }
+
+  return Promise.all(fonts.map((font) => {
+    const face = new FontFace(font.family, `url(${font.url})`)
+    document.fonts.add(face)
+    return face.load().catch((err) => {
+      console.log(`kaleido: failed to load font '${font.family}': ${err}`)
+    })
+  })).then(() => document.fonts.ready)
+}
+
+/**
+ * Inline @font-face rules (with base64 font data) into an SVG so the vector
+ * output embeds the fonts and renders identically anywhere, with no system
+ * font installation required.
+ *
+ * @param {string} imgData : either a raw SVG string or a
+ *   `data:image/svg+xml,...` URI (handled transparently).
+ * @param {Array<{family: string, format: string, url: string}>} fonts
+ * @return {string} imgData in the same form it was passed in.
+ */
+function injectFontsIntoSVG (imgData, fonts) {
+  if (!fonts || !fonts.length) return imgData
+
+  const css = fonts.map((font) =>
+    `@font-face { font-family: '${font.family}';` +
+    ` src: url(${font.url}) format('${font.format}'); }`
+  ).join('\n')
+  const styleEl = `<style type="text/css"><![CDATA[\n${css}\n]]></style>`
+
+  const isDataUri = imgData.indexOf('data:image/svg+xml,') === 0
+  let svg = isDataUri
+    ? window.decodeURIComponent(imgData.replace(cst.imgPrefix.svg, ''))
+    : imgData
+
+  // Insert the <style> block immediately after the opening <svg ...> tag.
+  svg = svg.replace(/(<svg\b[^>]*>)/, `$1${styleEl}`)
+
+  return isDataUri
+    ? 'data:image/svg+xml,' + window.encodeURIComponent(svg)
+    : svg
+}
+
 module.exports = render
 
 },{"./constants":51,"./parse":54,"semver":32}]},{},[50])(50)
diff --git a/src/py/tests/test_font_tools.py b/src/py/tests/test_font_tools.py
new file mode 100644
index 00000000..41e438fe
--- /dev/null
+++ b/src/py/tests/test_font_tools.py
@@ -0,0 +1,160 @@
+"""Tests for kaleido._utils.font_tools (custom font embedding).
+
+The font parser only needs a valid ``name`` table to extract a family, so the
+helpers below build the smallest possible sfnt/WOFF containers carrying name
+records. This keeps the tests free of any real font-file fixtures.
+"""
+
+import base64
+import struct
+
+import pytest
+
+from kaleido._utils import fig_tools, font_tools
+
+NAME_FAMILY = 1  # nameID 1: Font Family name
+NAME_TYPOGRAPHIC = 16  # nameID 16: Typographic Family name
+WOFF_HEADER_LEN = 44
+
+
+def _name_table(records):
+    """Build a minimal sfnt 'name' table from (name_id, family) records.
+
+    Records are emitted as platform 3 (Windows / UTF-16BE) entries.
+    """
+    storage_offset = 6 + 12 * len(records)
+    header = struct.pack(">HHH", 0, len(records), storage_offset)
+
+    recs = b""
+    storage = b""
+    for name_id, family in records:
+        raw = family.encode("utf-16-be")
+        recs += struct.pack(">HHHHHH", 3, 1, 0x409, name_id, len(raw), len(storage))
+        storage += raw
+    return header + recs + storage
+
+
+def _sfnt(records, flavor=b"\x00\x01\x00\x00"):
+    """Build a minimal single-table ('name') sfnt font."""
+    if isinstance(records, str):
+        records = [(NAME_FAMILY, records)]
+    name_tbl = _name_table(records)
+    name_offset = 12 + 16  # header(12) + one dir entry(16)
+    header = flavor + struct.pack(">HHHH", 1, 0, 0, 0)  # numTables=1, then unused
+    directory = struct.pack(">4sIII", b"name", 0, name_offset, len(name_tbl))
+    return header + directory + name_tbl
+
+
+def _woff(family, flavor=b"\x00\x01\x00\x00"):
+    """Build a minimal single-table WOFF (v1) container (name table uncompressed)."""
+    name_tbl = _name_table([(NAME_FAMILY, family)])
+    table_offset = WOFF_HEADER_LEN + 20  # header + one dir entry(20)
+    header = b"wOFF" + flavor + b"\x00" * 4 + struct.pack(">H", 1) + b"\x00" * 30
+    assert len(header) == WOFF_HEADER_LEN
+    directory = struct.pack(
+        ">4sIIII",
+        b"name",
+        table_offset,
+        len(name_tbl),  # compLength == origLength -> stored uncompressed
+        len(name_tbl),
+        0,
+    )
+    return header + directory + name_tbl
+
+
+# --- family extraction -------------------------------------------------------
+
+
+def test_ttf_family_and_format(tmp_path):
+    f = tmp_path / "Test.ttf"
+    f.write_bytes(_sfnt("My Test Font"))
+    face = font_tools.font_face_from_path(f)
+    assert face["family"] == "My Test Font"
+    assert face["format"] == "truetype"
+    assert face["url"].startswith("data:font/ttf;base64,")
+    # url must round-trip to the original bytes
+    b64 = face["url"].split(",", 1)[1]
+    assert base64.b64decode(b64) == f.read_bytes()
+
+
+def test_otf_uses_opentype_hint(tmp_path):
+    f = tmp_path / "Test.otf"
+    f.write_bytes(_sfnt("CFF Font", flavor=b"OTTO"))
+    face = font_tools.font_face_from_path(f)
+    assert face["family"] == "CFF Font"
+    assert face["format"] == "opentype"
+    assert face["url"].startswith("data:font/otf;base64,")
+
+
+def test_woff_is_decoded(tmp_path):
+    f = tmp_path / "Test.woff"
+    f.write_bytes(_woff("Woffy"))
+    face = font_tools.font_face_from_path(f)
+    assert face["family"] == "Woffy"
+    assert face["format"] == "woff"
+    assert face["url"].startswith("data:font/woff;base64,")
+
+
+def test_typographic_family_preferred_over_basic(tmp_path):
+    """nameID 16 (typographic) should win over nameID 1 (basic) when both exist."""
+    f = tmp_path / "Multi.ttf"
+    f.write_bytes(_sfnt([(NAME_FAMILY, "Basic"), (NAME_TYPOGRAPHIC, "Typographic")]))
+    assert font_tools.font_face_from_path(f)["family"] == "Typographic"
+
+
+# --- error paths -------------------------------------------------------------
+
+
+def test_missing_file(tmp_path):
+    with pytest.raises(FileNotFoundError):
+        font_tools.font_face_from_path(tmp_path / "nope.ttf")
+
+
+def test_woff2_rejected(tmp_path):
+    f = tmp_path / "Test.woff2"
+    f.write_bytes(b"wOF2" + b"\x00" * 32)
+    with pytest.raises(ValueError, match="woff2"):
+        font_tools.font_face_from_path(f)
+
+
+def test_ttc_rejected(tmp_path):
+    f = tmp_path / "Test.ttc"
+    f.write_bytes(b"ttcf" + b"\x00" * 32)
+    with pytest.raises(ValueError, match=r"[Cc]ollection"):
+        font_tools.font_face_from_path(f)
+
+
+def test_unrecognized_format(tmp_path):
+    f = tmp_path / "Test.bin"
+    f.write_bytes(b"\xde\xad\xbe\xef" + b"\x00" * 32)
+    with pytest.raises(ValueError, match="unrecognized"):
+        font_tools.font_face_from_path(f)
+
+
+def test_missing_name_table(tmp_path):
+    """A valid sfnt signature but no readable family name is an error."""
+    # numTables=0 -> no name table at all.
+    f = tmp_path / "NoName.ttf"
+    f.write_bytes(b"\x00\x01\x00\x00" + struct.pack(">HHHH", 0, 0, 0, 0))
+    with pytest.raises(ValueError, match="family name"):
+        font_tools.font_face_from_path(f)
+
+
+# --- integration with coerce_for_js ------------------------------------------
+
+
+def test_coerce_for_js_packages_fonts(tmp_path):
+    """opts['fonts'] paths should become FontFace descriptors in the spec."""
+    f = tmp_path / "Inter.ttf"
+    f.write_bytes(_sfnt("Inter"))
+    fig = {"data": [], "layout": {}}
+    spec = fig_tools.coerce_for_js(fig, None, {"format": "svg", "fonts": [f]})
+    assert "fonts" in spec
+    assert spec["fonts"][0]["family"] == "Inter"
+    assert spec["fonts"][0]["format"] == "truetype"
+
+
+def test_coerce_for_js_omits_fonts_when_absent():
+    """No 'fonts' key in the spec when none were requested."""
+    spec = fig_tools.coerce_for_js({"data": [], "layout": {}}, None, {"format": "svg"})
+    assert "fonts" not in spec