@bendyline/squisq-formats 1.4.0 → 1.4.2

package/src/pdf/import.ts

@@ -44,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,
@@ -160,30 +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 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,
+      );
     }
   }
 

package/src/pptx/import.ts

@@ -12,20 +12,42 @@
 import type {
   MarkdownBlockNode,
   MarkdownDocument,
+  MarkdownImage,
   MarkdownListItem,
   MarkdownTable,
   MarkdownTableCell,
   MarkdownTableRow,
 } from '@bendyline/squisq/markdown';
-import { getPartRelationships, getPartXml, openPackage } from '../ooxml/reader.js';
+import { stringifyMarkdown } from '@bendyline/squisq/markdown';
+import { getPartBinary, getPartRelationships, getPartXml, openPackage } from '../ooxml/reader.js';
 import type { OoxmlPackage } from '../ooxml/types.js';
 import { NS_DRAWINGML, NS_PML, NS_R } from '../ooxml/namespaces.js';
+import type { ContentContainer } from '@bendyline/squisq/storage';
+import { buildContainer } from '../shared/container.js';
+import { extToMime } from '../shared/images.js';
 
 export interface PptxImportOptions {
-  /** Whether to extract embedded images as data URIs (not yet used). */
+  /**
+   * Whether to extract embedded slide images into the document as image nodes
+   * (referencing `images/imageN.ext`). When false, pictures are ignored so the
+   * markdown never carries dangling image references with no backing container.
+   * `pptxToContainer` forces this on. Default: false.
+   */
   extractImages?: boolean;
 }
 
+/**
+ * Per-import mutable state used to collect embedded images across slides.
+ * Mirrors the docx import context's `extractedImages` / `imageCounter`.
+ */
+interface ImportContext {
+  pkg: OoxmlPackage;
+  extractImages: boolean;
+  /** Collected image files: `images/imageN.ext` → { data, mimeType } */
+  extractedImages: Map<string, { data: ArrayBuffer; mimeType: string }>;
+  imageCounter: number;
+}
+
 function attrNS(el: Element, ns: string, local: string, fallback: string): string | null {
   return el.getAttributeNS(ns, local) ?? el.getAttribute(fallback);
 }
@@ -92,11 +114,66 @@ function tableToMarkdown(tbl: Element): MarkdownTable {
   return { type: 'table', children: rows };
 }
 
+/** Directory portion of a part path, e.g. `ppt/slides/slide1.xml` → `ppt/slides`. */
+function baseDirOf(path: string): string {
+  const slash = path.lastIndexOf('/');
+  return slash === -1 ? '' : path.slice(0, slash);
+}
+
+/**
+ * Extract every `<p:pic>` picture in a slide as an image node, reading the
+ * `<a:blip r:embed>` relationship, resolving it to the media part, and copying
+ * the bytes into `ctx.extractedImages` under `images/imageN.ext`.
+ */
+async function extractSlideImages(
+  doc: Document,
+  slidePath: string,
+  ctx: ImportContext,
+): Promise<MarkdownImage[]> {
+  const rels = await getPartRelationships(ctx.pkg, slidePath);
+  const relById = new Map(rels.map((r) => [r.id, r.target]));
+  const baseDir = baseDirOf(slidePath);
+
+  const images: MarkdownImage[] = [];
+  const pics = doc.getElementsByTagNameNS(NS_PML, 'pic');
+  for (let i = 0; i < pics.length; i++) {
+    const pic = pics[i]!;
+    const blips = pic.getElementsByTagNameNS(NS_DRAWINGML, 'blip');
+    if (!blips.length) continue;
+    const embed = attrNS(blips[0]!, NS_R, 'embed', 'r:embed');
+    if (!embed) continue;
+    const target = relById.get(embed);
+    if (!target) continue;
+
+    const mediaPath = resolveTarget(baseDir, target);
+    const data = await getPartBinary(ctx.pkg, mediaPath);
+    if (!data) continue;
+
+    const dot = mediaPath.lastIndexOf('.');
+    const ext = dot !== -1 ? mediaPath.slice(dot).toLowerCase() : '.png';
+    const mimeType = extToMime(ext);
+
+    ctx.imageCounter++;
+    const imagePath = `images/image${ctx.imageCounter}${ext}`;
+    ctx.extractedImages.set(imagePath, { data, mimeType });
+
+    // Alt text from the picture's non-visual properties (descr, then name).
+    const cNvPrs = pic.getElementsByTagNameNS(NS_PML, 'cNvPr');
+    const alt =
+      (cNvPrs.length ? cNvPrs[0]!.getAttribute('descr') || cNvPrs[0]!.getAttribute('name') : '') ||
+      'Image';
+
+    images.push({ type: 'image', url: imagePath, alt });
+  }
+  return images;
+}
+
 async function convertSlide(
-  pkg: OoxmlPackage,
   path: string,
   index: number,
+  ctx: ImportContext,
 ): Promise<MarkdownBlockNode[]> {
+  const pkg = ctx.pkg;
   const doc = await getPartXml(pkg, path);
   if (!doc) return [];
   const out: MarkdownBlockNode[] = [];
@@ -136,21 +213,61 @@ async function convertSlide(
     out.push({ type: 'list', ordered: false, children: items });
   }
 
+  // Embedded pictures land after the bullet list and before any tables.
+  if (ctx.extractImages) {
+    const images = await extractSlideImages(doc, path, ctx);
+    for (const image of images) {
+      out.push({ type: 'paragraph', children: [image] });
+    }
+  }
+
   const tbls = doc.getElementsByTagNameNS(NS_DRAWINGML, 'tbl');
   for (let t = 0; t < tbls.length; t++) out.push(tableToMarkdown(tbls[t]!));
 
   return out;
 }
 
-export async function pptxToMarkdownDoc(
-  data: ArrayBuffer | Blob,
-  _options: PptxImportOptions = {},
-): Promise<MarkdownDocument> {
-  const pkg = await openPackage(data);
+async function importDocument(
+  pkg: OoxmlPackage,
+  options: PptxImportOptions,
+): Promise<{ doc: MarkdownDocument; ctx: ImportContext }> {
+  const ctx: ImportContext = {
+    pkg,
+    extractImages: options.extractImages ?? false,
+    extractedImages: new Map(),
+    imageCounter: 0,
+  };
   const paths = await orderedSlidePaths(pkg);
   const children: MarkdownBlockNode[] = [];
   for (let i = 0; i < paths.length; i++) {
-    children.push(...(await convertSlide(pkg, paths[i]!, i)));
+    children.push(...(await convertSlide(paths[i]!, i, ctx)));
   }
-  return { type: 'document', children };
+  return { doc: { type: 'document', children }, ctx };
+}
+
+export async function pptxToMarkdownDoc(
+  data: ArrayBuffer | Blob,
+  options: PptxImportOptions = {},
+): Promise<MarkdownDocument> {
+  const pkg = await openPackage(data);
+  const { doc } = await importDocument(pkg, options);
+  return doc;
+}
+
+/**
+ * Convert a .pptx file to a ContentContainer with markdown + extracted images.
+ *
+ * The container holds the primary markdown document plus every embedded slide
+ * image under `images/` (e.g. `images/image1.png`). Image extraction is always
+ * forced on here so the markdown's image references resolve inside the
+ * container. Mirrors `docxToContainer`.
+ */
+export async function pptxToContainer(
+  data: ArrayBuffer | Blob,
+  options: PptxImportOptions = {},
+): Promise<ContentContainer> {
+  const pkg = await openPackage(data);
+  const { doc, ctx } = await importDocument(pkg, { ...options, extractImages: true });
+
+  return buildContainer(stringifyMarkdown(doc), ctx.extractedImages);
 }

package/src/pptx/index.ts

@@ -25,7 +25,7 @@ import type { Doc } from '@bendyline/squisq/schemas';
 import { type PptxImportOptions, pptxToMarkdownDoc } from './import.js';
 
 export type { PptxImportOptions } from './import.js';
-export { pptxToMarkdownDoc } from './import.js';
+export { pptxToMarkdownDoc, pptxToContainer } from './import.js';
 
 /**
  * Convert a .pptx file to a squisq Doc (via the markdown model).