@sanity-labs/slides 0.0.0

package/src/core/op-translator-pptx.ts

@@ -0,0 +1,365 @@
+/**
+ * Pure translation from `SlideOp` (the reconciler's typed intent) to a
+ * compact intermediate representation that pptxgenjs can consume.
+ *
+ * # Why not emit pptxgenjs calls directly
+ *
+ * pptxgenjs is stateful: `slide.addText(...)` mutates the Slide. The
+ * `SlideOp` stream is sequential — `createShape` is followed by
+ * `insertText`, `updateTextStyle`, etc. — so a one-pass-per-op translator
+ * would have to issue `addText` immediately on `createShape`, then mutate
+ * the already-added text on style ops, which pptxgenjs doesn't support.
+ *
+ * Instead, this module collapses an op stream into an array of
+ * `PptxObject` records — one per slide-level object. The runtime then walks
+ * the records and emits pptxgenjs calls in one shot per shape.
+ *
+ * # Unit conversion
+ *
+ * SlideOps carry positions in EMU. pptxgenjs uses inches. This module is
+ * the single boundary that converts EMU → inches; the substrate's
+ * pt-then-EMU-at-emit choice is unchanged.
+ *
+ * # Per-runtime font substitution
+ *
+ * The translator accepts a `fontSubstitution` map. When a SlideOp's
+ * `updateTextStyle.fontFamily` matches a key, the value replaces it on
+ * emit. PPTX cannot embed fonts; viewers need the family installed locally.
+ * Brands ship their own substitution table (see `@sanity-labs/slides` for an
+ * example); the substrate's default is empty.
+ *
+ * # Known gaps
+ *
+ * - **Outline weight + outline color on TEXT_BOX shapes.** pptxgenjs
+ *   supports outlines via `line` on `addShape`, but text boxes go through
+ *   `addText` whose options don't carry an outline. If a brand needs
+ *   outlined text boxes, emit a sibling rectangle.
+ * - **Manifest persistence into the .pptx file.** The runtime holds the
+ *   manifest in memory only; re-fill against a previously-generated .pptx
+ *   is out of scope.
+ */
+
+import { EMU_PER_INCH } from './geometry.js';
+import type {
+  EmuRect,
+  HexColor,
+  ParagraphStyle,
+  ShapeProperties,
+  SlideOp,
+  TextStyle,
+} from './runtime.js';
+
+/**
+ * The pptxgenjs-shaped representation of a single object on a slide.
+ * Discriminated by `kind` so the runtime can dispatch `addText` vs
+ * `addShape` vs `addImage`.
+ */
+export type PptxObject = PptxText | PptxRectangle | PptxImage;
+
+/** A text box (TEXT_BOX shape) — emitted via `slide.addText`. */
+export interface PptxText {
+  readonly kind: 'text';
+  readonly slideId: string;
+  readonly objectId: string;
+  /** Position, in inches. */
+  readonly position: PptxPosition;
+  /** Background fill color, no leading `#`. */
+  readonly fill?: string;
+  /** Plain text content. Empty string when no `insertText` op was applied. */
+  readonly text: string;
+  /**
+   * Per-range text-style spans. The runtime composes these into an array
+   * of `TextProps` segments for pptxgenjs.
+   *
+   * Spans are recorded in op order; later spans on overlapping ranges win
+   * at composition time (matches FakeSlidesRuntime semantics).
+   */
+  readonly textSpans: ReadonlyArray<{ start: number; end: number; style: TextStyle }>;
+  /** Paragraph-level style — pptxgenjs applies one set per addText call. */
+  readonly paragraphStyle?: ParagraphStyle;
+}
+
+/** A non-text rectangle/ellipse — emitted via `slide.addShape`. */
+export interface PptxRectangle {
+  readonly kind: 'rectangle';
+  readonly slideId: string;
+  readonly objectId: string;
+  readonly position: PptxPosition;
+  readonly shape: 'rect' | 'ellipse' | 'line';
+  readonly fill?: string;
+  readonly outlineColor?: string;
+  readonly outlineWeight?: number;
+}
+
+/** An image — emitted via `slide.addImage`. */
+export interface PptxImage {
+  readonly kind: 'image';
+  readonly slideId: string;
+  readonly objectId: string;
+  readonly position: PptxPosition;
+  readonly url: string;
+  readonly altText?: string;
+}
+
+/** Position in inches — pptxgenjs's native unit. */
+export interface PptxPosition {
+  readonly x: number;
+  readonly y: number;
+  readonly w: number;
+  readonly h: number;
+}
+
+/** What the translator emits for a whole `applyOps` batch. */
+export interface PptxBatch {
+  /**
+   * Slides to create, in op order. For each entry, `insertAt` mirrors the
+   * SlideOp's index (currently informational; pptxgenjs appends in
+   * call order).
+   */
+  readonly slides: ReadonlyArray<{ slideId: string; insertAt: number | undefined }>;
+  /**
+   * Per-slide objects, in creation order. The runtime iterates and emits
+   * the corresponding pptxgenjs call.
+   */
+  readonly objects: readonly PptxObject[];
+  /** Object IDs (slide / shape / image) created by this batch. */
+  readonly createdObjectIds: readonly string[];
+}
+
+/**
+ * Per-call translator options. The font-substitution map is the Option X
+ * font resolver — see `pptx-runtime.ts` for the rationale.
+ */
+export interface TranslateOptions {
+  /**
+   * Map of resolved-font-name → output-font-name. When an op's
+   * `fontFamily` is a key, the value replaces it. Pass-through when not.
+   */
+  readonly fontSubstitution?: Readonly<Record<string, string>>;
+  /**
+   * Optional warning hook for fonts that aren't in the substitution table.
+   * Default: no-op. The runtime itself decides whether to log; libraries
+   * should not write to stdout/stderr without opt-in.
+   */
+  readonly onUnknownFont?: ((fontFamily: string) => void) | null;
+}
+
+/**
+ * Walk a SlideOp stream and produce the pptxgenjs-shaped batch.
+ *
+ * The translator is stateful within a single call: shapes accumulate
+ * styles from later ops. Across calls, it's pure — given the same ops
+ * and options, output is deterministic.
+ */
+export const translateOpsToPptx = (
+  ops: readonly SlideOp[],
+  options: TranslateOptions = {},
+): PptxBatch => {
+  const slides: { slideId: string; insertAt: number | undefined }[] = [];
+  const objects: PptxObject[] = [];
+  const objectIndex = new Map<string, number>();
+  const createdObjectIds: string[] = [];
+  const subs = options.fontSubstitution ?? {};
+  const warned = new Set<string>();
+  // Default to a no-op: libraries shouldn't write to stdout/stderr without
+  // explicit opt-in. The runtime can pass `console.warn` (or its own logger)
+  // when it actually wants user-facing warnings.
+  const warn = options.onUnknownFont ?? noopWarn;
+
+  const upsertText = (slideId: string, objectId: string, position: PptxPosition): PptxText => {
+    const idx = objectIndex.get(objectId);
+    if (idx !== undefined) {
+      const existing = objects[idx];
+      if (existing && existing.kind === 'text') return existing;
+      throw new Error(
+        `translateOpsToPptx: object "${objectId}" already exists as a non-text ${existing?.kind ?? 'unknown'}.`,
+      );
+    }
+    const text: PptxText = {
+      kind: 'text',
+      slideId,
+      objectId,
+      position,
+      text: '',
+      textSpans: [],
+    } as PptxText;
+    objectIndex.set(objectId, objects.length);
+    objects.push(text);
+    createdObjectIds.push(objectId);
+    return text;
+  };
+
+  const findText = (objectId: string, opName: string): PptxText => {
+    const idx = objectIndex.get(objectId);
+    if (idx === undefined) {
+      throw new Error(`translateOpsToPptx: ${opName} targets unknown object "${objectId}".`);
+    }
+    const obj = objects[idx];
+    if (!obj || obj.kind !== 'text') {
+      throw new Error(`translateOpsToPptx: ${opName} targets non-text object "${objectId}".`);
+    }
+    return obj;
+  };
+
+  const replaceObject = (idx: number, replacement: PptxObject): void => {
+    objects[idx] = replacement;
+  };
+
+  for (const op of ops) {
+    switch (op.type) {
+      case 'createSlide': {
+        slides.push({ slideId: op.slideId, insertAt: op.insertAt });
+        createdObjectIds.push(op.slideId);
+        break;
+      }
+      case 'createShape': {
+        const position = emuRectToInches(op.rect);
+        if (op.shape === 'TEXT_BOX') {
+          upsertText(op.slideId, op.shapeId, position);
+        } else {
+          // RECTANGLE / ELLIPSE / LINE — emit as pptxgenjs shape.
+          const rect: PptxRectangle = {
+            kind: 'rectangle',
+            slideId: op.slideId,
+            objectId: op.shapeId,
+            position,
+            shape: shapeKindToPptx(op.shape),
+          };
+          objectIndex.set(op.shapeId, objects.length);
+          objects.push(rect);
+          createdObjectIds.push(op.shapeId);
+        }
+        break;
+      }
+      case 'createImage': {
+        const image: PptxImage = {
+          kind: 'image',
+          slideId: op.slideId,
+          objectId: op.imageId,
+          position: emuRectToInches(op.rect),
+          url: op.url,
+          ...(op.altText !== undefined ? { altText: op.altText } : {}),
+        };
+        objectIndex.set(op.imageId, objects.length);
+        objects.push(image);
+        createdObjectIds.push(op.imageId);
+        break;
+      }
+      case 'insertText': {
+        const target = findText(op.objectId, 'insertText');
+        const idx = objectIndex.get(op.objectId);
+        if (idx === undefined) break;
+        replaceObject(idx, { ...target, text: op.text });
+        break;
+      }
+      case 'updateTextStyle': {
+        const target = findText(op.objectId, 'updateTextStyle');
+        const idx = objectIndex.get(op.objectId);
+        if (idx === undefined) break;
+        const style = applyFontSubstitution(op.style, subs, warn, warned);
+        const span = { start: op.range.start, end: op.range.end, style };
+        replaceObject(idx, { ...target, textSpans: [...target.textSpans, span] });
+        break;
+      }
+      case 'updateParagraphStyle': {
+        const target = findText(op.objectId, 'updateParagraphStyle');
+        const idx = objectIndex.get(op.objectId);
+        if (idx === undefined) break;
+        replaceObject(idx, {
+          ...target,
+          paragraphStyle: { ...(target.paragraphStyle ?? {}), ...op.style },
+        });
+        break;
+      }
+      case 'updateShapeProperties': {
+        const idx = objectIndex.get(op.objectId);
+        if (idx === undefined) {
+          throw new Error(
+            `translateOpsToPptx: updateShapeProperties targets unknown object "${op.objectId}".`,
+          );
+        }
+        const obj = objects[idx];
+        if (!obj) break;
+        replaceObject(idx, mergeShapeProperties(obj, op.properties));
+        break;
+      }
+    }
+  }
+
+  return { slides, objects, createdObjectIds };
+};
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/** Convert EMU rect to inches (pptxgenjs's native unit). */
+const emuRectToInches = (rect: EmuRect): PptxPosition => ({
+  x: rect.x / EMU_PER_INCH,
+  y: rect.y / EMU_PER_INCH,
+  w: rect.w / EMU_PER_INCH,
+  h: rect.h / EMU_PER_INCH,
+});
+
+const shapeKindToPptx = (kind: 'RECTANGLE' | 'ELLIPSE' | 'LINE'): 'rect' | 'ellipse' | 'line' => {
+  switch (kind) {
+    case 'RECTANGLE':
+      return 'rect';
+    case 'ELLIPSE':
+      return 'ellipse';
+    case 'LINE':
+      return 'line';
+  }
+};
+
+/**
+ * Strip the leading `#` from a hex color and return uppercase. pptxgenjs
+ * uses bare hex (e.g., `'FF5500'`).
+ */
+export const hexToPptxColor = (hex: HexColor): string => {
+  const stripped = hex.startsWith('#') ? hex.slice(1) : hex;
+  return stripped.toUpperCase();
+};
+
+const mergeShapeProperties = (obj: PptxObject, props: ShapeProperties): PptxObject => {
+  if (obj.kind === 'text') {
+    return {
+      ...obj,
+      ...(props.fillColor !== undefined ? { fill: hexToPptxColor(props.fillColor) } : {}),
+    };
+  }
+  if (obj.kind === 'rectangle') {
+    const next: PptxRectangle = { ...obj };
+    if (props.fillColor !== undefined)
+      (next as { fill?: string }).fill = hexToPptxColor(props.fillColor);
+    if (props.outlineColor !== undefined)
+      (next as { outlineColor?: string }).outlineColor = hexToPptxColor(props.outlineColor);
+    if (props.outlineWeight !== undefined)
+      (next as { outlineWeight?: number }).outlineWeight = props.outlineWeight;
+    return next;
+  }
+  // image — no shape properties apply
+  return obj;
+};
+
+const applyFontSubstitution = (
+  style: TextStyle,
+  subs: Readonly<Record<string, string>>,
+  warn: (font: string) => void,
+  warned: Set<string>,
+): TextStyle => {
+  if (style.fontFamily === undefined) return style;
+  const sub = subs[style.fontFamily];
+  if (sub !== undefined) {
+    if (sub === style.fontFamily) return style;
+    return { ...style, fontFamily: sub };
+  }
+  // Not in substitution table — emit warning once per font, then pass through.
+  if (!warned.has(style.fontFamily)) {
+    warned.add(style.fontFamily);
+    warn(style.fontFamily);
+  }
+  return style;
+};
+
+const noopWarn = (_font: string): void => {};

package/src/core/pptx-runtime.test.ts

@@ -0,0 +1,137 @@
+import { describe, expect, it } from 'vitest';
+import { promises as fs } from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { PptxSlidesRuntime, DEFAULT_PPTX_FONT_SUBSTITUTION } from './pptx-runtime.js';
+import { ptToEmu } from './geometry.js';
+import type { SlideOp } from './runtime.js';
+
+const tmpDir = async (): Promise<string> => {
+  return fs.mkdtemp(path.join(os.tmpdir(), 'pptx-runtime-test-'));
+};
+
+const isZipMagicNumber = (buf: Buffer): boolean =>
+  // PPTX is a ZIP — first two bytes are 'PK' (0x50, 0x4B).
+  buf.length >= 2 && buf[0] === 0x50 && buf[1] === 0x4b;
+
+describe('PptxSlidesRuntime', () => {
+  it('createDeckFromMaster mints a deckId and tracks it', async () => {
+    const runtime = new PptxSlidesRuntime();
+    const { deckId } = await runtime.createDeckFromMaster('sanity:cover-v1', 'Test Deck');
+    expect(deckId).toMatch(/^pptx-deck-\d+$/);
+    expect(runtime.listDeckIds()).toContain(deckId);
+  });
+
+  it('applyOps emits createObjectIds containing every created id', async () => {
+    const runtime = new PptxSlidesRuntime();
+    const { deckId } = await runtime.createDeckFromMaster('sanity:cover-v1', 'X');
+    const ops: SlideOp[] = [
+      { type: 'createSlide', slideId: 'slide_1' },
+      {
+        type: 'createShape',
+        slideId: 'slide_1',
+        shapeId: 'shape_1',
+        shape: 'TEXT_BOX',
+        rect: { x: 0, y: 0, w: ptToEmu(100), h: ptToEmu(50) },
+      },
+      { type: 'insertText', objectId: 'shape_1', text: 'hello' },
+    ];
+    const result = await runtime.applyOps(deckId, ops);
+    expect(result.createdObjectIds['slide_1']).toBe('slide_1');
+    expect(result.createdObjectIds['shape_1']).toBe('shape_1');
+    expect(result.revisionId).toBe('pptx-rev-1');
+  });
+
+  it('write produces a real PPTX file (ZIP magic number, non-zero bytes)', async () => {
+    const dir = await tmpDir();
+    const runtime = new PptxSlidesRuntime({ outputDir: dir });
+    const { deckId } = await runtime.createDeckFromMaster('sanity:cover-v1', 'Smoke Test');
+    const ops: SlideOp[] = [
+      { type: 'createSlide', slideId: 'slide_1' },
+      {
+        type: 'createShape',
+        slideId: 'slide_1',
+        shapeId: 'shape_1',
+        shape: 'TEXT_BOX',
+        rect: { x: ptToEmu(50), y: ptToEmu(50), w: ptToEmu(400), h: ptToEmu(100) },
+      },
+      { type: 'insertText', objectId: 'shape_1', text: 'Hello PPTX' },
+      {
+        type: 'updateTextStyle',
+        objectId: 'shape_1',
+        range: { start: 0, end: 10 },
+        style: { fontFamily: 'Inter', fontSize: 32, foregroundColor: '#FF5500', bold: true },
+      },
+    ];
+    await runtime.applyOps(deckId, ops);
+    const { filePath } = await runtime.write(deckId);
+    expect(filePath).toMatch(/Smoke-Test\.pptx$/);
+    const buf = await fs.readFile(filePath);
+    expect(buf.length).toBeGreaterThan(1000);
+    expect(isZipMagicNumber(buf)).toBe(true);
+    await fs.rm(dir, { recursive: true, force: true });
+  });
+
+  it('write emits a deck containing a fill-only background rectangle (regression: empty Box + fill)', async () => {
+    // The Cover component emits a full-bleed empty Box with a fill — the
+    // runtime should produce a non-trivial file even though the box has no
+    // text.
+    const dir = await tmpDir();
+    const runtime = new PptxSlidesRuntime({ outputDir: dir });
+    const { deckId } = await runtime.createDeckFromMaster('sanity:cover-v1', 'Bg Only');
+    const ops: SlideOp[] = [
+      { type: 'createSlide', slideId: 's' },
+      {
+        type: 'createShape',
+        slideId: 's',
+        shapeId: 'bg',
+        shape: 'TEXT_BOX',
+        rect: { x: 0, y: 0, w: ptToEmu(960), h: ptToEmu(540) },
+      },
+      { type: 'updateShapeProperties', objectId: 'bg', properties: { fillColor: '#0b0b0b' } },
+    ];
+    await runtime.applyOps(deckId, ops);
+    const { filePath } = await runtime.write(deckId);
+    const buf = await fs.readFile(filePath);
+    expect(isZipMagicNumber(buf)).toBe(true);
+    expect(buf.length).toBeGreaterThan(1000);
+    await fs.rm(dir, { recursive: true, force: true });
+  });
+
+  it('substrate ships an empty default substitution table (brands inject their own)', () => {
+    expect(Object.keys(DEFAULT_PPTX_FONT_SUBSTITUTION)).toHaveLength(0);
+  });
+
+  it('throws a clear error when applyOps targets an unknown deck', async () => {
+    const runtime = new PptxSlidesRuntime();
+    await expect(runtime.applyOps('does-not-exist', [])).rejects.toThrow(
+      /deck "does-not-exist" does not exist/,
+    );
+  });
+
+  it('attachManifest + getManifest round-trip', async () => {
+    const runtime = new PptxSlidesRuntime();
+    const { deckId } = await runtime.createDeckFromMaster('m', 't');
+    const manifest = {
+      manifestVersion: '1' as const,
+      generatedBy: 'react-pptx' as const,
+      generatedAt: '2026-01-01T00:00:00.000Z',
+      templateName: 'sanity',
+      deckId,
+      slots: {},
+      artifacts: [],
+    };
+    runtime.attachManifest(deckId, manifest);
+    expect(runtime.getManifest(deckId)).toEqual(manifest);
+  });
+
+  it('sanitizes deck title into safe filename (regression: spaces and slashes)', async () => {
+    const dir = await tmpDir();
+    const runtime = new PptxSlidesRuntime({ outputDir: dir });
+    const { deckId } = await runtime.createDeckFromMaster('m', 'Q2 Review / Final');
+    await runtime.applyOps(deckId, [{ type: 'createSlide', slideId: 's' }]);
+    const { filePath } = await runtime.write(deckId);
+    expect(filePath).toMatch(/Q2-Review-Final\.pptx$/);
+    await fs.rm(dir, { recursive: true, force: true });
+  });
+});