@bendyline/squisq-formats 1.4.2 → 2.0.0

package/src/html/docsHtmlBundle.ts

@@ -25,7 +25,7 @@ import type {
   HtmlNode,
 } from '@bendyline/squisq/markdown';
 import { markdownToDoc } from '@bendyline/squisq/doc';
-import type { Block, Doc } from '@bendyline/squisq/schemas';
+import type { Block, Doc, ThemeRegistry } from '@bendyline/squisq/schemas';
 import { generateExternalHtml } from './htmlTemplate.js';
 import {
   collectLinkRefs,
@@ -51,6 +51,8 @@ export interface HtmlBundleOptions {
   title?: string;
   /** Theme id applied uniformly to every page. */
   themeId?: string;
+  /** Explicit caller-owned registry for non-document custom themes. */
+  themeRegistry?: ThemeRegistry;
   /** Rendering mode for every page (default: 'static' — scrollable, link-friendly). */
   mode?: 'slideshow' | 'static';
   /** Maximum recursion depth (default: unlimited; cycles always handled). */
@@ -83,6 +85,7 @@ export async function markdownDocsToHtmlBundle(options: HtmlBundleOptions): Prom
     playerScript,
     title,
     themeId,
+    themeRegistry,
     mode = 'static',
     maxDepth = Infinity,
     entryAsIndex = false,
@@ -161,7 +164,6 @@ export async function markdownDocsToHtmlBundle(options: HtmlBundleOptions): Prom
     // link rewrite must walk that tree on every Doc before we serialize
     // it into the rendered HTML.
     let doc = markdownToDoc(mdDoc);
-    if (themeId) doc = { ...doc, themeId };
     if (linkMap.size > 0) {
       doc = rewriteDocLinks(doc, linkMap);
     }
@@ -179,6 +181,8 @@ export async function markdownDocsToHtmlBundle(options: HtmlBundleOptions): Prom
         imageRewriteMap.size > 0 ? Object.fromEntries(imageRewriteMap.entries()) : undefined,
       mode,
       title: pageTitle,
+      themeId,
+      themeRegistry,
     });
     zip.file(htmlPath, html);
   }

package/src/html/htmlTemplate.ts

@@ -10,7 +10,8 @@
  * 2. **External** — JS is referenced via `<script src>`, images via relative paths.
  */
 
-import type { Doc, Layer, Block } from '@bendyline/squisq/schemas';
+import type { Doc, Layer, Block, ThemeRegistry } from '@bendyline/squisq/schemas';
+import { readFrontmatterThemeId } from '@bendyline/squisq/markdown';
 import { arrayBufferToBase64DataUrl, inferMimeType } from './imageUtils.js';
 
 // ── Types ──────────────────────────────────────────────────────────
@@ -48,6 +49,8 @@ export interface HtmlExportOptions {
    * so the SquisqPlayer renders with that theme's colors and typography.
    */
   themeId?: string;
+  /** Explicit caller-owned registry for non-document custom themes. */
+  themeRegistry?: ThemeRegistry;
 }
 
 // ── Image Path Collection ──────────────────────────────────────────
@@ -230,12 +233,10 @@ export function generateInlineHtml(doc: Doc, options: HtmlExportOptions): string
     title = 'Squisq Document',
     autoPlay = false,
     themeId,
+    themeRegistry,
   } = options;
 
-  // Apply theme to doc if specified (the SquisqPlayer respects doc.themeId at render time)
-  if (themeId) {
-    doc = { ...doc, themeId };
-  }
+  doc = applyThemeSelection(doc, themeId, themeRegistry);
 
   // Build base64 image map
   const imageMap: Record<string, string> = {};
@@ -291,7 +292,7 @@ ${mode === 'static' ? '#squisq-root{align-items:flex-start;overflow-y:auto;backg
  */
 export function generateExternalHtml(
   doc: Doc,
-  options: Pick<HtmlExportOptions, 'mode' | 'title' | 'autoPlay'> & {
+  options: Pick<HtmlExportOptions, 'mode' | 'title' | 'autoPlay' | 'themeId' | 'themeRegistry'> & {
     /** Relative path to the player JS file (e.g., 'squisq-player.js') */
     playerScriptPath: string;
     /** Map of original image paths to their rewritten relative paths in the ZIP */
@@ -307,8 +308,12 @@ export function generateExternalHtml(
     mode = 'slideshow',
     title = 'Squisq Document',
     autoPlay = false,
+    themeId,
+    themeRegistry,
   } = options;
 
+  doc = applyThemeSelection(doc, themeId, themeRegistry);
+
   const docJson = escapeForScript(JSON.stringify(doc));
   const imageMapJson = imagePathMap ? escapeForScript(JSON.stringify(imagePathMap)) : '{}';
   const audioMapJson = audioPathMap ? escapeForScript(JSON.stringify(audioPathMap)) : 'null';
@@ -347,6 +352,26 @@ ${mode === 'static' ? '#squisq-root{align-items:flex-start;overflow-y:auto;backg
 </html>`;
 }
 
+function applyThemeSelection(
+  doc: Doc,
+  themeId: string | undefined,
+  registry: ThemeRegistry | undefined,
+): Doc {
+  const selectedId = themeId ?? doc.themeId ?? readFrontmatterThemeId(doc.frontmatter);
+  if (!selectedId) return doc;
+  const selectedDocTheme = doc.customThemes?.some((theme) => theme.id === selectedId);
+  if (selectedDocTheme || !registry) {
+    return selectedId === doc.themeId ? doc : { ...doc, themeId: selectedId };
+  }
+  const registered = registry.get(selectedId);
+  if (!registered) return selectedId === doc.themeId ? doc : { ...doc, themeId: selectedId };
+  return {
+    ...doc,
+    themeId: selectedId,
+    customThemes: [...(doc.customThemes ?? []), registered],
+  };
+}
+
 /**
  * Escape HTML special characters to prevent injection.
  */

package/src/html/imageUtils.ts

@@ -28,12 +28,21 @@ export function inferMimeType(filename: string): string {
  */
 export function arrayBufferToBase64DataUrl(buffer: ArrayBuffer, mimeType: string): string {
   const bytes = new Uint8Array(buffer);
-  let binary = '';
-  for (let i = 0; i < bytes.length; i++) {
-    binary += String.fromCharCode(bytes[i]);
+  // Keep chunks divisible by three so concatenating their independently
+  // encoded results cannot introduce padding in the middle of the stream.
+  // This avoids both quadratic string concatenation and one image-sized
+  // intermediate binary string for large embedded assets.
+  const chunkSize = 3 * 8192;
+  const chunks: string[] = [];
+  for (let offset = 0; offset < bytes.length; offset += chunkSize) {
+    const end = Math.min(offset + chunkSize, bytes.length);
+    let binary = '';
+    for (let i = offset; i < end; i++) {
+      binary += String.fromCharCode(bytes[i]);
+    }
+    chunks.push(btoa(binary));
   }
-  const base64 = btoa(binary);
-  return `data:${mimeType};base64,${base64}`;
+  return `data:${mimeType};base64,${chunks.join('')}`;
 }
 
 /**

package/src/html/index.ts

@@ -127,7 +127,16 @@ export function docToHtml(doc: Doc, options: HtmlExportOptions): string {
  * ```
  */
 export async function docToHtmlZip(doc: Doc, options: HtmlZipExportOptions): Promise<Blob> {
-  const { playerScript, images, audio, mode = 'slideshow', title, autoPlay } = options;
+  const {
+    playerScript,
+    images,
+    audio,
+    mode = 'slideshow',
+    title,
+    autoPlay,
+    themeId,
+    themeRegistry,
+  } = options;
 
   const zip = new JSZip();
 
@@ -174,6 +183,8 @@ export async function docToHtmlZip(doc: Doc, options: HtmlZipExportOptions): Pro
     mode,
     title,
     autoPlay,
+    themeId,
+    themeRegistry,
   });
   zip.file('index.html', html);
 

package/src/html/plainHtml.ts

@@ -23,7 +23,7 @@ import {
   type HtmlNode,
   readFrontmatterThemeId,
 } from '@bendyline/squisq/markdown';
-import type { Theme } from '@bendyline/squisq/schemas';
+import type { Theme, ThemeRegistry } from '@bendyline/squisq/schemas';
 import { resolveFontFamily, buildGoogleFontsUrl } from '@bendyline/squisq/schemas';
 import { resolveThemeForDoc } from '@bendyline/squisq/doc';
 
@@ -68,6 +68,8 @@ export interface PlainHtmlExportOptions {
    * 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
@@ -124,7 +126,9 @@ export function markdownDocToPlainHtml(
   // `squisq-theme` key. Stays undefined when nothing selects a theme so
   // un-themed exports render unstyled (unchanged behavior).
   const resolveId = themeId ?? readFrontmatterThemeId(doc.frontmatter);
-  const theme = options.theme ?? (resolveId ? resolveThemeForDoc(doc, resolveId) : undefined);
+  const theme =
+    options.theme ??
+    (resolveId ? resolveThemeForDoc(doc, resolveId, options.themeRegistry) : undefined);
   const ctx: RenderCtx = { images, links, htmlPolicy };
   const body = renderTopLevel(doc.children, ctx);
   const fontsLink = theme ? renderFontsLink(theme) : '';
@@ -187,7 +191,7 @@ function docUsesIcons(doc: MarkdownDocument): boolean {
  * blocks that follow them (up to the next sibling-or-higher heading).
  * Each group renders as a single `<section class="squisq-feature ...">`
  * with a media column and a text column — the plain-HTML analogue of
- * the SVG layer layout produced by `getLayers` for the same templates.
+ * the SVG layer layout produced by `materializeBlockLayers` for the same templates.
  */
 function renderTopLevel(children: MarkdownNode[], ctx: RenderCtx | undefined): string {
   const out: string[] = [];

package/src/html/plainHtmlBundle.ts

@@ -18,8 +18,7 @@
 import JSZip from 'jszip';
 import { parseMarkdown, inferDocumentTitle } from '@bendyline/squisq/markdown';
 import type { MarkdownDocument, HtmlNode } from '@bendyline/squisq/markdown';
-import type { Theme } from '@bendyline/squisq/schemas';
-import { resolveTheme } from '@bendyline/squisq/schemas';
+import type { Theme, ThemeRegistry } from '@bendyline/squisq/schemas';
 import { markdownDocToPlainHtml } from './plainHtml.js';
 
 // ── Public Types ───────────────────────────────────────────────────
@@ -36,13 +35,14 @@ export interface PlainHtmlBundleOptions {
   /** Optional theme applied uniformly to every page. Overrides {@link themeId}. */
   theme?: Theme;
   /**
-   * Optional theme id (e.g. `'warm-earth'`, `'gezellig'`). Resolved via
-   * `resolveTheme` and applied to every page. Convenient for callers
-   * that track themes by id (like the host export dialog) without
-   * having to resolve to a `Theme` object first. When both `theme` and
-   * `themeId` are supplied, `theme` wins.
+   * Optional theme id (e.g. `'warm-earth'`, `'gezellig'`) applied to every
+   * page. Each document resolves its own inline definition before consulting
+   * {@link themeRegistry}. When both `theme` and `themeId` are supplied,
+   * `theme` wins.
    */
   themeId?: string;
+  /** Explicit caller-owned registry for non-document custom themes. */
+  themeRegistry?: ThemeRegistry;
   /** Maximum recursion depth (default: unlimited; cycles always handled). */
   maxDepth?: number;
   /**
@@ -74,10 +74,10 @@ export async function markdownDocsToPlainHtmlBundle(
     title,
     theme,
     themeId,
+    themeRegistry,
     maxDepth = Infinity,
     entryAsIndex = false,
   } = options;
-  const resolvedTheme = theme ?? (themeId ? resolveTheme(themeId) : undefined);
   const entry = normalizePath(entryPath);
   if (!entry) {
     throw new Error('markdownDocsToPlainHtmlBundle: entryPath is required');
@@ -165,7 +165,9 @@ export async function markdownDocsToPlainHtmlBundle(
       title: docTitle ?? titleForFilename(path, mdDoc),
       images: imageRewriteMap,
       links: linkMap,
-      theme: resolvedTheme,
+      theme,
+      themeId,
+      themeRegistry,
     });
 
     const htmlPath = htmlPathFor(path);

package/src/index.ts

@@ -64,6 +64,15 @@ export type { HtmlImportOptions } from './html/index.js';
 export { markdownDocToEpub, docToEpub } from './epub/index.js';
 export type { EpubExportOptions } from './epub/index.js';
 
+// Theme inference from file imports (DOCX/PPTX/XLSX theme1.xml → Squisq Theme)
+export { inferThemeFromFile, compileExtractedTheme } from './infer/index.js';
+export type {
+  InferThemeOptions,
+  InferredFileTheme,
+  ExtractedFileTheme,
+  InferSourceFormat,
+} from './infer/index.js';
+
 // Format registry + programmatic convert()
 export {
   convert,
@@ -73,6 +82,14 @@ export {
   ConversionError,
   BUILTIN_FORMAT_IDS,
 } from './registry/index.js';
+
+// Shared bounded-decompression errors/options used by DBK and OOXML imports.
+export { ZipSafetyError } from './shared/zipSafety.js';
+export type {
+  ZipSafetyLimits,
+  ZipSafetyErrorCode,
+  ZipSafetyErrorOptions,
+} from './shared/zipSafety.js';
 export type {
   FormatId,
   ConversionResult,
@@ -83,4 +100,7 @@ export type {
   ConvertSource,
   ConversionErrorCode,
   ConversionErrorOptions,
+  BuiltinFormatOptions,
+  MarkdownFormatOptions,
+  DbkFormatOptions,
 } from './registry/index.js';

package/src/infer/extract.ts

@@ -0,0 +1,127 @@
+/**
+ * Per-format theme extraction: locate the theme part of an already-opened
+ * OOXML package, parse it, and resolve the document's background/text color
+ * mapping. Returns null when the file has no theme part at all.
+ */
+
+import type { OoxmlPackage } from '../ooxml/types.js';
+import { getPartRelationships, getPartXml } from '../ooxml/reader.js';
+import { CONTENT_TYPE_PPTX_THEME, NS_PML, NS_WML, REL_SLIDE_MASTER } from '../ooxml/namespaces.js';
+import { findRelByType, resolveTarget } from '../ooxml/readUtils.js';
+import type { OoxmlTheme } from '../ooxml/themeReader.js';
+import { parseThemeXml, readThemePart } from '../ooxml/themeReader.js';
+import type { ExtractedFileTheme, SchemeSlot } from './types.js';
+
+const DEFAULT_COLOR_MAP: { bg1: SchemeSlot; tx1: SchemeSlot } = { bg1: 'lt1', tx1: 'dk1' };
+
+const SCHEME_SLOTS: readonly SchemeSlot[] = ['dk1', 'lt1', 'dk2', 'lt2'];
+
+function asSchemeSlot(value: string | null | undefined): SchemeSlot | undefined {
+  return SCHEME_SLOTS.includes(value as SchemeSlot) ? (value as SchemeSlot) : undefined;
+}
+
+/**
+ * Fallback theme lookup for packages whose theme relationship is missing or
+ * unconventional: scan `[Content_Types].xml` overrides for the theme content
+ * type (shared by all three formats) and parse the first match.
+ */
+async function readThemeByContentType(pkg: OoxmlPackage): Promise<OoxmlTheme | null> {
+  for (const [partPath, contentType] of pkg.contentTypes.overrides) {
+    if (contentType !== CONTENT_TYPE_PPTX_THEME) continue;
+    const doc = await getPartXml(pkg, partPath);
+    if (doc) return parseThemeXml(doc);
+  }
+  return null;
+}
+
+function toExtracted(
+  sourceFormat: ExtractedFileTheme['sourceFormat'],
+  theme: OoxmlTheme,
+  colorMap: { bg1: SchemeSlot; tx1: SchemeSlot },
+  extraWarnings: string[] = [],
+): ExtractedFileTheme {
+  return {
+    sourceFormat,
+    ...(theme.name ? { themeName: theme.name } : {}),
+    ...(theme.colors ? { colors: theme.colors } : {}),
+    colorMap,
+    ...(theme.fonts ? { fonts: theme.fonts } : {}),
+    warnings: [...theme.warnings, ...extraWarnings],
+  };
+}
+
+/**
+ * DOCX: theme hangs off `word/document.xml`; an optional
+ * `w:clrSchemeMapping` in `word/settings.xml` remaps bg1/t1 slots
+ * (values `light1`/`dark1`/`light2`/`dark2`).
+ */
+export async function extractDocxTheme(pkg: OoxmlPackage): Promise<ExtractedFileTheme | null> {
+  const theme =
+    (await readThemePart(pkg, 'word/document.xml')) ?? (await readThemeByContentType(pkg));
+  if (!theme) return null;
+
+  let colorMap = DEFAULT_COLOR_MAP;
+  const settings = await getPartXml(pkg, 'word/settings.xml');
+  const mappingEls = settings?.getElementsByTagNameNS(NS_WML, 'clrSchemeMapping');
+  const mapping = mappingEls && mappingEls.length > 0 ? mappingEls[0]! : null;
+  if (mapping) {
+    const wordSlotToScheme: Record<string, SchemeSlot> = {
+      light1: 'lt1',
+      dark1: 'dk1',
+      light2: 'lt2',
+      dark2: 'dk2',
+    };
+    const bg1 =
+      wordSlotToScheme[
+        mapping.getAttributeNS(NS_WML, 'bg1') ?? mapping.getAttribute('w:bg1') ?? ''
+      ];
+    const tx1 =
+      wordSlotToScheme[mapping.getAttributeNS(NS_WML, 't1') ?? mapping.getAttribute('w:t1') ?? ''];
+    if (bg1 && tx1) colorMap = { bg1, tx1 };
+  }
+
+  return toExtracted('docx', theme, colorMap);
+}
+
+/**
+ * PPTX: theme hangs off the first slide master, whose `<p:clrMap>` records
+ * which scheme slots back the deck's background/text (dark decks set
+ * `bg1="dk1" tx1="lt1"`).
+ */
+export async function extractPptxTheme(pkg: OoxmlPackage): Promise<ExtractedFileTheme | null> {
+  const presRels = await getPartRelationships(pkg, 'ppt/presentation.xml');
+  const masterRel = findRelByType(presRels, REL_SLIDE_MASTER);
+  const masterPath = masterRel ? resolveTarget('ppt', masterRel.target) : undefined;
+
+  const warnings: string[] = [];
+  let theme: OoxmlTheme | null = null;
+  let colorMap = DEFAULT_COLOR_MAP;
+
+  if (masterPath) {
+    theme = await readThemePart(pkg, masterPath);
+    const masterDoc = await getPartXml(pkg, masterPath);
+    const clrMaps = masterDoc?.getElementsByTagNameNS(NS_PML, 'clrMap');
+    const clrMap = clrMaps && clrMaps.length > 0 ? clrMaps[0]! : null;
+    if (clrMap) {
+      const bg1 = asSchemeSlot(clrMap.getAttribute('bg1'));
+      const tx1 = asSchemeSlot(clrMap.getAttribute('tx1'));
+      if (bg1 && tx1) {
+        colorMap = { bg1, tx1 };
+      } else if (clrMap.getAttribute('bg1') || clrMap.getAttribute('tx1')) {
+        warnings.push('theme: unsupported clrMap slot mapping; using default bg1/tx1');
+      }
+    }
+  }
+  if (!theme) theme = await readThemeByContentType(pkg);
+  if (!theme) return null;
+
+  return toExtracted('pptx', theme, colorMap, warnings);
+}
+
+/** XLSX: theme hangs off `xl/workbook.xml`; no color remapping exists. */
+export async function extractXlsxTheme(pkg: OoxmlPackage): Promise<ExtractedFileTheme | null> {
+  const theme =
+    (await readThemePart(pkg, 'xl/workbook.xml')) ?? (await readThemeByContentType(pkg));
+  if (!theme) return null;
+  return toExtracted('xlsx', theme, DEFAULT_COLOR_MAP);
+}

package/src/infer/index.ts

@@ -0,0 +1,168 @@
+/**
+ * @bendyline/squisq-formats Infer Module
+ *
+ * "Infer theme and layouts from a file import": read the OOXML theme
+ * (colors + fonts) out of a DOCX/PPTX/XLSX file and compile it into a
+ * Squisq `Theme`; for PPTX, optionally derive custom layout templates
+ * from the deck's slide layouts/masters.
+ *
+ * Consumers:
+ *   - the editor's theme customizer surfaces (upload / drag-drop a file)
+ *   - the PPTX importer (theme + layouts ride along as frontmatter)
+ *
+ * PDF is deliberately unsupported: PDF files carry no theme tables, so
+ * inference would produce a mostly-default theme. `inferThemeFromFile`
+ * rejects PDF bytes with a clear `ConversionError`.
+ */
+
+import type { CustomTemplateDefinition, Theme } from '@bendyline/squisq/schemas';
+import { openPackage } from '../ooxml/reader.js';
+import type { OoxmlOpenOptions } from '../ooxml/reader.js';
+import type { OoxmlPackage } from '../ooxml/types.js';
+import { ConversionError } from '../registry/errors.js';
+import type { ExtractedFileTheme, InferSourceFormat } from './types.js';
+import { extractDocxTheme, extractPptxTheme, extractXlsxTheme } from './extract.js';
+import { colorHintsFromExtraction, compileExtractedTheme } from './mapTheme.js';
+
+export type { ExtractedFileTheme, InferSourceFormat, SchemeSlot } from './types.js';
+export { extractDocxTheme, extractPptxTheme, extractXlsxTheme } from './extract.js';
+export type { CompileExtractedOptions, MappedThemePartial } from './mapTheme.js';
+export {
+  colorHintsFromExtraction,
+  compileExtractedTheme,
+  extractedThemeToPartial,
+} from './mapTheme.js';
+
+export interface InferThemeOptions extends OoxmlOpenOptions {
+  /** Skip sniffing when the caller already knows the format (e.g. from the extension). */
+  format?: InferSourceFormat;
+  /** PPTX only: also derive custom layout templates from slide layouts/masters. */
+  inferLayouts?: boolean;
+  /** Preferred display name for the compiled theme (e.g. the file's basename). */
+  nameHint?: string;
+}
+
+export interface InferredFileTheme {
+  /** Compiled, validated Squisq theme (`custom-<slug>` id, seeds recorded). */
+  theme: Theme;
+  /** Raw extraction, for callers mapping into their own editing model. */
+  extraction: ExtractedFileTheme;
+  /** Present only for PPTX with `inferLayouts` and ≥1 non-redundant layout. */
+  layouts?: CustomTemplateDefinition[];
+  /** Non-fatal notes: sysClr fallbacks, dropped accents, skipped layouts, … */
+  warnings: string[];
+}
+
+async function looksLikePdf(data: ArrayBuffer | Blob): Promise<boolean> {
+  // Duck-typed (not instanceof): buffers routinely cross realms in test
+  // environments and web workers. Blobs carry `size`; ArrayBuffers carry
+  // `byteLength`.
+  let head: Uint8Array | null = null;
+  const blob = data as Blob;
+  if (
+    typeof blob.size === 'number' &&
+    typeof blob.slice === 'function' &&
+    typeof blob.arrayBuffer === 'function'
+  ) {
+    head = new Uint8Array(await blob.slice(0, 5).arrayBuffer());
+  } else if (typeof (data as ArrayBuffer).byteLength === 'number') {
+    const buf = data as ArrayBuffer;
+    head = new Uint8Array(buf, 0, Math.min(5, buf.byteLength));
+  }
+  if (!head || head.length < 4) return false;
+  // '%PDF'
+  return head[0] === 0x25 && head[1] === 0x50 && head[2] === 0x44 && head[3] === 0x46;
+}
+
+/**
+ * Classify an opened package from its already-parsed content types.
+ * (Deliberately not the registry's byte sniffer — that re-parses the zip
+ * and carries `dbk` semantics this path doesn't want.)
+ */
+function sniffOoxmlFormat(pkg: OoxmlPackage): InferSourceFormat | undefined {
+  const values = [...pkg.contentTypes.overrides.values(), ...pkg.contentTypes.defaults.values()];
+  for (const ct of values) {
+    if (ct.includes('wordprocessingml')) return 'docx';
+    if (ct.includes('presentationml')) return 'pptx';
+    if (ct.includes('spreadsheetml')) return 'xlsx';
+  }
+  return undefined;
+}
+
+const EXTRACTORS: Record<
+  InferSourceFormat,
+  (pkg: OoxmlPackage) => Promise<ExtractedFileTheme | null>
+> = {
+  docx: extractDocxTheme,
+  pptx: extractPptxTheme,
+  xlsx: extractXlsxTheme,
+};
+
+/**
+ * Infer a Squisq theme (and, for PPTX, optionally custom layout templates)
+ * from an office file's bytes.
+ *
+ * Throws `ConversionError`:
+ *   - `unsupported-input` for PDF bytes (no theme tables to read)
+ *   - `invalid-input` for non-OOXML data or files with no theme part
+ */
+export async function inferThemeFromFile(
+  data: ArrayBuffer | Blob,
+  options: InferThemeOptions = {},
+): Promise<InferredFileTheme> {
+  if (await looksLikePdf(data)) {
+    throw new ConversionError(
+      'unsupported-input',
+      'PDF theme inference is not supported — PDF files carry no theme color/font tables.',
+      { format: 'pdf' },
+    );
+  }
+
+  let pkg: OoxmlPackage;
+  try {
+    pkg = await openPackage(data, options);
+  } catch (err: unknown) {
+    throw new ConversionError(
+      'invalid-input',
+      'Could not read this file as a Word, PowerPoint, or Excel document.',
+      { cause: err },
+    );
+  }
+
+  const format = options.format ?? sniffOoxmlFormat(pkg);
+  if (!format) {
+    throw new ConversionError(
+      'invalid-input',
+      'Not a Word, PowerPoint, or Excel document — no theme to infer.',
+    );
+  }
+
+  const extraction = await EXTRACTORS[format](pkg);
+  if (!extraction) {
+    throw new ConversionError('invalid-input', 'No theme part found in this file.', { format });
+  }
+
+  const { theme, warnings: mapWarnings } = compileExtractedTheme(extraction, {
+    nameHint: options.nameHint,
+  });
+  const warnings = [...extraction.warnings, ...mapWarnings];
+
+  let layouts: CustomTemplateDefinition[] | undefined;
+  if (options.inferLayouts) {
+    if (format !== 'pptx') {
+      warnings.push('Layout inference is only available for PowerPoint files; skipped.');
+    } else {
+      const { analyzePptxLayouts } = await import('../pptx/layouts.js');
+      const analysis = await analyzePptxLayouts(pkg, {
+        colors: colorHintsFromExtraction(extraction),
+      });
+      warnings.push(...analysis.warnings);
+      const defs = analysis.layouts
+        .map((l) => (l.verdict.kind === 'custom' ? l.verdict.def : null))
+        .filter((d): d is CustomTemplateDefinition => d !== null);
+      if (defs.length > 0) layouts = defs;
+    }
+  }
+
+  return { theme, extraction, ...(layouts ? { layouts } : {}), warnings };
+}