@bendyline/squisq-formats 2.8.9 → 2.8.11

package/README.md

@@ -337,19 +337,21 @@ Also exported: `createRegistry` / `defaultRegistry` / `defaultFormats`, `BUILTIN
 
 ## Subpath Exports
 
-| Subpath                               | Contents                                                                        |
-| ------------------------------------- | ------------------------------------------------------------------------------- |
-| `@bendyline/squisq-formats/docx`      | DOCX import/export (+ `docxToContainer`)                                        |
-| `@bendyline/squisq-formats/pdf`       | PDF import/export (+ `pdfToContainer`, `configurePdfWorker`)                    |
-| `@bendyline/squisq-formats/html`      | Player HTML export, static plain-HTML export + bundles, HTML import             |
-| `@bendyline/squisq-formats/epub`      | EPUB 3 e-book export (with optional Media Overlays)                             |
-| `@bendyline/squisq-formats/pptx`      | PPTX export + import (text/lists/tables + slide images)                         |
-| `@bendyline/squisq-formats/xlsx`      | XLSX import + tables-only export                                                |
-| `@bendyline/squisq-formats/csv`       | CSV import/export (RFC 4180)                                                    |
-| `@bendyline/squisq-formats/ooxml`     | Shared OOXML infrastructure (package reader/writer, XML utilities, namespaces)  |
-| `@bendyline/squisq-formats/diagrams`  | `rasterizeDiagrams` / `findDiagrams`: diagrams as pictures for document exports |
-| `@bendyline/squisq-formats/container` | `ContentContainer` ↔ ZIP serialization                                          |
-| `@bendyline/squisq-formats/registry`  | Format registry + programmatic `convert()` (also re-exported from the root)     |
+| Subpath                                  | Contents                                                                        |
+| ---------------------------------------- | ------------------------------------------------------------------------------- |
+| `@bendyline/squisq-formats/docx`         | DOCX import/export (+ `docxToContainer`)                                        |
+| `@bendyline/squisq-formats/pdf`          | PDF import/export (+ `pdfToContainer`, `configurePdfWorker`)                    |
+| `@bendyline/squisq-formats/html`         | Player HTML export, static plain-HTML export + bundles, HTML import             |
+| `@bendyline/squisq-formats/html-prepare` | `prepareMarkdownDocForPlainHtml`: data tables and pictures for plain-HTML pages |
+| `@bendyline/squisq-formats/html-icons`   | `plainHtmlIcons`: inline icons as SVG outlines for plain-HTML pages             |
+| `@bendyline/squisq-formats/epub`         | EPUB 3 e-book export (with optional Media Overlays)                             |
+| `@bendyline/squisq-formats/pptx`         | PPTX export + import (text/lists/tables + slide images)                         |
+| `@bendyline/squisq-formats/xlsx`         | XLSX import + tables-only export                                                |
+| `@bendyline/squisq-formats/csv`          | CSV import/export (RFC 4180)                                                    |
+| `@bendyline/squisq-formats/ooxml`        | Shared OOXML infrastructure (package reader/writer, XML utilities, namespaces)  |
+| `@bendyline/squisq-formats/diagrams`     | `rasterizeDiagrams` / `findDiagrams`: diagrams as pictures for document exports |
+| `@bendyline/squisq-formats/container`    | `ContentContainer` ↔ ZIP serialization                                          |
+| `@bendyline/squisq-formats/registry`     | Format registry + programmatic `convert()` (also re-exported from the root)     |
 
 The package root re-exports the common converters; `./container`, the plain-HTML/bundle functions, `docxToContainer`, `pdfToContainer`, `PdfPageSize`, and the image utilities are subpath-only.
 

package/dist/{chunk-SZ3OIY6G.js → chunk-4SPMLGOG.js}

@@ -1,7 +1,3 @@
-import {
-  findDiagrams,
-  rasterizeDiagrams
-} from "./chunk-4LIFEQKX.js";
 import {
   arrayBufferToBase64DataUrl,
   extractFilename,
@@ -1022,80 +1018,6 @@ function escapeAttr(s) {
   return escapeHtml2(s).replace(/"/g, """);
 }
 
-// src/html/plainHtmlPrepare.ts
-import { isDataFilePath } from "@bendyline/squisq/doc";
-var PAGE_DIAGRAM_KINDS = [
-  "mermaid",
-  "diagram",
-  "timeline",
-  "container",
-  "chart"
-];
-function needsPlainHtmlPreparation(doc, options = {}) {
-  let icons = false;
-  let data = false;
-  const visit = (node) => {
-    if (!node || typeof node !== "object" || icons && data) return;
-    const n = node;
-    if (n.type === "inlineIcon") icons = true;
-    if (n.type === "heading") {
-      const src = n.templateAnnotation?.params?.src;
-      if (src && isDataFilePath(src)) data = true;
-    }
-    if (Array.isArray(n.children)) n.children.forEach(visit);
-  };
-  doc.children.forEach(visit);
-  if (icons || data && options.container) return true;
-  if (!options.renderDiagram) return false;
-  return findDiagrams(doc).some((diagram) => PAGE_DIAGRAM_KINDS.includes(diagram.kind));
-}
-async function prepareMarkdownDocForPlainHtml(doc, options = {}) {
-  const { renderDiagram, container, signal, onWarning } = options;
-  let markdownDoc = doc;
-  if (container) {
-    const { materializeDataReferences, DATA_PREVIEW_ROWS } = await import("./materialize-ICXNO4S4.js");
-    markdownDoc = await materializeDataReferences(markdownDoc, container, onWarning, {
-      maxRows: options.maxDataRows ?? DATA_PREVIEW_ROWS,
-      tableCache: options.dataTableCache
-    });
-  }
-  signal?.throwIfAborted();
-  const { plainHtmlIcons } = await import("./plainHtmlIcons-KBSIJ5EN.js");
-  const icons = await plainHtmlIcons(markdownDoc);
-  const images = /* @__PURE__ */ new Map();
-  if (!renderDiagram) return { markdownDoc, images, icons };
-  const pictured = await rasterizeDiagrams(markdownDoc, renderDiagram, {
-    kinds: PAGE_DIAGRAM_KINDS,
-    urlPrefix: "squisq-picture",
-    signal,
-    onWarning
-  });
-  const widths = /* @__PURE__ */ new Map();
-  for (const [url, picture] of pictured.images) {
-    const bytes = picture.data;
-    const buffer = bytes.buffer.slice(
-      bytes.byteOffset,
-      bytes.byteOffset + bytes.byteLength
-    );
-    images.set(url, arrayBufferToBase64DataUrl(buffer, picture.contentType));
-    widths.set(url, Math.round(picture.width));
-  }
-  return { markdownDoc: withPictureWidths(pictured.markdownDoc, widths), images, icons };
-}
-function withPictureWidths(doc, widths) {
-  if (widths.size === 0) return doc;
-  const visit = (node) => {
-    if (node.type === "image") {
-      const width = widths.get(node.url);
-      return width === void 0 ? node : { ...node, width };
-    }
-    const children = node.children;
-    if (!Array.isArray(children)) return node;
-    return { ...node, children: children.map(visit) };
-  };
-  return { ...doc, children: doc.children.map(visit) };
-}
-
 // src/html/plainHtmlBundle.ts
 import JSZip from "jszip";
 import { parseMarkdown, inferDocumentTitle } from "@bendyline/squisq/markdown";
@@ -1325,6 +1247,7 @@ function titleForFilename(path, mdDoc) {
 // src/html/pageTemplate.ts
 var HTML_PAGE_TEMPLATE_CONTENT_START = "<!-- squisq:content -->";
 var HTML_PAGE_TEMPLATE_CONTENT_END = "<!-- /squisq:content -->";
+var HTML_PAGE_TEMPLATE_IMAGE_SLOT = "og-image";
 var HtmlPageTemplateError = class extends Error {
   constructor(issues) {
     super(
@@ -1371,6 +1294,10 @@ function analyzeTemplate(html) {
       isTemplate: tags.some(isLightSlot),
       defaultSlotCount: defaultSlots.length,
       namedSlots,
+      usesImage: namedSlots.includes(HTML_PAGE_TEMPLATE_IMAGE_SLOT) || tags.some((tag) => {
+        if (tag.kind !== "start" || tag.name !== "meta" || tag.inert) return false;
+        return IMAGE_URL_META.has(metaKey(tag) ?? "");
+      }),
       errors: errors.sort((a, b) => a.line - b.line)
     }
   };
@@ -1382,19 +1309,24 @@ function applyHtmlPageTemplate(template, content, options = {}) {
   const { tags, slots, inspection } = analyzeTemplate(template);
   if (inspection.errors.length > 0) throw new HtmlPageTemplateError(inspection.errors);
   const values = content.values ?? {};
-  const valueFor = (name) => name === "title" ? content.title : values[name];
+  const { image } = content;
+  const valueFor = (name) => name === "title" ? content.title : name === HTML_PAGE_TEMPLATE_IMAGE_SLOT ? void 0 : values[name];
+  const slotMarkup = (name) => {
+    if (name === null) {
+      return `${HTML_PAGE_TEMPLATE_CONTENT_START}
+${content.bodyHtml}
+${HTML_PAGE_TEMPLATE_CONTENT_END}`;
+    }
+    if (name === HTML_PAGE_TEMPLATE_IMAGE_SLOT) return image && imageElement(image);
+    const value = valueFor(name);
+    return value === void 0 ? void 0 : escapeHtml3(value);
+  };
   const edits = [];
   const replacements = /* @__PURE__ */ new Set();
   for (const slot of slots) {
-    const value = slot.name === null ? void 0 : valueFor(slot.name);
-    if (slot.name === null || value !== void 0) {
-      const replacement = {
-        start: slot.start,
-        end: slot.end,
-        text: slot.name === null ? `${HTML_PAGE_TEMPLATE_CONTENT_START}
-${content.bodyHtml}
-${HTML_PAGE_TEMPLATE_CONTENT_END}` : escapeHtml3(value ?? "")
-      };
+    const markup = slotMarkup(slot.name);
+    if (markup !== void 0) {
+      const replacement = { start: slot.start, end: slot.end, text: markup };
       edits.push(replacement);
       replacements.add(replacement);
     } else {
@@ -1415,8 +1347,8 @@ ${HTML_PAGE_TEMPLATE_CONTENT_END}` : escapeHtml3(value ?? "")
   }
   for (const tag of tags) {
     if (tag.kind !== "start" || tag.name !== "meta" || tag.inert) continue;
-    const key = (attributeValue(tag, "name") ?? attributeValue(tag, "property"))?.toLowerCase();
-    const value = key ? metaValue(key, content.title, values.description) : void 0;
+    const key = metaKey(tag);
+    const value = key ? metaValue(key, content.title, values.description, image) : void 0;
     if (value === void 0) continue;
     const contentAttribute = tag.attributes.find((attribute) => attribute.name === "content");
     const text = `content="${escapeAttr2(value)}"`;
@@ -1693,11 +1625,34 @@ function fillTitleText(text, valueFor) {
 }
 var TITLE_META = /* @__PURE__ */ new Set(["og:title", "twitter:title"]);
 var DESCRIPTION_META = /* @__PURE__ */ new Set(["description", "og:description", "twitter:description"]);
-function metaValue(key, title, description) {
+var IMAGE_URL_META = /* @__PURE__ */ new Set([
+  "og:image",
+  "og:image:url",
+  "og:image:secure_url",
+  "twitter:image",
+  "twitter:image:src"
+]);
+var IMAGE_ALT_META = /* @__PURE__ */ new Set(["og:image:alt", "twitter:image:alt"]);
+function metaKey(tag) {
+  return (attributeValue(tag, "name") ?? attributeValue(tag, "property"))?.toLowerCase();
+}
+function metaValue(key, title, description, image) {
   if (TITLE_META.has(key)) return title;
   if (DESCRIPTION_META.has(key)) return description;
+  if (!image) return void 0;
+  if (IMAGE_URL_META.has(key)) return image.url;
+  if (IMAGE_ALT_META.has(key)) return image.alt;
+  if (key === "og:image:width" || key === "og:image:height") {
+    const size = key === "og:image:width" ? image.width : image.height;
+    return size === void 0 ? void 0 : String(size);
+  }
+  if (key === "og:image:type") return image.type;
   return void 0;
 }
+function imageElement(image) {
+  const size = image.width !== void 0 && image.height !== void 0 ? ` width="${String(image.width)}" height="${String(image.height)}"` : "";
+  return `<img src="${escapeAttr2(image.src ?? image.url)}" alt="${escapeAttr2(image.alt ?? "")}"${size}>`;
+}
 function headInsertionPoint(tags) {
   for (const tag of tags) {
     if (tag.inert) continue;
@@ -2765,12 +2720,11 @@ export {
   generateExternalHtml,
   markdownDocToPlainHtml,
   markdownDocToPlainHtmlParts,
-  needsPlainHtmlPreparation,
-  prepareMarkdownDocForPlainHtml,
   markdownDocsToPlainHtmlBundle,
   collectLinkRefs,
   HTML_PAGE_TEMPLATE_CONTENT_START,
   HTML_PAGE_TEMPLATE_CONTENT_END,
+  HTML_PAGE_TEMPLATE_IMAGE_SLOT,
   HtmlPageTemplateError,
   isHtmlPageTemplate,
   inspectHtmlPageTemplate,

package/dist/{chunk-6HUQFEP3.js → chunk-D2JA3MLG.js}

@@ -1,15 +1,15 @@
+import {
+  OUTSIDE_IN_FORMAT_IDS,
+  OUTSIDE_IN_OUTPUT_TEMPLATE_KEY,
+  resolveOutsideInLayout
+} from "./chunk-WJTC5OD6.js";
 import {
   convert,
   defaultRegistry
-} from "./chunk-WVDAFJFS.js";
+} from "./chunk-JINVU6QA.js";
 import {
   ConversionError
 } from "./chunk-KXOZMWBS.js";
-import {
-  OUTSIDE_IN_FORMAT_IDS,
-  OUTSIDE_IN_OUTPUT_TEMPLATE_KEY,
-  resolveOutsideInLayout
-} from "./chunk-WJTC5OD6.js";
 
 // src/outside-in/index.ts
 import {

package/dist/html/icons.d.ts

@@ -0,0 +1,29 @@
+import { MarkdownDocument } from '@bendyline/squisq/markdown';
+import { P as PlainHtmlIcon } from '../plainHtml-B6IXcSet.js';
+import '@bendyline/squisq/schemas';
+
+/**
+ * Inline icons as SVG, for pages that should not depend on a font.
+ *
+ * A Font Awesome icon in the plain renderer is `<i class="fa-solid fa-star">`,
+ * which draws only where Font Awesome's stylesheet and fonts load — a CDN the
+ * page may not be allowed to reach, or a bundle it doesn't ship. Each icon's
+ * outline is read here from the same Font Awesome faces the DOCX, PDF and
+ * EPUB exporters embed, and drawn as a small inline `<svg>` instead: no font,
+ * no network, and it takes the text color like the glyph would.
+ *
+ * This module is its own entry, `@bendyline/squisq-formats/html-icons`, and
+ * nothing under `/html` may import it: the faces and their parser are ~2.5 MB,
+ * and a one-file bundle of `/html` would carry them even if it never drew an
+ * icon. Hosts pass `plainHtmlIcons` to `prepareMarkdownDocForPlainHtml`
+ * (`@bendyline/squisq-formats/html-prepare`) as `outlineIcons`.
+ */
+
+/**
+ * The outline of every icon `doc` uses, keyed `family:name` — the `icons`
+ * option of `markdownDocToPlainHtml`. An icon the catalog doesn't know is left
+ * out and keeps its Font Awesome markup.
+ */
+declare function plainHtmlIcons(doc: MarkdownDocument): Promise<Map<string, PlainHtmlIcon>>;
+
+export { plainHtmlIcons };

package/dist/{plainHtmlIcons-KBSIJ5EN.js → html/icons.js}

@@ -3,7 +3,7 @@ var fonts = /* @__PURE__ */ new Map();
 function loadFont(family) {
   let font = fonts.get(family);
   if (!font) {
-    font = Promise.all([import("@pdf-lib/fontkit"), import("./fontAwesome-C6FRDYTY.js")]).then(
+    font = Promise.all([import("@pdf-lib/fontkit"), import("../fontAwesome-C6FRDYTY.js")]).then(
       ([fontkit, { fontAwesomeFace }]) => fontkit.default.create(fontAwesomeFace(family).data)
     );
     font.catch(() => fonts.delete(family));
@@ -42,7 +42,7 @@ async function plainHtmlIcons(doc) {
   const icons = /* @__PURE__ */ new Map();
   const used = usedIcons(doc);
   if (used.size === 0) return icons;
-  const { fontAwesomeGlyph } = await import("./fontAwesome-C6FRDYTY.js");
+  const { fontAwesomeGlyph } = await import("../fontAwesome-C6FRDYTY.js");
   for (const [key, [family, name]] of used) {
     const glyph = fontAwesomeGlyph(family, name);
     if (!glyph) continue;

package/dist/html/index.d.ts

@@ -1,10 +1,8 @@
 import { Theme, ThemeRegistry, Doc } from '@bendyline/squisq/schemas';
 import { H as HtmlExportOptions } from '../import-ipP4Ghp8.js';
 export { a as HtmlImportOptions, c as collectImagePaths, g as generateExternalHtml, h as htmlToMarkdown, b as htmlToMarkdownDoc, d as htmlToMarkdownDocSync } from '../import-ipP4Ghp8.js';
-import { HtmlPolicy, MarkdownDocument } from '@bendyline/squisq/markdown';
-import { DataSourceTable } from '@bendyline/squisq/doc';
-import { ContentContainer } from '@bendyline/squisq/storage';
-import { DiagramRasterizer } from '../diagrams/index.js';
+export { a as PlainHtmlExportOptions, P as PlainHtmlIcon, b as PlainHtmlParts, m as markdownDocToPlainHtml, c as markdownDocToPlainHtmlParts } from '../plainHtml-B6IXcSet.js';
+import { MarkdownDocument } from '@bendyline/squisq/markdown';
 
 /**
  * Image Utilities for HTML Export
@@ -38,215 +36,6 @@ declare function arrayBufferToBase64DataUrl(buffer: ArrayBuffer, mimeType: strin
  */
 declare function extractFilename(path: string): string;
 
-/**
- * Plain HTML Export — semantic, player-free
- *
- * Renders a MarkdownDocument to a self-contained HTML string. Unlike
- * `docToHtml` (which bundles the SquisqPlayer IIFE and renders SVG block
- * cards), this output is what a reader-mode tool would produce: semantic
- * `<h1>`/`<p>`/`<ul>`/etc. with a small embedded stylesheet, no JS, no
- * runtime path-rewriting. Drives both the "Page" preview tab in the
- * editor and the plain-style branch of the export dialog so what users
- * see live matches the file they download.
- *
- * Image URLs default to the markdown's own paths. Pass `images` to
- * substitute a different value per source URL — typically pre-resolved
- * blob URLs (live preview) or data URIs (single-file export).
- */
-
-interface PlainHtmlExportOptions {
-    /** Document title — populates `<title>` and is HTML-escaped. */
-    title?: string;
-    /**
-     * Substitution map for image `src` URLs. Keys are the URL exactly as
-     * it appears in the markdown source; values are the URL to emit in
-     * the rendered `<img src>`. URLs not present in the map fall through
-     * unchanged (so external `https://…` references still work).
-     */
-    images?: Map<string, string>;
-    /**
-     * Substitution map for anchor `href` URLs. Keys are the URL exactly
-     * as it appears in the markdown source (e.g. `'resume.md'`,
-     * `'resume.md#experience'`); values are the URL to emit. URLs not in
-     * the map pass through unchanged. Used by the recursive bundle
-     * exporter to rewrite `.md` references to `.html` so a static export
-     * of a linked document tree is internally browsable.
-     */
-    links?: Map<string, string>;
-    /**
-     * Optional Squisq theme. When provided, the rendered page uses the
-     * theme's colors and typography, and any Google-hosted fonts the
-     * theme references are loaded via a `<link>` to fonts.googleapis.com
-     * so the face renders correctly without host preloads.
-     *
-     * When omitted, the function falls back (in order) to {@link themeId}
-     * and then to `doc.frontmatter.themeId` — so an authored
-     * `themeId: warm-earth` in the doc's frontmatter styles the export
-     * automatically, without the caller having to wire theme resolution
-     * themselves.
-     */
-    theme?: Theme;
-    /**
-     * Optional theme id (e.g. `'warm-earth'`, `'gezellig'`). Convenient
-     * for hosts whose export dialog tracks themes by id — they can pass
-     * the id straight through instead of resolving to a `Theme` object.
-     * When both `theme` and `themeId` are provided, `theme` wins.
-     */
-    themeId?: string;
-    /** Explicit caller-owned registry for non-document custom themes. */
-    themeRegistry?: ThemeRegistry;
-    /**
-     * Optional FontAwesome CSS text to inline into the rendered page,
-     * replacing the default cross-origin `<link>` to cdnjs. Required for
-     * sandboxed iframe previews where tracking prevention or stricter
-     * origin policies can silently drop cross-origin font fetches —
-     * inlining keeps the icons resolvable purely from same-origin
-     * resources. Hosts typically gather this string by scraping
-     * `document.styleSheets` for `@font-face` rules whose family starts
-     * with `"Font Awesome"`. A CDN `<link>` is emitted only when this option
-     * is absent and {@link externalResources} is explicitly `allow`.
-     */
-    iconsCss?: string;
-    /**
-     * Whether this exporter may add remote font/icon stylesheets. Defaults to
-     * `deny`, keeping the generated file self-contained. Authored links and
-     * images are unaffected; bundle exporters are responsible for inlining or
-     * rewriting those document resources.
-     */
-    externalResources?: 'deny' | 'allow';
-    /**
-     * Raw HTML policy. Defaults to `sanitize`, which removes unsafe tags,
-     * event handlers, and executable URL schemes before emitting HTML.
-     */
-    htmlPolicy?: HtmlPolicy;
-    /**
-     * How a hosted video (a paragraph that is only a link to a YouTube, Vimeo,
-     * Loom or Wistia page, or that provider's `<iframe>` embed
-     * code) renders:
-     *
-     * - `player` (default) — the provider's player iframe;
-     * - `poster` — a static card linking to the video's page (the provider's
-     *   thumbnail where it serves one). For contexts where a player cannot run:
-     *   a preview iframe sandboxed without `allow-scripts` (nested frames
-     *   inherit the sandbox, so the player would load broken), or print.
-     */
-    videoEmbeds?: 'player' | 'poster';
-    /**
-     * Inline icons as SVG, keyed `family:name` (`solid:star`) — the `icons` that
-     * `prepareMarkdownDocForPlainHtml` returns. An icon found here is drawn as
-     * an inline `<svg>` in the text color and needs no Font Awesome stylesheet;
-     * any other icon keeps its Font Awesome markup (see {@link iconsCss}).
-     */
-    icons?: ReadonlyMap<string, PlainHtmlIcon>;
-}
-/** One icon's outline: an SVG path in a `0 0 width height` box whose height is 1em. */
-interface PlainHtmlIcon {
-    width: number;
-    height: number;
-    path: string;
-}
-/**
- * Render a parsed markdown document as a complete, semantic HTML page.
- *
- * When `options.theme` is provided, the output adopts the theme's
- * colors and typography. Google-hosted fonts referenced by the theme
- * are loaded via a single `<link>` to fonts.googleapis.com so the page
- * renders consistently when opened standalone.
- */
-declare function markdownDocToPlainHtml(doc: MarkdownDocument, options?: PlainHtmlExportOptions): string;
-/**
- * The pieces of a plain HTML page that belong to the document itself, for a
- * host that places the document inside a page of its own (see
- * `applyHtmlPageTemplate`).
- */
-interface PlainHtmlParts {
-    /** The `title` option, unescaped. */
-    title: string;
-    /** The rendered document body, footnotes included. */
-    bodyHtml: string;
-    /**
-     * `<head>` markup for the CSS the body's own constructs need — feature
-     * sections, video embeds, SVG islands, icons — and nothing that styles the
-     * page around them: no theme typography, colors, fonts, or `body` rules.
-     */
-    featureHeadHtml: string;
-}
-/**
- * Render a document's body and the functional CSS it depends on, without the
- * page shell or theme stylesheet `markdownDocToPlainHtml` wraps around them.
- * The theme (when one resolves) still informs body rendering, such as the
- * color an SVG island's `currentColor` follows.
- */
-declare function markdownDocToPlainHtmlParts(doc: MarkdownDocument, options?: PlainHtmlExportOptions): PlainHtmlParts;
-
-/**
- * Preparing a document for a static HTML page.
- *
- * A plain HTML page (`markdownDocToPlainHtml`, or a page template filled from
- * `markdownDocToPlainHtmlParts`) runs no script, so what the player draws at
- * runtime has to be settled before the page is written:
- *
- * - `{[dataTable src=…]}` references (and charts fed by one) get the table
- *   they point at, bounded to a preview window with a "Showing N of M rows"
- *   note — the author's body link to the full file follows it;
- * - Mermaid fences, ASCII diagrams and timelines, drawing / layout / diagram
- *   blocks, and charts become pictures, drawn by a host-supplied renderer
- *   (drawing needs a browser) and returned as `data:` URLs;
- * - inline icons become inline SVG outlines, so the page needs no Font
- *   Awesome stylesheet or font.
- *
- * File trees stay preformatted text, which a page shows as well as a picture
- * would and keeps selectable; SVG islands the renderer already draws.
- */
-
-interface PlainHtmlPreparationOptions {
-    /**
-     * Draws diagrams and charts as pictures. In a browser, pass
-     * `createDiagramPictureRenderer()` from
-     * `@bendyline/squisq-react/diagram-pictures`. Without one, diagrams stay as
-     * their source and charts as their table.
-     */
-    renderDiagram?: DiagramRasterizer;
-    /**
-     * The container holding the document's data sidecars. Without one, a data
-     * reference keeps only its link.
-     */
-    container?: ContentContainer | null;
-    /** Rows per data table; a block's own `previewRows` wins. Default 100. */
-    maxDataRows?: number;
-    /**
-     * A caller-owned memo of data-file reads, for a host that prepares the
-     * same document again and again (a live preview). The caller clears it
-     * when the files may have changed.
-     */
-    dataTableCache?: Map<string, Promise<DataSourceTable>>;
-    signal?: AbortSignal;
-    /** Receives a note for each table or picture that could not be produced. */
-    onWarning?: (message: string) => void;
-}
-interface PreparedPlainHtmlDocument {
-    /** The document to render, with data tables filled in and pictures in place. */
-    markdownDoc: MarkdownDocument;
-    /**
-     * The pictures as `data:` URLs, keyed by the image URL written into
-     * `markdownDoc`. Merge them into the renderer's `images` option.
-     */
-    images: Map<string, string>;
-    /** Outlines of the document's inline icons: the renderer's `icons` option. */
-    icons: Map<string, PlainHtmlIcon>;
-}
-/**
- * Whether {@link prepareMarkdownDocForPlainHtml} would change anything for
- * `doc` with these options — so a live preview renders a document with
- * nothing to prepare at once, without waiting on the asynchronous step.
- */
-declare function needsPlainHtmlPreparation(doc: MarkdownDocument, options?: Pick<PlainHtmlPreparationOptions, 'renderDiagram' | 'container'>): boolean;
-/**
- * Settle everything in `doc` a script-free page cannot draw. Never throws for
- * one table or picture: each degrades to its link or source with a warning.
- */
-declare function prepareMarkdownDocForPlainHtml(doc: MarkdownDocument, options?: PlainHtmlPreparationOptions): Promise<PreparedPlainHtmlDocument>;
-
 /**
  * HTML Page Templates
  *
@@ -259,6 +48,8 @@ declare function prepareMarkdownDocForPlainHtml(doc: MarkdownDocument, options?:
  * - `<slot name="title">` receives the document title, and
  *   `<slot name="KEY">` the caller's value for `KEY` (typically a
  *   frontmatter field), inserted as text;
+ * - `<slot name="og-image">` receives the page's social preview picture, when
+ *   the caller supplies one, as an `<img>`;
  * - a slot with no value is replaced by its children — the standard fallback
  *   content — so a template opened directly in a browser previews with its
  *   placeholders.
@@ -268,7 +59,7 @@ declare function prepareMarkdownDocForPlainHtml(doc: MarkdownDocument, options?:
  *
  * `<title>` cannot contain elements, so slots written inside it are matched
  * as text; a `<title>` without one is replaced by the document title.
- * Existing description and Open Graph / Twitter title and description
+ * Existing description and Open Graph / Twitter title, description, and image
  * `<meta>` tags receive the document's values. Relative URLs in the template
  * are rewritten so they still resolve from the generated page's location.
  *
@@ -280,6 +71,28 @@ declare function prepareMarkdownDocForPlainHtml(doc: MarkdownDocument, options?:
 declare const HTML_PAGE_TEMPLATE_CONTENT_START = "<!-- squisq:content -->";
 /** Marks the end of the injected document body in a templated page. */
 declare const HTML_PAGE_TEMPLATE_CONTENT_END = "<!-- /squisq:content -->";
+/** The named slot that receives the page's social preview picture. */
+declare const HTML_PAGE_TEMPLATE_IMAGE_SLOT = "og-image";
+/** A page's social preview picture: its Open Graph and Twitter card image. */
+interface HtmlPageTemplateImage {
+    /**
+     * URL written to the image `<meta>` tags. Social sites expect an absolute
+     * URL; a relative one is written as given.
+     */
+    url: string;
+    /**
+     * URL the `og-image` slot's `<img>` loads, typically relative to the page
+     * so it also shows before the site is published. Default: {@link url}.
+     */
+    src?: string;
+    /** Size in pixels. */
+    width?: number;
+    height?: number;
+    /** Text alternative. */
+    alt?: string;
+    /** Media type, such as `image/png`. */
+    type?: string;
+}
 interface HtmlPageTemplateContent {
     /** Rendered document body. Inserted as-is; the caller sanitizes it. */
     bodyHtml: string;
@@ -293,9 +106,16 @@ interface HtmlPageTemplateContent {
     title: string;
     /**
      * Text for named slots, keyed by slot name. `description` also fills
-     * description `<meta>` tags. `title` comes from {@link title}.
+     * description `<meta>` tags. `title` comes from {@link title}, and
+     * `og-image` from {@link image}.
      */
     values?: Readonly<Record<string, string | undefined>>;
+    /**
+     * The page's social preview picture. Fills the template's `og-image` slot
+     * and the Open Graph / Twitter image `<meta>` tags it declares; without
+     * one, both keep what the template wrote.
+     */
+    image?: HtmlPageTemplateImage;
 }
 interface HtmlPageTemplateOptions {
     /**
@@ -322,6 +142,12 @@ interface HtmlPageTemplateInspection {
     defaultSlotCount: number;
     /** Distinct named slots, in document order. */
     namedSlots: string[];
+    /**
+     * True when a supplied {@link HtmlPageTemplateContent.image} would appear
+     * in the page: the template has an `og-image` slot or an Open Graph /
+     * Twitter image `<meta>` tag. A host can skip drawing a picture otherwise.
+     */
+    usesImage: boolean;
     /** Problems that make {@link applyHtmlPageTemplate} refuse the template. */
     errors: HtmlPageTemplateIssue[];
 }
@@ -561,4 +387,4 @@ declare function docToHtml(doc: Doc, options: HtmlExportOptions): string;
  */
 declare function docToHtmlZip(doc: Doc, options: HtmlZipExportOptions): Promise<Blob>;
 
-export { HTML_PAGE_TEMPLATE_CONTENT_END, HTML_PAGE_TEMPLATE_CONTENT_START, type HtmlBundleOptions, HtmlExportOptions, type HtmlPageTemplateContent, HtmlPageTemplateError, type HtmlPageTemplateInspection, type HtmlPageTemplateIssue, type HtmlPageTemplateOptions, type HtmlZipExportOptions, type PlainHtmlBundleOptions, type PlainHtmlExportOptions, type PlainHtmlIcon, type PlainHtmlParts, type PlainHtmlPreparationOptions, type PreparedPlainHtmlDocument, applyHtmlPageTemplate, arrayBufferToBase64DataUrl, collectLinkRefs, docToHtml, docToHtmlZip, extractFilename, extractHtmlPageTemplateContent, inferMimeType, inspectHtmlPageTemplate, isHtmlPageTemplate, markdownDocToPlainHtml, markdownDocToPlainHtmlParts, markdownDocsToHtmlBundle, markdownDocsToPlainHtmlBundle, needsPlainHtmlPreparation, prepareMarkdownDocForPlainHtml };
+export { HTML_PAGE_TEMPLATE_CONTENT_END, HTML_PAGE_TEMPLATE_CONTENT_START, HTML_PAGE_TEMPLATE_IMAGE_SLOT, type HtmlBundleOptions, HtmlExportOptions, type HtmlPageTemplateContent, HtmlPageTemplateError, type HtmlPageTemplateImage, type HtmlPageTemplateInspection, type HtmlPageTemplateIssue, type HtmlPageTemplateOptions, type HtmlZipExportOptions, type PlainHtmlBundleOptions, applyHtmlPageTemplate, arrayBufferToBase64DataUrl, collectLinkRefs, docToHtml, docToHtmlZip, extractFilename, extractHtmlPageTemplateContent, inferMimeType, inspectHtmlPageTemplate, isHtmlPageTemplate, markdownDocsToHtmlBundle, markdownDocsToPlainHtmlBundle };

package/dist/html/index.js

@@ -1,6 +1,7 @@
 import {
   HTML_PAGE_TEMPLATE_CONTENT_END,
   HTML_PAGE_TEMPLATE_CONTENT_START,
+  HTML_PAGE_TEMPLATE_IMAGE_SLOT,
   HtmlPageTemplateError,
   applyHtmlPageTemplate,
   collectImagePaths,
@@ -17,11 +18,8 @@ import {
   markdownDocToPlainHtml,
   markdownDocToPlainHtmlParts,
   markdownDocsToHtmlBundle,
-  markdownDocsToPlainHtmlBundle,
-  needsPlainHtmlPreparation,
-  prepareMarkdownDocForPlainHtml
-} from "../chunk-SZ3OIY6G.js";
-import "../chunk-4LIFEQKX.js";
+  markdownDocsToPlainHtmlBundle
+} from "../chunk-4SPMLGOG.js";
 import {
   arrayBufferToBase64DataUrl,
   extractFilename,
@@ -33,6 +31,7 @@ import "../chunk-JZR32FON.js";
 export {
   HTML_PAGE_TEMPLATE_CONTENT_END,
   HTML_PAGE_TEMPLATE_CONTENT_START,
+  HTML_PAGE_TEMPLATE_IMAGE_SLOT,
   HtmlPageTemplateError,
   applyHtmlPageTemplate,
   arrayBufferToBase64DataUrl,
@@ -52,7 +51,5 @@ export {
   markdownDocToPlainHtml,
   markdownDocToPlainHtmlParts,
   markdownDocsToHtmlBundle,
-  markdownDocsToPlainHtmlBundle,
-  needsPlainHtmlPreparation,
-  prepareMarkdownDocForPlainHtml
+  markdownDocsToPlainHtmlBundle
 };

package/dist/html/prepare.d.ts

@@ -0,0 +1,97 @@
+import { MarkdownDocument } from '@bendyline/squisq/markdown';
+import { DataSourceTable } from '@bendyline/squisq/doc';
+import { ContentContainer } from '@bendyline/squisq/storage';
+import { DiagramRasterizer } from '../diagrams/index.js';
+import { P as PlainHtmlIcon } from '../plainHtml-B6IXcSet.js';
+import '@bendyline/squisq/schemas';
+
+/**
+ * Preparing a document for a static HTML page.
+ *
+ * A plain HTML page (`markdownDocToPlainHtml`, or a page template filled from
+ * `markdownDocToPlainHtmlParts`) runs no script, so what the player draws at
+ * runtime has to be settled before the page is written:
+ *
+ * - `{[dataTable src=…]}` references (and charts fed by one) get the table
+ *   they point at, bounded to a preview window with a "Showing N of M rows"
+ *   note — the author's body link to the full file follows it;
+ * - Mermaid fences, ASCII diagrams and timelines, drawing / layout / diagram
+ *   blocks, and charts become pictures, drawn by a host-supplied renderer
+ *   (drawing needs a browser) and returned as `data:` URLs;
+ * - inline icons become inline SVG outlines, drawn by a host-supplied
+ *   outliner (`plainHtmlIcons` from `@bendyline/squisq-formats/html-icons`),
+ *   so the page needs no Font Awesome stylesheet or font.
+ *
+ * File trees stay preformatted text, which a page shows as well as a picture
+ * would and keeps selectable; SVG islands the renderer already draws.
+ *
+ * This module is its own entry, `@bendyline/squisq-formats/html-prepare`, and
+ * nothing under `/html` imports it. A bundler that writes one file inlines
+ * every dynamic import it can reach, and filling data tables reaches the XLSX
+ * reader (an XML parser and zip code, ~300 KB) that a host only rendering
+ * plain HTML — say, an editor-extension host — must not carry. Both drawing
+ * steps are the host's to pass in for the same reason: the icon outlines alone
+ * (Font Awesome's faces and their parser) are ~2.5 MB.
+ */
+
+/**
+ * Outlines the inline icons `doc` uses, keyed `family:name` — the renderer's
+ * `icons` option. `plainHtmlIcons` from `@bendyline/squisq-formats/html-icons`
+ * is one.
+ */
+type PlainHtmlIconOutliner = (doc: MarkdownDocument) => Promise<Map<string, PlainHtmlIcon>>;
+interface PlainHtmlPreparationOptions {
+    /**
+     * Draws diagrams and charts as pictures. In a browser, pass
+     * `createDiagramPictureRenderer()` from
+     * `@bendyline/squisq-react/diagram-pictures`. Without one, diagrams stay as
+     * their source and charts as their table.
+     */
+    renderDiagram?: DiagramRasterizer;
+    /**
+     * Draws inline icons as SVG outlines. Pass `plainHtmlIcons` from
+     * `@bendyline/squisq-formats/html-icons`; it needs no browser. Without one,
+     * icons keep their Font Awesome markup.
+     */
+    outlineIcons?: PlainHtmlIconOutliner;
+    /**
+     * The container holding the document's data sidecars. Without one, a data
+     * reference keeps only its link.
+     */
+    container?: ContentContainer | null;
+    /** Rows per data table; a block's own `previewRows` wins. Default 100. */
+    maxDataRows?: number;
+    /**
+     * A caller-owned memo of data-file reads, for a host that prepares the
+     * same document again and again (a live preview). The caller clears it
+     * when the files may have changed.
+     */
+    dataTableCache?: Map<string, Promise<DataSourceTable>>;
+    signal?: AbortSignal;
+    /** Receives a note for each table or picture that could not be produced. */
+    onWarning?: (message: string) => void;
+}
+interface PreparedPlainHtmlDocument {
+    /** The document to render, with data tables filled in and pictures in place. */
+    markdownDoc: MarkdownDocument;
+    /**
+     * The pictures as `data:` URLs, keyed by the image URL written into
+     * `markdownDoc`. Merge them into the renderer's `images` option.
+     */
+    images: Map<string, string>;
+    /** Outlines of the document's inline icons: the renderer's `icons` option. */
+    icons: Map<string, PlainHtmlIcon>;
+}
+/**
+ * Whether {@link prepareMarkdownDocForPlainHtml} would change anything for
+ * `doc` with these options — so a live preview renders a document with
+ * nothing to prepare at once, without waiting on the asynchronous step.
+ */
+declare function needsPlainHtmlPreparation(doc: MarkdownDocument, options?: Pick<PlainHtmlPreparationOptions, 'renderDiagram' | 'outlineIcons' | 'container'>): boolean;
+/**
+ * Settle everything in `doc` a script-free page cannot draw. Never throws for
+ * one table or picture: each degrades to its link or source with a warning.
+ */
+declare function prepareMarkdownDocForPlainHtml(doc: MarkdownDocument, options?: PlainHtmlPreparationOptions): Promise<PreparedPlainHtmlDocument>;
+
+export { type PlainHtmlIconOutliner, type PlainHtmlPreparationOptions, type PreparedPlainHtmlDocument, needsPlainHtmlPreparation, prepareMarkdownDocForPlainHtml };

package/dist/html/prepare.js

@@ -0,0 +1,85 @@
+import {
+  findDiagrams,
+  rasterizeDiagrams
+} from "../chunk-4LIFEQKX.js";
+import {
+  arrayBufferToBase64DataUrl
+} from "../chunk-WMIDXNGR.js";
+import "../chunk-JZR32FON.js";
+
+// src/html/plainHtmlPrepare.ts
+import { isDataFilePath } from "@bendyline/squisq/doc";
+var PAGE_DIAGRAM_KINDS = [
+  "mermaid",
+  "diagram",
+  "timeline",
+  "container",
+  "chart"
+];
+function needsPlainHtmlPreparation(doc, options = {}) {
+  let icons = false;
+  let data = false;
+  const visit = (node) => {
+    if (!node || typeof node !== "object" || icons && data) return;
+    const n = node;
+    if (n.type === "inlineIcon") icons = true;
+    if (n.type === "heading") {
+      const src = n.templateAnnotation?.params?.src;
+      if (src && isDataFilePath(src)) data = true;
+    }
+    if (Array.isArray(n.children)) n.children.forEach(visit);
+  };
+  doc.children.forEach(visit);
+  if (icons && options.outlineIcons || data && options.container) return true;
+  if (!options.renderDiagram) return false;
+  return findDiagrams(doc).some((diagram) => PAGE_DIAGRAM_KINDS.includes(diagram.kind));
+}
+async function prepareMarkdownDocForPlainHtml(doc, options = {}) {
+  const { renderDiagram, outlineIcons, container, signal, onWarning } = options;
+  let markdownDoc = doc;
+  if (container) {
+    const { materializeDataReferences, DATA_PREVIEW_ROWS } = await import("../materialize-ICXNO4S4.js");
+    markdownDoc = await materializeDataReferences(markdownDoc, container, onWarning, {
+      maxRows: options.maxDataRows ?? DATA_PREVIEW_ROWS,
+      tableCache: options.dataTableCache
+    });
+  }
+  signal?.throwIfAborted();
+  const icons = outlineIcons ? await outlineIcons(markdownDoc) : /* @__PURE__ */ new Map();
+  const images = /* @__PURE__ */ new Map();
+  if (!renderDiagram) return { markdownDoc, images, icons };
+  const pictured = await rasterizeDiagrams(markdownDoc, renderDiagram, {
+    kinds: PAGE_DIAGRAM_KINDS,
+    urlPrefix: "squisq-picture",
+    signal,
+    onWarning
+  });
+  const widths = /* @__PURE__ */ new Map();
+  for (const [url, picture] of pictured.images) {
+    const bytes = picture.data;
+    const buffer = bytes.buffer.slice(
+      bytes.byteOffset,
+      bytes.byteOffset + bytes.byteLength
+    );
+    images.set(url, arrayBufferToBase64DataUrl(buffer, picture.contentType));
+    widths.set(url, Math.round(picture.width));
+  }
+  return { markdownDoc: withPictureWidths(pictured.markdownDoc, widths), images, icons };
+}
+function withPictureWidths(doc, widths) {
+  if (widths.size === 0) return doc;
+  const visit = (node) => {
+    if (node.type === "image") {
+      const width = widths.get(node.url);
+      return width === void 0 ? node : { ...node, width };
+    }
+    const children = node.children;
+    if (!Array.isArray(children)) return node;
+    return { ...node, children: children.map(visit) };
+  };
+  return { ...doc, children: doc.children.map(visit) };
+}
+export {
+  needsPlainHtmlPreparation,
+  prepareMarkdownDocForPlainHtml
+};

package/dist/index.d.ts

@@ -19,8 +19,8 @@ import '@bendyline/squisq/markdown';
 import './reader-B_m1aKZC.js';
 import '@bendyline/squisq/storage';
 import './layouts-CTdPlB-u.js';
-import '@bendyline/squisq/doc';
-import './diagrams/index.js';
+import './plainHtml-B6IXcSet.js';
 import './themeReader-DCtwC83Q.js';
 import '@bendyline/squisq/transform';
 import './container/index.js';
+import './diagrams/index.js';

package/dist/index.js

@@ -5,7 +5,7 @@ import {
   htmlToMarkdown,
   htmlToMarkdownDoc,
   htmlToMarkdownDocSync
-} from "./chunk-SZ3OIY6G.js";
+} from "./chunk-4SPMLGOG.js";
 import {
   docToEpub,
   markdownDocToEpub
@@ -29,7 +29,14 @@ import {
   renderOutsideInDocument,
   withOutsideInMarkdownEditing,
   withOutsideInMetadata
-} from "./chunk-6HUQFEP3.js";
+} from "./chunk-D2JA3MLG.js";
+import {
+  OUTSIDE_IN_FORMAT_IDS,
+  OUTSIDE_IN_OUTPUT_TEMPLATE_KEY,
+  chooseOutsideInMarkdownPath,
+  isOutsideInTargetPath,
+  resolveOutsideInLayout
+} from "./chunk-WJTC5OD6.js";
 import {
   DEFAULT_CONVERSION_LIMITS,
   convert,
@@ -38,18 +45,10 @@ import {
   defaultRegistry,
   prepareConversion,
   resolveConversionLimits
-} from "./chunk-WVDAFJFS.js";
+} from "./chunk-JINVU6QA.js";
 import {
   ConversionError
 } from "./chunk-KXOZMWBS.js";
-import {
-  OUTSIDE_IN_FORMAT_IDS,
-  OUTSIDE_IN_OUTPUT_TEMPLATE_KEY,
-  chooseOutsideInMarkdownPath,
-  isOutsideInTargetPath,
-  resolveOutsideInLayout
-} from "./chunk-WJTC5OD6.js";
-import "./chunk-4LIFEQKX.js";
 import {
   docToDocx,
   docxToDoc,
@@ -61,7 +60,7 @@ import {
   markdownDocToPptx,
   pptxToDoc,
   pptxToMarkdownDoc
-} from "./chunk-GFHUJ7L4.js";
+} from "./chunk-S5VXWSRR.js";
 import "./chunk-6N2J7C2B.js";
 import "./chunk-WMIDXNGR.js";
 import "./chunk-DHAK4PII.js";

package/dist/outside-in/index.js

@@ -7,9 +7,7 @@ import {
   renderOutsideInDocument,
   withOutsideInMarkdownEditing,
   withOutsideInMetadata
-} from "../chunk-6HUQFEP3.js";
-import "../chunk-WVDAFJFS.js";
-import "../chunk-KXOZMWBS.js";
+} from "../chunk-D2JA3MLG.js";
 import {
   OUTSIDE_IN_FORMAT_IDS,
   OUTSIDE_IN_OUTPUT_TEMPLATE_KEY,
@@ -17,6 +15,8 @@ import {
   isOutsideInTargetPath,
   resolveOutsideInLayout
 } from "../chunk-WJTC5OD6.js";
+import "../chunk-JINVU6QA.js";
+import "../chunk-KXOZMWBS.js";
 import "../chunk-7AWFHP5U.js";
 export {
   OUTSIDE_IN_FORMAT_IDS,

package/dist/plainHtml-B6IXcSet.d.ts

@@ -0,0 +1,148 @@
+import { HtmlPolicy, MarkdownDocument } from '@bendyline/squisq/markdown';
+import { Theme, ThemeRegistry } from '@bendyline/squisq/schemas';
+
+/**
+ * Plain HTML Export — semantic, player-free
+ *
+ * Renders a MarkdownDocument to a self-contained HTML string. Unlike
+ * `docToHtml` (which bundles the SquisqPlayer IIFE and renders SVG block
+ * cards), this output is what a reader-mode tool would produce: semantic
+ * `<h1>`/`<p>`/`<ul>`/etc. with a small embedded stylesheet, no JS, no
+ * runtime path-rewriting. Drives both the "Page" preview tab in the
+ * editor and the plain-style branch of the export dialog so what users
+ * see live matches the file they download.
+ *
+ * Image URLs default to the markdown's own paths. Pass `images` to
+ * substitute a different value per source URL — typically pre-resolved
+ * blob URLs (live preview) or data URIs (single-file export).
+ */
+
+interface PlainHtmlExportOptions {
+    /** Document title — populates `<title>` and is HTML-escaped. */
+    title?: string;
+    /**
+     * Substitution map for image `src` URLs. Keys are the URL exactly as
+     * it appears in the markdown source; values are the URL to emit in
+     * the rendered `<img src>`. URLs not present in the map fall through
+     * unchanged (so external `https://…` references still work).
+     */
+    images?: Map<string, string>;
+    /**
+     * Substitution map for anchor `href` URLs. Keys are the URL exactly
+     * as it appears in the markdown source (e.g. `'resume.md'`,
+     * `'resume.md#experience'`); values are the URL to emit. URLs not in
+     * the map pass through unchanged. Used by the recursive bundle
+     * exporter to rewrite `.md` references to `.html` so a static export
+     * of a linked document tree is internally browsable.
+     */
+    links?: Map<string, string>;
+    /**
+     * Optional Squisq theme. When provided, the rendered page uses the
+     * theme's colors and typography, and any Google-hosted fonts the
+     * theme references are loaded via a `<link>` to fonts.googleapis.com
+     * so the face renders correctly without host preloads.
+     *
+     * When omitted, the function falls back (in order) to {@link themeId}
+     * and then to `doc.frontmatter.themeId` — so an authored
+     * `themeId: warm-earth` in the doc's frontmatter styles the export
+     * automatically, without the caller having to wire theme resolution
+     * themselves.
+     */
+    theme?: Theme;
+    /**
+     * Optional theme id (e.g. `'warm-earth'`, `'gezellig'`). Convenient
+     * for hosts whose export dialog tracks themes by id — they can pass
+     * the id straight through instead of resolving to a `Theme` object.
+     * When both `theme` and `themeId` are provided, `theme` wins.
+     */
+    themeId?: string;
+    /** Explicit caller-owned registry for non-document custom themes. */
+    themeRegistry?: ThemeRegistry;
+    /**
+     * Optional FontAwesome CSS text to inline into the rendered page,
+     * replacing the default cross-origin `<link>` to cdnjs. Required for
+     * sandboxed iframe previews where tracking prevention or stricter
+     * origin policies can silently drop cross-origin font fetches —
+     * inlining keeps the icons resolvable purely from same-origin
+     * resources. Hosts typically gather this string by scraping
+     * `document.styleSheets` for `@font-face` rules whose family starts
+     * with `"Font Awesome"`. A CDN `<link>` is emitted only when this option
+     * is absent and {@link externalResources} is explicitly `allow`.
+     */
+    iconsCss?: string;
+    /**
+     * Whether this exporter may add remote font/icon stylesheets. Defaults to
+     * `deny`, keeping the generated file self-contained. Authored links and
+     * images are unaffected; bundle exporters are responsible for inlining or
+     * rewriting those document resources.
+     */
+    externalResources?: 'deny' | 'allow';
+    /**
+     * Raw HTML policy. Defaults to `sanitize`, which removes unsafe tags,
+     * event handlers, and executable URL schemes before emitting HTML.
+     */
+    htmlPolicy?: HtmlPolicy;
+    /**
+     * How a hosted video (a paragraph that is only a link to a YouTube, Vimeo,
+     * Loom or Wistia page, or that provider's `<iframe>` embed
+     * code) renders:
+     *
+     * - `player` (default) — the provider's player iframe;
+     * - `poster` — a static card linking to the video's page (the provider's
+     *   thumbnail where it serves one). For contexts where a player cannot run:
+     *   a preview iframe sandboxed without `allow-scripts` (nested frames
+     *   inherit the sandbox, so the player would load broken), or print.
+     */
+    videoEmbeds?: 'player' | 'poster';
+    /**
+     * Inline icons as SVG, keyed `family:name` (`solid:star`) — the `icons` that
+     * `prepareMarkdownDocForPlainHtml` (`@bendyline/squisq-formats/html-prepare`)
+     * returns when given `outlineIcons`, or `plainHtmlIcons` from
+     * `@bendyline/squisq-formats/html-icons` called directly. An icon found here
+     * is drawn as an inline `<svg>` in the text color and needs no Font Awesome
+     * stylesheet; any other icon keeps its Font Awesome markup (see
+     * {@link iconsCss}).
+     */
+    icons?: ReadonlyMap<string, PlainHtmlIcon>;
+}
+/** One icon's outline: an SVG path in a `0 0 width height` box whose height is 1em. */
+interface PlainHtmlIcon {
+    width: number;
+    height: number;
+    path: string;
+}
+/**
+ * Render a parsed markdown document as a complete, semantic HTML page.
+ *
+ * When `options.theme` is provided, the output adopts the theme's
+ * colors and typography. Google-hosted fonts referenced by the theme
+ * are loaded via a single `<link>` to fonts.googleapis.com so the page
+ * renders consistently when opened standalone.
+ */
+declare function markdownDocToPlainHtml(doc: MarkdownDocument, options?: PlainHtmlExportOptions): string;
+/**
+ * The pieces of a plain HTML page that belong to the document itself, for a
+ * host that places the document inside a page of its own (see
+ * `applyHtmlPageTemplate`).
+ */
+interface PlainHtmlParts {
+    /** The `title` option, unescaped. */
+    title: string;
+    /** The rendered document body, footnotes included. */
+    bodyHtml: string;
+    /**
+     * `<head>` markup for the CSS the body's own constructs need — feature
+     * sections, video embeds, SVG islands, icons — and nothing that styles the
+     * page around them: no theme typography, colors, fonts, or `body` rules.
+     */
+    featureHeadHtml: string;
+}
+/**
+ * Render a document's body and the functional CSS it depends on, without the
+ * page shell or theme stylesheet `markdownDocToPlainHtml` wraps around them.
+ * The theme (when one resolves) still informs body rendering, such as the
+ * color an SVG island's `currentColor` follows.
+ */
+declare function markdownDocToPlainHtmlParts(doc: MarkdownDocument, options?: PlainHtmlExportOptions): PlainHtmlParts;
+
+export { type PlainHtmlIcon as P, type PlainHtmlExportOptions as a, type PlainHtmlParts as b, markdownDocToPlainHtmlParts as c, markdownDocToPlainHtml as m };

package/dist/pptx/index.js

@@ -4,7 +4,7 @@ import {
   pptxToContainer,
   pptxToDoc,
   pptxToMarkdownDoc
-} from "../chunk-GFHUJ7L4.js";
+} from "../chunk-S5VXWSRR.js";
 import {
   analyzePptxLayouts,
   inspectPptxLayouts

package/dist/registry/index.js

@@ -9,7 +9,7 @@ import {
   defaultRegistry,
   prepareConversion,
   resolveConversionLimits
-} from "../chunk-WVDAFJFS.js";
+} from "../chunk-JINVU6QA.js";
 import {
   ConversionError
 } from "../chunk-KXOZMWBS.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bendyline/squisq-formats",
-  "version": "2.8.9",
+  "version": "2.8.11",
   "description": "Document format converters — DOCX, PDF, OOXML import/export",
   "license": "MIT",
   "author": "Bendyline",
@@ -83,6 +83,16 @@
       "import": "./dist/html/index.js",
       "default": "./dist/html/index.js"
     },
+    "./html-icons": {
+      "types": "./dist/html/icons.d.ts",
+      "import": "./dist/html/icons.js",
+      "default": "./dist/html/icons.js"
+    },
+    "./html-prepare": {
+      "types": "./dist/html/prepare.d.ts",
+      "import": "./dist/html/prepare.js",
+      "default": "./dist/html/prepare.js"
+    },
     "./epub": {
       "types": "./dist/epub/index.d.ts",
       "import": "./dist/epub/index.js",
@@ -125,7 +135,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@bendyline/squisq": "2.13.8",
+    "@bendyline/squisq": "2.13.9",
     "@pdf-lib/fontkit": "1.1.1",
     "@pdf-lib/upng": "1.0.1",
     "@xmldom/xmldom": "0.9.12",