@bendyline/squisq-formats 1.4.2 → 2.0.1

package/src/epub/export.ts

@@ -22,7 +22,7 @@
  */
 
 import JSZip from 'jszip';
-import type { Doc, AudioSegment } from '@bendyline/squisq/schemas';
+import type { Doc, AudioSegment, ThemeRegistry } from '@bendyline/squisq/schemas';
 import { resolveFontFamily } from '@bendyline/squisq/schemas';
 import { resolveThemeForDoc } from '@bendyline/squisq/doc';
 import type {
@@ -36,7 +36,7 @@ import type {
   MarkdownTableRow,
   MarkdownTableCell,
 } from '@bendyline/squisq/markdown';
-import { readFrontmatterThemeId } from '@bendyline/squisq/markdown';
+import { readFrontmatterThemeId, sanitizeUrl } from '@bendyline/squisq/markdown';
 import { escapeXml } from '../ooxml/xmlUtils.js';
 import { inferMimeType, extractFilename } from '../html/imageUtils.js';
 import { extractPlainText } from '../shared/text.js';
@@ -56,6 +56,8 @@ export interface EpubExportOptions {
   publisher?: string;
   /** Squisq theme ID for CSS styling */
   themeId?: string;
+  /** Explicit caller-owned registry for non-document custom themes. */
+  themeRegistry?: ThemeRegistry;
   /** Pre-resolved image data keyed by relative path as it appears in the markdown */
   images?: Map<string, ArrayBuffer>;
   /** Cover image data (JPEG or PNG) */
@@ -93,7 +95,7 @@ export async function markdownDocToEpub(
   const language = options.language ?? 'en';
   const description = options.description ?? '';
   const publisher = options.publisher ?? '';
-  const uuid = crypto.randomUUID();
+  const uuid = createEpubUuid();
 
   // Split document into chapters
   const chapters = splitIntoChapters(doc.children);
@@ -101,22 +103,13 @@ export async function markdownDocToEpub(
   // Collect images referenced in the document, deduplicating filenames
   const imageEntries = collectDocImages(doc.children);
   const resolvedImages = new Map<string, { data: ArrayBuffer; mime: string; filename: string }>();
+  const usedImageNames = new Set<string>();
   if (options.images) {
-    const usedNames = new Set<string>();
     for (const src of imageEntries) {
       const data = options.images.get(src);
       if (data) {
-        let filename = extractFilename(src);
-        // Deduplicate: if two paths share a basename (e.g. a/hero.png and b/hero.png)
-        if (usedNames.has(filename)) {
-          const dot = filename.lastIndexOf('.');
-          const base = dot > 0 ? filename.slice(0, dot) : filename;
-          const ext = dot > 0 ? filename.slice(dot) : '';
-          let counter = 2;
-          while (usedNames.has(`${base}-${counter}${ext}`)) counter++;
-          filename = `${base}-${counter}${ext}`;
-        }
-        usedNames.add(filename);
+        const filename = uniqueFilename(safeArchiveBasename(src, 'image'), usedImageNames);
+        usedImageNames.add(filename);
         resolvedImages.set(src, { data, mime: inferMimeType(filename), filename });
       }
     }
@@ -124,7 +117,11 @@ export async function markdownDocToEpub(
 
   // Generate theme CSS — honor an explicit themeId, else the doc's frontmatter
   // theme (`squisq-theme` / legacy), mirroring the other export formats.
-  const css = generateStylesheet(options.themeId ?? readFrontmatterThemeId(doc.frontmatter), doc);
+  const css = generateStylesheet(
+    options.themeId ?? readFrontmatterThemeId(doc.frontmatter),
+    doc,
+    options.themeRegistry,
+  );
 
   // Build the ZIP
   const zip = new JSZip();
@@ -155,7 +152,8 @@ export async function markdownDocToEpub(
       bytes[1] === 0x50 &&
       bytes[2] === 0x4e &&
       bytes[3] === 0x47;
-    coverFilename = isPng ? 'cover.png' : 'cover.jpg';
+    coverFilename = uniqueFilename(isPng ? 'cover.png' : 'cover.jpg', usedImageNames);
+    usedImageNames.add(coverFilename);
     zip.file(`OEBPS/images/${coverFilename}`, options.coverImage);
 
     // Generate cover XHTML page — full-bleed image, no margins
@@ -184,17 +182,28 @@ export async function markdownDocToEpub(
   // Per-segment audio file info, indexed by segment index (null if data missing)
   const segmentAudioFiles: ({ filename: string; mime: string } | null)[] = [];
   const allAudioFiles: { filename: string; mime: string }[] = [];
+  const audioFilenameBySource = new Map<string, string>();
+  const usedAudioFilenames = new Set<string>();
 
   if (hasAudio) {
     for (const seg of audioSegments) {
       const data = audioMap.get(seg.src) ?? audioMap.get(seg.name);
       if (data) {
-        const filename = extractFilename(seg.src);
-        const finalName = filename.includes('.') ? filename : `${filename}.mp3`;
-        zip.file(`OEBPS/audio/${finalName}`, data);
+        const sourceKey = seg.src || seg.name;
+        let finalName = audioFilenameBySource.get(sourceKey);
+        let isNewFile = false;
+        if (!finalName) {
+          const basename = safeArchiveBasename(sourceKey || 'narration', 'narration');
+          const withExtension = basename.includes('.') ? basename : `${basename}.mp3`;
+          finalName = uniqueFilename(withExtension, usedAudioFilenames);
+          audioFilenameBySource.set(sourceKey, finalName);
+          usedAudioFilenames.add(finalName);
+          zip.file(`OEBPS/audio/${finalName}`, data);
+          isNewFile = true;
+        }
         const info = { filename: finalName, mime: inferMimeType(finalName) };
         segmentAudioFiles.push(info);
-        allAudioFiles.push(info);
+        if (isNewFile) allAudioFiles.push(info);
       } else {
         segmentAudioFiles.push(null);
       }
@@ -535,14 +544,18 @@ function inlineToXhtml(node: MarkdownInlineNode, images: ImageMap): string {
       return `<code>${escapeXml(node.value)}</code>`;
 
     case 'link': {
+      const href = sanitizeUrl(node.url, 'link');
+      if (!href) return inlinesToXhtml(node.children, images);
       const titleAttr = node.title ? ` title="${escapeXml(node.title)}"` : '';
-      return `<a href="${escapeXml(node.url)}"${titleAttr}>${inlinesToXhtml(node.children, images)}</a>`;
+      return `<a href="${escapeXml(href)}"${titleAttr}>${inlinesToXhtml(node.children, images)}</a>`;
     }
 
     case 'image': {
       const alt = escapeXml(node.alt ?? '');
       const resolved = images.get(node.url);
-      const src = resolved ? `../images/${resolved.filename}` : escapeXml(node.url);
+      const safeSrc = resolved ? `../images/${resolved.filename}` : sanitizeUrl(node.url, 'media');
+      if (!safeSrc) return alt;
+      const src = escapeXml(safeSrc);
       return `<img src="${src}" alt="${alt}"/>`;
     }
 
@@ -561,6 +574,58 @@ function inlineToXhtml(node: MarkdownInlineNode, images: ImageMap): string {
   }
 }
 
+/**
+ * Produce an EPUB identifier without assuming `crypto.randomUUID()` exists.
+ * `randomUUID` is unavailable in older/non-secure browser contexts; use
+ * `getRandomValues` when possible and retain a non-cryptographic last resort
+ * because this UUID is an identifier, not a security token.
+ */
+function createEpubUuid(): string {
+  const webCrypto = globalThis.crypto;
+  if (typeof webCrypto?.randomUUID === 'function') return webCrypto.randomUUID();
+
+  const bytes = new Uint8Array(16);
+  if (typeof webCrypto?.getRandomValues === 'function') {
+    webCrypto.getRandomValues(bytes);
+  } else {
+    let seed = Date.now() ^ Math.floor(Math.random() * 0x7fffffff);
+    for (let i = 0; i < bytes.length; i++) {
+      seed = Math.imul(seed ^ (seed >>> 15), 1 | seed);
+      bytes[i] = seed & 0xff;
+    }
+  }
+  // RFC 4122 version 4 / variant 1 bits.
+  bytes[6] = (bytes[6]! & 0x0f) | 0x40;
+  bytes[8] = (bytes[8]! & 0x3f) | 0x80;
+  const hex = Array.from(bytes, (b) => b.toString(16).padStart(2, '0')).join('');
+  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}
+
+/** Flatten an external path to a safe archive basename. */
+function safeArchiveBasename(path: string, fallback: string): string {
+  const filename = extractFilename(path.replace(/\\/g, '/'));
+  const safe = Array.from(filename, (character) => {
+    const codePoint = character.codePointAt(0) ?? 0;
+    return character === '\\' || character === '/' || codePoint < 0x20 || codePoint === 0x7f
+      ? '_'
+      : character;
+  })
+    .join('')
+    .trim();
+  return !safe || safe === '.' || safe === '..' ? fallback : safe;
+}
+
+/** Return a basename that does not collide with a prior archive member. */
+function uniqueFilename(filename: string, used: ReadonlySet<string>): string {
+  if (!used.has(filename)) return filename;
+  const dot = filename.lastIndexOf('.');
+  const base = dot > 0 ? filename.slice(0, dot) : filename;
+  const ext = dot > 0 ? filename.slice(dot) : '';
+  let suffix = 2;
+  while (used.has(`${base}-${suffix}${ext}`)) suffix++;
+  return `${base}-${suffix}${ext}`;
+}
+
 // ── SMIL Media Overlays ───────────────────────────────────────────
 
 /**
@@ -778,10 +843,14 @@ ${navItems}
 
 // ── Stylesheet ────────────────────────────────────────────────────
 
-function generateStylesheet(themeId: string | undefined, doc?: MarkdownDocument): string {
+function generateStylesheet(
+  themeId: string | undefined,
+  doc?: MarkdownDocument,
+  registry?: ThemeRegistry,
+): string {
   let themeVars = '';
   if (themeId) {
-    const theme = resolveThemeForDoc(doc, themeId);
+    const theme = resolveThemeForDoc(doc, themeId, registry);
     themeVars = `
   --epub-bg: ${theme.colors.background};
   --epub-text: ${theme.colors.text};

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,15 +64,33 @@ 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,
+  prepareConversion,
   createRegistry,
   defaultRegistry,
   defaultFormats,
   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 +101,9 @@ export type {
   ConvertSource,
   ConversionErrorCode,
   ConversionErrorOptions,
+  BuiltinFormatOptions,
+  MarkdownFormatOptions,
+  DbkFormatOptions,
+  PreparedConversion,
+  PreparedExportOptions,
 } 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);
+}