@bendyline/squisq-formats 1.4.2 → 2.0.1

package/src/infer/index.ts

@@ -0,0 +1,199 @@
+/**
+ * @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, throwIfOoxmlAborted } 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, signal?: AbortSignal): Promise<boolean> {
+  throwIfOoxmlAborted(signal);
+  // 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 waitForAbortable(blob.slice(0, 5).arrayBuffer(), signal));
+  } else if (typeof (data as ArrayBuffer).byteLength === 'number') {
+    const buf = data as ArrayBuffer;
+    head = new Uint8Array(buf, 0, Math.min(5, buf.byteLength));
+  }
+  throwIfOoxmlAborted(signal);
+  if (!head || head.length < 4) return false;
+  // '%PDF'
+  return head[0] === 0x25 && head[1] === 0x50 && head[2] === 0x44 && head[3] === 0x46;
+}
+
+function waitForAbortable<T>(work: Promise<T>, signal?: AbortSignal): Promise<T> {
+  throwIfOoxmlAborted(signal);
+  if (!signal) return work;
+  return new Promise<T>((resolve, reject) => {
+    let settled = false;
+    const finish = (complete: () => void): void => {
+      if (settled) return;
+      settled = true;
+      signal.removeEventListener('abort', handleAbort);
+      complete();
+    };
+    const handleAbort = (): void =>
+      finish(() => reject(signal.reason ?? new Error('OOXML operation was cancelled')));
+    signal.addEventListener('abort', handleAbort, { once: true });
+    if (signal.aborted) handleAbort();
+    work.then(
+      (value) => finish(() => resolve(value)),
+      (error: unknown) => finish(() => reject(error)),
+    );
+  });
+}
+
+/**
+ * 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> {
+  throwIfOoxmlAborted(options.signal);
+  if (await looksLikePdf(data, options.signal)) {
+    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) {
+    if (options.signal?.aborted) throw options.signal.reason ?? err;
+    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);
+  throwIfOoxmlAborted(options.signal);
+  if (!format) {
+    throw new ConversionError(
+      'invalid-input',
+      'Not a Word, PowerPoint, or Excel document — no theme to infer.',
+    );
+  }
+
+  const extraction = await EXTRACTORS[format](pkg);
+  throwIfOoxmlAborted(options.signal);
+  if (!extraction) {
+    throw new ConversionError('invalid-input', 'No theme part found in this file.', { format });
+  }
+
+  const { theme, warnings: mapWarnings } = compileExtractedTheme(extraction, {
+    nameHint: options.nameHint,
+  });
+  throwIfOoxmlAborted(options.signal);
+  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),
+        signal: options.signal,
+      });
+      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;
+    }
+  }
+
+  throwIfOoxmlAborted(options.signal);
+  return { theme, extraction, ...(layouts ? { layouts } : {}), warnings };
+}

package/src/infer/mapTheme.ts

@@ -0,0 +1,176 @@
+/**
+ * Map a raw OOXML theme extraction onto a compiled Squisq `Theme`.
+ *
+ * Only a handful of seeds are taken from the file (lead accents, background,
+ * text, major/minor fonts); `compileTheme` derives the rest of the palette
+ * via OKLCh so the result is always a complete, validated theme that stays
+ * re-editable in the customizer (seeds are recorded on `Theme.seedColors`).
+ */
+
+import type {
+  DeepPartial,
+  Theme,
+  ThemeColorScheme,
+  ThemeSeedColors,
+} from '@bendyline/squisq/schemas';
+import {
+  accentToColorScheme,
+  compileTheme,
+  contrastRatio,
+  isHex,
+  matchFontFamily,
+  relativeLuminance,
+} from '@bendyline/squisq/schemas';
+import type { PptxColorHints } from '../pptx/layouts.js';
+import type { ExtractedFileTheme } from './types.js';
+
+export interface CompileExtractedOptions {
+  /** Preferred display name for the compiled theme (e.g. the file's basename). */
+  nameHint?: string;
+}
+
+export interface MappedThemePartial {
+  partial: DeepPartial<Theme>;
+  warnings: string[];
+}
+
+/** Neutral primary used when a theme resolves no usable accent slots. */
+const FALLBACK_PRIMARY = '#3182ce';
+
+/** Accents closer to the background than this contrast are dropped (near-invisible). */
+const MIN_ACCENT_CONTRAST = 1.3;
+
+const ACCENT_SLOTS = ['accent1', 'accent2', 'accent3', 'accent4', 'accent5', 'accent6'] as const;
+
+/** Companion slot providing `backgroundLight` for each background slot. */
+const COMPANION_SLOT = { lt1: 'lt2', dk1: 'dk2', lt2: 'lt1', dk2: 'dk1' } as const;
+
+function slugify(name: string): string {
+  const slug = name
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+  return slug || 'imported';
+}
+
+/**
+ * Build the `DeepPartial<Theme>` for an extraction. Exported for tests; most
+ * callers want {@link compileExtractedTheme}.
+ */
+export function extractedThemeToPartial(
+  extraction: ExtractedFileTheme,
+  opts: CompileExtractedOptions = {},
+): MappedThemePartial {
+  const warnings: string[] = [];
+  const { colors, colorMap, fonts } = extraction;
+
+  const name = opts.nameHint?.trim() || extraction.themeName || 'Imported Theme';
+  const partial: DeepPartial<Theme> = {
+    id: `custom-${slugify(name)}`,
+    name,
+    description: `Imported from a ${extraction.sourceFormat} file${
+      extraction.themeName ? ` (theme "${extraction.themeName}")` : ''
+    }.`,
+  };
+
+  if (colors) {
+    const primary = colors.accent1 ?? colors.accent2;
+    if (!primary) {
+      warnings.push('theme: no usable accent colors; primary defaults to Squisq blue');
+    }
+
+    let background: string | undefined = colors[colorMap.bg1];
+    let text: string | undefined = colors[colorMap.tx1];
+    // Pathological color maps can land background and text on similar
+    // surfaces; when they don't contrast, let the compiler derive both
+    // from the primary instead of shipping unreadable seeds.
+    if (
+      background &&
+      text &&
+      Math.abs(relativeLuminance(background) - relativeLuminance(text)) < 0.2
+    ) {
+      warnings.push('theme: background and text colors are too close; deriving surfaces instead');
+      background = undefined;
+      text = undefined;
+    }
+
+    const seeds: ThemeSeedColors = {
+      primary: primary ?? FALLBACK_PRIMARY,
+      ...(colors.accent2 ? { secondary: colors.accent2 } : {}),
+      ...(colors.accent3 ? { accent: colors.accent3 } : {}),
+      ...(background ? { background } : {}),
+      ...(text ? { text } : {}),
+    };
+    partial.seedColors = seeds;
+
+    const explicitColors: DeepPartial<Theme>['colors'] = {};
+    const companion = background ? colors[COMPANION_SLOT[colorMap.bg1]] : undefined;
+    if (background && companion && companion !== background) {
+      explicitColors.backgroundLight = companion;
+    }
+    if (colors.hlink && isHex(colors.hlink)) {
+      explicitColors.highlight = colors.hlink;
+    }
+    if (Object.keys(explicitColors).length > 0) partial.colors = explicitColors;
+
+    const schemes: Record<string, ThemeColorScheme> = {};
+    const seenHexes = new Set<string>();
+    const schemeBackground = background ?? colors[colorMap.bg1];
+    for (const slot of ACCENT_SLOTS) {
+      const hex = colors[slot];
+      if (!hex || seenHexes.has(hex)) continue;
+      if (schemeBackground && contrastRatio(hex, schemeBackground) < MIN_ACCENT_CONTRAST) {
+        warnings.push(`theme: ${slot} is too close to the background; dropped from accents`);
+        continue;
+      }
+      seenHexes.add(hex);
+      schemes[slot] = accentToColorScheme(hex);
+    }
+    if (Object.keys(schemes).length > 0) partial.colorSchemes = schemes;
+  }
+
+  if (fonts?.majorLatin || fonts?.minorLatin) {
+    partial.typography = {
+      ...(fonts.majorLatin ? { titleFont: matchFontFamily(fonts.majorLatin) } : {}),
+      ...(fonts.minorLatin ? { bodyFont: matchFontFamily(fonts.minorLatin) } : {}),
+    };
+  }
+
+  return { partial, warnings };
+}
+
+/**
+ * Compile an extraction into a full validated Squisq theme. Mapping warnings
+ * (dropped accents, low-contrast surfaces) are returned alongside; extraction
+ * warnings stay on `extraction.warnings`.
+ */
+export function compileExtractedTheme(
+  extraction: ExtractedFileTheme,
+  opts: CompileExtractedOptions = {},
+): { theme: Theme; warnings: string[] } {
+  const { partial, warnings } = extractedThemeToPartial(extraction, opts);
+  return { theme: compileTheme(partial), warnings };
+}
+
+/**
+ * Build the color hints the PPTX layout generator uses to resolve scheme
+ * color references (`a:schemeClr val="accent1"`, `bg1`, `tx1`, …) on
+ * decorative shapes.
+ */
+export function colorHintsFromExtraction(extraction: ExtractedFileTheme): PptxColorHints {
+  const { colors, colorMap } = extraction;
+  if (!colors) return {};
+  const schemeColors: Record<string, string> = {};
+  for (const [slot, hex] of Object.entries(colors)) {
+    if (typeof hex === 'string') schemeColors[slot] = hex;
+  }
+  const background = colors[colorMap.bg1];
+  const text = colors[colorMap.tx1];
+  if (background) schemeColors['bg1'] = background;
+  if (text) schemeColors['tx1'] = text;
+  return {
+    ...(background ? { background } : {}),
+    ...(text ? { text } : {}),
+    schemeColors,
+  };
+}

package/src/infer/types.ts

@@ -0,0 +1,27 @@
+/**
+ * Shared types for file-import theme inference.
+ */
+
+import type { OoxmlColorScheme, OoxmlFontScheme } from '../ooxml/themeReader.js';
+
+/** Source formats theme inference supports. PDF carries no theme tables. */
+export type InferSourceFormat = 'docx' | 'pptx' | 'xlsx';
+
+/** The four surface/text scheme slots a color map can point at. */
+export type SchemeSlot = 'dk1' | 'lt1' | 'dk2' | 'lt2';
+
+/**
+ * Raw theme extraction from one office file, before mapping onto a Squisq
+ * `Theme`. `colorMap` records which scheme slots back the document's
+ * background/text — PPTX masters carry `<p:clrMap bg1=… tx1=…>` and DOCX may
+ * carry `w:clrSchemeMapping`; dark decks map `bg1="dk1"` and invert here.
+ */
+export interface ExtractedFileTheme {
+  sourceFormat: InferSourceFormat;
+  /** `a:theme@name` when present (e.g. "Office Theme", "Ion"). */
+  themeName?: string;
+  colors?: OoxmlColorScheme;
+  colorMap: { bg1: SchemeSlot; tx1: SchemeSlot };
+  fonts?: OoxmlFontScheme;
+  warnings: string[];
+}

package/src/ooxml/index.ts

@@ -25,6 +25,13 @@ export type {
 } from './types.js';
 
 // Reader
+export type { OoxmlOpenOptions } from './reader.js';
+export { ZipSafetyError } from '../shared/zipSafety.js';
+export type {
+  ZipSafetyLimits,
+  ZipSafetyErrorCode,
+  ZipSafetyErrorOptions,
+} from '../shared/zipSafety.js';
 export {
   openPackage,
   getPartRelationships,
@@ -33,6 +40,13 @@ export {
   getCoreProperties,
 } from './reader.js';
 
+// Read utilities
+export { attrNS, baseDirOf, resolveTarget, findRelByType } from './readUtils.js';
+
+// Theme reader
+export type { OoxmlColorScheme, OoxmlFontScheme, OoxmlTheme } from './themeReader.js';
+export { parseThemeXml, readThemePart } from './themeReader.js';
+
 // Writer
 export type { OoxmlPackageBuilder } from './writer.js';
 export { createPackage } from './writer.js';

package/src/ooxml/readUtils.ts

@@ -0,0 +1,44 @@
+/**
+ * Shared DOM-read helpers for OOXML importers.
+ *
+ * Every importer walks parts with `getElementsByTagNameNS` and resolves
+ * relationship targets relative to the referencing part; these helpers hold
+ * the common pieces so new readers (theme, slide layouts) don't re-implement
+ * them per format.
+ */
+
+import type { Relationship } from './types.js';
+
+/**
+ * Read a namespaced attribute with a qualified-name fallback for documents
+ * whose producer omitted the namespace declaration (e.g. `r:id`).
+ */
+export function attrNS(el: Element, ns: string, local: string, qualified: string): string | null {
+  return el.getAttributeNS(ns, local) ?? el.getAttribute(qualified);
+}
+
+/** Directory portion of a part path, e.g. `ppt/slides/slide1.xml` → `ppt/slides`. */
+export function baseDirOf(path: string): string {
+  const slash = path.lastIndexOf('/');
+  return slash === -1 ? '' : path.slice(0, slash);
+}
+
+/**
+ * Resolve a relationship target against the referencing part's directory.
+ * Absolute targets (leading `/`) are package-rooted; relative targets may
+ * climb with `..` segments (e.g. `../slideLayouts/slideLayout1.xml`).
+ */
+export function resolveTarget(baseDir: string, target: string): string {
+  if (target.startsWith('/')) return target.replace(/^\//, '');
+  const stack = baseDir ? baseDir.split('/') : [];
+  for (const seg of target.split('/')) {
+    if (seg === '..') stack.pop();
+    else if (seg !== '.') stack.push(seg);
+  }
+  return stack.join('/');
+}
+
+/** First relationship of the given type, if any. */
+export function findRelByType(rels: Relationship[], type: string): Relationship | undefined {
+  return rels.find((r) => r.type === type);
+}