@bendyline/squisq-formats 1.4.2 → 2.0.1

package/src/ooxml/reader.ts

@@ -5,12 +5,67 @@
  * 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 the
+ * package-owned xmldom parser in 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 packageSignals = new WeakMap<OoxmlPackage, AbortSignal>();
+const MAX_CONTENT_TYPES_BYTES = 1024 * 1024;
+const MAX_RELATIONSHIPS_BYTES = 4 * 1024 * 1024;
+const CANCELLATION_CHECKPOINT_INTERVAL = 256;
+
+/** Preserve the caller's exact cancellation reason across OOXML traversal. */
+export function throwIfOoxmlAborted(signal?: AbortSignal): void {
+  if (!signal?.aborted) return;
+  throw signal.reason ?? new Error('OOXML operation was cancelled');
+}
+
+async function cancellationCheckpoint(index: number, signal?: AbortSignal): Promise<void> {
+  throwIfOoxmlAborted(signal);
+  if (index > 0 && index % CANCELLATION_CHECKPOINT_INTERVAL === 0) {
+    await new Promise<void>((resolve) => setTimeout(resolve, 0));
+    throwIfOoxmlAborted(signal);
+  }
+}
+
+/**
+ * Parse XML in browsers and Node. Test runners and SSR hosts can install a
+ * partial browser DOMParser whose namespace behavior differs from browsers,
+ * so Node always uses the package-owned, namespace-aware xmldom parser.
+ */
+function parseXml(source: string, signal?: AbortSignal): Document {
+  throwIfOoxmlAborted(signal);
+  const runtime = globalThis as {
+    DOMParser?: DomParserLike;
+    process?: { versions?: { node?: string } };
+  };
+  const nativeParser = runtime.process?.versions?.node ? undefined : runtime.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'}`);
+  }
+  throwIfOoxmlAborted(signal);
+  return doc;
+}
 
 // ============================================
 // Package Opening
@@ -22,14 +77,26 @@ 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> {
+  throwIfOoxmlAborted(limits.signal);
+  const archive = await openBoundedZipArchive(data, limits);
+  const contentTypes = await parseContentTypes(archive, limits.signal);
+  const rootRelationships = await parseRelationships(archive, '', limits.signal);
+  throwIfOoxmlAborted(limits.signal);
 
-  return { zip, contentTypes, rootRelationships };
+  const pkg = {
+    contentTypes,
+    rootRelationships,
+  } as unknown as OoxmlPackage;
+  packageArchives.set(pkg, archive);
+  if (limits.signal) packageSignals.set(pkg, limits.signal);
+  return pkg;
 }
 
 // ============================================
@@ -39,19 +106,21 @@ 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,
+  signal?: AbortSignal,
+): 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, signal);
 
   // Parse <Default Extension="rels" ContentType="..." />
   const defaultEls = doc.getElementsByTagName('Default');
   for (let i = 0; i < defaultEls.length; i++) {
+    await cancellationCheckpoint(i, signal);
     const el = defaultEls[i];
     const ext = el.getAttribute('Extension');
     const ct = el.getAttribute('ContentType');
@@ -61,6 +130,7 @@ async function parseContentTypes(zip: JSZip): Promise<ContentTypeMap> {
   // Parse <Override PartName="/word/document.xml" ContentType="..." />
   const overrideEls = doc.getElementsByTagName('Override');
   for (let i = 0; i < overrideEls.length; i++) {
+    await cancellationCheckpoint(i, signal);
     const el = overrideEls[i];
     const partName = el.getAttribute('PartName');
     const ct = el.getAttribute('ContentType');
@@ -89,7 +159,7 @@ export async function getPartRelationships(
   pkg: OoxmlPackage,
   partPath: string,
 ): Promise<Relationship[]> {
-  return parseRelationships(pkg.zip, partPath);
+  return parseRelationships(pkg, partPath, packageSignals.get(pkg));
 }
 
 /**
@@ -98,14 +168,17 @@ 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,
+  signal?: AbortSignal,
+): 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, signal);
   const result: Relationship[] = [];
 
   const els = doc.getElementsByTagNameNS(NS_RELATIONSHIPS, 'Relationship');
@@ -113,6 +186,7 @@ async function parseRelationships(zip: JSZip, partPath: string): Promise<Relatio
   const fallbackEls = els.length > 0 ? els : doc.getElementsByTagName('Relationship');
 
   for (let i = 0; i < fallbackEls.length; i++) {
+    await cancellationCheckpoint(i, signal);
     const el = fallbackEls[i];
     const id = el.getAttribute('Id');
     const type = el.getAttribute('Type');
@@ -159,11 +233,10 @@ 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 signal = packageSignals.get(pkg);
+  throwIfOoxmlAborted(signal);
+  const bytes = await readPackagePart(pkg, partPath);
+  return bytes ? parseXml(new TextDecoder().decode(bytes), signal) : null;
 }
 
 /**
@@ -177,9 +250,32 @@ 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');
+  throwIfOoxmlAborted(packageSignals.get(pkg));
+  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> {
+  throwIfOoxmlAborted(packageSignals.get(pkg));
+  const archive = packageArchives.get(pkg);
+  if (!archive) {
+    throw new TypeError('Invalid OoxmlPackage: create packages with openPackage().');
+  }
+  return archive.read(path, maxBytes);
 }
 
 // ============================================
@@ -193,6 +289,8 @@ export async function getPartBinary(
  * @returns Parsed core properties (all fields optional)
  */
 export async function getCoreProperties(pkg: OoxmlPackage): Promise<CoreProperties> {
+  const signal = packageSignals.get(pkg);
+  throwIfOoxmlAborted(signal);
   const doc = await getPartXml(pkg, 'docProps/core.xml');
   if (!doc) return {};
 
@@ -204,7 +302,7 @@ export async function getCoreProperties(pkg: OoxmlPackage): Promise<CoreProperti
     return undefined;
   }
 
-  return {
+  const properties = {
     title: getText(NS_DC, 'title'),
     subject: getText(NS_DC, 'subject'),
     creator: getText(NS_DC, 'creator'),
@@ -215,4 +313,6 @@ export async function getCoreProperties(pkg: OoxmlPackage): Promise<CoreProperti
     created: getText(NS_DCTERMS, 'created'),
     modified: getText(NS_DCTERMS, 'modified'),
   };
+  throwIfOoxmlAborted(signal);
+  return properties;
 }

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[];
 }
 
 /**

package/src/ooxml/writer.ts

@@ -20,6 +20,7 @@ import {
   REL_CORE_PROPERTIES,
 } from './namespaces.js';
 import { xmlDeclaration, escapeXml } from './xmlUtils.js';
+import { assertSafeZipPath } from '../shared/zipSafety.js';
 
 // ============================================
 // Package Builder
@@ -99,14 +100,17 @@ export function createPackage(): OoxmlPackageBuilder {
 
   return {
     addPart(path, content, contentType) {
+      assertSafeZipPath(path);
       parts.push({ path, content, contentType });
     },
 
     addBinaryPart(path, data, contentType) {
+      assertSafeZipPath(path);
       parts.push({ path, binaryContent: data, contentType });
     },
 
     addRelationship(sourcePart, rel) {
+      if (sourcePart) assertSafeZipPath(sourcePart);
       relationships.push({ sourcePart, relationship: rel });
     },
 
@@ -139,6 +143,10 @@ function assemble(
   coreProps?: CoreProperties,
 ): JSZip {
   const zip = new JSZip();
+  // Assembly must be idempotent: callers may request both Blob and
+  // ArrayBuffer representations from one builder. Never append generated
+  // relationships to the builder-owned array.
+  const assembledRelationships = relationships.slice();
 
   // Write content parts
   for (const part of parts) {
@@ -154,22 +162,32 @@ function assemble(
     const coreXml = buildCorePropertiesXml(coreProps);
     zip.file('docProps/core.xml', coreXml);
 
-    // Add relationship to core properties
-    relationships.push({
-      sourcePart: '',
-      relationship: {
-        id: `rId${relationships.length + 100}`,
-        type: REL_CORE_PROPERTIES,
-        target: 'docProps/core.xml',
-      },
-    });
+    // Add the generated relationship unless the caller already supplied it.
+    if (
+      !assembledRelationships.some(
+        ({ sourcePart, relationship }) =>
+          sourcePart === '' && relationship.type === REL_CORE_PROPERTIES,
+      )
+    ) {
+      const ids = new Set(assembledRelationships.map(({ relationship }) => relationship.id));
+      let nextId = 100;
+      while (ids.has(`rId${nextId}`)) nextId++;
+      assembledRelationships.push({
+        sourcePart: '',
+        relationship: {
+          id: `rId${nextId}`,
+          type: REL_CORE_PROPERTIES,
+          target: 'docProps/core.xml',
+        },
+      });
+    }
   }
 
   // Build and write [Content_Types].xml
   zip.file('[Content_Types].xml', buildContentTypesXml(parts, coreProps));
 
   // Build and write _rels/*.rels files
-  const relsBySource = groupRelationshipsBySource(relationships);
+  const relsBySource = groupRelationshipsBySource(assembledRelationships);
   for (const [sourcePart, rels] of relsBySource) {
     const relsPath = sourcePart === '' ? '_rels/.rels' : buildRelsPath(sourcePart);
     zip.file(relsPath, buildRelationshipsXml(rels));

package/src/pdf/export.ts

@@ -21,7 +21,7 @@
 
 import { PDFDocument, StandardFonts, rgb, PDFFont, PDFPage } from 'pdf-lib';
 
-import type { Doc } from '@bendyline/squisq/schemas';
+import type { Doc, ThemeRegistry } from '@bendyline/squisq/schemas';
 import { docToMarkdown, resolveThemeForDoc } from '@bendyline/squisq/doc';
 import type {
   MarkdownDocument,
@@ -110,6 +110,8 @@ export interface PdfExportOptions {
    * Font changes are not supported (pdf-lib uses standard 14 PDF fonts only).
    */
   themeId?: string;
+  /** Explicit caller-owned registry for non-document custom themes. */
+  themeRegistry?: ThemeRegistry;
 }
 
 /**
@@ -219,7 +221,7 @@ async function createExportContext(
   // including inline custom themes (resolved doc-scoped).
   const themeId = options.themeId ?? readFrontmatterThemeId(doc.frontmatter);
   if (themeId) {
-    const theme = resolveThemeForDoc(doc, themeId);
+    const theme = resolveThemeForDoc(doc, themeId, options.themeRegistry);
     if (theme.colors) {
       colorText = hexToRgb(theme.colors.text) ?? COLOR_TEXT;
       colorHeading = hexToRgb(theme.colors.primary) ?? COLOR_HEADING;