@bendyline/squisq-formats 1.4.1 → 2.0.0

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);
+}

package/src/ooxml/reader.ts

@@ -5,12 +5,44 @@
  * structural metadata: [Content_Types].xml, relationships, and
  * core properties.
  *
- * Uses JSZip to unzip and the browser's DOMParser to parse XML.
+ * Uses bounded JSZip member streams and a platform DOMParser (with an xmldom
+ * fallback in bare Node/SSR) to parse XML.
  */
 
-import JSZip from 'jszip';
+import { DOMParser as XmldomDOMParser } from '@xmldom/xmldom';
 import type { OoxmlPackage, ContentTypeMap, Relationship, CoreProperties } from './types.js';
 import { NS_RELATIONSHIPS, NS_DC, NS_DCTERMS, NS_CORE_PROPERTIES } from './namespaces.js';
+import {
+  openBoundedZipArchive,
+  type BoundedZipArchive,
+  type ZipSafetyLimits,
+} from '../shared/zipSafety.js';
+
+export type OoxmlOpenOptions = ZipSafetyLimits;
+
+type DomParserLike = new () => {
+  parseFromString(source: string, mimeType: string): unknown;
+};
+
+/** Safe read sessions for opaque packages opened by this module. */
+const packageArchives = new WeakMap<OoxmlPackage, BoundedZipArchive>();
+const MAX_CONTENT_TYPES_BYTES = 1024 * 1024;
+const MAX_RELATIONSHIPS_BYTES = 4 * 1024 * 1024;
+
+/**
+ * Parse XML in browsers and bare Node. Browser DOMParser is preferred; the
+ * pure-JS xmldom implementation is the package-owned fallback for Node/SSR.
+ */
+function parseXml(source: string): Document {
+  const nativeParser = (globalThis as { DOMParser?: DomParserLike }).DOMParser;
+  const Parser = nativeParser ?? (XmldomDOMParser as unknown as DomParserLike);
+  const doc = new Parser().parseFromString(source, 'application/xml') as Document;
+  const parserErrors = doc.getElementsByTagName('parsererror');
+  if (parserErrors.length > 0) {
+    throw new Error(`Invalid OOXML XML part: ${parserErrors[0]?.textContent ?? 'parse error'}`);
+  }
+  return doc;
+}
 
 // ============================================
 // Package Opening
@@ -22,14 +54,23 @@ import { NS_RELATIONSHIPS, NS_DC, NS_DCTERMS, NS_CORE_PROPERTIES } from './names
  * Parses the ZIP archive, [Content_Types].xml, and root relationships.
  *
  * @param data - The raw .docx/.pptx/.xlsx file as ArrayBuffer or Blob
+ * @param limits - Optional archive count, size, and compression-ratio limits
  * @returns A parsed OoxmlPackage
  */
-export async function openPackage(data: ArrayBuffer | Blob): Promise<OoxmlPackage> {
-  const zip = await JSZip.loadAsync(data);
-  const contentTypes = await parseContentTypes(zip);
-  const rootRelationships = await parseRelationships(zip, '');
+export async function openPackage(
+  data: ArrayBuffer | Blob,
+  limits: OoxmlOpenOptions = {},
+): Promise<OoxmlPackage> {
+  const archive = await openBoundedZipArchive(data, limits);
+  const contentTypes = await parseContentTypes(archive);
+  const rootRelationships = await parseRelationships(archive, '');
 
-  return { zip, contentTypes, rootRelationships };
+  const pkg = {
+    contentTypes,
+    rootRelationships,
+  } as unknown as OoxmlPackage;
+  packageArchives.set(pkg, archive);
+  return pkg;
 }
 
 // ============================================
@@ -39,15 +80,13 @@ export async function openPackage(data: ArrayBuffer | Blob): Promise<OoxmlPackag
 /**
  * Parse [Content_Types].xml from the archive.
  */
-async function parseContentTypes(zip: JSZip): Promise<ContentTypeMap> {
+async function parseContentTypes(archive: BoundedZipArchive): Promise<ContentTypeMap> {
   const overrides = new Map<string, string>();
   const defaults = new Map<string, string>();
 
-  const file = zip.file('[Content_Types].xml');
-  if (!file) return { overrides, defaults };
-
-  const text = await file.async('text');
-  const doc = new DOMParser().parseFromString(text, 'application/xml');
+  const text = await archive.readText('[Content_Types].xml', MAX_CONTENT_TYPES_BYTES);
+  if (text === null) return { overrides, defaults };
+  const doc = parseXml(text);
 
   // Parse <Default Extension="rels" ContentType="..." />
   const defaultEls = doc.getElementsByTagName('Default');
@@ -89,7 +128,7 @@ export async function getPartRelationships(
   pkg: OoxmlPackage,
   partPath: string,
 ): Promise<Relationship[]> {
-  return parseRelationships(pkg.zip, partPath);
+  return parseRelationships(pkg, partPath);
 }
 
 /**
@@ -98,14 +137,16 @@ export async function getPartRelationships(
  * For root relationships, relsPath = "_rels/.rels".
  * For part relationships, relsPath = "<dir>/_rels/<filename>.rels".
  */
-async function parseRelationships(zip: JSZip, partPath: string): Promise<Relationship[]> {
+async function parseRelationships(
+  source: OoxmlPackage | BoundedZipArchive,
+  partPath: string,
+): Promise<Relationship[]> {
   const relsPath = partPath === '' ? '_rels/.rels' : buildRelsPath(partPath);
 
-  const file = zip.file(relsPath);
-  if (!file) return [];
-
-  const text = await file.async('text');
-  const doc = new DOMParser().parseFromString(text, 'application/xml');
+  const bytes = await readArchivePart(source, relsPath, MAX_RELATIONSHIPS_BYTES);
+  if (!bytes) return [];
+  const text = new TextDecoder().decode(bytes);
+  const doc = parseXml(text);
   const result: Relationship[] = [];
 
   const els = doc.getElementsByTagNameNS(NS_RELATIONSHIPS, 'Relationship');
@@ -159,11 +200,8 @@ function buildRelsPath(partPath: string): string {
  * @returns Parsed XML Document, or null if the part doesn't exist
  */
 export async function getPartXml(pkg: OoxmlPackage, partPath: string): Promise<Document | null> {
-  const file = pkg.zip.file(partPath);
-  if (!file) return null;
-
-  const text = await file.async('text');
-  return new DOMParser().parseFromString(text, 'application/xml');
+  const bytes = await readPackagePart(pkg, partPath);
+  return bytes ? parseXml(new TextDecoder().decode(bytes)) : null;
 }
 
 /**
@@ -177,9 +215,30 @@ export async function getPartBinary(
   pkg: OoxmlPackage,
   partPath: string,
 ): Promise<ArrayBuffer | null> {
-  const file = pkg.zip.file(partPath);
-  if (!file) return null;
-  return file.async('arraybuffer');
+  const bytes = await readPackagePart(pkg, partPath);
+  return bytes ? bytes.slice().buffer : null;
+}
+
+function readArchivePart(
+  source: OoxmlPackage | BoundedZipArchive,
+  path: string,
+  maxBytes?: number,
+): Promise<Uint8Array | null> {
+  return 'entries' in source
+    ? source.read(path, maxBytes)
+    : readPackagePart(source, path, maxBytes);
+}
+
+async function readPackagePart(
+  pkg: OoxmlPackage,
+  path: string,
+  maxBytes?: number,
+): Promise<Uint8Array | null> {
+  const archive = packageArchives.get(pkg);
+  if (!archive) {
+    throw new TypeError('Invalid OoxmlPackage: create packages with openPackage().');
+  }
+  return archive.read(path, maxBytes);
 }
 
 // ============================================

package/src/ooxml/themeReader.ts

@@ -0,0 +1,197 @@
+/**
+ * OOXML theme reader — parses a `theme1.xml` part (DrawingML `a:theme`)
+ * into normalized color and font schemes.
+ *
+ * Shared by DOCX/PPTX/XLSX theme inference: all three formats carry the same
+ * theme part shape, differing only in where the part hangs (document/master/
+ * workbook relationships). This module never fails hard — unreadable slots
+ * degrade to fallbacks or absence, with a warning per degradation.
+ */
+
+import type { OoxmlPackage } from './types.js';
+import { getPartRelationships, getPartXml } from './reader.js';
+import { NS_DRAWINGML, REL_THEME } from './namespaces.js';
+import { baseDirOf, findRelByType, resolveTarget } from './readUtils.js';
+
+/**
+ * The clrScheme slots as normalized `#rrggbb` strings. The four surface/text
+ * slots always resolve (falling back to black/white when degraded); accent and
+ * hyperlink slots are omitted when unresolvable.
+ */
+export interface OoxmlColorScheme {
+  dk1: string;
+  lt1: string;
+  dk2: string;
+  lt2: string;
+  accent1?: string;
+  accent2?: string;
+  accent3?: string;
+  accent4?: string;
+  accent5?: string;
+  accent6?: string;
+  hlink?: string;
+  folHlink?: string;
+}
+
+export interface OoxmlFontScheme {
+  /** `a:fontScheme > a:majorFont > a:latin@typeface` (headings). */
+  majorLatin?: string;
+  /** `a:fontScheme > a:minorFont > a:latin@typeface` (body). */
+  minorLatin?: string;
+}
+
+export interface OoxmlTheme {
+  /** `a:theme@name` (e.g. "Office Theme", "Ion"). */
+  name?: string;
+  /** Absent when the theme carries no parseable `a:clrScheme`. */
+  colors?: OoxmlColorScheme;
+  /** Absent when the theme carries no `a:fontScheme` latin typefaces. */
+  fonts?: OoxmlFontScheme;
+  warnings: string[];
+}
+
+const HEX6_RE = /^[0-9a-fA-F]{6}$/;
+
+/** Well-known sysClr values that resolve without a `lastClr` hint. */
+const SYS_COLOR_DEFAULTS: Record<string, string> = {
+  windowText: '000000',
+  window: 'ffffff',
+};
+
+/**
+ * Resolve one clrScheme slot element to a `#rrggbb` string, or null.
+ * Only the base color matters for theming — trailing transform children
+ * (`a:lumMod`, `a:tint`, …) are ignored.
+ */
+function resolveSchemeColor(slot: Element): string | null {
+  for (let i = 0; i < slot.childNodes.length; i++) {
+    const child = slot.childNodes[i];
+    if (!child || child.nodeType !== 1) continue;
+    const el = child as Element;
+    if (el.localName === 'srgbClr') {
+      const val = el.getAttribute('val');
+      return val && HEX6_RE.test(val) ? `#${val.toLowerCase()}` : null;
+    }
+    if (el.localName === 'sysClr') {
+      const lastClr = el.getAttribute('lastClr');
+      if (lastClr && HEX6_RE.test(lastClr)) return `#${lastClr.toLowerCase()}`;
+      const val = el.getAttribute('val');
+      const known = val ? SYS_COLOR_DEFAULTS[val] : undefined;
+      return known ? `#${known}` : null;
+    }
+    // Any other color form (schemeClr self-reference, prstClr, …) is
+    // unresolvable without a full DrawingML color pipeline.
+    return null;
+  }
+  return null;
+}
+
+function firstNS(parent: Element | Document, local: string): Element | null {
+  const els = parent.getElementsByTagNameNS(NS_DRAWINGML, local);
+  return els.length > 0 ? els[0]! : null;
+}
+
+function parseColorScheme(clrScheme: Element, warnings: string[]): OoxmlColorScheme {
+  const resolve = (slotName: string): string | null => {
+    const slot = firstNS(clrScheme, slotName);
+    if (!slot) return null;
+    return resolveSchemeColor(slot);
+  };
+
+  const dk1 = resolve('dk1');
+  const lt1 = resolve('lt1');
+  if (!dk1) warnings.push('theme: dk1 color could not be resolved; using #000000');
+  if (!lt1) warnings.push('theme: lt1 color could not be resolved; using #ffffff');
+
+  const dk2 = resolve('dk2');
+  const lt2 = resolve('lt2');
+
+  const colors: OoxmlColorScheme = {
+    dk1: dk1 ?? '#000000',
+    lt1: lt1 ?? '#ffffff',
+    dk2: dk2 ?? dk1 ?? '#000000',
+    lt2: lt2 ?? lt1 ?? '#ffffff',
+  };
+
+  for (const slot of ['accent1', 'accent2', 'accent3', 'accent4', 'accent5', 'accent6'] as const) {
+    const hex = resolve(slot);
+    if (hex) colors[slot] = hex;
+    else warnings.push(`theme: ${slot} color could not be resolved; dropped`);
+  }
+  for (const slot of ['hlink', 'folHlink'] as const) {
+    const hex = resolve(slot);
+    if (hex) colors[slot] = hex;
+  }
+  return colors;
+}
+
+function parseFontScheme(fontScheme: Element, warnings: string[]): OoxmlFontScheme | undefined {
+  const readLatin = (fontName: 'majorFont' | 'minorFont'): string | undefined => {
+    const font = firstNS(fontScheme, fontName);
+    if (!font) return undefined;
+    const latin = firstNS(font, 'latin');
+    const typeface = latin?.getAttribute('typeface')?.trim();
+    if (!typeface) {
+      warnings.push(`theme: ${fontName} has no latin typeface`);
+      return undefined;
+    }
+    return typeface;
+  };
+
+  const majorLatin = readLatin('majorFont');
+  const minorLatin = readLatin('minorFont');
+  if (!majorLatin && !minorLatin) return undefined;
+  return {
+    ...(majorLatin ? { majorLatin } : {}),
+    ...(minorLatin ? { minorLatin } : {}),
+  };
+}
+
+/** Parse an already-loaded theme part Document. */
+export function parseThemeXml(themeDoc: Document): OoxmlTheme {
+  const warnings: string[] = [];
+
+  const root = firstNS(themeDoc, 'theme');
+  const name = root?.getAttribute('name')?.trim() || undefined;
+
+  const clrScheme = firstNS(themeDoc, 'clrScheme');
+  let colors: OoxmlColorScheme | undefined;
+  if (clrScheme) {
+    colors = parseColorScheme(clrScheme, warnings);
+  } else {
+    warnings.push('theme: no clrScheme found');
+  }
+
+  const fontScheme = firstNS(themeDoc, 'fontScheme');
+  let fonts: OoxmlFontScheme | undefined;
+  if (fontScheme) {
+    fonts = parseFontScheme(fontScheme, warnings);
+  } else {
+    warnings.push('theme: no fontScheme found');
+  }
+
+  return {
+    ...(name ? { name } : {}),
+    ...(colors ? { colors } : {}),
+    ...(fonts ? { fonts } : {}),
+    warnings,
+  };
+}
+
+/**
+ * Resolve the theme part related from `fromPartPath` (via `REL_THEME`) and
+ * parse it. Returns null when the part has no theme relationship or the
+ * target part is missing — callers decide whether that's an error.
+ */
+export async function readThemePart(
+  pkg: OoxmlPackage,
+  fromPartPath: string,
+): Promise<OoxmlTheme | null> {
+  const rels = await getPartRelationships(pkg, fromPartPath);
+  const rel = findRelByType(rels, REL_THEME);
+  if (!rel) return null;
+  const themePath = resolveTarget(baseDirOf(fromPartPath), rel.target);
+  const doc = await getPartXml(pkg, themePath);
+  if (!doc) return null;
+  return parseThemeXml(doc);
+}

package/src/ooxml/types.ts

@@ -3,26 +3,25 @@
  *
  * Shared type definitions for all Office Open XML formats (DOCX, PPTX, XLSX).
  * These model the common structural elements of the OOXML package format:
- * ZIP archive, relationships, content types, and core properties.
+ * relationships, content types, and core properties.
  */
 
-import type JSZip from 'jszip';
-
 // ============================================
 // Package
 // ============================================
 
 /**
- * An opened OOXML package — wraps the JSZip archive plus parsed
- * structural metadata (content types, root relationships).
+ * An opened OOXML package. Instances are created only by `openPackage`; the
+ * archive remains private so every part read goes through the bounded reader.
  */
+declare const ooxmlPackageBrand: unique symbol;
 export interface OoxmlPackage {
-  /** The underlying JSZip archive */
-  zip: JSZip;
+  /** Nominal brand: callers cannot manually construct a safety-bypassing package. */
+  readonly [ooxmlPackageBrand]: never;
   /** Parsed [Content_Types].xml entries */
-  contentTypes: ContentTypeMap;
+  readonly contentTypes: ContentTypeMap;
   /** Root-level relationships (_rels/.rels) */
-  rootRelationships: Relationship[];
+  readonly rootRelationships: readonly Relationship[];
 }
 
 /**