@bendyline/squisq-formats 1.3.0 → 1.4.0

package/src/__tests__/exportThemeReconciliation.test.ts

@@ -0,0 +1,87 @@
+/**
+ * Export theme reconciliation.
+ *
+ * Every export format must honor the theme the document selects in its
+ * frontmatter (`squisq-theme`) — including an inline custom theme stored in
+ * `squisq-custom-themes` — without an explicit `themeId` option. This guards
+ * the fix that made PDF/EPUB read the frontmatter theme like PPTX/DOCX/HTML,
+ * and that custom themes resolve doc-scoped in exports (no global register).
+ */
+
+import { describe, it, expect } from 'vitest';
+import JSZip from 'jszip';
+import { compileTheme } from '@bendyline/squisq/schemas';
+import { writeCustomThemesToFrontmatter } from '@bendyline/squisq/doc';
+import { parseMarkdown } from '@bendyline/squisq/markdown';
+import { markdownDocToPptx } from '../pptx/export';
+import { markdownDocToDocx } from '../docx/export';
+import { markdownDocToPdf } from '../pdf/export';
+import { markdownDocToEpub } from '../epub/export';
+import { markdownDocToPlainHtml } from '../html/plainHtml';
+
+const brand = compileTheme({
+  id: 'custom-brand',
+  name: 'Brand',
+  seedColors: { primary: '#ff0088', background: '#123456', text: '#abcdef' },
+});
+
+const withTheme = parseMarkdown(`---
+title: Audit
+squisq-theme: custom-brand
+squisq-custom-themes: ${writeCustomThemesToFrontmatter([brand])}
+---
+
+# Heading One
+
+Body with a [link](https://example.com).
+`);
+
+const noTheme = parseMarkdown('# Heading One\n\nBody.\n');
+
+/** Concatenate the text of every XML/CSS/HTML entry in a ZIP export. */
+async function zipText(buf: ArrayBuffer): Promise<string> {
+  const zip = await JSZip.loadAsync(buf);
+  let text = '';
+  for (const name of Object.keys(zip.files)) {
+    if (/\.(xml|css|html|xhtml|rels)$/i.test(name)) {
+      text += await zip.files[name].async('string');
+    }
+  }
+  return text.toLowerCase();
+}
+
+describe('export theme reconciliation (frontmatter-only custom theme)', () => {
+  it('HTML applies the frontmatter custom theme colors', () => {
+    const html = markdownDocToPlainHtml(withTheme, {}).toLowerCase();
+    expect(html).toContain('123456'); // background
+    expect(html).toContain('abcdef'); // text
+  });
+
+  it('PPTX applies the frontmatter custom theme colors', async () => {
+    const text = await zipText(await markdownDocToPptx(withTheme, {}));
+    expect(text).toContain('123456');
+  });
+
+  it('DOCX applies the frontmatter custom theme colors', async () => {
+    const text = await zipText(await markdownDocToDocx(withTheme, {}));
+    expect(text).toContain('123456');
+  });
+
+  it('EPUB applies the frontmatter custom theme colors (frontmatter fallback)', async () => {
+    const text = await zipText(await markdownDocToEpub(withTheme, {}));
+    expect(text).toContain('123456');
+  });
+
+  it('PDF themes from frontmatter — themed output differs from un-themed', async () => {
+    const themed = new Uint8Array(await markdownDocToPdf(withTheme, {}));
+    const plain = new Uint8Array(await markdownDocToPdf(noTheme, {}));
+    const differs = themed.length !== plain.length || !themed.every((b, i) => b === plain[i]);
+    expect(differs).toBe(true);
+  });
+
+  it('an explicit themeId option still overrides the frontmatter theme', async () => {
+    const bare = await zipText(await markdownDocToPptx(withTheme, { themeId: 'standard' }));
+    // The custom background must NOT appear when the caller forces 'standard'.
+    expect(bare).not.toContain('123456');
+  });
+});

package/src/__tests__/htmlImport.test.ts

@@ -0,0 +1,57 @@
+import { describe, expect, it } from 'vitest';
+import { htmlToMarkdown, htmlToMarkdownDocSync } from '../html/import.js';
+
+describe('htmlToMarkdown', () => {
+  it('converts headings and paragraphs', () => {
+    const md = htmlToMarkdown('<h1>Title</h1><p>Hello <strong>world</strong>.</p>');
+    expect(md).toContain('# Title');
+    expect(md).toContain('Hello **world**.');
+  });
+
+  it('converts links and inline code', () => {
+    const md = htmlToMarkdown(
+      '<p>See <a href="https://x.test">site</a> and <code>npm i</code></p>',
+    );
+    expect(md).toContain('[site](https://x.test)');
+    expect(md).toContain('`npm i`');
+  });
+
+  it('converts unordered and ordered lists', () => {
+    const md = htmlToMarkdown('<ul><li>a</li><li>b</li></ul><ol><li>one</li><li>two</li></ol>');
+    expect(md).toMatch(/[-*]\s+a/);
+    expect(md).toMatch(/[-*]\s+b/);
+    expect(md).toMatch(/1\.\s+one/);
+  });
+
+  it('converts blockquotes and tables', () => {
+    const md = htmlToMarkdown(
+      '<blockquote><p>quoted</p></blockquote>' +
+        '<table><thead><tr><th>H</th></tr></thead><tbody><tr><td>cell</td></tr></tbody></table>',
+    );
+    expect(md).toContain('> quoted');
+    expect(md).toContain('cell');
+  });
+
+  it('drops scripts and styles (sanitized by default)', () => {
+    const md = htmlToMarkdown('<p>safe</p><script>alert(1)</script><style>.x{color:red}</style>');
+    expect(md).toContain('safe');
+    expect(md).not.toContain('alert(1)');
+    expect(md).not.toContain('color:red');
+  });
+
+  it('strips javascript: links via sanitizer', () => {
+    const md = htmlToMarkdown('<a href="javascript:alert(1)">click</a>');
+    expect(md).not.toContain('javascript:alert(1)');
+  });
+
+  it('builds a document node tree', () => {
+    const doc = htmlToMarkdownDocSync('<h2>Hi</h2>');
+    expect(doc.type).toBe('document');
+    expect(doc.children[0]?.type).toBe('heading');
+  });
+
+  it('handles unwrapped div/span containers', () => {
+    const md = htmlToMarkdown('<div><span>plain </span><em>text</em></div>');
+    expect(md).toContain('plain *text*');
+  });
+});

package/src/__tests__/plainHtml.test.ts

@@ -43,6 +43,12 @@ describe('markdownDocToPlainHtml', () => {
     );
   });
 
+  it('renders unsafe markdown links as inert text by default', () => {
+    const html = render('[x](javascript:alert(1))');
+    expect(html).toContain('<p>x</p>');
+    expect(html).not.toContain('javascript:');
+  });
+
   it('renders ordered and unordered lists', () => {
     const html = render('- one\n- two\n\n1. first\n2. second');
     expect(html).toContain('<ul>');
@@ -112,6 +118,31 @@ describe('markdownDocToPlainHtml', () => {
     expect(html).not.toContain('src="resized.png"');
   });
 
+  it('sanitizes raw HTML by default', () => {
+    const html = render(
+      '<div><img src="x.jpg" onerror="alert(1)"><script>alert(1)</script><span onclick="alert(1)">ok</span></div>',
+    );
+    expect(html).toContain('<img src="x.jpg" />');
+    expect(html).toContain('<span>ok</span>');
+    expect(html).not.toContain('<script>');
+    expect(html).not.toContain('onerror');
+    expect(html).not.toContain('onclick');
+    expect(html).not.toContain('javascript:');
+  });
+
+  it('strips raw HTML when requested', () => {
+    const html = render('<div><span>hidden</span></div>', { htmlPolicy: 'strip' });
+    expect(html).not.toContain('<span>hidden</span>');
+    expect(html).not.toContain('hidden');
+  });
+
+  it('preserves raw HTML only with the trusted opt-in', () => {
+    const html = render('<div><span onclick="alert(1)">ok</span></div>', {
+      htmlPolicy: 'trusted',
+    });
+    expect(html).toContain('<div><span onclick="alert(1)">ok</span></div>');
+  });
+
   it('escapes quotes in href and src attributes', () => {
     const html = render('![a](a"b.jpg)\n\n[c](d"e)');
     expect(html).toContain('&quot;');

package/src/__tests__/pptxExport.test.ts

@@ -0,0 +1,138 @@
+import { describe, expect, it } from 'vitest';
+import type { MarkdownBlockNode, MarkdownDocument } from '@bendyline/squisq/markdown';
+import type { Transition } from '@bendyline/squisq/schemas';
+import { TRANSITION_TYPES } from '@bendyline/squisq/schemas';
+import { markdownDocToPptx } from '../pptx/export';
+import { openPackage, getPartXml } from '../ooxml/reader';
+import { NS_PML, NS_PML_2010 } from '../ooxml/namespaces';
+
+function docWithSecondSlideTransition(transition: Transition): MarkdownDocument {
+  return {
+    type: 'document',
+    children: [
+      {
+        type: 'heading',
+        depth: 2,
+        children: [{ type: 'text', value: 'One' }],
+      },
+      {
+        type: 'paragraph',
+        children: [{ type: 'text', value: 'Intro' }],
+      },
+      {
+        type: 'heading',
+        depth: 2,
+        children: [{ type: 'text', value: 'Two' }],
+        attributes: {
+          params: {
+            transition: transition.type,
+            ...(transition.duration !== undefined
+              ? { transitionDuration: String(transition.duration) }
+              : {}),
+            ...(transition.direction ? { transitionDirection: transition.direction } : {}),
+          },
+          blockMeta: { transition },
+        },
+      },
+      {
+        type: 'paragraph',
+        children: [{ type: 'text', value: 'Body' }],
+      },
+    ],
+  };
+}
+
+function docWithAllTransitions(): MarkdownDocument {
+  const children: MarkdownBlockNode[] = [
+    {
+      type: 'heading',
+      depth: 2,
+      children: [{ type: 'text', value: 'Transition Gallery' }],
+    },
+    {
+      type: 'paragraph',
+      children: [{ type: 'text', value: 'Intro slide before transition checks.' }],
+    },
+  ];
+
+  for (const type of TRANSITION_TYPES) {
+    const transition: Transition = { type, duration: 0.8 };
+    children.push(
+      {
+        type: 'heading',
+        depth: 2,
+        children: [{ type: 'text', value: type }],
+        attributes: {
+          params: { transition: type, transitionDuration: '0.8' },
+          blockMeta: { transition },
+        },
+      },
+      {
+        type: 'paragraph',
+        children: [{ type: 'text', value: `Transition token: ${type}` }],
+      },
+    );
+  }
+
+  return { type: 'document', children };
+}
+
+describe('markdownDocToPptx transitions', () => {
+  it('writes valid transition XML for every shared transition token', async () => {
+    const pkg = await openPackage(await markdownDocToPptx(docWithAllTransitions()));
+
+    for (let i = 0; i < TRANSITION_TYPES.length; i++) {
+      const type = TRANSITION_TYPES[i];
+      const slide = await getPartXml(pkg, `ppt/slides/slide${i + 2}.xml`);
+      expect(slide, type).not.toBeNull();
+
+      const transitions = slide!.getElementsByTagNameNS(NS_PML, 'transition');
+      if (type === 'cut') {
+        expect(transitions, type).toHaveLength(0);
+        continue;
+      }
+
+      expect(transitions, type).toHaveLength(1);
+      expect(transitions[0].getAttribute('spd'), type).toBe('med');
+
+      const childElements = Array.from(transitions[0].childNodes).filter(
+        (node): node is Element => node.nodeType === 1,
+      );
+      expect(childElements, type).toHaveLength(1);
+      expect([NS_PML, NS_PML_2010], type).toContain(childElements[0].namespaceURI);
+
+      if (childElements[0].namespaceURI === NS_PML_2010) {
+        expect(slide!.documentElement.getAttribute('mc:Ignorable'), type).toContain('p14');
+      }
+    }
+  });
+
+  it('writes standard PresentationML transition XML', async () => {
+    const md = docWithSecondSlideTransition({
+      type: 'checkerboard',
+      duration: 1.3,
+      direction: 'vertical',
+    });
+
+    const pkg = await openPackage(await markdownDocToPptx(md));
+    const slide = await getPartXml(pkg, 'ppt/slides/slide2.xml');
+    const transition = slide!.getElementsByTagNameNS(NS_PML, 'transition')[0];
+    const checker = transition.getElementsByTagNameNS(NS_PML, 'checker')[0];
+
+    expect(transition.getAttribute('spd')).toBe('slow');
+    expect(checker.getAttribute('dir')).toBe('vert');
+  });
+
+  it('writes PowerPoint 2010 transition XML when needed', async () => {
+    const md = docWithSecondSlideTransition({ type: 'flash', duration: 0.4 });
+
+    const pkg = await openPackage(await markdownDocToPptx(md));
+    const slide = await getPartXml(pkg, 'ppt/slides/slide2.xml');
+    const transition = slide!.getElementsByTagNameNS(NS_PML, 'transition')[0];
+    const flash = transition.getElementsByTagNameNS(NS_PML_2010, 'flash')[0];
+
+    expect(transition.getAttribute('spd')).toBe('fast');
+    expect(flash).toBeDefined();
+    expect(slide!.documentElement.getAttribute('mc:Ignorable')).toBe('p14');
+  });
+});

package/src/__tests__/pptxImport.test.ts

@@ -0,0 +1,70 @@
+/**
+ * Tests for PPTX import: pptxToMarkdownDoc. Builds a minimal .pptx fixture with
+ * the shared OOXML writer, then imports it.
+ */
+
+import { describe, expect, it } from 'vitest';
+import type {
+  MarkdownHeading,
+  MarkdownList,
+  MarkdownParagraph,
+  MarkdownText,
+} from '@bendyline/squisq/markdown';
+import { NS_DRAWINGML, NS_PML, NS_R, REL_OFFICE_DOCUMENT, REL_SLIDE } from '../ooxml/namespaces';
+import { createPackage } from '../ooxml/writer';
+import { xmlDeclaration } from '../ooxml/xmlUtils';
+import { pptxToMarkdownDoc } from '../pptx/import';
+
+async function buildTestPptx(): Promise<ArrayBuffer> {
+  const pkg = createPackage();
+
+  pkg.addPart(
+    'ppt/presentation.xml',
+    `${xmlDeclaration()}<p:presentation xmlns:p="${NS_PML}" xmlns:r="${NS_R}">` +
+      `<p:sldIdLst><p:sldId id="256" r:id="rId1"/></p:sldIdLst></p:presentation>`,
+    'application/xml',
+  );
+  pkg.addPart(
+    'ppt/slides/slide1.xml',
+    `${xmlDeclaration()}<p:sld xmlns:p="${NS_PML}" xmlns:a="${NS_DRAWINGML}"><p:cSld><p:spTree>` +
+      `<p:sp><p:nvSpPr><p:nvPr><p:ph type="title"/></p:nvPr></p:nvSpPr>` +
+      `<p:txBody><a:p><a:r><a:t>My Title</a:t></a:r></a:p></p:txBody></p:sp>` +
+      `<p:sp><p:txBody>` +
+      `<a:p><a:r><a:t>First bullet</a:t></a:r></a:p>` +
+      `<a:p><a:r><a:t>Second bullet</a:t></a:r></a:p>` +
+      `</p:txBody></p:sp>` +
+      `</p:spTree></p:cSld></p:sld>`,
+    'application/xml',
+  );
+
+  pkg.addRelationship('', {
+    id: 'rId1',
+    type: REL_OFFICE_DOCUMENT,
+    target: 'ppt/presentation.xml',
+  });
+  pkg.addRelationship('ppt/presentation.xml', {
+    id: 'rId1',
+    type: REL_SLIDE,
+    target: 'slides/slide1.xml',
+  });
+
+  return pkg.toArrayBuffer();
+}
+
+describe('pptxToMarkdownDoc', () => {
+  it('imports a slide as a heading + bullet list', async () => {
+    const doc = await pptxToMarkdownDoc(await buildTestPptx());
+    expect(doc.type).toBe('document');
+
+    const heading = doc.children[0] as MarkdownHeading;
+    expect(heading.type).toBe('heading');
+    expect(heading.depth).toBe(2);
+    expect((heading.children[0] as MarkdownText).value).toBe('My Title');
+
+    const list = doc.children[1] as MarkdownList;
+    expect(list.type).toBe('list');
+    expect(list.children).toHaveLength(2);
+    const firstItemPara = list.children[0]!.children[0] as MarkdownParagraph;
+    expect((firstItemPara.children[0] as MarkdownText).value).toBe('First bullet');
+  });
+});

package/src/__tests__/roundTripMatrix.fixtures.ts

@@ -0,0 +1,86 @@
+import { parseMarkdown, type MarkdownDocument } from '@bendyline/squisq/markdown';
+
+export interface RoundTripFixture {
+  name: string;
+  markdown: string;
+  doc: MarkdownDocument;
+  keyPhrases: string[];
+  headingTexts: string[];
+}
+
+function makeFixture(
+  name: string,
+  markdown: string,
+  keyPhrases: string[],
+  headingTexts: string[],
+): RoundTripFixture {
+  return {
+    name,
+    markdown,
+    doc: parseMarkdown(markdown),
+    keyPhrases,
+    headingTexts,
+  };
+}
+
+export const ROUNDTRIP_FIXTURES = {
+  story: makeFixture(
+    'story',
+    `# River Journal
+
+The field team walked the north bank and recorded water conditions.
+
+## Morning Snapshot
+
+- Water level is steady.
+- Team status is ready.
+- Safety checks are complete.
+
+## Notes
+
+The crew published an update and linked the [full report](https://example.com/report).
+`,
+    ['river journal', 'north bank', 'water level', 'team status', 'full report'],
+    ['River Journal', 'Morning Snapshot', 'Notes'],
+  ),
+
+  mixed: makeFixture(
+    'mixed',
+    `# Ops Weekly
+
+This week we tracked **launch readiness**, *quality signals*, and risk burn-down.
+
+## Checklist
+
+1. Confirm deployment window.
+2. Validate rollback script.
+3. Notify stakeholders.
+
+## Outcome
+
+Launch readiness improved and support tickets declined.
+`,
+    [
+      'ops weekly',
+      'launch readiness',
+      'quality signals',
+      'rollback script',
+      'support tickets declined',
+    ],
+    ['Ops Weekly', 'Checklist', 'Outcome'],
+  ),
+
+  table: makeFixture(
+    'table',
+    `# Metrics
+
+| Metric | Value |
+| --- | --- |
+| Throughput | 120 req/s |
+| Error Rate | 0.2% |
+| P95 | 180ms |
+`,
+    ['metrics', 'throughput', '120 req/s', 'error rate', 'p95'],
+    ['Metrics'],
+  ),
+};

package/src/__tests__/roundTripMatrix.helpers.ts

@@ -0,0 +1,154 @@
+import { expect } from 'vitest';
+import type {
+  MarkdownDocument,
+  MarkdownNode,
+  MarkdownBlockNode,
+  MarkdownHeading,
+} from '@bendyline/squisq/markdown';
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null;
+}
+
+function collectText(node: unknown, out: string[]): void {
+  if (!isRecord(node)) return;
+
+  const maybeType = node.type;
+  if (typeof maybeType === 'string') {
+    if (maybeType === 'text' && typeof node.value === 'string') {
+      out.push(node.value);
+    }
+    if ((maybeType === 'code' || maybeType === 'inlineCode') && typeof node.value === 'string') {
+      out.push(node.value);
+    }
+    if (maybeType === 'link' && typeof node.url === 'string') {
+      out.push(node.url);
+    }
+    if (maybeType === 'image') {
+      if (typeof node.alt === 'string') out.push(node.alt);
+      if (typeof node.url === 'string') out.push(node.url);
+    }
+  }
+
+  const children = node.children;
+  if (Array.isArray(children)) {
+    for (const child of children) collectText(child, out);
+  }
+}
+
+function normalizeText(input: string): string {
+  return input
+    .toLowerCase()
+    .replace(/\r\n/g, '\n')
+    .replace(/[^a-z0-9%/.:\-\s]+/g, ' ')
+    .replace(/\s+/g, ' ')
+    .trim();
+}
+
+function compactText(input: string): string {
+  return normalizeText(input).replace(/\s+/g, '');
+}
+
+function extractDocumentText(doc: MarkdownDocument): string {
+  const out: string[] = [];
+  collectText(doc, out);
+  return normalizeText(out.join(' '));
+}
+
+function extractHeadingTexts(doc: MarkdownDocument): string[] {
+  return doc.children
+    .filter((block): block is MarkdownHeading => block.type === 'heading')
+    .map((heading) => {
+      const out: string[] = [];
+      collectText(heading, out);
+      return normalizeText(out.join(' '));
+    })
+    .filter(Boolean);
+}
+
+function containsNodeType(node: unknown, wantedType: string): boolean {
+  if (!isRecord(node)) return false;
+  if (node.type === wantedType) return true;
+  const children = node.children;
+  if (!Array.isArray(children)) return false;
+  return children.some((child) => containsNodeType(child, wantedType));
+}
+
+function retainRatio(source: string, roundTrip: string): number {
+  const sourceTokens = source.split(' ').filter((t) => t.length >= 4);
+  if (sourceTokens.length === 0) return 1;
+
+  const targetSet = new Set(roundTrip.split(' ').filter((t) => t.length >= 4));
+  let matched = 0;
+  for (const token of sourceTokens) {
+    if (targetSet.has(token)) matched++;
+  }
+  return matched / sourceTokens.length;
+}
+
+export interface HybridRoundTripAssertions {
+  source: MarkdownDocument;
+  roundTrip: MarkdownDocument;
+  keyPhrases: string[];
+  headingTexts?: string[];
+  requireHeadingOrder?: boolean;
+  requireListSurvival?: boolean;
+  requireTableSurvival?: boolean;
+  minRetainRatio?: number;
+}
+
+export function assertHybridRoundTrip(args: HybridRoundTripAssertions): void {
+  const sourceText = extractDocumentText(args.source);
+  const roundTripText = extractDocumentText(args.roundTrip);
+
+  expect(roundTripText.length).toBeGreaterThan(0);
+
+  const minRetainRatio = args.minRetainRatio ?? 0.5;
+  expect(retainRatio(sourceText, roundTripText)).toBeGreaterThanOrEqual(minRetainRatio);
+
+  for (const phrase of args.keyPhrases) {
+    const normalizedPhrase = normalizeText(phrase);
+    if (roundTripText.includes(normalizedPhrase)) continue;
+    expect(compactText(roundTripText)).toContain(compactText(normalizedPhrase));
+  }
+
+  if (args.requireHeadingOrder && args.headingTexts && args.headingTexts.length > 0) {
+    const normalizedExpected = args.headingTexts.map((h) => normalizeText(h));
+    const actualHeadings = extractHeadingTexts(args.roundTrip);
+
+    let cursor = -1;
+    for (const expectedHeading of normalizedExpected) {
+      const next = actualHeadings.findIndex(
+        (heading, index) => index > cursor && heading.includes(expectedHeading),
+      );
+      expect(next).toBeGreaterThan(cursor);
+      cursor = next;
+    }
+  }
+
+  if (args.requireListSurvival && containsNodeType(args.source, 'list')) {
+    expect(containsNodeType(args.roundTrip, 'list')).toBe(true);
+  }
+
+  if (args.requireTableSurvival && containsNodeType(args.source, 'table')) {
+    expect(containsNodeType(args.roundTrip, 'table')).toBe(true);
+  }
+}
+
+export function extractNormalizedText(doc: MarkdownDocument): string {
+  return extractDocumentText(doc);
+}
+
+export function docHasNodeType(doc: MarkdownDocument, wantedType: MarkdownNode['type']): boolean {
+  return containsNodeType(doc, wantedType);
+}
+
+export function firstHeadingText(doc: MarkdownDocument): string | null {
+  const firstHeading = doc.children.find(
+    (block): block is MarkdownBlockNode & { type: 'heading' } => block.type === 'heading',
+  );
+  if (!firstHeading) return null;
+  const out: string[] = [];
+  collectText(firstHeading, out);
+  return normalizeText(out.join(' '));
+}