@open-press/core 0.6.0 → 0.7.1

package/engine/react/pipeline/allocate.mjs

@@ -0,0 +1,248 @@
+// Layer 4 — Allocation.
+//
+// Per chain, fills MdxAreas with block IDs using the Phase 1 region allocator.
+// Returns:
+//   - `allocation`: { [frameKey]: { [chainId]: blockIds[][] } } — areas per chain, area index → blockIds
+//   - `hints`: { totalPagesPerChain: { [chainId]: number } } — fed back to <Sections>
+//   - `warnings`: chain-overflowed, etc.
+
+const SANITY_LIMIT = 200;
+
+/**
+ * @param {object} opts
+ * @param {Array<FrameInstance>} opts.frames       Layer 2 frame structure.
+ * @param {Array<MdxAreaMeasurement>} opts.mdxAreas Layer 3 MdxArea capacities.
+ * @param {Array<BlockMeasurement>} opts.blockHeights Layer 3 block heights.
+ * @param {Record<string, object>} opts.sources    Resolved sources (for chain block lists).
+ * @returns {AllocationResult}
+ */
+export function allocateChains({ frames, mdxAreas, blockHeights, sources }) {
+  // Group MdxAreas by chainId, sorted by (frame order, indexInFrame)
+  const chainAreas = groupAreasByChain(frames, mdxAreas);
+  // Group block heights by chainId
+  const blockHeightsByChain = groupBlockHeights(blockHeights);
+
+  const allocation = {};
+  const warnings = [];
+  const totalPagesPerChain = {};
+  // Track per-chain how many extension iterations the caller (orchestrator)
+  // should request. The actual *cloning* is done at the Press tree level
+  // by feeding hints back to <Sections>; here we just report how many
+  // frames each chain *should* have.
+
+  for (const [chainId, chainSource] of iterateChains(sources)) {
+    const areas = chainAreas.get(chainId) ?? [];
+    const blocks = buildBlockStream(chainSource, blockHeightsByChain.get(chainId));
+
+    const regions = areas.map((a) => ({
+      id: `${a.frameKey}#${a.indexInFrame}`,
+      capacity: a.capacity,
+      pageIndex: 0, // not used here; we keep our own mapping
+      columnIndex: a.indexInFrame,
+      __frameKey: a.frameKey,
+      __chainId: chainId,
+      __overflow: a.overflow,
+    }));
+
+    if (regions.length === 0 || blocks.length === 0) {
+      // No areas to fill, or no blocks to place.
+      if (blocks.length > 0 && !chainId.startsWith("toc:")) {
+        warnings.push({ code: "chain-has-no-area", chainId });
+      }
+      // Frames already correctly count to 0 for this chain.
+      // (Or it's a static-source chain like the cover, which doesn't allocate.)
+      // Skip.
+      // If chain has blocks but no areas, that's an authoring error.
+      const sourceFrameCount = frames.filter((f) => f.mdxAreas.some((a) => a.chainId === chainId)).length;
+      totalPagesPerChain[chainId] = Math.max(1, sourceFrameCount);
+      continue;
+    }
+
+    const { result, neededAreas } = greedyAllocate(blocks, regions);
+    const lastOverflow = regions[regions.length - 1].__overflow;
+    const sourceFramesForChain = uniqueFramesForChain(frames, chainId);
+
+    if (neededAreas > regions.length) {
+      // Overflow detected.
+      if (lastOverflow === "error") {
+        const remaining = blocks.slice(result.consumed).map((b) => b.id);
+        throw new Error(
+          `Chain "${chainId}" overflowed and the last MdxArea is overflow="error". ` +
+            `Remaining block IDs: ${remaining.slice(0, 5).join(", ")}${remaining.length > 5 ? `, ... (${remaining.length} total)` : ""}.`,
+        );
+      }
+      if (lastOverflow === "truncate") {
+        warnings.push({
+          code: "chain-overflowed",
+          chainId,
+          remainingBlocks: blocks.length - result.consumed,
+        });
+        // Don't grow totalPages; truncate at current capacity.
+        totalPagesPerChain[chainId] = sourceFramesForChain;
+        recordAllocation(allocation, result, regions);
+        continue;
+      }
+      // overflow="extend" (default): scale frame count up.
+      const areasPerFrame = Math.max(1, regions.length / Math.max(1, sourceFramesForChain));
+      const extraAreasNeeded = neededAreas - regions.length;
+      const extraFramesNeeded = Math.ceil(extraAreasNeeded / areasPerFrame);
+      const newTotal = sourceFramesForChain + extraFramesNeeded;
+      if (newTotal > SANITY_LIMIT) {
+        throw new Error(
+          `Chain "${chainId}" would require ${newTotal} frames after extension, exceeding the sanity limit of ${SANITY_LIMIT}. ` +
+            `Check that block content fits within the MdxArea capacity.`,
+        );
+      }
+      totalPagesPerChain[chainId] = newTotal;
+      // Don't record allocation yet — orchestrator will re-render with more
+      // frames and re-allocate.
+      continue;
+    }
+
+    totalPagesPerChain[chainId] = sourceFramesForChain;
+    recordAllocation(allocation, result, regions);
+  }
+
+  return {
+    allocation,
+    hints: { totalPagesPerChain },
+    warnings,
+  };
+}
+
+function greedyAllocate(blocks, regions) {
+  const filled = [];
+  let regionIndex = 0;
+  let currentBlockIds = [];
+  let currentHeight = 0;
+  let consumed = 0;
+  const flush = () => {
+    if (currentBlockIds.length === 0) return;
+    filled.push({
+      region: regions[regionIndex],
+      blockIds: currentBlockIds,
+    });
+    currentBlockIds = [];
+    currentHeight = 0;
+  };
+  for (let blockIndex = 0; blockIndex < blocks.length; blockIndex += 1) {
+    const block = blocks[blockIndex];
+    while (regionIndex < regions.length) {
+      const region = regions[regionIndex];
+      const nextBlock = blocks[blockIndex + 1];
+      const keepWithNextHeight = shouldKeepWithNext(block, nextBlock) ? block.height + nextBlock.height : 0;
+      if (
+        currentBlockIds.length > 0 &&
+        keepWithNextHeight > 0 &&
+        currentHeight + keepWithNextHeight > region.capacity
+      ) {
+        flush();
+        regionIndex += 1;
+        continue;
+      }
+      if (currentBlockIds.length === 0 || currentHeight + block.height <= region.capacity) {
+        currentBlockIds.push(block.id);
+        currentHeight += block.height;
+        consumed += 1;
+        break;
+      }
+      // Doesn't fit — flush current region and advance
+      flush();
+      regionIndex += 1;
+    }
+    if (regionIndex >= regions.length) break;
+  }
+  flush();
+  // neededAreas = total regions consumed if we had unlimited supply
+  // For overflow detection we estimate: if consumed < blocks.length, we need more areas.
+  let neededAreas = filled.length;
+  if (consumed < blocks.length) {
+    // Estimate how many more areas needed
+    const lastCap = regions[regions.length - 1].capacity;
+    const remainingBlocks = blocks.slice(consumed);
+    let h = 0;
+    let extra = 0;
+    let inExtra = false;
+    for (const b of remainingBlocks) {
+      if (!inExtra || h + b.height > lastCap) {
+        extra += 1;
+        h = b.height;
+        inExtra = true;
+      } else {
+        h += b.height;
+      }
+    }
+    neededAreas += extra;
+  }
+  return { result: { filled, consumed }, neededAreas };
+}
+
+function shouldKeepWithNext(block, nextBlock) {
+  if (!nextBlock) return false;
+  return /^h[1-6]$/.test(String(block?.name ?? ""));
+}
+
+function recordAllocation(allocation, result, regions) {
+  for (const fill of result.filled) {
+    const frameKey = fill.region.__frameKey;
+    const chainId = fill.region.__chainId;
+    const areaIndex = fill.region.columnIndex;
+    if (!allocation[frameKey]) allocation[frameKey] = {};
+    if (!allocation[frameKey][chainId]) allocation[frameKey][chainId] = [];
+    allocation[frameKey][chainId][areaIndex] = fill.blockIds;
+  }
+}
+
+function groupAreasByChain(frames, mdxAreas) {
+  // mdxAreas come from chromium in DOM order. We need to order by (frame
+  // sequence position in Press tree, indexInFrame). Use frames[] order.
+  const frameOrder = new Map();
+  frames.forEach((f, idx) => frameOrder.set(f.frameKey, idx));
+  const byChain = new Map();
+  const sorted = [...mdxAreas].sort((a, b) => {
+    const fa = frameOrder.get(a.frameKey) ?? Number.MAX_SAFE_INTEGER;
+    const fb = frameOrder.get(b.frameKey) ?? Number.MAX_SAFE_INTEGER;
+    if (fa !== fb) return fa - fb;
+    return a.indexInFrame - b.indexInFrame;
+  });
+  for (const area of sorted) {
+    if (!byChain.has(area.chainId)) byChain.set(area.chainId, []);
+    byChain.get(area.chainId).push(area);
+  }
+  return byChain;
+}
+
+function groupBlockHeights(blockHeights) {
+  const byChain = new Map();
+  for (const block of blockHeights) {
+    if (!byChain.has(block.chainId)) byChain.set(block.chainId, new Map());
+    byChain.get(block.chainId).set(block.id, block.height);
+  }
+  return byChain;
+}
+
+function buildBlockStream(chainSource, heightMap) {
+  if (!chainSource || !heightMap) return [];
+  return chainSource.map((block) => ({
+    id: block.id,
+    kind: block.kind,
+    name: block.name,
+    height: heightMap.get(block.id) ?? 0,
+  }));
+}
+
+function* iterateChains(sources) {
+  for (const source of Object.values(sources)) {
+    for (const [chainId, blocks] of Object.entries(source.chains)) {
+      yield [chainId, blocks];
+    }
+  }
+}
+
+function uniqueFramesForChain(frames, chainId) {
+  const set = new Set();
+  for (const f of frames) {
+    if (f.mdxAreas.some((a) => a.chainId === chainId)) set.add(f.frameKey);
+  }
+  return Math.max(1, set.size);
+}

package/engine/react/pipeline/final-render.mjs

@@ -0,0 +1,94 @@
+// Layer 5 — Final Render.
+//
+// Given the allocation map (frameKey -> chainId -> areaIndex -> blockIds),
+// pre-compiles each MdxArea's block subset into React nodes, then renders
+// the Press tree one more time with `PressContext.allocation` populated.
+// The output HTML is parsed back into per-frame fragments for document.json.
+
+import React from "react";
+import { expandPressTree } from "./press-tree.mjs";
+import { compileChainBlocks } from "../sources/mdx-resolver.mjs";
+
+/**
+ * @returns {{ frames: Array<{ frameKey, role, chrome, html, blockIds, mdxAreas }>, html: string }}
+ */
+export async function renderFinalPress({
+  Press,
+  PressContext,
+  sources,
+  hints,
+  toc,
+  allocation: blockAllocation, // chainId blockId allocator output: { [frameKey]: { [chainId]: blockIds[][] } }
+  renderRegistry,
+}) {
+  // 1. Compile React nodes per (frameKey, chainId, areaIndex)
+  const reactAllocation = await buildReactAllocation(blockAllocation, sources, renderRegistry, toc);
+
+  // 2. Render Press tree with allocation in context
+  const { html, frames } = expandPressTree({
+    Press,
+    PressContext,
+    sources,
+    hints,
+    toc,
+    allocation: reactAllocation,
+  });
+
+  // 3. Annotate frame instances with blockIds (for document.json)
+  const framesWithBlocks = frames.map((frame) => {
+    const frameBlocks = blockAllocation[frame.frameKey] ?? {};
+    const blockIds = [];
+    const mdxAreas = frame.mdxAreas.map((area) => {
+      const ids = frameBlocks[area.chainId]?.[area.indexInFrame] ?? [];
+      blockIds.push(...ids);
+      return {
+        chainId: area.chainId,
+        indexInFrame: area.indexInFrame,
+        blockIds: ids,
+      };
+    });
+    return {
+      frameKey: frame.frameKey,
+      role: frame.role,
+      chrome: frame.chrome,
+      html: frame.html,
+      blockIds,
+      mdxAreas,
+    };
+  });
+
+  return { frames: framesWithBlocks, html };
+}
+
+async function buildReactAllocation(blockAllocation, sources, renderRegistry, toc) {
+  /** @type {Record<string, Record<string, React.ReactNode[]>>} */
+  const out = {};
+  const sourceOfChain = new Map();
+  for (const source of Object.values(sources)) {
+    for (const chainId of Object.keys(source.chains)) {
+      sourceOfChain.set(chainId, source.id);
+    }
+  }
+
+  for (const [frameKey, chainMap] of Object.entries(blockAllocation)) {
+    out[frameKey] = {};
+    for (const [chainId, areaArr] of Object.entries(chainMap)) {
+      const nodesByArea = [];
+      for (let areaIndex = 0; areaIndex < areaArr.length; areaIndex++) {
+        const blockIds = areaArr[areaIndex] ?? [];
+        if (blockIds.length === 0) {
+          nodesByArea[areaIndex] = null;
+          continue;
+        }
+        const sourceId = sourceOfChain.get(chainId);
+        const renderData = renderRegistry.get(sourceId);
+        const compiled = await compileChainBlocks({ renderData, chainId, blockIds, toc });
+        nodesByArea[areaIndex] = compiled.map(({ Content }, i) =>
+          React.createElement(Content, { key: `${areaIndex}-${i}` }),
+        );
+      }
+      out[frameKey][chainId] = nodesByArea;
+    }
+  }
+  return out;
+}

package/engine/react/pipeline/frame-measurement.mjs

@@ -0,0 +1,300 @@
+// Layer 3 — Frame Measurement.
+//
+// Renders the Press tree (from Layer 2) plus a hidden "blocks zone" that
+// contains every chain's full content, sends the combined document to
+// Chromium, then queries the DOM for:
+//   - MdxArea capacities (per frameKey + chainId + indexInFrame)
+//   - Block heights (per chainId + blockId)
+//
+// The blocks zone uses the same `.page-body` CSS context as the live
+// frames so widths and font metrics match.
+
+import fs from "node:fs/promises";
+import path from "node:path";
+import React from "react";
+import { renderToStaticMarkup } from "react-dom/server";
+import { chromium } from "playwright";
+import { createCaptionNumberingState, numberCaptionsInHtml } from "../caption-numbering.mjs";
+import { compileChainBlocks } from "../sources/mdx-resolver.mjs";
+
+const DEFAULT_VIEWPORT = { width: 794, height: 1123 };
+
+// Safety inset applied to measured MdxArea capacities. A small reserve keeps
+// content that visually fits "exactly" from clipping due to anti-aliasing,
+// line breaks, and rounding.
+const CAPACITY_SAFETY_RATIO = 0.04;
+const CAPACITY_SAFETY_MAX_PX = 96;
+
+/**
+ * @param {object} opts
+ * @param {string} opts.pressHtml   Rendered Press tree HTML (Layer 2).
+ * @param {Record<string, object>} opts.sources Resolved sources keyed by sourceId.
+ * @param {Map<string, object>} opts.renderRegistry Internal render data per sourceId.
+ * @param {string} opts.css         Combined CSS for measurement context.
+ * @param {string=} opts.baseHref   Base URL for relative media paths in MDX.
+ * @param {string=} opts.mediaDir  Local media dir for inlining /openpress/media/* assets.
+ * @param {object=} opts.captionNumbering Caption label formatter options.
+ * @param {{width:number,height:number}=} opts.viewport
+ */
+export async function measureFrames({
+  pressHtml,
+  sources,
+  renderRegistry,
+  css = "",
+  baseHref = "",
+  mediaDir = "",
+  captionNumbering = {},
+  viewport = DEFAULT_VIEWPORT,
+}) {
+  const chainContent = await buildChainContent(sources, renderRegistry, captionNumbering);
+  const html = await buildMeasurementDocument({ pressHtml, chainContent, css, baseHref, mediaDir });
+  return runChromiumMeasurement(html, viewport);
+}
+
+async function buildChainContent(sources, renderRegistry, captionNumbering) {
+  const out = new Map();
+  const captionState = createCaptionNumberingState();
+  for (const source of Object.values(sources)) {
+    for (const [chainId, blocks] of Object.entries(source.chains)) {
+      const blockIds = blocks.map((b) => b.id);
+      const renderData = renderRegistry.get(source.id);
+      const compiled = await compileChainBlocks({ renderData, chainId, blockIds });
+      const html = compiled
+        .map(({ Content }, idx) => renderToStaticMarkup(React.createElement(Content, { key: idx })))
+        .join("");
+      out.set(
+        chainId,
+        chainId.startsWith("toc:") ? html : numberCaptionsInHtml(html, captionNumbering, captionState),
+      );
+    }
+  }
+  return out;
+}
+
+async function buildMeasurementDocument({ pressHtml, chainContent, css, baseHref, mediaDir }) {
+  const normalizedPressHtml = await inlineMeasurementMediaUrls(pressHtml, mediaDir);
+  const blocksZoneParts = [];
+  for (const [chainId, contentHtml] of chainContent.entries()) {
+    const normalizedContentHtml = await inlineMeasurementMediaUrls(contentHtml, mediaDir);
+    const containerTag = chainId.startsWith("toc:") ? "ol" : "div";
+    const containerClass = chainId.startsWith("toc:") ? ' class="toc-list"' : "";
+    blocksZoneParts.push(`
+      <section class="reader-page reader-page--content" data-openpress-measure-frame="${escapeAttr(chainId)}" data-page-kind="content">
+        <div class="page-frame">
+          <main class="page-body">
+            <${containerTag}${containerClass} data-block-measurement-chain="${escapeAttr(chainId)}" style="overflow: visible;">
+              ${normalizedContentHtml}
+            </${containerTag}>
+          </main>
+        </div>
+      </section>
+    `);
+  }
+  const blocksZone = blocksZoneParts.join("\n");
+
+  return `<!doctype html>
+<html>
+  <head>
+    <meta charset="utf-8">
+    ${baseHref ? `<base href="${escapeAttr(baseHref)}">` : ""}
+    <style>
+      body { margin: 0; }
+      ${css}
+      /* Reader-page is hidden by default in the workspace theme (only the
+         is-active page is shown). Override visibility in measurement zones
+         but do not touch the page-frame display, because the theme uses
+         CSS grid with grid-template-rows reserving page-header and
+         page-footer space; we must preserve that layout so MdxArea
+         inherits the real page-body cell height. */
+      [data-openpress-frames-zone] .reader-page,
+      [data-openpress-blocks-zone] .reader-page {
+        display: block !important;
+      }
+      /* MdxArea fills its grid/flex parent so we measure the layout slot,
+         not the inserted content. */
+      [data-openpress-frames-zone] [data-openpress-mdx-area="true"] {
+        display: block;
+        box-sizing: border-box;
+        min-height: 0;
+        align-self: stretch;
+        overflow: visible;
+      }
+      [data-openpress-frames-zone] { position: relative; }
+      [data-openpress-blocks-zone] { position: fixed; left: -200000px; top: 0; visibility: hidden; pointer-events: none; }
+    </style>
+  </head>
+  <body>
+    <div data-openpress-frames-zone>${normalizedPressHtml}</div>
+    <div data-openpress-blocks-zone>${blocksZone}</div>
+  </body>
+</html>`;
+}
+
+async function runChromiumMeasurement(html, viewport) {
+  const browser = await chromium.launch();
+  try {
+    const page = await browser.newPage({ viewport });
+    await page.setContent(html, { waitUntil: "load" });
+    // Match the print-ready settle: fonts first (font metrics affect image
+    // alt-text fallback boxes), then await every image's `complete` AND
+    // `decode()` so intrinsic sizes are committed before layout, then two
+    // animation frames so the chromium layout pass observes the final box
+    // model. Without this, `getBoundingClientRect()` on figures that hold
+    // images can race the decode and return collapsed heights, causing the
+    // allocator to pack too many blocks per page.
+    await page.evaluate(async () => {
+      if (document.fonts?.ready) await document.fonts.ready;
+      await Promise.all(Array.from(document.images).map(async (img) => {
+        if (!img.complete) {
+          await new Promise((resolve) => {
+            const settle = () => {
+              img.removeEventListener("load", settle);
+              img.removeEventListener("error", settle);
+              resolve(undefined);
+            };
+            img.addEventListener("load", settle, { once: true });
+            img.addEventListener("error", settle, { once: true });
+          });
+        }
+        await img.decode?.().catch(() => undefined);
+      }));
+      await new Promise((resolve) => requestAnimationFrame(() => requestAnimationFrame(resolve)));
+    });
+
+    const mdxAreas = await page.evaluate((safety) => {
+      const zone = document.querySelector("[data-openpress-frames-zone]");
+      if (!zone) return [];
+      const areas = Array.from(zone.querySelectorAll("[data-openpress-mdx-area]"));
+      const out = [];
+      for (const el of areas) {
+        const frame = el.closest("[data-openpress-frame-key]");
+        if (!frame) continue;
+        const frameKey = frame.getAttribute("data-openpress-frame-key") || "";
+        const chainId = el.getAttribute("data-openpress-mdx-area-chain") || "";
+        const overflow = el.getAttribute("data-openpress-mdx-area-overflow") || "extend";
+        // Index within this frame's same-chain areas
+        const sameInFrame = Array.from(frame.querySelectorAll(`[data-openpress-mdx-area][data-openpress-mdx-area-chain="${chainId}"]`));
+        const indexInFrame = sameInFrame.indexOf(el);
+        const rect = measuredMdxAreaRect(el);
+        const inset = Math.min(safety.maxPx, Math.max(0, rect.height * safety.ratio));
+        const capacity = Math.max(1, rect.height - inset);
+        out.push({
+          frameKey,
+          chainId,
+          overflow,
+          indexInFrame,
+          capacity,
+          rawHeight: rect.height,
+          width: rect.width,
+        });
+      }
+      return out;
+
+      function measuredMdxAreaRect(el) {
+        const rect = el.getBoundingClientRect();
+        if (rect.height > 1) return rect;
+        const candidates = [
+          el.parentElement,
+          el.closest(".page-body"),
+          el.closest("[data-openpress-frame-key]")?.querySelector(".page-body"),
+        ];
+        for (const candidate of candidates) {
+          if (!candidate) continue;
+          const fallback = candidate.getBoundingClientRect();
+          if (fallback.height > rect.height) {
+            return {
+              height: fallback.height,
+              width: rect.width > 0 ? rect.width : fallback.width,
+            };
+          }
+        }
+        return rect;
+      }
+    }, { ratio: CAPACITY_SAFETY_RATIO, maxPx: CAPACITY_SAFETY_MAX_PX });
+
+    const blockHeights = await page.evaluate(() => {
+      const zone = document.querySelector("[data-openpress-blocks-zone]");
+      if (!zone) return [];
+      const out = [];
+      for (const chain of zone.querySelectorAll("[data-block-measurement-chain]")) {
+        const chainId = chain.getAttribute("data-block-measurement-chain") ?? "";
+        const parentTop = chain.parentElement?.getBoundingClientRect().top ?? chain.getBoundingClientRect().top;
+        let previousBottom = parentTop;
+        for (const el of Array.from(chain.querySelectorAll("[data-openpress-block-id]"))) {
+          const rect = el.getBoundingClientRect();
+          out.push({
+            id: el.getAttribute("data-openpress-block-id"),
+            height: Math.max(rect.height, rect.bottom - previousBottom),
+            chainId,
+          });
+          previousBottom = Math.max(previousBottom, rect.bottom);
+        }
+      }
+      return out;
+    });
+
+    return { mdxAreas, blockHeights };
+  } finally {
+    await browser.close();
+  }
+}
+
+function escapeAttr(value) {
+  return String(value).replace(/&/g, "&amp;").replace(/"/g, "&quot;").replace(/</g, "&lt;");
+}
+
+async function inlineMeasurementMediaUrls(html, mediaDir) {
+  if (!mediaDir || !html) return html;
+  let out = String(html);
+  const matches = new Set();
+  for (const match of out.matchAll(/\bsrc=(['"])([^\1]*?)\1/g)) {
+    const src = match[2];
+    if (!src) continue;
+    if (src.startsWith('/openpress/media/')) {
+      matches.add(src.slice('/openpress/media/'.length));
+      continue;
+    }
+    if (src.startsWith('media/')) {
+      matches.add(src.slice('media/'.length));
+      continue;
+    }
+    if (src.startsWith('./media/')) {
+      matches.add(src.slice('./media/'.length));
+    }
+  }
+  for (const rawName of matches) {
+    const dataUrl = await mediaDataUrl(mediaDir, rawName);
+    if (!dataUrl) continue;
+    out = out.replaceAll(`/openpress/media/${rawName}`, dataUrl);
+    out = out.replaceAll(`media/${rawName}`, dataUrl);
+    out = out.replaceAll(`./media/${rawName}`, dataUrl);
+  }
+  return out;
+}
+
+async function mediaDataUrl(mediaDir, rawName) {
+  let fileName;
+  try {
+    fileName = decodeURIComponent(String(rawName));
+  } catch {
+    fileName = String(rawName);
+  }
+  if (!fileName || fileName !== path.basename(fileName)) return null;
+  const filePath = path.join(mediaDir, fileName);
+  let bytes;
+  try {
+    bytes = await fs.readFile(filePath);
+  } catch {
+    return null;
+  }
+  return `data:${mediaMimeType(fileName)};base64,${bytes.toString("base64")}`;
+}
+
+function mediaMimeType(fileName) {
+  const ext = path.extname(fileName).toLowerCase();
+  if (ext === ".svg") return "image/svg+xml";
+  if (ext === ".jpg" || ext === ".jpeg") return "image/jpeg";
+  if (ext === ".gif") return "image/gif";
+  if (ext === ".webp") return "image/webp";
+  return "image/png";
+}