@bendyline/squisq-formats 2.0.0 → 2.1.0

package/src/__tests__/convert.test.ts

@@ -10,7 +10,7 @@ import { parseMarkdown } from '@bendyline/squisq/markdown';
 import { markdownToDoc } from '@bendyline/squisq/doc';
 import { MemoryContentContainer } from '@bendyline/squisq/storage';
 import { createTransformStyleRegistry, resolveTransformStyle } from '@bendyline/squisq/transform';
-import { convert, ConversionError, defaultRegistry } from '../registry/index';
+import { convert, ConversionError, defaultRegistry, prepareConversion } from '../registry/index';
 import { zipToContainer } from '../container/index';
 import { markdownDocToPptx } from '../pptx/export';
 import { buildThemedPptx } from './pptxInferFixtures';
@@ -57,6 +57,31 @@ describe('convert error paths', () => {
       format: 'docx',
     });
   });
+
+  it('threads cancellation to exporters and preserves the abort reason', async () => {
+    const controller = new AbortController();
+    const reason = new Error('caller cancelled conversion');
+    reason.name = 'AbortError';
+    const registry = defaultRegistry();
+    registry.register({
+      id: 'abortable',
+      label: 'Abortable',
+      mimeType: 'application/x-abortable',
+      extensions: ['.abortable'],
+      async exportDoc(_input, options) {
+        expect(options.signal).toBe(controller.signal);
+        controller.abort(reason);
+        throw new Error('must not replace the abort reason');
+      },
+    });
+
+    await expect(
+      convert({ kind: 'markdown', markdown: '# Cancel me' }, 'abortable', {
+        registry,
+        signal: controller.signal,
+      }),
+    ).rejects.toBe(reason);
+  });
 });
 
 describe('format option threading', () => {
@@ -110,6 +135,16 @@ describe('format option threading', () => {
       }),
     ).rejects.toMatchObject({ code: 'invalid-input', format: 'docx' });
   });
+
+  it('can emit DBK with STORE so strict import compression limits accept its own output', async () => {
+    const result = await convert(
+      { kind: 'markdown', markdown: `# Self-compatible DBK\n\n${'x'.repeat(16 * 1024)}` },
+      'dbk',
+      { formatOptions: { dbk: { compression: 'STORE' } } },
+    );
+    const restored = await zipToContainer(result.bytes, { maxCompressionRatio: 1.01 });
+    expect(await restored.readDocument()).toContain('Self-compatible DBK');
+  });
 });
 
 // ── round trip: md → docx → md ──────────────────────────────────────
@@ -191,6 +226,113 @@ describe('byte sniffing', () => {
 // ── transform threading ─────────────────────────────────────────────
 
 describe('transform threading', () => {
+  it('normalizes and transforms once before exporting multiple targets', async () => {
+    let importCount = 0;
+    let transformLookupCount = 0;
+    const exportCounts = { first: 0, second: 0 };
+    const markers: string[] = [];
+    const exportSignals: Array<AbortSignal | undefined> = [];
+    const formats = defaultRegistry();
+    formats.register({
+      id: 'counted-input',
+      label: 'Counted input',
+      mimeType: 'application/x-counted-input',
+      extensions: ['.counted'],
+      async importDoc() {
+        importCount += 1;
+        return parseMarkdown(SAMPLE_MD);
+      },
+    });
+    for (const [id, key] of [
+      ['prepared-first', 'first'],
+      ['prepared-second', 'second'],
+    ] as const) {
+      formats.register({
+        id,
+        label: id,
+        mimeType: `application/x-${id}`,
+        extensions: [`.${key}`],
+        async exportDoc(input, options) {
+          exportCounts[key] += 1;
+          exportSignals.push(options.signal);
+          const targetOptions = options.formatOptions?.[id] as { marker?: string } | undefined;
+          markers.push(targetOptions?.marker ?? 'missing');
+          expect(input.doc.blocks.length).toBeGreaterThan(0);
+          return {
+            bytes: new TextEncoder().encode(key),
+            mimeType: `application/x-${id}`,
+            suggestedFilename: '',
+            warnings: [`${key} warning`],
+          };
+        },
+      });
+    }
+
+    const style = { ...resolveTransformStyle('magazine'), id: 'counted-transform' };
+    const backingTransforms = createTransformStyleRegistry([style]);
+    const transformRegistry = {
+      register: (candidate: typeof style) => backingTransforms.register(candidate),
+      unregister: (id: string) => backingTransforms.unregister(id),
+      get: (id: string) => {
+        transformLookupCount += 1;
+        return backingTransforms.get(id);
+      },
+      list: () => backingTransforms.list(),
+    };
+    const overall = new AbortController();
+    const prepared = await prepareConversion(
+      {
+        kind: 'bytes',
+        data: new TextEncoder().encode('count me once'),
+        filename: 'source.counted',
+      },
+      {
+        registry: formats,
+        from: 'counted-input',
+        transformStyle: 'counted-transform',
+        transformRegistry,
+        signal: overall.signal,
+      },
+    );
+    const first = await prepared.convert('prepared-first', {
+      formatOptions: { 'prepared-first': { marker: 'one' } },
+    });
+    const target = new AbortController();
+    const second = await prepared.convert('prepared-second', {
+      signal: target.signal,
+      formatOptions: { 'prepared-second': { marker: 'two' } },
+    });
+
+    expect(importCount).toBe(1);
+    expect(transformLookupCount).toBe(1);
+    expect(exportCounts).toEqual({ first: 1, second: 1 });
+    expect(markers).toEqual(['one', 'two']);
+    expect(exportSignals[0]).toBe(overall.signal);
+    expect(exportSignals[1]?.aborted).toBe(false);
+    expect(first.suggestedFilename).toBe('source.first');
+    expect(second.suggestedFilename).toBe('source.second');
+    expect(first.warnings).toContain('first warning');
+    expect(second.warnings).toContain('second warning');
+
+    await expect(prepared.convert('missing-target')).rejects.toMatchObject({
+      name: 'ConversionError',
+      code: 'unknown-format',
+      format: 'missing-target',
+    });
+    const targetReason = new Error('cancel target export');
+    target.abort(targetReason);
+    expect(exportSignals[1]?.reason).toBe(targetReason);
+    await expect(prepared.convert('prepared-first', { signal: target.signal })).rejects.toBe(
+      targetReason,
+    );
+    const overallReason = new Error('cancel prepared conversion');
+    overall.abort(overallReason);
+    await expect(
+      prepared.convert('prepared-first', { signal: new AbortController().signal }),
+    ).rejects.toBe(overallReason);
+    expect(exportCounts.first).toBe(1);
+  });
+
   it('applies a transform style before handing off to the exporter', async () => {
     // A capture format records the NormalizedInput it receives, letting us
     // observe that the transform ran without depending on any converter.

package/src/__tests__/docxExport.test.ts

@@ -22,6 +22,7 @@ import type {
   MarkdownEmphasis,
   MarkdownInlineCode,
   MarkdownLink,
+  MarkdownContainerDirective,
 } from '@bendyline/squisq/markdown';
 
 import { markdownDocToDocx, docToDocx } from '../docx/export';
@@ -81,6 +82,39 @@ describe('markdownDocToDocx', () => {
     expect(body).toBeDefined();
   });
 
+  it('exports DOCX story directives to header and footer parts', async () => {
+    const doc: MarkdownDocument = {
+      type: 'document',
+      children: [
+        { type: 'paragraph', children: [{ type: 'text', value: 'Body' }] },
+        {
+          type: 'containerDirective',
+          name: 'docx-header',
+          children: [{ type: 'paragraph', children: [{ type: 'text', value: 'Header' }] }],
+        } satisfies MarkdownContainerDirective,
+        {
+          type: 'containerDirective',
+          name: 'docx-footer',
+          children: [{ type: 'paragraph', children: [{ type: 'text', value: 'Footer' }] }],
+        } satisfies MarkdownContainerDirective,
+      ],
+    };
+
+    const zip = await exportAndParse(doc);
+    const documentXml = await zip.file('word/document.xml')!.async('text');
+    const headerXml = await zip.file('word/header1.xml')!.async('text');
+    const footerXml = await zip.file('word/footer1.xml')!.async('text');
+    const relationships = await zip.file('word/_rels/document.xml.rels')!.async('text');
+
+    expect(documentXml).toContain('<w:headerReference');
+    expect(documentXml).toContain('<w:footerReference');
+    expect(documentXml).not.toContain('Header');
+    expect(headerXml).toContain('Header');
+    expect(footerXml).toContain('Footer');
+    expect(relationships).toContain('/relationships/header');
+    expect(relationships).toContain('/relationships/footer');
+  });
+
   // ============================================
   // Headings
   // ============================================

package/src/__tests__/docxImport.test.ts

@@ -14,9 +14,13 @@ import {
   REL_STYLES,
   REL_NUMBERING,
   REL_HYPERLINK,
+  REL_HEADER,
+  REL_FOOTER,
   CONTENT_TYPE_DOCX_DOCUMENT,
   CONTENT_TYPE_DOCX_STYLES,
   CONTENT_TYPE_DOCX_NUMBERING,
+  CONTENT_TYPE_DOCX_HEADER,
+  CONTENT_TYPE_DOCX_FOOTER,
 } from '../ooxml/namespaces';
 import { xmlDeclaration } from '../ooxml/xmlUtils';
 import { docxToMarkdownDoc, docxToDoc } from '../docx/import';
@@ -31,6 +35,7 @@ import type {
   MarkdownStrikethrough,
   MarkdownLink,
   MarkdownInlineNode,
+  MarkdownContainerDirective,
 } from '@bendyline/squisq/markdown';
 
 // ============================================
@@ -47,6 +52,7 @@ interface DocxFixtureOptions {
     target: string;
     targetMode?: 'External';
   }>;
+  extraParts?: Array<{ path: string; content: string; contentType: string }>;
 }
 
 async function buildTestDocx(options: DocxFixtureOptions): Promise<ArrayBuffer> {
@@ -81,6 +87,10 @@ async function buildTestDocx(options: DocxFixtureOptions): Promise<ArrayBuffer>
     pkg.addPart('word/numbering.xml', options.numberingXml, CONTENT_TYPE_DOCX_NUMBERING);
   }
 
+  for (const part of options.extraParts ?? []) {
+    pkg.addPart(part.path, part.content, part.contentType);
+  }
+
   // Root relationship
   pkg.addRelationship('', {
     id: 'rId1',
@@ -164,6 +174,25 @@ describe('docxToMarkdownDoc', () => {
     );
   });
 
+  it('imports visible content inside controls, revisions, and text boxes once', async () => {
+    const data = await buildTestDocx({
+      bodyXml:
+        `<w:p>` +
+        `<w:r><w:t>Body </w:t></w:r>` +
+        `<w:sdt><w:sdtContent><w:r><w:t>controlled </w:t></w:r></w:sdtContent></w:sdt>` +
+        `<w:ins><w:r><w:t>inserted </w:t></w:r></w:ins>` +
+        `<mc:AlternateContent xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006">` +
+        `<mc:Choice><w:drawing><w:txbxContent><w:p><w:r><w:t>text box</w:t></w:r></w:p></w:txbxContent></w:drawing></mc:Choice>` +
+        `<mc:Fallback><w:pict><w:txbxContent><w:p><w:r><w:t>fallback duplicate</w:t></w:r></w:p></w:txbxContent></w:pict></mc:Fallback>` +
+        `</mc:AlternateContent>` +
+        `</w:p>`,
+    });
+
+    const paragraph = docText(await docxToMarkdownDoc(data));
+    expect(paragraph).toContain('Body controlled inserted text box');
+    expect(paragraph).not.toContain('fallback duplicate');
+  });
+
   it('skips empty paragraphs', async () => {
     const data = await buildTestDocx({
       bodyXml: `<w:p><w:pPr/></w:p><w:p><w:r><w:t>Text</w:t></w:r></w:p>`,
@@ -331,6 +360,27 @@ describe('docxToMarkdownDoc', () => {
     expect(list.ordered).toBe(true);
   });
 
+  it('retains nested list text after an empty parent numbering paragraph', async () => {
+    const numberingXml =
+      xmlDeclaration() +
+      `<w:numbering xmlns:w="${NS_WML}">` +
+      `<w:abstractNum w:abstractNumId="3">` +
+      `<w:lvl w:ilvl="0"><w:numFmt w:val="decimal"/></w:lvl>` +
+      `<w:lvl w:ilvl="1"><w:numFmt w:val="decimal"/></w:lvl>` +
+      `</w:abstractNum>` +
+      `<w:num w:numId="3"><w:abstractNumId w:val="3"/></w:num>` +
+      `</w:numbering>`;
+    const data = await buildTestDocx({
+      bodyXml:
+        `<w:p><w:pPr><w:numPr><w:ilvl w:val="0"/><w:numId w:val="3"/></w:numPr></w:pPr></w:p>` +
+        `<w:p><w:pPr><w:numPr><w:ilvl w:val="1"/><w:numId w:val="3"/></w:numPr></w:pPr>` +
+        `<w:r><w:t>Nested content survives</w:t></w:r></w:p>`,
+      numberingXml,
+    });
+
+    expect(docText(await docxToMarkdownDoc(data))).toContain('Nested content survives');
+  });
+
   // ============================================
   // Tables
   // ============================================
@@ -363,6 +413,57 @@ describe('docxToMarkdownDoc', () => {
     expect((cell10.children[0] as MarkdownText).value).toBe('1');
   });
 
+  it('flattens nested table contents without losing their text', async () => {
+    const data = await buildTestDocx({
+      bodyXml:
+        `<w:tbl><w:tr><w:tc>` +
+        `<w:p><w:r><w:t>Outer</w:t></w:r></w:p>` +
+        `<w:tbl><w:tr>` +
+        `<w:tc><w:p><w:r><w:t>Nested A</w:t></w:r></w:p></w:tc>` +
+        `<w:tc><w:p><w:r><w:t>Nested B</w:t></w:r></w:p></w:tc>` +
+        `</w:tr></w:tbl>` +
+        `</w:tc></w:tr></w:tbl>`,
+    });
+
+    expect(docText(await docxToMarkdownDoc(data))).toContain('Outer Nested A Nested B');
+  });
+
+  it('imports headers and footers as explicit DOCX story directives', async () => {
+    const headerXml =
+      xmlDeclaration() +
+      `<w:hdr xmlns:w="${NS_WML}"><w:p><w:r><w:t>Header text</w:t></w:r></w:p></w:hdr>`;
+    const footerXml =
+      xmlDeclaration() +
+      `<w:ftr xmlns:w="${NS_WML}"><w:p><w:r><w:t>Footer text</w:t></w:r></w:p></w:ftr>`;
+    const data = await buildTestDocx({
+      bodyXml:
+        `<w:p><w:r><w:t>Body text</w:t></w:r></w:p>` +
+        `<w:sectPr><w:headerReference w:type="default" r:id="rIdHeader"/>` +
+        `<w:footerReference w:type="default" r:id="rIdFooter"/></w:sectPr>`,
+      documentRels: [
+        { id: 'rIdHeader', type: REL_HEADER, target: 'header1.xml' },
+        { id: 'rIdFooter', type: REL_FOOTER, target: 'footer1.xml' },
+      ],
+      extraParts: [
+        { path: 'word/header1.xml', content: headerXml, contentType: CONTENT_TYPE_DOCX_HEADER },
+        { path: 'word/footer1.xml', content: footerXml, contentType: CONTENT_TYPE_DOCX_FOOTER },
+      ],
+    });
+
+    const doc = await docxToMarkdownDoc(data);
+    const header = doc.children.find(
+      (node): node is MarkdownContainerDirective =>
+        node.type === 'containerDirective' && node.name === 'docx-header',
+    );
+    const footer = doc.children.find(
+      (node): node is MarkdownContainerDirective =>
+        node.type === 'containerDirective' && node.name === 'docx-footer',
+    );
+    expect(header?.attributes?.type).toBe('default');
+    expect(footer?.attributes?.type).toBe('default');
+    expect(docText(doc)).toContain('Body text Header text Footer text');
+  });
+
   // ============================================
   // Empty Document
   // ============================================
@@ -387,8 +488,28 @@ describe('docxToMarkdownDoc', () => {
     const para = doc.children[0] as MarkdownParagraph;
     expect(para.children.some((c: MarkdownInlineNode) => c.type === 'break')).toBe(true);
   });
+
+  it('retains tabs as visible word boundaries', async () => {
+    const data = await buildTestDocx({
+      bodyXml: `<w:p><w:r><w:t>Before</w:t><w:tab/><w:t>After</w:t></w:r></w:p>`,
+    });
+
+    expect(docText(await docxToMarkdownDoc(data))).toBe('Before After');
+  });
 });
 
+function docText(doc: Awaited<ReturnType<typeof docxToMarkdownDoc>>): string {
+  const text: string[] = [];
+  const visit = (node: unknown): void => {
+    if (!node || typeof node !== 'object') return;
+    const value = node as { type?: string; value?: string; children?: unknown[] };
+    if ((value.type === 'text' || value.type === 'code') && value.value) text.push(value.value);
+    value.children?.forEach(visit);
+  };
+  visit(doc);
+  return text.join(' ').replace(/\s+/g, ' ').trim();
+}
+
 // ============================================
 // docxToDoc convenience wrapper
 // ============================================

package/src/__tests__/html.test.ts

@@ -300,6 +300,10 @@ describe('docToHtml', () => {
     const html = docToHtml(doc, { playerScript: MOCK_PLAYER_SCRIPT, mode: 'static' });
 
     expect(html).toContain('"static"');
+    // The page rendition owns its own background/scrolling — the host shim
+    // must not hardcode a white background that fights themed pages.
+    expect(html).toContain('#squisq-root{display:block}');
+    expect(html).not.toContain('background:#fff');
   });
 
   it('inlines images as base64 data URIs', () => {

package/src/__tests__/ooxml.test.ts

@@ -126,6 +126,23 @@ describe('createPackage / openPackage round-trip', () => {
     expect(doc?.getElementsByTagName('value')[0]?.textContent).toBe('node');
   });
 
+  it('ignores an incomplete ambient DOMParser when running in Node', async () => {
+    const pkg = createPackage();
+    pkg.addPart('word/document.xml', '<doc><value>node</value></doc>', 'application/xml');
+    const buffer = await pkg.toArrayBuffer();
+
+    class IncompleteDomParser {
+      parseFromString(): never {
+        throw new Error('ambient parser must not be used in Node');
+      }
+    }
+
+    vi.stubGlobal('DOMParser', IncompleteDomParser);
+    const opened = await openPackage(buffer);
+    const doc = await getPartXml(opened, 'word/document.xml');
+    expect(doc?.getElementsByTagName('value')[0]?.textContent).toBe('node');
+  });
+
   it('applies archive resource limits before parsing OOXML parts', async () => {
     const pkg = createPackage();
     pkg.addPart('word/document.xml', '<doc/>', 'application/xml');

package/src/__tests__/ooxmlCancellation.test.ts

@@ -0,0 +1,113 @@
+import { describe, expect, it } from 'vitest';
+import { inferThemeFromFile } from '../infer/index';
+import { getPartXml, openPackage } from '../ooxml/reader';
+import { inspectPptxLayouts } from '../pptx/layouts';
+import { prepareZipInput } from '../shared/zipEntryCount';
+import { buildThemedPptx } from './pptxInferFixtures';
+
+function blockingBlob(onRead: () => void): Blob {
+  const blob = {
+    size: 128,
+    slice: () => blob,
+    arrayBuffer: () => {
+      onRead();
+      return new Promise<ArrayBuffer>(() => undefined);
+    },
+  };
+  return blob as unknown as Blob;
+}
+
+describe('OOXML cancellation', () => {
+  it('preserves the exact reason while theme inference reads Blob input', async () => {
+    let markStarted: (() => void) | undefined;
+    const started = new Promise<void>((resolve) => {
+      markStarted = resolve;
+    });
+    const controller = new AbortController();
+    const reason = new Error('stop inference');
+    const pending = inferThemeFromFile(
+      blockingBlob(() => markStarted?.()),
+      {
+        signal: controller.signal,
+      },
+    );
+
+    await started;
+    controller.abort(reason);
+
+    await expect(pending).rejects.toBe(reason);
+  });
+
+  it('preserves the exact reason while layout inspection opens Blob input', async () => {
+    let markStarted: (() => void) | undefined;
+    const started = new Promise<void>((resolve) => {
+      markStarted = resolve;
+    });
+    const controller = new AbortController();
+    const reason = new Error('stop layout inspection');
+    const pending = inspectPptxLayouts(
+      blockingBlob(() => markStarted?.()),
+      {
+        signal: controller.signal,
+      },
+    );
+
+    await started;
+    controller.abort(reason);
+
+    await expect(pending).rejects.toBe(reason);
+  });
+
+  it('propagates package cancellation through later OOXML part traversal', async () => {
+    const controller = new AbortController();
+    const pkg = await openPackage(await buildThemedPptx(), { signal: controller.signal });
+    const reason = new Error('stop OOXML traversal');
+    controller.abort(reason);
+
+    await expect(getPartXml(pkg, 'ppt/presentation.xml')).rejects.toBe(reason);
+  });
+
+  it('handles a synchronously re-entrant FileReader abort exactly once', async () => {
+    const previous = globalThis.FileReader;
+    let abortCalls = 0;
+    class ReentrantFileReader {
+      result: ArrayBuffer | null = null;
+      error: DOMException | null = null;
+      onload: ((event: ProgressEvent<FileReader>) => void) | null = null;
+      onerror: ((event: ProgressEvent<FileReader>) => void) | null = null;
+      onabort: ((event: ProgressEvent<FileReader>) => void) | null = null;
+      readAsArrayBuffer(): void {
+        // Remain pending until the caller aborts.
+      }
+
+      abort(): void {
+        abortCalls += 1;
+        this.onabort?.({} as ProgressEvent<FileReader>);
+      }
+    }
+    Object.defineProperty(globalThis, 'FileReader', {
+      configurable: true,
+      writable: true,
+      value: ReentrantFileReader,
+    });
+
+    const blobLike = { size: 1, slice: () => blobLike } as unknown as Blob;
+    const controller = new AbortController();
+    const reason = new Error('stop FileReader');
+    try {
+      const pending = prepareZipInput(blobLike, controller.signal);
+      controller.abort(reason);
+      await expect(pending).rejects.toBe(reason);
+      expect(abortCalls).toBe(1);
+    } finally {
+      if (previous === undefined) Reflect.deleteProperty(globalThis, 'FileReader');
+      else {
+        Object.defineProperty(globalThis, 'FileReader', {
+          configurable: true,
+          writable: true,
+          value: previous,
+        });
+      }
+    }
+  });
+});

package/src/container/index.ts

@@ -24,6 +24,12 @@ import {
 } from '../shared/zipSafety.js';
 
 export type ZipToContainerOptions = ZipSafetyLimits;
+export interface ContainerToZipOptions {
+  /** STORE avoids producing archives that violate strict import compression-ratio policies. */
+  compression?: 'STORE' | 'DEFLATE';
+  /** JSZip DEFLATE level; ignored for STORE. */
+  compressionLevel?: number;
+}
 export { ZipSafetyError };
 export type { ZipSafetyLimits, ZipSafetyErrorCode, ZipSafetyErrorOptions };
 
@@ -36,7 +42,10 @@ export type { ZipSafetyLimits, ZipSafetyErrorCode, ZipSafetyErrorOptions };
  * @param container — The container to serialize
  * @returns A Blob containing the ZIP archive
  */
-export async function containerToZip(container: ContentContainer): Promise<Blob> {
+export async function containerToZip(
+  container: ContentContainer,
+  options: ContainerToZipOptions = {},
+): Promise<Blob> {
   const zip = new JSZip();
   const entries = await container.listFiles();
 
@@ -48,10 +57,15 @@ export async function containerToZip(container: ContentContainer): Promise<Blob>
     }
   }
 
+  const compression = options.compression ?? 'DEFLATE';
+  const compressionLevel = options.compressionLevel ?? 6;
+  if (!Number.isSafeInteger(compressionLevel) || compressionLevel < 1 || compressionLevel > 9) {
+    throw new Error('ZIP compression level must be an integer between 1 and 9');
+  }
   return zip.generateAsync({
     type: 'blob',
-    compression: 'DEFLATE',
-    compressionOptions: { level: 6 },
+    compression,
+    ...(compression === 'DEFLATE' ? { compressionOptions: { level: compressionLevel } } : {}),
   });
 }