@bendyline/squisq-formats 0.1.0

package/src/docx/index.ts

@@ -0,0 +1,26 @@
+/**
+ * @bendyline/squisq-formats DOCX Module
+ *
+ * Import and export squisq documents (MarkdownDocument / Doc)
+ * to/from Microsoft Word .docx files (Office Open XML WordprocessingML).
+ *
+ * All operations run in the browser — no server required.
+ *
+ * @example
+ * ```ts
+ * import {
+ *   markdownDocToDocx,
+ *   docToDocx,
+ *   docxToMarkdownDoc,
+ *   docxToDoc,
+ * } from '@bendyline/squisq-formats/docx';
+ * ```
+ */
+
+// Export
+export { markdownDocToDocx, docToDocx } from './export.js';
+export type { DocxExportOptions } from './export.js';
+
+// Import
+export { docxToMarkdownDoc, docxToDoc } from './import.js';
+export type { DocxImportOptions } from './import.js';

package/src/docx/styles.ts

@@ -0,0 +1,145 @@
+/**
+ * DOCX Constants & Style Definitions
+ *
+ * Shared constants for DOCX import and export: built-in style IDs,
+ * numbering format mappings, content type strings, and default
+ * formatting values.
+ */
+
+// ============================================
+// Built-in Style IDs
+// ============================================
+
+/**
+ * Word built-in paragraph style IDs → heading depth.
+ * These are the default style IDs in Word's Normal.dotm template.
+ * Import uses these to detect heading levels from pStyle values.
+ */
+export const HEADING_STYLE_MAP: Record<string, number> = {
+  Heading1: 1,
+  Heading2: 2,
+  Heading3: 3,
+  Heading4: 4,
+  Heading5: 5,
+  Heading6: 6,
+  heading1: 1,
+  heading2: 2,
+  heading3: 3,
+  heading4: 4,
+  heading5: 5,
+  heading6: 6,
+  // Some localized/legacy variants
+  Title: 1,
+  Subtitle: 2,
+};
+
+/**
+ * Heading depth → Word style ID mapping (for export).
+ */
+export const DEPTH_TO_STYLE_ID: Record<number, string> = {
+  1: 'Heading1',
+  2: 'Heading2',
+  3: 'Heading3',
+  4: 'Heading4',
+  5: 'Heading5',
+  6: 'Heading6',
+};
+
+/**
+ * Paragraph style IDs that map to blockquotes on import.
+ */
+export const QUOTE_STYLE_IDS = new Set(['Quote', 'IntenseQuote', 'quote', 'BlockQuote']);
+
+/**
+ * Paragraph style ID for code blocks.
+ */
+export const CODE_STYLE_IDS = new Set(['Code', 'CodeBlock', 'HTMLCode', 'PlainText']);
+
+/**
+ * Character style IDs that indicate inline code.
+ */
+export const INLINE_CODE_STYLE_IDS = new Set(['CodeChar', 'HTMLCodeChar', 'VerbatimChar']);
+
+// ============================================
+// Numbering Formats
+// ============================================
+
+/**
+ * Word numbering format values that indicate an unordered (bullet) list.
+ */
+export const BULLET_NUM_FORMATS = new Set(['bullet', 'none']);
+
+/**
+ * Word numbering format values that indicate an ordered (numbered) list.
+ */
+export const ORDERED_NUM_FORMATS = new Set([
+  'decimal',
+  'upperRoman',
+  'lowerRoman',
+  'upperLetter',
+  'lowerLetter',
+  'ordinal',
+  'cardinalText',
+  'ordinalText',
+]);
+
+// ============================================
+// Default Formatting
+// ============================================
+
+/** Default font family for document body text */
+export const DEFAULT_FONT = 'Calibri';
+
+/** Default font family for headings */
+export const DEFAULT_HEADING_FONT = 'Calibri Light';
+
+/** Default font size in half-points (22 = 11pt) */
+export const DEFAULT_FONT_SIZE_HALF_POINTS = 22;
+
+/** Default code font */
+export const DEFAULT_CODE_FONT = 'Consolas';
+
+/** Default code font size in half-points (20 = 10pt) */
+export const DEFAULT_CODE_FONT_SIZE = 20;
+
+/**
+ * Heading font sizes in half-points (Word default sizes).
+ */
+export const HEADING_FONT_SIZES: Record<number, number> = {
+  1: 32, // 16pt
+  2: 26, // 13pt
+  3: 24, // 12pt
+  4: 22, // 11pt
+  5: 22, // 11pt
+  6: 22, // 11pt
+};
+
+/** Hyperlink color (standard Word blue) */
+export const HYPERLINK_COLOR = '0563C1';
+
+// ============================================
+// EMU (English Metric Units) Helpers
+// ============================================
+
+/**
+ * Convert inches to EMUs (English Metric Units).
+ * 1 inch = 914400 EMUs.
+ */
+export function inchesToEmu(inches: number): number {
+  return Math.round(inches * 914400);
+}
+
+/**
+ * Convert points to half-points (Word's internal unit for font sizes).
+ */
+export function pointsToHalfPoints(points: number): number {
+  return Math.round(points * 2);
+}
+
+/**
+ * Convert points to twentieths of a point (twips), used for spacing/margins.
+ * 1 point = 20 twips.
+ */
+export function pointsToTwips(points: number): number {
+  return Math.round(points * 20);
+}

package/src/html/htmlTemplate.ts

@@ -0,0 +1,307 @@
+/**
+ * HTML Template Generation for SquisqPlayer Exports
+ *
+ * Generates complete, self-contained HTML documents that load the SquisqPlayer
+ * IIFE bundle and render a Doc as either an interactive slideshow or a static
+ * scrollable document.
+ *
+ * Two variants:
+ * 1. **Inline** — All JS, CSS, and images are embedded in the HTML (single file).
+ * 2. **External** — JS is referenced via `<script src>`, images via relative paths.
+ */
+
+import type { Doc, Layer, Block } from '@bendyline/squisq/schemas';
+import { arrayBufferToBase64DataUrl, inferMimeType } from './imageUtils.js';
+
+// ── Types ──────────────────────────────────────────────────────────
+
+export interface HtmlExportOptions {
+  /** The IIFE player bundle source code (from @bendyline/squisq-react/standalone-source) */
+  playerScript: string;
+
+  /**
+   * Map of relative image paths (as they appear in the Doc) to binary image data.
+   * For inline HTML export, these are converted to base64 data URIs.
+   * For ZIP export, these are written as separate files.
+   */
+  images?: Map<string, ArrayBuffer>;
+
+  /**
+   * Map of audio segment identifiers to binary audio data.
+   * Keys should match the audio segment `name` or `url` fields in the Doc.
+   * Only used in ZIP exports — single HTML uses timer-based playback.
+   */
+  audio?: Map<string, ArrayBuffer>;
+
+  /** Rendering mode: 'slideshow' (interactive, default) or 'static' (scrollable) */
+  mode?: 'slideshow' | 'static';
+
+  /** HTML page title (default: 'Squisq Document') */
+  title?: string;
+
+  /** Auto-play slideshow on load (default: false) */
+  autoPlay?: boolean;
+}
+
+// ── Image Path Collection ──────────────────────────────────────────
+
+/**
+ * Collect all relative image paths referenced in a Doc's layers and template blocks.
+ * Returns a Set of unique relative paths that need to be resolved.
+ */
+export function collectImagePaths(doc: Doc): Set<string> {
+  const paths = new Set<string>();
+
+  function addIfRelative(src: string | undefined) {
+    if (
+      !src ||
+      src.startsWith('data:') ||
+      src.startsWith('blob:') ||
+      src.startsWith('http://') ||
+      src.startsWith('https://')
+    ) {
+      return;
+    }
+    paths.add(src);
+  }
+
+  function scanLayers(layers: Layer[] | undefined) {
+    if (!layers) return;
+    for (const layer of layers) {
+      if (layer.type === 'image') addIfRelative(layer.content.src);
+      if (layer.type === 'video') {
+        addIfRelative(layer.content.src);
+        addIfRelative(layer.content.posterSrc);
+      }
+      if (layer.type === 'map') addIfRelative(layer.content.staticSrc);
+    }
+  }
+
+  function scanBlock(block: Block) {
+    scanLayers(block.layers);
+    if (block.children) block.children.forEach(scanBlock);
+  }
+
+  // Scan all blocks
+  doc.blocks.forEach(scanBlock);
+
+  // Scan start block hero
+  if (doc.startBlock?.heroSrc) addIfRelative(doc.startBlock.heroSrc);
+
+  // Scan persistent layers
+  if (doc.persistentLayers) {
+    for (const pl of doc.persistentLayers.bottomLayers ?? []) {
+      if ('src' in pl && typeof pl.src === 'string') addIfRelative(pl.src);
+    }
+    for (const pl of doc.persistentLayers.topLayers ?? []) {
+      if ('src' in pl && typeof pl.src === 'string') addIfRelative(pl.src);
+    }
+  }
+
+  // Scan template block fields that reference images
+  for (const block of doc.blocks) {
+    scanTemplateImageFields(block as unknown as Record<string, unknown>, paths);
+  }
+
+  return paths;
+}
+
+/**
+ * Recursively scan any object for known image-bearing field names.
+ */
+function scanTemplateImageFields(obj: Record<string, unknown>, paths: Set<string>): void {
+  if (!obj || typeof obj !== 'object') return;
+
+  const imageFieldNames = [
+    'imageSrc',
+    'src',
+    'heroSrc',
+    'backgroundImage',
+    'posterSrc',
+    'staticSrc',
+    'videoSrc',
+    'thumbnailSrc',
+  ];
+
+  for (const key of imageFieldNames) {
+    const val = obj[key];
+    if (typeof val === 'string' && val && !val.startsWith('data:') && !val.startsWith('http')) {
+      paths.add(val);
+    }
+    // Handle nested objects like { src: '...' }
+    if (val && typeof val === 'object' && !Array.isArray(val)) {
+      scanTemplateImageFields(val as Record<string, unknown>, paths);
+    }
+  }
+
+  // Handle arrays (e.g., images: [{ src: '...' }])
+  if (Array.isArray(obj)) {
+    for (const item of obj) {
+      if (item && typeof item === 'object') {
+        scanTemplateImageFields(item as Record<string, unknown>, paths);
+      }
+    }
+  }
+
+  // Recurse into known array/object fields
+  for (const key of ['images', 'accentImage', 'backgroundVideo', 'children', 'blocks']) {
+    const val = obj[key];
+    if (Array.isArray(val)) {
+      for (const item of val) {
+        if (item && typeof item === 'object') {
+          scanTemplateImageFields(item as Record<string, unknown>, paths);
+        }
+      }
+    } else if (val && typeof val === 'object') {
+      scanTemplateImageFields(val as Record<string, unknown>, paths);
+    }
+  }
+}
+
+// ── HTML Generation ────────────────────────────────────────────────
+
+/**
+ * Escape a string for safe embedding in a `<script>` tag.
+ * Prevents `</script>` from closing the tag prematurely.
+ */
+function escapeForScript(str: string): string {
+  return str.replace(/<\/(script)/gi, '<\\/$1');
+}
+
+/**
+ * Generate a complete inline HTML document with all JS and images embedded.
+ *
+ * @param doc - The Doc to render
+ * @param options - Export options
+ * @returns Complete HTML string
+ */
+export function generateInlineHtml(doc: Doc, options: HtmlExportOptions): string {
+  const {
+    playerScript,
+    images,
+    mode = 'slideshow',
+    title = 'Squisq Document',
+    autoPlay = false,
+  } = options;
+
+  // Build base64 image map
+  const imageMap: Record<string, string> = {};
+  if (images) {
+    for (const [path, buffer] of images.entries()) {
+      const mimeType = inferMimeType(path);
+      imageMap[path] = arrayBufferToBase64DataUrl(buffer, mimeType);
+    }
+  }
+
+  const docJson = escapeForScript(JSON.stringify(doc));
+  const imageMapJson = escapeForScript(JSON.stringify(imageMap));
+
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>${escapeHtml(title)}</title>
+<style>
+*,*::before,*::after{box-sizing:border-box}
+html,body{margin:0;padding:0;height:100%;background:#1a1a2e;color:#e0e0e0;font-family:system-ui,-apple-system,sans-serif}
+#squisq-root{width:100%;height:100%;display:flex;align-items:center;justify-content:center}
+${mode === 'static' ? '#squisq-root{align-items:flex-start;overflow-y:auto;background:#fff;color:#1f2937}' : ''}
+</style>
+</head>
+<body>
+<div id="squisq-root"></div>
+<script>${escapeForScript(playerScript)}</script>
+<script>
+(function(){
+  var doc = JSON.parse(${JSON.stringify(docJson)});
+  var images = JSON.parse(${JSON.stringify(imageMapJson)});
+  SquisqPlayer.mount(document.getElementById("squisq-root"), doc, {
+    mode: ${JSON.stringify(mode)},
+    images: images,
+    autoPlay: ${JSON.stringify(autoPlay)},
+    basePath: "."
+  });
+})();
+</script>
+</body>
+</html>`;
+}
+
+/**
+ * Generate an HTML document that references external JS and image files.
+ * Used for ZIP exports where files sit alongside the HTML.
+ *
+ * @param doc - The Doc to render (image/audio paths should already be rewritten to relative)
+ * @param options - Export options (playerScript is not embedded, referenced via src)
+ * @returns Complete HTML string
+ */
+export function generateExternalHtml(
+  doc: Doc,
+  options: Pick<HtmlExportOptions, 'mode' | 'title' | 'autoPlay'> & {
+    /** Relative path to the player JS file (e.g., 'squisq-player.js') */
+    playerScriptPath: string;
+    /** Map of original image paths to their rewritten relative paths in the ZIP */
+    imagePathMap?: Record<string, string>;
+    /** Map of audio segment IDs to their rewritten relative paths in the ZIP */
+    audioPathMap?: Record<string, string>;
+  },
+): string {
+  const {
+    playerScriptPath,
+    imagePathMap,
+    audioPathMap,
+    mode = 'slideshow',
+    title = 'Squisq Document',
+    autoPlay = false,
+  } = options;
+
+  const docJson = escapeForScript(JSON.stringify(doc));
+  const imageMapJson = imagePathMap ? escapeForScript(JSON.stringify(imagePathMap)) : '{}';
+  const audioMapJson = audioPathMap ? escapeForScript(JSON.stringify(audioPathMap)) : 'null';
+
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>${escapeHtml(title)}</title>
+<style>
+*,*::before,*::after{box-sizing:border-box}
+html,body{margin:0;padding:0;height:100%;background:#1a1a2e;color:#e0e0e0;font-family:system-ui,-apple-system,sans-serif}
+#squisq-root{width:100%;height:100%;display:flex;align-items:center;justify-content:center}
+${mode === 'static' ? '#squisq-root{align-items:flex-start;overflow-y:auto;background:#fff;color:#1f2937}' : ''}
+</style>
+</head>
+<body>
+<div id="squisq-root"></div>
+<script src="${escapeHtml(playerScriptPath)}"></script>
+<script>
+(function(){
+  var doc = JSON.parse(${JSON.stringify(docJson)});
+  var images = JSON.parse(${JSON.stringify(imageMapJson)});
+  var audio = ${audioMapJson};
+  SquisqPlayer.mount(document.getElementById("squisq-root"), doc, {
+    mode: ${JSON.stringify(mode)},
+    images: images,
+    audio: audio,
+    autoPlay: ${JSON.stringify(autoPlay)},
+    basePath: "."
+  });
+})();
+</script>
+</body>
+</html>`;
+}
+
+/**
+ * Escape HTML special characters to prevent injection.
+ */
+function escapeHtml(str: string): string {
+  return str
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#39;');
+}

package/src/html/imageUtils.ts

@@ -0,0 +1,66 @@
+/**
+ * Image Utilities for HTML Export
+ *
+ * Browser-compatible helpers for converting image data to base64 data URIs
+ * and inferring MIME types from filenames.
+ */
+
+/** Map of file extensions to MIME types */
+const MIME_MAP: Record<string, string> = {
+  jpg: 'image/jpeg',
+  jpeg: 'image/jpeg',
+  png: 'image/png',
+  gif: 'image/gif',
+  webp: 'image/webp',
+  svg: 'image/svg+xml',
+  ico: 'image/x-icon',
+  bmp: 'image/bmp',
+  avif: 'image/avif',
+  mp3: 'audio/mpeg',
+  wav: 'audio/wav',
+  ogg: 'audio/ogg',
+  mp4: 'video/mp4',
+  webm: 'video/webm',
+};
+
+/**
+ * Infer a MIME type from a filename's extension.
+ * Returns 'application/octet-stream' for unknown types.
+ */
+export function inferMimeType(filename: string): string {
+  const ext = filename.split('.').pop()?.toLowerCase() ?? '';
+  return MIME_MAP[ext] ?? 'application/octet-stream';
+}
+
+/**
+ * Convert an ArrayBuffer to a base64-encoded data URI string.
+ *
+ * @param buffer - The binary image data
+ * @param mimeType - MIME type (e.g., 'image/jpeg'). If not provided, defaults to
+ *   'application/octet-stream'.
+ * @returns A `data:` URI string
+ */
+export function arrayBufferToBase64DataUrl(buffer: ArrayBuffer, mimeType: string): string {
+  const bytes = new Uint8Array(buffer);
+  let binary = '';
+  for (let i = 0; i < bytes.length; i++) {
+    binary += String.fromCharCode(bytes[i]);
+  }
+  const base64 = btoa(binary);
+  return `data:${mimeType};base64,${base64}`;
+}
+
+/**
+ * Extract the filename from a path or URL (strips directory and query).
+ *
+ * @example
+ *   extractFilename('images/hero.jpg') // 'hero.jpg'
+ *   extractFilename('https://example.com/photo.png?v=2') // 'photo.png'
+ */
+export function extractFilename(path: string): string {
+  // Strip query/hash
+  const clean = path.split('?')[0].split('#')[0];
+  // Get last segment
+  const parts = clean.split('/');
+  return parts[parts.length - 1] || path;
+}