@bendyline/squisq-formats 1.3.1 → 1.4.1

package/src/registry/errors.ts

@@ -0,0 +1,46 @@
+/**
+ * Structured error for the format registry / `convert()` pipeline.
+ *
+ * Every failure path in the registry throws a `ConversionError` with a stable
+ * machine-readable `code`, so callers can branch on the failure kind rather
+ * than string-matching messages.
+ */
+
+import type { FormatId } from './types.js';
+
+/** Machine-readable failure kinds surfaced by the registry / `convert()`. */
+export type ConversionErrorCode =
+  | 'unknown-format'
+  | 'unsupported-input'
+  | 'unsupported-output'
+  | 'invalid-input'
+  | 'missing-dependency'
+  | 'conversion-failed';
+
+/** Options for constructing a {@link ConversionError}. */
+export interface ConversionErrorOptions {
+  /** The format id the error relates to, if any. */
+  format?: FormatId;
+  /** A human-oriented remediation hint. */
+  hint?: string;
+  /** The underlying error, preserved on `error.cause`. */
+  cause?: unknown;
+}
+
+/** An error raised by the format registry or `convert()`. */
+export class ConversionError extends Error {
+  readonly code: ConversionErrorCode;
+  readonly format?: FormatId;
+  readonly hint?: string;
+
+  constructor(code: ConversionErrorCode, message: string, opts: ConversionErrorOptions = {}) {
+    super(message);
+    this.name = 'ConversionError';
+    this.code = code;
+    this.format = opts.format;
+    this.hint = opts.hint;
+    if (opts.cause !== undefined) {
+      (this as Error & { cause?: unknown }).cause = opts.cause;
+    }
+  }
+}

package/src/registry/index.ts

@@ -0,0 +1,38 @@
+/**
+ * Format registry + programmatic `convert()` — @bendyline/squisq-formats/registry
+ *
+ * A small registry maps format ids (`md`, `docx`, `pdf`, `pptx`, `xlsx`, `csv`,
+ * `html`, `htmlzip`, `epub`, `dbk`) to `FormatDefinition`s that know how to
+ * import to / export from squisq's markdown + Doc model. `convert()` is the
+ * front door: give it a source and a target format id and it returns the
+ * encoded bytes plus a suggested filename.
+ *
+ * @example
+ * ```ts
+ * import { convert } from '@bendyline/squisq-formats/registry';
+ *
+ * const result = await convert(
+ *   { kind: 'markdown', markdown: '# Hello', baseName: 'greeting' },
+ *   'docx',
+ * );
+ * // result.bytes, result.mimeType, result.suggestedFilename ('greeting.docx')
+ * ```
+ */
+
+export type {
+  FormatId,
+  ConversionResult,
+  NormalizedInput,
+  ConvertOptions,
+  FormatDefinition,
+  FormatRegistry,
+  ConvertSource,
+} from './types.js';
+export { BUILTIN_FORMAT_IDS } from './types.js';
+
+export { ConversionError } from './errors.js';
+export type { ConversionErrorCode, ConversionErrorOptions } from './errors.js';
+
+export { createRegistry, defaultRegistry } from './registry.js';
+export { defaultFormats } from './defaultFormats.js';
+export { convert } from './convert.js';

package/src/registry/registry.ts

@@ -0,0 +1,48 @@
+/**
+ * Format registry implementation.
+ *
+ * `createRegistry()` returns an empty, mutable registry (last-write-wins by id);
+ * `defaultRegistry()` returns one preloaded with every built-in format.
+ */
+
+import type { FormatDefinition, FormatId, FormatRegistry } from './types.js';
+import { defaultFormats } from './defaultFormats.js';
+
+/** Normalize an extension to lowercase, without a leading dot. */
+function normalizeExt(ext: string): string {
+  return ext.replace(/^\.+/, '').toLowerCase();
+}
+
+/** Create an empty registry. Registering an existing id overwrites it. */
+export function createRegistry(): FormatRegistry {
+  const byId = new Map<FormatId, FormatDefinition>();
+
+  return {
+    register(def: FormatDefinition): void {
+      byId.set(def.id, def);
+    },
+    get(id: FormatId): FormatDefinition | undefined {
+      return byId.get(id);
+    },
+    byExtension(ext: string): FormatDefinition | undefined {
+      const target = normalizeExt(ext);
+      if (!target) return undefined;
+      for (const def of byId.values()) {
+        if (def.extensions.some((e) => normalizeExt(e) === target)) return def;
+      }
+      return undefined;
+    },
+    list(): FormatDefinition[] {
+      return [...byId.values()];
+    },
+  };
+}
+
+/** Create a registry preloaded with all built-in formats. */
+export function defaultRegistry(): FormatRegistry {
+  const registry = createRegistry();
+  for (const def of defaultFormats()) {
+    registry.register(def);
+  }
+  return registry;
+}

package/src/registry/types.ts

@@ -0,0 +1,107 @@
+/**
+ * Format registry — shared types.
+ *
+ * The registry is the programmatic heart of `convert()`: it maps a small set of
+ * format ids (`md`, `docx`, `pdf`, …) to `FormatDefinition`s, each of which
+ * knows how to import to / export from squisq's markdown + Doc model. Every
+ * converter module is loaded lazily via `import()` inside the definition
+ * methods, so pulling in the registry never eagerly bundles heavy converters.
+ */
+
+import type { Doc } from '@bendyline/squisq/schemas';
+import type { MarkdownDocument } from '@bendyline/squisq/markdown';
+import type { ContentContainer } from '@bendyline/squisq/storage';
+
+/** A format identifier (e.g. `'docx'`). Strings so hosts can register their own. */
+export type FormatId = string;
+
+/** The built-in formats the default registry ships with. */
+export const BUILTIN_FORMAT_IDS = [
+  'md',
+  'docx',
+  'pdf',
+  'pptx',
+  'xlsx',
+  'csv',
+  'html',
+  'htmlzip',
+  'epub',
+  'dbk',
+] as const;
+
+/** The bytes + metadata produced by a successful export. */
+export interface ConversionResult {
+  /** Encoded output bytes. */
+  bytes: Uint8Array;
+  /** MIME type of the output. */
+  mimeType: string;
+  /** A sensible download filename (`<baseName>.<ext>`). */
+  suggestedFilename: string;
+  /** Non-fatal notes accumulated during conversion (may be empty). */
+  warnings: string[];
+}
+
+/**
+ * A source normalized into every shape an exporter might need. `doc` is always
+ * present; `markdownDoc` is present when the source was markdown-shaped (an
+ * exporter that wants markdown but finds none derives it from `doc`).
+ */
+export interface NormalizedInput {
+  doc: Doc;
+  markdownDoc?: MarkdownDocument;
+  container: ContentContainer;
+  baseName: string;
+}
+
+/** Options threaded through `convert()` and into every format method. */
+export interface ConvertOptions {
+  /** Registry to resolve formats against. Defaults to `defaultRegistry()`. */
+  registry?: FormatRegistry;
+  /** Explicit source format id (skips extension/byte sniffing). */
+  from?: FormatId;
+  /** Theme id to apply to the exported document. */
+  themeId?: string;
+  /** Transform style id to apply before export. */
+  transformStyle?: string;
+  /** Content-aware auto-templating when deriving a Doc from markdown. */
+  autoTemplates?: boolean;
+  /** Title hint for exporters that support one (epub, html). */
+  title?: string;
+  /** Lazily resolve the standalone player IIFE bundle (required for HTML export). */
+  resolvePlayerScript?: () => Promise<string>;
+  /** Per-format escape hatch for extra options. */
+  formatOptions?: Record<FormatId, Record<string, unknown>>;
+}
+
+/** Describes how a single format imports to / exports from the squisq model. */
+export interface FormatDefinition {
+  id: FormatId;
+  label: string;
+  mimeType: string;
+  extensions: readonly string[];
+  /** Import raw bytes to a MarkdownDocument. */
+  importDoc?(data: ArrayBuffer, options: ConvertOptions): Promise<MarkdownDocument>;
+  /** Import raw bytes to a ContentContainer (markdown + extracted media). */
+  importContainer?(data: ArrayBuffer, options: ConvertOptions): Promise<ContentContainer>;
+  /** Export a normalized input to bytes. */
+  exportDoc?(input: NormalizedInput, options: ConvertOptions): Promise<ConversionResult>;
+}
+
+/** A mutable collection of format definitions keyed by id. */
+export interface FormatRegistry {
+  register(def: FormatDefinition): void;
+  get(id: FormatId): FormatDefinition | undefined;
+  byExtension(ext: string): FormatDefinition | undefined;
+  list(): FormatDefinition[];
+}
+
+/** The three shapes `convert()` accepts as a source. */
+export type ConvertSource =
+  | { kind: 'bytes'; data: ArrayBuffer | Uint8Array; filename?: string }
+  | {
+      kind: 'markdown';
+      markdown: string | MarkdownDocument;
+      container?: ContentContainer;
+      baseName?: string;
+    }
+  | { kind: 'doc'; doc: Doc; container?: ContentContainer; baseName?: string };

package/src/shared/container.ts

@@ -0,0 +1,28 @@
+/**
+ * Shared tail for the container-producing importers.
+ *
+ * `docxToContainer`, `pptxToContainer`, and `pdfToContainer` all end the same
+ * way: create a `MemoryContentContainer`, write the primary markdown document,
+ * then write each extracted image under its path with its MIME type. This
+ * factors that identical epilogue into one place.
+ */
+
+import { MemoryContentContainer } from '@bendyline/squisq/storage';
+import type { ContentContainer } from '@bendyline/squisq/storage';
+
+/**
+ * Assemble a {@link ContentContainer} from a markdown document plus a set of
+ * media files. `images` is any iterable of `[path, { data, mimeType }]` pairs
+ * (a `Map` from the importers' extraction context satisfies this directly).
+ */
+export async function buildContainer(
+  markdown: string,
+  images: Iterable<readonly [string, { data: ArrayBuffer; mimeType: string }]>,
+): Promise<ContentContainer> {
+  const container = new MemoryContentContainer();
+  await container.writeDocument(markdown);
+  for (const [path, { data, mimeType }] of images) {
+    await container.writeFile(path, new Uint8Array(data), mimeType);
+  }
+  return container;
+}

package/src/shared/images.ts

@@ -0,0 +1,44 @@
+/**
+ * Shared extension → MIME-type mapping for embedded media.
+ *
+ * Previously triplicated with subtle drift: the docx and pptx importers each
+ * carried a byte-identical dotted-key map (png/jpg/.../emf/wmf), while the html
+ * exporter's `inferMimeType` used no-dot keys and a different key set (added
+ * audio/video/ico/avif, omitted tiff/emf/wmf). This module is the single union
+ * of all of them, so a newly-supported type only has to be added once.
+ */
+
+/** Union of every extension→MIME entry the format modules need. */
+const EXT_TO_MIME: Record<string, string> = {
+  // Raster / vector images
+  png: 'image/png',
+  jpg: 'image/jpeg',
+  jpeg: 'image/jpeg',
+  gif: 'image/gif',
+  webp: 'image/webp',
+  bmp: 'image/bmp',
+  svg: 'image/svg+xml',
+  tiff: 'image/tiff',
+  tif: 'image/tiff',
+  ico: 'image/x-icon',
+  avif: 'image/avif',
+  // Office vector formats (docx/pptx embedded metafiles)
+  emf: 'image/emf',
+  wmf: 'image/wmf',
+  // Audio / video (html export inlines these as data URIs)
+  mp3: 'audio/mpeg',
+  wav: 'audio/wav',
+  ogg: 'audio/ogg',
+  mp4: 'video/mp4',
+  webm: 'video/webm',
+};
+
+/**
+ * Map a file extension to its MIME type. Tolerates a leading dot and any
+ * casing (`.PNG`, `png`, `.png` all resolve). Returns
+ * `application/octet-stream` for unknown extensions.
+ */
+export function extToMime(ext: string): string {
+  const key = ext.replace(/^\./, '').toLowerCase();
+  return EXT_TO_MIME[key] ?? 'application/octet-stream';
+}

package/src/shared/inlineRuns.ts

@@ -0,0 +1,99 @@
+/**
+ * Shared inline walker for the "run-based" exporters.
+ *
+ * DOCX (`<w:r>`) and PPTX (`<a:r>`) both render inline markdown by threading an
+ * active character-format object DOWN through nested nodes (strong → bold,
+ * emphasis → italic, …) and emitting flat styled runs at the leaves — as
+ * opposed to the HTML exporters, which WRAP children in tags, or the PDF
+ * exporter, which accumulates positioned spans. That control flow is identical
+ * between DOCX and PPTX; only the leaf serialization differs.
+ *
+ * This module owns the traversal once. Each exporter supplies the handful of
+ * leaf handlers (`run`, `link`, `image`, `lineBreak`, optional `footnoteRef`)
+ * via {@link InlineRunHandlers}. Because the handler interface is typed, adding
+ * a new inline node type here forces both exporters to be considered — there's
+ * no longer a per-exporter `default:` that can silently drift.
+ */
+
+import type {
+  MarkdownInlineNode,
+  MarkdownLink,
+  MarkdownImage,
+  MarkdownFootnoteReference,
+} from '@bendyline/squisq/markdown';
+import { stripHtmlTags } from './text.js';
+
+/** Active character formatting threaded down through nested inline nodes. */
+export interface InlineRunFormat {
+  bold?: boolean;
+  italic?: boolean;
+  strike?: boolean;
+  code?: boolean;
+  /** Explicit run color (hex without `#`); only some exporters use this. */
+  color?: string;
+}
+
+/**
+ * Per-format leaf handlers. The walker handles the shared format-threading
+ * control flow; these turn the leaves into the target dialect's markup.
+ */
+export interface InlineRunHandlers {
+  /** Emit a styled text run for `text`, given the active format. */
+  run(text: string, format: InlineRunFormat): string;
+  /** Emit a hyperlink (the handler manages its own child rendering). */
+  link(node: MarkdownLink, format: InlineRunFormat): string;
+  /** Emit an inline image. */
+  image(node: MarkdownImage, format: InlineRunFormat): string;
+  /** Emit a hard line break. */
+  lineBreak(): string;
+  /** Emit a footnote reference. Omit to drop footnote refs (PPTX). */
+  footnoteRef?(node: MarkdownFootnoteReference): string;
+}
+
+/** Walk a list of inline nodes, concatenating each rendered run. */
+export function inlineNodesToRuns(
+  nodes: MarkdownInlineNode[],
+  handlers: InlineRunHandlers,
+  format: InlineRunFormat = {},
+): string {
+  let out = '';
+  for (const node of nodes) {
+    out += inlineNodeToRuns(node, handlers, format);
+  }
+  return out;
+}
+
+/** Render a single inline node under the active format. */
+export function inlineNodeToRuns(
+  node: MarkdownInlineNode,
+  handlers: InlineRunHandlers,
+  format: InlineRunFormat,
+): string {
+  switch (node.type) {
+    case 'text':
+      return handlers.run(node.value, format);
+    case 'strong':
+      return inlineNodesToRuns(node.children, handlers, { ...format, bold: true });
+    case 'emphasis':
+      return inlineNodesToRuns(node.children, handlers, { ...format, italic: true });
+    case 'delete':
+      return inlineNodesToRuns(node.children, handlers, { ...format, strike: true });
+    case 'inlineCode':
+      return handlers.run(node.value, { ...format, code: true });
+    case 'inlineMath':
+      return handlers.run(node.value, { ...format, code: true });
+    case 'htmlInline':
+      return handlers.run(stripHtmlTags(node.rawHtml), format);
+    case 'link':
+      return handlers.link(node, format);
+    case 'image':
+      return handlers.image(node, format);
+    case 'break':
+      return handlers.lineBreak();
+    case 'footnoteReference':
+      return handlers.footnoteRef ? handlers.footnoteRef(node) : '';
+    default:
+      // linkReference, imageReference, textDirective, inlineIcon, … — skip.
+      return '';
+  }
+}

package/src/shared/text.ts

@@ -0,0 +1,41 @@
+/**
+ * Shared plain-text helpers used by every format exporter.
+ *
+ * These were previously copy-pasted into the docx / pptx / epub exporters with
+ * subtle drift (e.g. some handled `inlineMath`, some handled `break`). Keeping a
+ * single implementation here means a fix or a newly-supported inline node type
+ * only has to be added in one place.
+ */
+
+import type { MarkdownInlineNode } from '@bendyline/squisq/markdown';
+
+/** Strip HTML tags from a string, keeping only the text content. */
+export function stripHtmlTags(html: string): string {
+  return html.replace(/<[^>]*>/g, '');
+}
+
+/** Flatten a single inline node to its plain-text content. */
+export function inlineToPlainText(node: MarkdownInlineNode): string {
+  switch (node.type) {
+    case 'text':
+    case 'inlineCode':
+    case 'inlineMath':
+      return node.value;
+    case 'emphasis':
+    case 'strong':
+    case 'delete':
+    case 'link':
+      return extractPlainText(node.children);
+    case 'image':
+      return node.alt ?? '';
+    case 'break':
+      return ' ';
+    default:
+      return '';
+  }
+}
+
+/** Flatten an array of inline nodes to their concatenated plain-text content. */
+export function extractPlainText(nodes: MarkdownInlineNode[]): string {
+  return nodes.map(inlineToPlainText).join('');
+}