Where file import plugs in: Each format parser produces HMBlockNode[], then the existing flattenToOperations() converts those into DocumentOperation[] (ReplaceBlock + MoveBlocks ops). From there, the standard signing and publishing flow takes over — no changes needed downstream.

For updates (document update --replace-body), the CLI already has matchBlockIds() and computeReplaceOps() in block-diff.ts that diff old vs new block trees and emit minimal operations. File import can use the same path.

• npm: mammoth

• Bundle size: ~160 KB gzipped

• Browser support: Yes

• Structural quality: Excellent

• Converts .docx to clean semantic HTML. Maps Word styles to HTML elements:

• | Word Style | HTML Output | |-----------|-------------| | Heading 1 | <h1> | | Heading 2 | <h2> | | Bold | <strong> | | Italic | <em> | | Lists | <ol> / <ul> | | Tables | <table> | | Images | <img> (base64) |

• Custom style mappings are supported.

• Repo: https://github.com/mwilliamson/mammoth.js

• SDK Integration

  Two possible conversion paths:

  Path A — mammoth → HTML → BlockNote's HTML-to-blocks

  BlockNote (used in packages/editor) already has tryParseHTMLToBlocks() which converts HTML into its internal block model. From there, the existing editor-to-HMBlockNode conversion can be reused. This path gets the richest output with minimal new code but couples the import to the editor package.

  Path B — mammoth → HTML → custom HMBlockNode[] mapper

  Write a standalone HTML-to-HMBlockNode converter. Walk the DOM tree and map:

  • <h1>–<h6> → {type: 'Heading', text, annotations} with heading-level nesting

  • <p> → {type: 'Paragraph', text, annotations}

  • <strong>, <em>, <code>, <a> → annotation spans with starts/ends character positions

  • <ul> / <ol> → Paragraph blocks with childrenType: 'Unordered' | 'Ordered'

  • <table> → Code block (current CLI behavior) or future Table block type

  • <img> → extract base64 data, upload via blob storage, create {type: 'Image', link: ipfsUrl}

  Then call flattenToOperations(blocks) and feed into the standard document create or document update flow.

  Image handling note: mammoth extracts images as base64 <img> tags. These need to be uploaded to blob storage (UnixFS chunking, ~256KB chunks, via storeBlobs with 4MB message limit) and replaced with IPFS CID links before creating the Image blocks.

  CLI usage would look like:

  seed-cli document create z6Mk... --title "Imported Doc" --docx report.docx --key main
  seed-cli document update hm://z6Mk.../doc --replace-docx updated.docx --key main
  

• Alternative: officeparser

  • npm: officeparser

  • Produces a hierarchical AST (paragraphs, headings, tables, lists, bold/italic)

  • Also handles .pptx, .xlsx, .odt, .pdf, .rtf

  • Newer and less battle-tested than mammoth

• npm: pdfjs-dist

• Bundle size: ~400–800 KB gzipped (heavy)

• Browser support: Yes (this is Firefox's PDF engine)

• Structural quality: Low — PDFs have no semantic structure

• Extracts text items with position coordinates (x, y), font info, and text content per page via page.getTextContent(). Does not natively give you headings, paragraphs, or tables — you must reconstruct structure from:

  • Headings: larger font size

  • Paragraphs: spatial proximity grouping

  • Tables: grid-aligned text detection

  • Images: separate rendering pass

• Repo: https://github.com/mozilla/pdf.js

• SDK Integration

  PDF is the hardest format because pdfjs-dist returns positioned text items, not semantic blocks. A heuristic layer is needed between the parser and HMBlockNode[].

  Conversion flow:

  .pdf → pdfjs getTextContent() → TextItem[] with {str, transform, fontName, ...}
    → heuristic grouping:
        1. Group text items into lines (same Y coordinate within tolerance)
        2. Group lines into paragraphs (vertical gap < threshold)
        3. Detect headings (font size > body font size)
        4. Detect lists (lines starting with "•", "-", "1.")
    → HMBlockNode[] (mostly Paragraph + Heading blocks)
    → flattenToOperations(blocks)
    → standard signing/publish flow
  

  What maps cleanly to HMBlockNode:

  • Large-font text → {type: 'Heading', text} with annotations

  • Body text groups → {type: 'Paragraph', text} with bold/italic from font metadata

  • Bullet/numbered patterns → Paragraph with childrenType: 'Unordered' | 'Ordered'

  What doesn't map well:

  • Multi-column layouts (text items interleave columns)

  • Tables (must detect grid alignment — complex heuristic)

  • Images (requires separate canvas rendering per page, then blob upload)

  • Headers/footers (appear as regular text items)

  • Mathematical formulas (not extractable as LaTeX)

  The existing parseInlineFormatting() in markdown.ts builds annotation spans from character positions. The same pattern applies here — as you concatenate text items into a paragraph string, track font changes to create Bold/Italic annotations with correct starts/ends offsets.

  CLI usage would look like:

  seed-cli document create z6Mk... --title "Research Paper" --pdf paper.pdf --key main
  # Best-effort text extraction with heuristic heading detection
  

  Practical recommendation: Offer this as a "basic text import" rather than promising structural fidelity. The --verbose flag could show warnings about low-confidence heading detection or skipped elements.

• Alternative: unpdf

  • npm: unpdf

  • Bundle size: ~390 KB gzipped

  • Cleaner async/await API wrapper around pdf.js

  • Methods: extractText, extractLinks, getMeta

  • Repo: https://github.com/unjs/unpdf

  • SDK note: extractText returns plain string per page — simpler but loses all font/position metadata needed for heading detection. Only viable for plain-text-only import.