@bendyline/squisq-formats 1.3.1 → 1.4.1

package/src/index.ts

@@ -7,11 +7,15 @@
  * Supported formats:
  * - **DOCX** — Microsoft Word (import + export) ✅
  * - **PDF**  — Portable Document Format (import + export) ✅
- * - **PPTX** — Microsoft PowerPoint (export ✅, import planned)
- * - **XLSX** — Microsoft Excel (planned)
+ * - **PPTX** — Microsoft PowerPoint (import + export ✅; import extracts slide-level embedded images)
+ * - **XLSX** — Microsoft Excel (import ✅, export ✅ tables-only)
+ * - **CSV**  — Comma-separated values (import ✅, export ✅)
+ * - **HTML** — import + export (single-file, ZIP, plain, and player-embedding)
+ * - **EPUB** — export ✅
  *
  * All converters run in the browser — no server or native binaries required.
- * The shared `ooxml/` subpath export provides reusable OOXML infrastructure.
+ * The shared `ooxml/` subpath export provides reusable OOXML infrastructure, and the
+ * `registry` subpath exposes a format registry + `convert()` pipeline over all of the above.
  *
  * @example
  * ```ts
@@ -28,14 +32,18 @@
 export { markdownDocToDocx, docToDocx, docxToMarkdownDoc, docxToDoc } from './docx/index.js';
 export type { DocxExportOptions, DocxImportOptions } from './docx/index.js';
 
-// PPTX (export implemented, import stub)
+// PPTX (import + export)
 export { markdownDocToPptx, docToPptx, pptxToMarkdownDoc, pptxToDoc } from './pptx/index.js';
 export type { PptxExportOptions, PptxImportOptions } from './pptx/index.js';
 
-// XLSX (stub)
+// XLSX (import + export; export is tables-only → one worksheet per markdown table)
 export { markdownDocToXlsx, docToXlsx, xlsxToMarkdownDoc, xlsxToDoc } from './xlsx/index.js';
 export type { XlsxExportOptions, XlsxImportOptions } from './xlsx/index.js';
 
+// CSV (import + export)
+export { csvToMarkdownDoc, csvToDoc, markdownDocToCsv, parseCsv } from './csv/index.js';
+export type { CsvImportOptions, CsvExportOptions } from './csv/index.js';
+
 // PDF (fully implemented)
 export {
   markdownDocToPdf,
@@ -49,7 +57,30 @@ export type { PdfExportOptions, PdfImportOptions } from './pdf/index.js';
 // HTML (fully implemented)
 export { docToHtml, docToHtmlZip, collectImagePaths } from './html/index.js';
 export type { HtmlExportOptions, HtmlZipExportOptions } from './html/index.js';
+export { htmlToMarkdown, htmlToMarkdownDoc, htmlToMarkdownDocSync } from './html/index.js';
+export type { HtmlImportOptions } from './html/index.js';
 
 // EPUB (export)
 export { markdownDocToEpub, docToEpub } from './epub/index.js';
 export type { EpubExportOptions } from './epub/index.js';
+
+// Format registry + programmatic convert()
+export {
+  convert,
+  createRegistry,
+  defaultRegistry,
+  defaultFormats,
+  ConversionError,
+  BUILTIN_FORMAT_IDS,
+} from './registry/index.js';
+export type {
+  FormatId,
+  ConversionResult,
+  NormalizedInput,
+  ConvertOptions,
+  FormatDefinition,
+  FormatRegistry,
+  ConvertSource,
+  ConversionErrorCode,
+  ConversionErrorOptions,
+} from './registry/index.js';

package/src/ooxml/index.ts

@@ -91,4 +91,7 @@ export {
   REL_SLIDE_LAYOUT,
   REL_SLIDE_MASTER,
   CONTENT_TYPE_XLSX_WORKBOOK,
+  CONTENT_TYPE_XLSX_WORKSHEET,
+  CONTENT_TYPE_XLSX_STYLES,
+  REL_WORKSHEET,
 } from './namespaces.js';

package/src/ooxml/namespaces.ts

@@ -77,6 +77,9 @@ export const NS_WML = 'http://schemas.openxmlformats.org/wordprocessingml/2006/m
 /** PresentationML main namespace (p:) */
 export const NS_PML = 'http://schemas.openxmlformats.org/presentationml/2006/main';
 
+/** PowerPoint 2010 extension namespace (p14:) */
+export const NS_PML_2010 = 'http://schemas.microsoft.com/office/powerpoint/2010/main';
+
 // ============================================
 // SpreadsheetML (XLSX)
 // ============================================
@@ -181,3 +184,13 @@ export const REL_SLIDE_MASTER =
 
 export const CONTENT_TYPE_XLSX_WORKBOOK =
   'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet.main+xml';
+
+export const CONTENT_TYPE_XLSX_WORKSHEET =
+  'application/vnd.openxmlformats-officedocument.spreadsheetml.worksheet+xml';
+
+export const CONTENT_TYPE_XLSX_STYLES =
+  'application/vnd.openxmlformats-officedocument.spreadsheetml.styles+xml';
+
+/** Relationship type: Worksheet */
+export const REL_WORKSHEET =
+  'http://schemas.openxmlformats.org/officeDocument/2006/relationships/worksheet';

package/src/pdf/export.ts

@@ -22,8 +22,7 @@
 import { PDFDocument, StandardFonts, rgb, PDFFont, PDFPage } from 'pdf-lib';
 
 import type { Doc } from '@bendyline/squisq/schemas';
-import { resolveTheme } from '@bendyline/squisq/schemas';
-import { docToMarkdown } from '@bendyline/squisq/doc';
+import { docToMarkdown, resolveThemeForDoc } from '@bendyline/squisq/doc';
 import type {
   MarkdownDocument,
   MarkdownBlockNode,
@@ -51,6 +50,7 @@ import type {
   MarkdownInlineMath,
   MarkdownFootnoteReference,
 } from '@bendyline/squisq/markdown';
+import { readFrontmatterThemeId } from '@bendyline/squisq/markdown';
 
 import {
   PAGE_WIDTH_LETTER,
@@ -127,7 +127,7 @@ export async function markdownDocToPdf(
   pdfDoc.setCreationDate(new Date());
   pdfDoc.setModificationDate(new Date());
 
-  const ctx = await createExportContext(pdfDoc, options);
+  const ctx = await createExportContext(pdfDoc, options, doc);
 
   renderBlocks(doc.children, ctx, 0);
 
@@ -190,6 +190,7 @@ interface ExportContext {
 async function createExportContext(
   pdfDoc: PDFDocument,
   options: PdfExportOptions,
+  doc: MarkdownDocument,
 ): Promise<ExportContext> {
   const [regular, bold, italic, boldItalic, mono, monoBold] = await Promise.all([
     pdfDoc.embedFont(StandardFonts.Helvetica),
@@ -213,8 +214,12 @@ async function createExportContext(
   let colorHeading = COLOR_HEADING;
   let colorLink = COLOR_LINK;
 
-  if (options.themeId) {
-    const theme = resolveTheme(options.themeId);
+  // Honor an explicit themeId, else the doc's frontmatter theme (`squisq-theme`
+  // / legacy) — mirroring PPTX/DOCX/HTML so every format themes consistently,
+  // including inline custom themes (resolved doc-scoped).
+  const themeId = options.themeId ?? readFrontmatterThemeId(doc.frontmatter);
+  if (themeId) {
+    const theme = resolveThemeForDoc(doc, themeId);
     if (theme.colors) {
       colorText = hexToRgb(theme.colors.text) ?? COLOR_TEXT;
       colorHeading = hexToRgb(theme.colors.primary) ?? COLOR_HEADING;

package/src/pdf/import.ts

@@ -22,6 +22,7 @@
 
 import type { Doc } from '@bendyline/squisq/schemas';
 import { markdownToDoc } from '@bendyline/squisq/doc';
+import { stringifyMarkdown } from '@bendyline/squisq/markdown';
 import type {
   MarkdownDocument,
   MarkdownBlockNode,
@@ -43,8 +44,8 @@ import type {
   MarkdownImage,
 } from '@bendyline/squisq/markdown';
 
-import { MemoryContentContainer } from '@bendyline/squisq/storage';
 import type { ContentContainer } from '@bendyline/squisq/storage';
+import { buildContainer } from '../shared/container.js';
 
 import {
   DEFAULT_FONT_SIZE,
@@ -159,31 +160,44 @@ export async function pdfToContainer(
   const textLines = await extractTextLines(bytes);
   const images = await extractImages(bytes);
 
+  // Under Node there is no DOM/canvas, so extractImages() returns [] via its
+  // environment guard and embedded images can't be decoded. The registry's
+  // `importContainer` wrapper surfaces this (typeof document === 'undefined')
+  // as a ConversionResult warning; direct callers of pdfToContainer get no
+  // signal, which is an accepted trade-off for the degraded Node path.
+
   const bodySize = options.bodyFontSize ?? detectBodyFontSize(textLines);
 
-  // If we have images, insert image references into the block list
-  let blocks = classifyLines(textLines, bodySize, options);
+  // Classify text into blocks, capturing the originating page of each block
+  // (parallel array) so images can be placed on their own page rather than
+  // dumped at the document end.
+  const blockPages: number[] = [];
+  let blocks = classifyLines(textLines, bodySize, options, blockPages);
   if (images.length > 0) {
-    blocks = insertImageBlocks(blocks, images);
+    blocks = insertImageBlocks(blocks, blockPages, images);
   }
 
   const markdownDoc: MarkdownDocument = { type: 'document', children: blocks };
 
-  const { stringifyMarkdown } = await import('@bendyline/squisq/markdown');
-  const markdown = stringifyMarkdown(markdownDoc);
-
-  const container = new MemoryContentContainer();
-  await container.writeDocument(markdown);
-
-  for (const img of images) {
-    await container.writeFile(img.path, new Uint8Array(img.data), 'image/png');
-  }
-
-  return container;
+  // pdf image extraction only ever produces PNG (canvas re-encode), so every
+  // entry gets image/png.
+  return buildContainer(
+    stringifyMarkdown(markdownDoc),
+    images.map((img) => [img.path, { data: img.data, mimeType: 'image/png' }] as const),
+  );
 }
 
-/** Extracted image with position info for placement. */
-interface ExtractedImage {
+/**
+ * Extracted image with position info for placement.
+ *
+ * `page` is captured reliably from the operator-list walk. `y` is currently
+ * always 0 — recovering a real y within the page would require tracking the
+ * current transformation matrix (CTM) during the paint operator, which is out
+ * of scope here (see the placement note in `insertImageBlocks`).
+ *
+ * Exported for direct unit testing of `insertImageBlocks`.
+ */
+export interface ExtractedImage {
   path: string;
   data: ArrayBuffer;
   page: number;
@@ -328,29 +342,86 @@ function imageDataToPng(img: PdfjsImageData): ArrayBuffer | null {
   }
 }
 
+/** Wrap an extracted image as a paragraph containing an image node. */
+function imageParagraph(img: ExtractedImage): MarkdownParagraph {
+  const imgNode: MarkdownImage = {
+    type: 'image',
+    url: img.path,
+    alt: `Image ${img.path.replace('images/image', '').replace('.png', '')}`,
+  };
+  return { type: 'paragraph', children: [imgNode] };
+}
+
 /**
- * Insert image reference blocks between text blocks.
- * Places each image after the last text block on the same page (or at the end).
+ * Insert image reference blocks among the text blocks, page by page.
+ *
+ * Each image is placed immediately after the LAST content block that
+ * originated from the same page (per the parallel `blockPages` array).
+ * Images on a page that produced no text blocks (e.g. an image-only page)
+ * fall back to the last block of the nearest preceding page that did; if no
+ * such page exists, they are appended at the document end.
+ *
+ * Placement is intentionally page-level only. Ordering *within* a page follows
+ * the extraction order of the images (roughly the paint-operator order) — real
+ * vertical (y) ordering within a page is future work, since `ExtractedImage.y`
+ * is not yet populated (it needs CTM tracking during the paint operator).
+ *
+ * @param blocks - The classified content blocks, in document order.
+ * @param blockPages - Parallel array: `blockPages[i]` is the 0-based page that
+ *   `blocks[i]` came from. Must be the same length as `blocks`.
+ * @param images - Extracted images with a reliable `page` field.
  */
-function insertImageBlocks(
+export function insertImageBlocks(
   blocks: MarkdownBlockNode[],
+  blockPages: number[],
   images: ExtractedImage[],
 ): MarkdownBlockNode[] {
   if (images.length === 0) return blocks;
 
-  // Simple strategy: append all images at the end as paragraphs
-  const result = [...blocks];
+  // No text blocks at all → every image simply appends in order.
+  if (blocks.length === 0) {
+    return images.map(imageParagraph);
+  }
+
+  // Map each page → index of its LAST block, and remember which pages have
+  // blocks (sorted ascending) for the image-only-page fallback lookup.
+  const lastBlockIndexByPage = new Map<number, number>();
+  for (let i = 0; i < blocks.length; i++) {
+    lastBlockIndexByPage.set(blockPages[i], i);
+  }
+  const pagesWithBlocks = [...lastBlockIndexByPage.keys()].sort((a, b) => a - b);
+
+  const lastIndex = blocks.length - 1;
+
+  /** Resolve the block index after which an image on `page` should be inserted. */
+  const anchorFor = (page: number): number => {
+    const direct = lastBlockIndexByPage.get(page);
+    if (direct !== undefined) return direct;
+    // Image-only page: fall back to the nearest preceding page with blocks.
+    let anchor = -1;
+    for (const p of pagesWithBlocks) {
+      if (p < page) anchor = lastBlockIndexByPage.get(p)!;
+      else break;
+    }
+    // No preceding page with blocks → append at the document end.
+    return anchor === -1 ? lastIndex : anchor;
+  };
+
+  // Group image paragraphs by the block index they should follow, preserving
+  // image order within each group.
+  const insertAfter = new Map<number, MarkdownParagraph[]>();
   for (const img of images) {
-    const imgNode: MarkdownImage = {
-      type: 'image',
-      url: img.path,
-      alt: `Image ${img.path.replace('images/image', '').replace('.png', '')}`,
-    };
-    const para: MarkdownParagraph = {
-      type: 'paragraph',
-      children: [imgNode],
-    };
-    result.push(para);
+    const anchor = anchorFor(img.page);
+    const group = insertAfter.get(anchor);
+    if (group) group.push(imageParagraph(img));
+    else insertAfter.set(anchor, [imageParagraph(img)]);
+  }
+
+  const result: MarkdownBlockNode[] = [];
+  for (let i = 0; i < blocks.length; i++) {
+    result.push(blocks[i]);
+    const imgs = insertAfter.get(i);
+    if (imgs) result.push(...imgs);
   }
   return result;
 }
@@ -592,8 +663,20 @@ function classifyLines(
   lines: TextLine[],
   bodySize: number,
   options: PdfImportOptions,
+  /**
+   * Optional out-parameter: when provided, receives one entry per produced
+   * block giving the 0-based page that block originated from. Kept parallel
+   * to the returned block array so image placement can be page-aware without
+   * mutating the (strictly-typed) block nodes themselves.
+   */
+  blockPages?: number[],
 ): MarkdownBlockNode[] {
   const blocks: MarkdownBlockNode[] = [];
+  /** Push a block and record its originating page in the parallel array. */
+  const pushBlock = (block: MarkdownBlockNode, page: number): void => {
+    blocks.push(block);
+    if (blockPages) blockPages.push(page);
+  };
   const detectTables = options.detectTables !== false;
   const detectCodeBlocks = options.detectCodeBlocks !== false;
   const detectBlockquotes = options.detectBlockquotes !== false;
@@ -610,11 +693,14 @@ function classifyLines(
     // --- Heading detection ---
     if (line.fontSize >= IMPORT_HEADING_MIN_SIZE && line.fontSize > bodySize + 1) {
       const depth = sizeToHeadingDepth(line.fontSize);
-      blocks.push({
-        type: 'heading',
-        depth,
-        children: buildInlineNodes(line, options),
-      } as MarkdownHeading);
+      pushBlock(
+        {
+          type: 'heading',
+          depth,
+          children: buildInlineNodes(line, options),
+        } as MarkdownHeading,
+        line.page,
+      );
       i++;
       continue;
     }
@@ -626,10 +712,13 @@ function classifyLines(
         codeLines.push(lines[i].text);
         i++;
       }
-      blocks.push({
-        type: 'code',
-        value: codeLines.join('\n'),
-      } as MarkdownCodeBlock);
+      pushBlock(
+        {
+          type: 'code',
+          value: codeLines.join('\n'),
+        } as MarkdownCodeBlock,
+        line.page,
+      );
       continue;
     }
 
@@ -639,7 +728,7 @@ function classifyLines(
       if (tableLines > 0) {
         const table = buildTable(lines.slice(i, i + tableLines), options);
         if (table) {
-          blocks.push(table);
+          pushBlock(table, line.page);
           i += tableLines;
           continue;
         }
@@ -651,7 +740,7 @@ function classifyLines(
     const orderedMatch = line.text.match(IMPORT_ORDERED_PREFIX);
     if (bulletMatch || orderedMatch) {
       const listResult = consumeList(lines, i, typicalLeftMargin, bodySize, options);
-      blocks.push(listResult.list);
+      pushBlock(listResult.list, line.page);
       i = listResult.nextIndex;
       continue;
     }
@@ -675,10 +764,13 @@ function classifyLines(
             children: buildInlineNodes(ql, options),
           }) as MarkdownParagraph,
       );
-      blocks.push({
-        type: 'blockquote',
-        children: quoteBlocks,
-      } as MarkdownBlockquote);
+      pushBlock(
+        {
+          type: 'blockquote',
+          children: quoteBlocks,
+        } as MarkdownBlockquote,
+        line.page,
+      );
       continue;
     }
 
@@ -721,10 +813,13 @@ function classifyLines(
     }
 
     if (allInlines.length > 0) {
-      blocks.push({
-        type: 'paragraph',
-        children: mergeAdjacentText(allInlines),
-      } as MarkdownParagraph);
+      pushBlock(
+        {
+          type: 'paragraph',
+          children: mergeAdjacentText(allInlines),
+        } as MarkdownParagraph,
+        line.page,
+      );
     }
   }