@bendyline/squisq-formats 1.0.1 → 1.1.1

package/src/__tests__/container.test.ts

@@ -0,0 +1,189 @@
+/**
+ * Tests for container ZIP serialization: containerToZip, zipToContainer.
+ *
+ * Verifies round-trip fidelity: write files to a container, serialize to ZIP,
+ * deserialize back, and confirm all files are intact.
+ */
+
+import { describe, it, expect } from 'vitest';
+import JSZip from 'jszip';
+import { MemoryContentContainer } from '@bendyline/squisq/storage';
+import { containerToZip, zipToContainer } from '../container/index';
+
+// ============================================
+// Helpers
+// ============================================
+
+/** Helper to read a Blob as ArrayBuffer (works in jsdom) */
+async function blobToArrayBuffer(blob: Blob): Promise<ArrayBuffer> {
+  return new Promise((resolve, reject) => {
+    const reader = new FileReader();
+    reader.onload = () => resolve(reader.result as ArrayBuffer);
+    reader.onerror = () => reject(reader.error);
+    reader.readAsArrayBuffer(blob);
+  });
+}
+
+// ============================================
+// containerToZip
+// ============================================
+
+describe('containerToZip', () => {
+  it('creates a valid ZIP from an empty container', async () => {
+    const container = new MemoryContentContainer();
+    const blob = await containerToZip(container);
+    expect(blob).toBeInstanceOf(Blob);
+    expect(blob.size).toBeGreaterThan(0);
+
+    // Should be parseable as a ZIP with no files
+    const zip = await JSZip.loadAsync(await blobToArrayBuffer(blob));
+    expect(Object.keys(zip.files)).toHaveLength(0);
+  });
+
+  it('includes all files from the container', async () => {
+    const container = new MemoryContentContainer();
+    await container.writeDocument('# Hello World');
+    await container.writeFile('images/hero.jpg', new Uint8Array([0xff, 0xd8, 0xff]), 'image/jpeg');
+    await container.writeFile('timing.json', new TextEncoder().encode('{"duration":10}'));
+
+    const blob = await containerToZip(container);
+    const zip = await JSZip.loadAsync(await blobToArrayBuffer(blob));
+
+    const filenames = Object.keys(zip.files)
+      .filter((f) => !zip.files[f].dir)
+      .sort();
+    expect(filenames).toEqual(['images/hero.jpg', 'index.md', 'timing.json']);
+  });
+
+  it('preserves file content', async () => {
+    const container = new MemoryContentContainer();
+    const markdown = '# Test Document\n\nSome content.';
+    await container.writeDocument(markdown);
+
+    const blob = await containerToZip(container);
+    const zip = await JSZip.loadAsync(await blobToArrayBuffer(blob));
+
+    const content = await zip.file('index.md')!.async('string');
+    expect(content).toBe(markdown);
+  });
+
+  it('preserves binary content', async () => {
+    const container = new MemoryContentContainer();
+    const binaryData = new Uint8Array([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+    await container.writeFile('image.png', binaryData, 'image/png');
+
+    const blob = await containerToZip(container);
+    const zip = await JSZip.loadAsync(await blobToArrayBuffer(blob));
+
+    const data = await zip.file('image.png')!.async('uint8array');
+    expect(data).toEqual(binaryData);
+  });
+});
+
+// ============================================
+// zipToContainer
+// ============================================
+
+describe('zipToContainer', () => {
+  it('loads files from a ZIP', async () => {
+    const zip = new JSZip();
+    zip.file('index.md', '# Hello');
+    zip.file('images/photo.jpg', new Uint8Array([0xff, 0xd8]));
+    const zipBlob = await zip.generateAsync({ type: 'blob' });
+
+    const container = await zipToContainer(zipBlob);
+    const entries = await container.listFiles();
+    expect(entries.map((e) => e.path).sort()).toEqual(['images/photo.jpg', 'index.md']);
+  });
+
+  it('preserves text content', async () => {
+    const zip = new JSZip();
+    zip.file('index.md', '# My Document\n\nParagraph.');
+    const zipBlob = await zip.generateAsync({ type: 'blob' });
+
+    const container = await zipToContainer(zipBlob);
+    expect(await container.readDocument()).toBe('# My Document\n\nParagraph.');
+  });
+
+  it('preserves binary content', async () => {
+    const original = new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8]);
+    const zip = new JSZip();
+    zip.file('data.bin', original);
+    const zipBlob = await zip.generateAsync({ type: 'blob' });
+
+    const container = await zipToContainer(zipBlob);
+    const data = await container.readFile('data.bin');
+    expect(new Uint8Array(data!)).toEqual(original);
+  });
+
+  it('skips directory entries', async () => {
+    const zip = new JSZip();
+    zip.folder('images');
+    zip.file('images/photo.jpg', new Uint8Array([0xff]));
+    const zipBlob = await zip.generateAsync({ type: 'blob' });
+
+    const container = await zipToContainer(zipBlob);
+    const entries = await container.listFiles();
+    // Only the file, not the directory
+    expect(entries).toHaveLength(1);
+    expect(entries[0].path).toBe('images/photo.jpg');
+  });
+
+  it('works with ArrayBuffer input', async () => {
+    const zip = new JSZip();
+    zip.file('readme.md', '# Read me');
+    const ab = await zip.generateAsync({ type: 'arraybuffer' });
+
+    const container = await zipToContainer(ab);
+    expect(await container.readDocument()).toBe('# Read me');
+  });
+});
+
+// ============================================
+// Round-trip
+// ============================================
+
+describe('containerToZip / zipToContainer round-trip', () => {
+  it('round-trips a container with markdown and media', async () => {
+    // Create original container
+    const original = new MemoryContentContainer();
+    const markdown = '# Round Trip Test\n\n![hero](images/hero.jpg)\n\nSome text.';
+    await original.writeDocument(markdown);
+    await original.writeFile(
+      'images/hero.jpg',
+      new Uint8Array([0xff, 0xd8, 0xff, 0xe0]),
+      'image/jpeg',
+    );
+    await original.writeFile(
+      'audio/narration.mp3',
+      new Uint8Array([0x49, 0x44, 0x33]),
+      'audio/mpeg',
+    );
+    await original.writeFile('timing.json', new TextEncoder().encode('{"segments":[]}'));
+
+    // Serialize to ZIP
+    const zipBlob = await containerToZip(original);
+
+    // Deserialize back
+    const restored = await zipToContainer(zipBlob);
+
+    // Verify document
+    expect(await restored.readDocument()).toBe(markdown);
+    expect(await restored.getDocumentPath()).toBe('index.md');
+
+    // Verify all files present
+    const entries = (await restored.listFiles()).map((e) => e.path).sort();
+    expect(entries).toEqual(['audio/narration.mp3', 'images/hero.jpg', 'index.md', 'timing.json']);
+
+    // Verify binary content
+    const heroData = new Uint8Array((await restored.readFile('images/hero.jpg'))!);
+    expect(heroData).toEqual(new Uint8Array([0xff, 0xd8, 0xff, 0xe0]));
+
+    const audioData = new Uint8Array((await restored.readFile('audio/narration.mp3'))!);
+    expect(audioData).toEqual(new Uint8Array([0x49, 0x44, 0x33]));
+
+    // Verify JSON sidecar
+    const timingData = new TextDecoder().decode((await restored.readFile('timing.json'))!);
+    expect(timingData).toBe('{"segments":[]}');
+  });
+});

package/src/container/index.ts

@@ -0,0 +1,89 @@
+/**
+ * Container ZIP serialization — convert between ContentContainer and ZIP archives.
+ *
+ * Uses JSZip (already a formats dependency) to serialize a ContentContainer to
+ * a ZIP blob and to deserialize a ZIP blob into a MemoryContentContainer.
+ *
+ * ZIP structure mirrors the container's flat path hierarchy directly:
+ *   index.md
+ *   images/hero.jpg
+ *   audio/narration.mp3
+ *   timing.json
+ */
+
+import JSZip from 'jszip';
+import type { ContentContainer } from '@bendyline/squisq/storage';
+import { MemoryContentContainer } from '@bendyline/squisq/storage';
+
+/**
+ * Serialize a ContentContainer to a ZIP blob.
+ *
+ * All files in the container are written to the ZIP archive preserving
+ * their path structure. The resulting blob can be saved as a .zip file.
+ *
+ * @param container — The container to serialize
+ * @returns A Blob containing the ZIP archive
+ */
+export async function containerToZip(container: ContentContainer): Promise<Blob> {
+  const zip = new JSZip();
+  const entries = await container.listFiles();
+
+  for (const entry of entries) {
+    const data = await container.readFile(entry.path);
+    if (data) {
+      zip.file(entry.path, new Uint8Array(data));
+    }
+  }
+
+  return zip.generateAsync({
+    type: 'blob',
+    compression: 'DEFLATE',
+    compressionOptions: { level: 6 },
+  });
+}
+
+/**
+ * Deserialize a ZIP archive into a MemoryContentContainer.
+ *
+ * Reads all files from the ZIP and writes them into a new MemoryContentContainer.
+ * Directory entries are skipped. The resulting container can be used immediately
+ * for rendering, editing, or saving to persistent storage.
+ *
+ * @param zipData — The ZIP archive as ArrayBuffer, Uint8Array, or Blob
+ * @returns A MemoryContentContainer populated with the ZIP's contents
+ */
+export async function zipToContainer(
+  zipData: ArrayBuffer | Uint8Array | Blob,
+): Promise<MemoryContentContainer> {
+  const zip = await JSZip.loadAsync(zipData);
+  const container = new MemoryContentContainer();
+
+  const filePromises: Promise<void>[] = [];
+
+  zip.forEach((relativePath, zipEntry) => {
+    // Skip directories
+    if (zipEntry.dir) return;
+
+    // Strip leading slash if present
+    const entryPath = relativePath.startsWith('/') ? relativePath.slice(1) : relativePath;
+    if (!entryPath) return;
+
+    // Path-traversal protection: reject absolute paths, backslashes, and .. segments
+    if (
+      entryPath.startsWith('/') ||
+      entryPath.includes('\\') ||
+      entryPath.split('/').some((seg) => seg === '..')
+    ) {
+      return;
+    }
+
+    filePromises.push(
+      zipEntry.async('arraybuffer').then((data) => {
+        return container.writeFile(entryPath, data);
+      }),
+    );
+  });
+
+  await Promise.all(filePromises);
+  return container;
+}

package/src/docx/export.ts

@@ -17,7 +17,8 @@
  * ```
  */
 
-import type { Doc } from '@bendyline/squisq/schemas';
+import type { Doc, Theme } from '@bendyline/squisq/schemas';
+import { resolveTheme } from '@bendyline/squisq/schemas';
 import { docToMarkdown } from '@bendyline/squisq/doc';
 import type {
   MarkdownDocument,
@@ -90,6 +91,12 @@ export interface DocxExportOptions {
   defaultFont?: string;
   /** Default body font size in points. Default: 11 */
   defaultFontSize?: number;
+  /**
+   * Squisq theme ID to apply (e.g., 'documentary', 'cinematic').
+   * When set, overrides fonts with the theme's typography and applies
+   * the theme's primary color to headings.
+   */
+  themeId?: string;
 }
 
 /**
@@ -167,13 +174,32 @@ class ExportContext {
   hasFootnotes = false;
 
   readonly font: string;
+  readonly headingFont: string;
   readonly fontSize: number;
+  /** Heading text color (hex without #), or undefined for default */
+  readonly headingColor: string | undefined;
 
   constructor(options: DocxExportOptions) {
-    this.font = options.defaultFont ?? DEFAULT_FONT;
+    let themeFont: string | undefined;
+    let themeTitleFont: string | undefined;
+    let themeHeadingColor: string | undefined;
+
+    if (options.themeId) {
+      const theme: Theme = resolveTheme(options.themeId);
+      themeFont = theme.typography?.bodyFontFamily;
+      themeTitleFont = theme.typography?.titleFontFamily;
+      if (theme.colors?.primary) {
+        const c = theme.colors.primary;
+        themeHeadingColor = c.startsWith('#') ? c.slice(1) : c;
+      }
+    }
+
+    this.font = options.defaultFont ?? themeFont ?? DEFAULT_FONT;
+    this.headingFont = themeTitleFont ?? this.font;
     this.fontSize = options.defaultFontSize
       ? options.defaultFontSize * 2
       : DEFAULT_FONT_SIZE_HALF_POINTS;
+    this.headingColor = themeHeadingColor;
   }
 
   /** Allocate a new relationship ID */
@@ -632,7 +658,7 @@ async function buildDocxPackage(
   pkg.addPart('word/document.xml', documentXml, CONTENT_TYPE_DOCX_DOCUMENT);
 
   // --- word/styles.xml ---
-  const stylesXml = buildStylesXml(options);
+  const stylesXml = buildStylesXml(options, ctx);
   pkg.addPart('word/styles.xml', stylesXml, CONTENT_TYPE_DOCX_STYLES);
 
   // --- word/settings.xml ---
@@ -754,9 +780,9 @@ function buildDocumentXml(bodyXml: string): string {
   );
 }
 
-function buildStylesXml(options: DocxExportOptions): string {
-  const font = options.defaultFont ?? DEFAULT_FONT;
-  const headingFont = DEFAULT_HEADING_FONT;
+function buildStylesXml(options: DocxExportOptions, ctx: ExportContext): string {
+  const font = ctx.font;
+  const headingFont = ctx.headingFont;
 
   return (
     xmlDeclaration() +
@@ -776,7 +802,7 @@ function buildStylesXml(options: DocxExportOptions): string {
     `<w:qFormat/>` +
     `</w:style>` +
     // Heading styles
-    buildHeadingStyles(headingFont) +
+    buildHeadingStyles(headingFont, ctx.headingColor) +
     // Quote style
     `<w:style w:type="paragraph" w:styleId="Quote">` +
     `<w:name w:val="Quote"/>` +
@@ -827,11 +853,12 @@ function buildStylesXml(options: DocxExportOptions): string {
   );
 }
 
-function buildHeadingStyles(headingFont: string): string {
+function buildHeadingStyles(headingFont: string, headingColor?: string): string {
   let result = '';
   for (let depth = 1; depth <= 6; depth++) {
     const styleId = DEPTH_TO_STYLE_ID[depth];
     const fontSize = HEADING_FONT_SIZES[depth] ?? 22;
+    const colorXml = headingColor ? `<w:color w:val="${headingColor}"/>` : '';
     result +=
       `<w:style w:type="paragraph" w:styleId="${styleId}">` +
       `<w:name w:val="heading ${depth}"/>` +
@@ -842,6 +869,7 @@ function buildHeadingStyles(headingFont: string): string {
       `<w:rPr>` +
       `<w:rFonts w:ascii="${escapeXml(headingFont)}" w:hAnsi="${escapeXml(headingFont)}"/>` +
       `<w:b/>` +
+      colorXml +
       `<w:sz w:val="${fontSize}"/>` +
       `<w:szCs w:val="${fontSize}"/>` +
       `</w:rPr>` +

package/src/html/htmlTemplate.ts

@@ -41,6 +41,13 @@ export interface HtmlExportOptions {
 
   /** Auto-play slideshow on load (default: false) */
   autoPlay?: boolean;
+
+  /**
+   * Squisq theme ID to apply (e.g., 'documentary', 'cinematic').
+   * When set, the theme is assigned to the Doc before rendering,
+   * so the SquisqPlayer renders with that theme's colors and typography.
+   */
+  themeId?: string;
 }
 
 // ── Image Path Collection ──────────────────────────────────────────
@@ -182,8 +189,14 @@ export function generateInlineHtml(doc: Doc, options: HtmlExportOptions): string
     mode = 'slideshow',
     title = 'Squisq Document',
     autoPlay = false,
+    themeId,
   } = options;
 
+  // Apply theme to doc if specified (the SquisqPlayer respects doc.themeId at render time)
+  if (themeId) {
+    doc = { ...doc, themeId };
+  }
+
   // Build base64 image map
   const imageMap: Record<string, string> = {};
   if (images) {

package/src/index.ts

@@ -7,7 +7,7 @@
  * Supported formats:
  * - **DOCX** — Microsoft Word (import + export) ✅
  * - **PDF**  — Portable Document Format (import + export) ✅
- * - **PPTX** — Microsoft PowerPoint (planned)
+ * - **PPTX** — Microsoft PowerPoint (export ✅, import planned)
  * - **XLSX** — Microsoft Excel (planned)
  *
  * All converters run in the browser — no server or native binaries required.
@@ -28,7 +28,7 @@
 export { markdownDocToDocx, docToDocx, docxToMarkdownDoc, docxToDoc } from './docx/index.js';
 export type { DocxExportOptions, DocxImportOptions } from './docx/index.js';
 
-// PPTX (stub)
+// PPTX (export implemented, import stub)
 export { markdownDocToPptx, docToPptx, pptxToMarkdownDoc, pptxToDoc } from './pptx/index.js';
 export type { PptxExportOptions, PptxImportOptions } from './pptx/index.js';
 

package/src/ooxml/index.ts

@@ -83,5 +83,12 @@ export {
   CONTENT_TYPE_DOCX_FONT_TABLE,
   CONTENT_TYPE_DOCX_FOOTNOTES,
   CONTENT_TYPE_PPTX_PRESENTATION,
+  CONTENT_TYPE_PPTX_SLIDE,
+  CONTENT_TYPE_PPTX_SLIDE_LAYOUT,
+  CONTENT_TYPE_PPTX_SLIDE_MASTER,
+  CONTENT_TYPE_PPTX_THEME,
+  REL_SLIDE,
+  REL_SLIDE_LAYOUT,
+  REL_SLIDE_MASTER,
   CONTENT_TYPE_XLSX_WORKBOOK,
 } from './namespaces.js';

package/src/ooxml/namespaces.ts

@@ -156,5 +156,28 @@ export const CONTENT_TYPE_DOCX_FOOTNOTES =
 export const CONTENT_TYPE_PPTX_PRESENTATION =
   'application/vnd.openxmlformats-officedocument.presentationml.presentation.main+xml';
 
+export const CONTENT_TYPE_PPTX_SLIDE =
+  'application/vnd.openxmlformats-officedocument.presentationml.slide+xml';
+
+export const CONTENT_TYPE_PPTX_SLIDE_LAYOUT =
+  'application/vnd.openxmlformats-officedocument.presentationml.slideLayout+xml';
+
+export const CONTENT_TYPE_PPTX_SLIDE_MASTER =
+  'application/vnd.openxmlformats-officedocument.presentationml.slideMaster+xml';
+
+export const CONTENT_TYPE_PPTX_THEME = 'application/vnd.openxmlformats-officedocument.theme+xml';
+
+/** Relationship type: Slide */
+export const REL_SLIDE =
+  'http://schemas.openxmlformats.org/officeDocument/2006/relationships/slide';
+
+/** Relationship type: Slide layout */
+export const REL_SLIDE_LAYOUT =
+  'http://schemas.openxmlformats.org/officeDocument/2006/relationships/slideLayout';
+
+/** Relationship type: Slide master */
+export const REL_SLIDE_MASTER =
+  'http://schemas.openxmlformats.org/officeDocument/2006/relationships/slideMaster';
+
 export const CONTENT_TYPE_XLSX_WORKBOOK =
   'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet.main+xml';

package/src/pdf/export.ts

@@ -22,6 +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 type {
   MarkdownDocument,
@@ -103,6 +104,12 @@ export interface PdfExportOptions {
   margin?: number;
   /** Default body font size in points. Default: 11. */
   defaultFontSize?: number;
+  /**
+   * Squisq theme ID to apply (e.g., 'documentary', 'cinematic').
+   * When set, overrides heading, text, and link colors with the theme palette.
+   * Font changes are not supported (pdf-lib uses standard 14 PDF fonts only).
+   */
+  themeId?: string;
 }
 
 /**
@@ -151,6 +158,12 @@ interface FontSet {
   monoBold: PDFFont;
 }
 
+interface RgbColor {
+  r: number;
+  g: number;
+  b: number;
+}
+
 interface ExportContext {
   pdfDoc: PDFDocument;
   fonts: FontSet;
@@ -166,6 +179,12 @@ interface ExportContext {
   contentWidth: number;
   /** Bottom margin y position. */
   bottomY: number;
+  /** Resolved colors (may be overridden by theme). */
+  colors: {
+    text: RgbColor;
+    heading: RgbColor;
+    link: RgbColor;
+  };
 }
 
 async function createExportContext(
@@ -189,6 +208,20 @@ async function createExportContext(
 
   const page = pdfDoc.addPage([pageWidth, pageHeight]);
 
+  // Resolve theme colors if themeId is set
+  let colorText = COLOR_TEXT;
+  let colorHeading = COLOR_HEADING;
+  let colorLink = COLOR_LINK;
+
+  if (options.themeId) {
+    const theme = resolveTheme(options.themeId);
+    if (theme.colors) {
+      colorText = hexToRgb(theme.colors.text) ?? COLOR_TEXT;
+      colorHeading = hexToRgb(theme.colors.primary) ?? COLOR_HEADING;
+      colorLink = hexToRgb(theme.colors.highlight || theme.colors.secondary) ?? COLOR_LINK;
+    }
+  }
+
   return {
     pdfDoc,
     fonts: { regular, bold, italic, boldItalic, mono, monoBold },
@@ -200,6 +233,7 @@ async function createExportContext(
     y: pageHeight - margin,
     contentWidth: pageWidth - 2 * margin,
     bottomY: margin,
+    colors: { text: colorText, heading: colorHeading, link: colorLink },
   };
 }
 
@@ -262,7 +296,7 @@ function flattenInlines(
           text: (node as MarkdownText).value,
           font,
           fontSize: state.code ? CODE_FONT_SIZE : ctx.fontSize,
-          color: state.code ? COLOR_CODE_TEXT : (state.color ?? COLOR_TEXT),
+          color: state.code ? COLOR_CODE_TEXT : (state.color ?? ctx.colors.text),
           link: state.link,
           strikethrough: state.strikethrough,
         });
@@ -307,7 +341,7 @@ function flattenInlines(
           ...flattenInlines(linkNode.children, ctx, {
             ...state,
             link: linkNode.url,
-            color: COLOR_LINK,
+            color: ctx.colors.link,
           }),
         );
         break;
@@ -329,7 +363,7 @@ function flattenInlines(
           text: '\n',
           font: ctx.fonts.regular,
           fontSize: ctx.fontSize,
-          color: COLOR_TEXT,
+          color: ctx.colors.text,
         });
         break;
 
@@ -361,7 +395,7 @@ function flattenInlines(
           text: `[${ref.identifier}]`,
           font: ctx.fonts.regular,
           fontSize: ctx.fontSize * 0.75,
-          color: COLOR_LINK,
+          color: ctx.colors.link,
         });
         break;
       }
@@ -376,7 +410,7 @@ function flattenInlines(
             text: fallback.value,
             font: pickFont(ctx, state.bold, state.italic),
             fontSize: ctx.fontSize,
-            color: state.color ?? COLOR_TEXT,
+            color: state.color ?? ctx.colors.text,
           });
         }
         break;
@@ -601,7 +635,7 @@ function renderHeading(node: MarkdownHeading, ctx: ExportContext, extraIndent: n
     bold: true,
     italic: false,
     code: false,
-    color: COLOR_HEADING,
+    color: ctx.colors.heading,
   });
 
   drawSpans(spans, ctx, w, x0);
@@ -704,7 +738,7 @@ function renderListItem(
     y: ctx.y - ctx.fontSize,
     size: ctx.fontSize,
     font: bulletFont,
-    color: rgb(COLOR_TEXT.r, COLOR_TEXT.g, COLOR_TEXT.b),
+    color: rgb(ctx.colors.text.r, ctx.colors.text.g, ctx.colors.text.b),
   });
 
   const textIndent = indent + bulletWidth + 4;
@@ -969,7 +1003,7 @@ function renderFootnoteDefinition(
     y: ctx.y - ctx.fontSize * 0.75,
     size: ctx.fontSize * 0.75,
     font: ctx.fonts.bold,
-    color: rgb(COLOR_LINK.r, COLOR_LINK.g, COLOR_LINK.b),
+    color: rgb(ctx.colors.link.r, ctx.colors.link.g, ctx.colors.link.b),
   });
 
   // Render children indented
@@ -1022,8 +1056,22 @@ function renderFallbackBlock(
       y: ctx.y - ctx.fontSize,
       size: ctx.fontSize,
       font: ctx.fonts.regular,
-      color: rgb(COLOR_TEXT.r, COLOR_TEXT.g, COLOR_TEXT.b),
+      color: rgb(ctx.colors.text.r, ctx.colors.text.g, ctx.colors.text.b),
     });
     ctx.y -= lineH + PARAGRAPH_SPACING;
   }
 }
+
+// ============================================
+// Color Helpers
+// ============================================
+
+function hexToRgb(hex: string): RgbColor | undefined {
+  const h = hex.startsWith('#') ? hex.slice(1) : hex;
+  if (h.length !== 6) return undefined;
+  const r = parseInt(h.slice(0, 2), 16);
+  const g = parseInt(h.slice(2, 4), 16);
+  const b = parseInt(h.slice(4, 6), 16);
+  if (isNaN(r) || isNaN(g) || isNaN(b)) return undefined;
+  return { r: r / 255, g: g / 255, b: b / 255 };
+}